Skip to content

armgit / spree

Public Imported from GitHub
0

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

Add customs duties and shopper-visible custom fees

Damian Legawiec2ed88a23c67d
diff --git a/CLAUDE.md b/CLAUDE.md
index 380940eef7..1162126e5c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,6 +39,7 @@ Active plans (6.0 target, work pending):
- `6.0-service-workflows.md` — Two-tier services doctrine (2026-07-30). **Tier 1 `app/services/`:** plain `ServiceModule` classes, hand-written `def call(cart:, ...)`, Ruby kwargs as the contract — the permanent default; no DSL, no new `run`-pipelines, no hand-rolled sagas. **Tier 2 `app/workflows/`:** `Spree::Workflow` — named steps inside a plain `def perform(order:, ...)` (the ActiveJob::Continuable shape; bare `super` turns parameters into readers). Vocabulary: `step`/`external_step` (+ `with:`, `on_flow_failure:`), `run_hooks` + class-level `hooks`, `failure`/`halt!`; plain `ApplicationRecord.transaction`/`with_lock`/`rescue`/`publish_event`; every step instrumented as `step.spree_workflow`. Money lives in `Carts::RecalculateTotals` (single totals seam; the completed-order branch is the post-placement resum — rows re-summed, never regenerated), statuses in `Orders::UpdateStatuses` (refreshes each fulfillment's state, then rolls up); Order/CartUpdater are 6.1-removed warning shells. Shared Cart/Order surface lives in `Spree::Purchase::*` concerns; completion side effects (newsletter, account creation, risk) run in the sync `OrderPlacedSubscriber` on order.placed. Reserved for flows needing hooks, compensation/external I/O, or replay — currently `Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`, `Carts::RecalculateTotals` (+ order twins) and `Orders::Cancel` (absorbed `Order#after_cancel`; gateway settlement is an external_step). A service graduates to the workflow tier when it earns a hook, never speculatively — but hooks on flows already in the tier ship deliberately on the 6.0 boundary (2026-08-02), since hook keys are public API and moving one later is breaking. **New models get no state machine** — plain `status` string + inclusion validation, transitions through workflows; gateway I/O never in a save callback. Three hook families, contracts settled 2026-08-02: **lifecycle** (past tense, read-only), **validate** (handler calls `workflow.reject!(message)` to veto), **context** (`set_*_context`/`get_provider_data` — handler returns a hash, `run_hooks` deep-merges all handlers and returns it; last writer wins on collision). Phase 3 **shipped (2026-08-02)**: `run_hooks` returns the merged hash and `Workflow#reject!` is public API; `validate`/context/lifecycle hooks live on AddItem, Complete, Recalculate, RecalculateTotals, Cancel and Resume; `Fulfillments::Create`, `Payments::Capture`/`Refund`, `Payments::HandleWebhook` and `Carts::Merge` moved to `app/workflows/` (seams `fulfillment_create_workflow`, `payment_capture_workflow`, `payment_refund_workflow`, `payments_handle_webhook_workflow`, `cart_merge_workflow`; legacy names readable one release). **Customer registration (2026-08-05):** `Customers::Create` (seam `customer_create_workflow`, hooks `customers.create.validate`/`after_create`) is the single storefront customer-creation flow — self-registration + checkout account box (optional `order:` adopts addresses and links the order); absorbs `Orders::CreateUserAccount` (deprecated shell); admin create stays plain CRUD; token issuance stays in controllers; core sends NO welcome email — signup email is host-app code on `user.created` or the `after_create` hook. Payment workflows own the transaction boundary and guards — money movement stays in the model, called from an `external_step`. No workflows for plain CRUD. Workflow Dependencies seams use `*_workflow` keys; legacy `*_service` names stay settable/readable with warnings until 6.1 but writes are stashed, never applied (old service classes aren't workflow-contract compatible). `Carts::Complete` battery must pass unmodified. **Durability = plain Rails:** long-running background work uses `ActiveJob::Continuable` directly (reference: `Spree::Imports::ProcessJob` — CSV spine with a row-number cursor; `CreateRowsJob`/`ProcessRowsJob` deprecated shells); workflows are synchronous request-cycle flows and are NOT jobs — Workflow-level durable execution ships only if the payout run proves the need.
- `6.0-extendable-validations.md` — Workflow `validate` hooks are THE validation extension surface; **no generic model-validation registry** (design finalized 2026-08-13 — decorators stay the documented additive path, relaxing core rules = store preferences/predicate overrides). Ships: `Carts::UpsertItems` graduated to a workflow absorbing every non-increment item mutation (bulk payloads, PATCH quantity, DELETE = quantity 0; per-item `validate` with `AddItem`-compatible readers, shared item-application steps, ONE recalculate per batch; **partial-success on the storefront** — rejected items skip onto the cart's existing `warnings` array on 2xx, while the **order twin fails the whole batch**; no whole-batch veto; `SetQuantity`/`RemoveLineItem` → deprecated shells), `Products::Create`/`Update`/`Destroy` workflows (all write paths route through: Admin API v3, CSV importer, seeds; no standalone variant workflow), **rejections carry `ActiveModel::Errors`** (`Workflow#errors` + argument-less `reject!` rendering via `render_validation_error`; `reject!(message)` bridges to `:base`), `Spree.hooks.validate!` wired into boot, Address polish (document `Spree.validators.addresses` + removal API, `require_company` store preference). Address and cart creation get NO workflow (plain CRUD); custom-field value validation deferred to its own plan (Shopify-style per-definition rules, new-writes-only; `required` stays advisory). **Constraints now:** new item mutations route through `AddItem`/`UpsertItems`, new product write paths call the `Products::*` workflows, no hardcoded error codes at hook-bearing `render_service_error` call sites, clients must check `warnings` on storefront bulk-item 2xx responses. **Shipped 2026-08-13** (all four phases).
- `6.0-store-scoped-configuration.md` — Move eight commerce-behavior globals (`auto_capture` + `auto_capture_on_dispatch` → one `capture_method` string; `allow_checkout_on_gateway_error` dropped, not moved — nothing reads it; `track_inventory_levels`, `stock_reservations_enabled`, `track_price_history`, `show_products_without_price`, `address_requires_phone`, `disable_sku_validation`) from `Spree::Config` to `Spree::Store` preferences. Store preference is **authoritative — no runtime fallback** (a fallback chain is what made `default_stock_reservation_ttl_minutes` silently unreachable); upgrade carries values over via `spree:store_settings:backfill_from_config`; globals are deprecated shells until 6.1. Storeless readers (`Address`, the product availability scope) use `Spree::Current.store` with a default fallback. Seven dead settings (`products_per_page`, `storefront_*_path`, …) get shells then deletion. **Capture timing is one vocabulary (2026-08-13):** `Spree::CaptureMethod` = `checkout | on_dispatch | manual` — a Store preference, overridable by a nullable `capture_method` **column** on PaymentMethod (null = inherit; a column, not a preference, since the payment-method preferences blob is per-provider gateway credentials); read `resolved_capture_method`, write `capture_method`; dispatch capture is decided per payment so a `manual` method is never charged by a dispatch; `spree:migrate_capture_methods` carries `auto_capture` over. **Constraints now:** no new `Spree::Config` reads of the movers; no new code against `auto_capture`/`auto_capture_on_dispatch` (deprecated on both models); new behavior flags are born on Store, never global; jobs that validate addresses or query the catalog must set `Spree::Current.store`.
+- `6.0-duties-and-custom-fees.md` — Customs duties + shopper-visible custom fees on the shipped typed-`Fee` substrate (**6.0 scope implemented 2026-08-14**; 6.1 provider gem pending): a duty is a `Fee(kind: 'duty')` snapshotting its inputs (`hs_code`/`country_of_origin`/rate/provider) in `metadata` — never a TaxLine, never a new table; classification = three plain columns on `spree_variants` (`hs_code`, `country_of_origin` — **an ISO alpha-2 code, NEVER a country record id, since `spree_countries` is slated for removal**; `customs_description`) editable in both dashboard editors (variant sheet + bulk spreadsheet, sharing `normalize-customs.ts`) and shipped WITH their first consumer (EasyPost customs declaration + shipping-terms option on international labels — EasyPost declares, it never estimates); Store API cart/order serializers gain `fees` + `fee_total` (itemized shopper display is the point); duty estimation rides `Spree.adjusters` (provider gem writes duty fees + its own import-VAT `TaxLine(fee_id:)` rows) — no dedicated duty-provider contract unless a real gem proves the need; internal tax provider excludes `kind: 'duty'` from default fee taxing (no domestic tax stacked on duty, no double-count). 6.0 = plumbing; 6.1 = landed-cost provider gem + `Spree::Market` shipping-terms setting. **Constraints now:** never re-derive duty from the live catalog on an existing order (the metadata snapshot is authoritative); store-serializer money work must not assume fees stay hidden; EasyPost customs data is international-only, never required for domestic; admin cart/order serializers deliberately DROP the inherited `fees` association (admin reads/writes fees through `/orders/:id/fees`, and an admin serializer must never render a store serializer); variant write paths need the field in BOTH `PermittedAttributes` and the nested `Admin::Products::VariantsController` list. Still pending from the plan: excluding `kind: 'duty'` from `TaxProvider::Internal`'s fee taxing (blocked on that branch reaching main).
- `6.0-store-scoped-custom-field-definitions.md` — Add `store_id` + persisted `filter_key` to `Spree::MetafieldDefinition` (today global and computed), making uniqueness `(store_id, resource_type, filter_key)` with a DB index. Deferred from the 5.6 custom-field search/sort/filter work (schema change, not patch-safe). **Until then:** `filter_key` is a computed method — no Ransack predicates or `where`/`order` against it; definitions are global; uniqueness rests on a `CONCAT` validation with no index behind it.
- `6.0-opentelemetry.md` — First-class OpenTelemetry support (design finalized 2026-08-12; **phases 1–3 implemented same day** — core notifications + `spree/opentelemetry` gem + telemetry docs page; remaining: fast-follow spans, spree-starter Gemfile mention, collector smoke test): core emits a documented `ActiveSupport::Notifications` surface (NO OpenTelemetry dependency in core) + new optional top-level `spree_opentelemetry` gem (`spree/opentelemetry`) that boots the SDK from standard `OTEL_*` env vars (Saleor-style, no host initializer; `OTEL_SDK_DISABLED` kill switch), installs Rails auto-instrumentation, and translates Spree notifications into spans. Traces only in 6.0 (Ruby metrics/logs SDKs experimental; RED metrics via collector spanmetrics). First cut = commerce core four: workflows (`external_step` marks `external: true` → CLIENT spans; `outcome` payload key set inside the instrumented block), events dispatch, webhook delivery (+ outbound W3C `traceparent`), payment gateway boundary; provider bases/Meilisearch/imports/OIDC fast-follow. **Constraints now:** outbound network calls in workflows are always `external_step`, never `step`; never `rescue StandardError` around workflow execution (`FailureSignal`/`Halted` inherit `Exception`); notification payload keys are public API (additive only) and must be PII-safe; telemetry config is env-var deployment config — never `Spree::Config`, store preferences, or admin UI.
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index f4ade8ad1b..9d8adc70cd 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -92,16 +92,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImE4MTdiZTNhLTFlNDQtNDZjNC05MzE4LTFiODUxNTdjMDQxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2Nzc3NDA4fQ.ym8H4TbzxzTi87OgBymqLx2o9pNBCorYqa2pgU0E5Qk
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZmMDI3NDc2LWUxZjgtNDAyYy04NTY2LWZjNWI4OWI2ZDY2MiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2NzE0MDcyfQ.fvTEQ5MrPpK-fR29P32ZUIYUYdruCmnzIwSaVMchQsk
user:
id: adm_UkLWZg9DAJ
- first_name: Jenee
- last_name: Renner
- full_name: Jenee Renner
+ first_name: Greg
+ last_name: Effertz
+ full_name: Greg Effertz
selected_locale:
- created_at: '2026-08-15T06:58:28.798Z'
- updated_at: '2026-08-15T06:58:28.798Z'
+ created_at: '2026-08-14T13:22:52.168Z'
+ updated_at: '2026-08-14T13:22:52.168Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -204,16 +204,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE2NWFmNDU1LTk3MTMtNGU5MS1hYTRmLTU4ODc1MjU0NTU2NCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2Nzc3NDA4fQ.A-VUXBvckC85sdgDK9152lYwNQEx9Jipvez21FNIdeU
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjY0NjMxN2RlLThiMDEtNDk0Zi05MTE3LTQyZjQwMDMzNGNjNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2NzE0MDcyfQ.1qa8MT4A_zh1OqYctFZMd0Jkp1AqePpUWwAC2eagb1E
user:
id: adm_UkLWZg9DAJ
- first_name: Sybil
- last_name: Reinger
- full_name: Sybil Reinger
+ first_name: Cindie
+ last_name: Turcotte
+ full_name: Cindie Turcotte
selected_locale:
- created_at: '2026-08-15T06:58:28.854Z'
- updated_at: '2026-08-15T06:58:28.854Z'
+ created_at: '2026-08-14T13:22:52.219Z'
+ updated_at: '2026-08-14T13:22:52.219Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -315,13 +315,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Michal
- last_name: Welch
- full_name: Michal Welch
+ first_name: Dottie
+ last_name: Cormier
+ full_name: Dottie Cormier
selected_locale:
- created_at: '2026-08-15T06:58:34.503Z'
- updated_at: '2026-08-15T06:58:34.503Z'
+ created_at: '2026-08-14T13:22:56.651Z'
+ updated_at: '2026-08-14T13:22:56.651Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -432,13 +432,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Chiquita
- last_name: Tremblay
- full_name: Chiquita Tremblay
+ first_name: Avery
+ last_name: Jacobs
+ full_name: Avery Jacobs
selected_locale: de
- created_at: '2026-08-15T06:58:34.544Z'
- updated_at: '2026-08-15T06:58:34.554Z'
+ created_at: '2026-08-14T13:22:56.683Z'
+ updated_at: '2026-08-14T13:22:56.698Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -626,16 +626,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImI2MDQzZWYzLWZhMWYtNGY2ZS04N2RkLWI5ZGE4NzAxNDc3NCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2NzgwNzIxfQ.DnYDXufA2mVgKSKCecvmjFuKeRr3WRkASNlVBeWiHog
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImZiMjI1N2JjLWRmNzYtNGJkZC05YmNlLTk0MzNiZDFlZjAzMiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2NzE3MzgzfQ.8uOe41cCtIqkyxy-X_oBHlWtBJVPKnSbaoLL_uWcLRM
user:
id: adm_UkLWZg9DAJ
- first_name: Kiersten
- last_name: Jenkins
- full_name: Kiersten Jenkins
+ first_name: Delena
+ last_name: Stiedemann
+ full_name: Delena Stiedemann
selected_locale:
- created_at: '2026-08-15T06:58:41.965Z'
- updated_at: '2026-08-15T06:58:41.976Z'
+ created_at: '2026-08-14T13:23:03.524Z'
+ updated_at: '2026-08-14T13:23:03.535Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -704,7 +704,7 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImQ3MDFhYjE0LWVhMWItNDVmNS1hNzM2LWYyOTliNmMwMmYwOCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2Nzc3NDI3fQ.MRVqEZ16yqboZtiTuixDV1jWzwAOurho8mUapCEeptA
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImU1Nzk3N2Q5LTM2YzAtNGE4My1hYmM3LTAzY2U1OTc5MjFiNiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2NzE0MDg4fQ.z0vFt02rCExBKKTjG2RDt2LQCTyB6OjGILC-jPmBrXs
user:
id: adm_UkLWZg9DAJ
@@ -712,8 +712,8 @@ paths:
last_name: Owner
full_name: Olivia Owner
selected_locale:
- created_at: '2026-08-15T06:58:47.089Z'
- updated_at: '2026-08-15T06:58:47.089Z'
+ created_at: '2026-08-14T13:23:08.003Z'
+ updated_at: '2026-08-14T13:23:08.003Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -766,7 +766,7 @@ paths:
type: string
description: ISO currency code for the store.
example: USD
- country_code:
+ country_iso:
type: string
description: ISO 3166-1 alpha-2 country code for the store.
example: US
@@ -853,8 +853,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-15T06:58:28.390Z'
- updated_at: '2026-08-15T06:58:28.390Z'
+ created_at: '2026-08-14T13:22:51.817Z'
+ updated_at: '2026-08-14T13:22:51.817Z'
meta:
page: 1
limit: 25
@@ -938,8 +938,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-08-15T06:58:28.452Z'
- updated_at: '2026-08-15T06:58:28.452Z'
+ created_at: '2026-08-14T13:22:51.866Z'
+ updated_at: '2026-08-14T13:22:51.866Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -1026,8 +1026,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-15T06:58:28.484Z'
- updated_at: '2026-08-15T06:58:28.484Z'
+ created_at: '2026-08-14T13:22:51.893Z'
+ updated_at: '2026-08-14T13:22:51.893Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -1088,8 +1088,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-08-15T06:58:28.527Z'
- updated_at: '2026-08-15T06:58:28.542Z'
+ created_at: '2026-08-14T13:22:51.928Z'
+ updated_at: '2026-08-14T13:22:51.941Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -1209,34 +1209,34 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-15T06:58:28.618Z'
- updated_at: '2026-08-15T06:58:28.618Z'
+ created_at: '2026-08-14T13:22:51.992Z'
+ updated_at: '2026-08-14T13:22:51.992Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_z35ip2EGXiYeGLYroyvAJVKH
+ plaintext_token: pk_zzvf4TQZ9KzfrBSzNNgyUMn6
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_Ef9ZLtumw
+ token_prefix: sk_1p982aCo1
scopes:
- write_all
- created_at: '2026-08-15T06:58:28.620Z'
- updated_at: '2026-08-15T06:58:28.620Z'
+ created_at: '2026-08-14T13:22:51.993Z'
+ updated_at: '2026-08-14T13:22:51.993Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: eaque
+ name: corporis
key_type: secret
- token_prefix: sk_P443avskw
+ token_prefix: sk_1WeBKpEnC
scopes:
- write_all
- created_at: '2026-08-15T06:58:28.621Z'
- updated_at: '2026-08-15T06:58:28.621Z'
+ created_at: '2026-08-14T13:22:51.994Z'
+ updated_at: '2026-08-14T13:22:51.994Z'
revoked_at:
last_used_at:
channel_id:
@@ -1303,16 +1303,16 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_77SgLPyNB
+ token_prefix: sk_gaDR5JKTR
scopes:
- read_orders
- created_at: '2026-08-15T06:58:28.666Z'
- updated_at: '2026-08-15T06:58:28.666Z'
+ created_at: '2026-08-14T13:22:52.051Z'
+ updated_at: '2026-08-14T13:22:52.051Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: sk_77SgLPyNBSN6UYKev19bFfHb
- created_by_email: [email protected]
+ plaintext_token: sk_gaDR5JKTRwo6M58JCRNVfVQ1
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -1401,12 +1401,12 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-15T06:58:28.694Z'
- updated_at: '2026-08-15T06:58:28.694Z'
+ created_at: '2026-08-14T13:22:52.083Z'
+ updated_at: '2026-08-14T13:22:52.083Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_3kYKULFavxFpsRvRjEAx32cn
+ plaintext_token: pk_dqafZMQtfsuid4Tw2UJYmTCF
created_by_email:
patch:
summary: Update an API key
@@ -1460,11 +1460,11 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
- token_prefix: sk_nmHXXafaP
+ token_prefix: sk_HjedJ7QLs
scopes:
- write_all
- created_at: '2026-08-15T06:58:28.714Z'
- updated_at: '2026-08-15T06:58:28.735Z'
+ created_at: '2026-08-14T13:22:52.102Z'
+ updated_at: '2026-08-14T13:22:52.115Z'
revoked_at:
last_used_at:
channel_id:
@@ -1561,13 +1561,13 @@ paths:
application/json:
example:
id: key_EfhxLZ9ck8
- name: veniam
+ name: esse
key_type: secret
- token_prefix: sk_n4WZVFRwi
+ token_prefix: sk_eNChDqD3t
scopes:
- write_all
- created_at: '2026-08-15T06:58:28.764Z'
- updated_at: '2026-08-15T06:58:28.764Z'
+ created_at: '2026-08-14T13:22:52.139Z'
+ updated_at: '2026-08-14T13:22:52.139Z'
revoked_at:
last_used_at:
channel_id:
@@ -1625,12 +1625,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_k9RnDkhzA
+ token_prefix: sk_guScDmmeP
scopes:
- write_all
- created_at: '2026-08-15T06:58:28.774Z'
- updated_at: '2026-08-15T06:58:28.786Z'
- revoked_at: '2026-08-15T06:58:28.786Z'
+ created_at: '2026-08-14T13:22:52.147Z'
+ updated_at: '2026-08-14T13:22:52.160Z'
+ revoked_at: '2026-08-14T13:22:52.160Z'
last_used_at:
channel_id:
plaintext_token:
@@ -1707,8 +1707,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-15T06:58:28.922Z'
- updated_at: '2026-08-15T06:58:28.922Z'
+ created_at: '2026-08-14T13:22:52.278Z'
+ updated_at: '2026-08-14T13:22:52.278Z'
meta:
page: 1
limit: 25
@@ -1782,8 +1782,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-15T06:58:28.969Z'
- updated_at: '2026-08-15T06:58:28.978Z'
+ created_at: '2026-08-14T13:22:52.322Z'
+ updated_at: '2026-08-14T13:22:52.328Z'
schema:
"$ref": "#/components/schemas/Category"
'422':
@@ -1889,8 +1889,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-15T06:58:29.020Z'
- updated_at: '2026-08-15T06:58:29.020Z'
+ created_at: '2026-08-14T13:22:52.366Z'
+ updated_at: '2026-08-14T13:22:52.366Z'
schema:
"$ref": "#/components/schemas/Category"
'404':
@@ -1960,8 +1960,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-15T06:58:29.103Z'
- updated_at: '2026-08-15T06:58:29.128Z'
+ created_at: '2026-08-14T13:22:52.417Z'
+ updated_at: '2026-08-14T13:22:52.456Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -2076,8 +2076,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-15T06:58:29.175Z'
- updated_at: '2026-08-15T06:58:29.196Z'
+ created_at: '2026-08-14T13:22:52.510Z'
+ updated_at: '2026-08-14T13:22:52.529Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -2189,8 +2189,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1380
- slug: product-1380
+ name: Product 18240
+ slug: product-18240
meta_title:
meta_description:
meta_keywords:
@@ -2202,14 +2202,25 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Ipsam eaque exercitationem veniam cumque minima. Ex tenetur
- ipsam recusandae minus. Excepturi adipisci sed nulla sapiente quo
- libero. Enim quo tempore necessitatibus voluptate facere labore
- beatae modi. Cumque voluptatum occaecati illo fugiat ea exercitationem.
- description_html: Ipsam eaque exercitationem veniam cumque minima.
- Ex tenetur ipsam recusandae minus. Excepturi adipisci sed nulla
- sapiente quo libero. Enim quo tempore necessitatibus voluptate facere
- labore beatae modi. Cumque voluptatum occaecati illo fugiat ea exercitationem.
+ description: Est aspernatur adipisci sapiente minima dignissimos quis.
+ Doloremque facilis est necessitatibus dolores exercitationem qui
+ quasi. Earum rem vitae similique maiores corrupti. Laboriosam non
+ explicabo alias temporibus quasi labore. Nam minus consectetur magni
+ maxime sapiente alias reprehenderit nesciunt. Ad maiores saepe quo
+ possimus vitae porro nemo consectetur. Nesciunt tempore exercitationem
+ praesentium minus iure natus. Repellat cumque tempore corporis quia.
+ Corrupti voluptatum at optio illum iure. Autem eum est velit ullam
+ deserunt. Consequatur harum maiores architecto consequuntur voluptas
+ nobis sint tenetur. Ipsum eius voluptate ipsam placeat nam facilis
+ voluptatum repellat. Rerum quia mollitia tenetur voluptate inventore
+ vel expedita. Praesentium totam odit excepturi est. Nihil consequuntur
+ et eveniet consectetur atque eligendi perferendis. Maiores aliquam
+ quod eos in quasi.
+ description_html: |-
+ Est aspernatur adipisci sapiente minima dignissimos quis. Doloremque facilis est necessitatibus dolores exercitationem qui quasi. Earum rem vitae similique maiores corrupti. Laboriosam non explicabo alias temporibus quasi labore.
+ Nam minus consectetur magni maxime sapiente alias reprehenderit nesciunt. Ad maiores saepe quo possimus vitae porro nemo consectetur. Nesciunt tempore exercitationem praesentium minus iure natus. Repellat cumque tempore corporis quia.
+ Corrupti voluptatum at optio illum iure. Autem eum est velit ullam deserunt. Consequatur harum maiores architecto consequuntur voluptas nobis sint tenetur. Ipsum eius voluptate ipsam placeat nam facilis voluptatum repellat. Rerum quia mollitia tenetur voluptate inventore vel expedita.
+ Praesentium totam odit excepturi est. Nihil consequuntur et eveniet consectetur atque eligendi perferendis. Maiores aliquam quod eos in quasi.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -2224,14 +2235,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:29.324Z'
- updated_at: '2026-08-15T06:58:29.324Z'
+ created_at: '2026-08-14T13:22:52.629Z'
+ updated_at: '2026-08-14T13:22:52.629Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-15T06:58:29.303Z'
- updated_at: '2026-08-15T06:58:29.337Z'
+ created_at: '2026-08-14T13:22:52.606Z'
+ updated_at: '2026-08-14T13:22:52.643Z'
delivery_profile_id: fp_UkLWZg9DAJ
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
@@ -2402,8 +2413,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-15T06:58:28.082Z'
- updated_at: '2026-08-15T06:58:28.082Z'
+ created_at: '2026-08-14T13:22:51.548Z'
+ updated_at: '2026-08-14T13:22:51.548Z'
stock_location_ids: []
- id: ch_gbHJdmfrXB
name: Wholesale
@@ -2415,8 +2426,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-15T06:58:29.534Z'
- updated_at: '2026-08-15T06:58:29.534Z'
+ created_at: '2026-08-14T13:22:52.803Z'
+ updated_at: '2026-08-14T13:22:52.803Z'
stock_location_ids: []
meta:
page: 1
@@ -2502,8 +2513,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-15T06:58:29.596Z'
- updated_at: '2026-08-15T06:58:29.596Z'
+ created_at: '2026-08-14T13:22:52.873Z'
+ updated_at: '2026-08-14T13:22:52.873Z'
stock_location_ids: []
requestBody:
content:
@@ -2602,8 +2613,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-15T06:58:29.611Z'
- updated_at: '2026-08-15T06:58:29.611Z'
+ created_at: '2026-08-14T13:22:52.888Z'
+ updated_at: '2026-08-14T13:22:52.888Z'
stock_location_ids: []
patch:
summary: Update a channel
@@ -2658,8 +2669,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access: login_required
preferred_guest_checkout: false
- created_at: '2026-08-15T06:58:29.640Z'
- updated_at: '2026-08-15T06:58:29.664Z'
+ created_at: '2026-08-14T13:22:52.917Z'
+ updated_at: '2026-08-14T13:22:52.937Z'
stock_location_ids: []
requestBody:
content:
@@ -2942,8 +2953,8 @@ paths:
- id: orule_UkLWZg9DAJ
position: 1
active: true
- created_at: '2026-08-15T06:58:28.087Z'
- updated_at: '2026-08-15T06:58:28.087Z'
+ created_at: '2026-08-14T13:22:51.553Z'
+ updated_at: '2026-08-14T13:22:51.553Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -2954,8 +2965,8 @@ paths:
- id: orule_gbHJdmfrXB
position: 2
active: true
- created_at: '2026-08-15T06:58:28.090Z'
- updated_at: '2026-08-15T06:58:28.090Z'
+ created_at: '2026-08-14T13:22:51.556Z'
+ updated_at: '2026-08-14T13:22:51.556Z'
type: minimize_splits
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -2966,8 +2977,8 @@ paths:
- id: orule_EfhxLZ9ck8
position: 3
active: true
- created_at: '2026-08-15T06:58:28.093Z'
- updated_at: '2026-08-15T06:58:28.093Z'
+ created_at: '2026-08-14T13:22:51.559Z'
+ updated_at: '2026-08-14T13:22:51.559Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -3032,8 +3043,8 @@ paths:
id: orule_VqXmZF31wY
position: 3
active: true
- created_at: '2026-08-15T06:58:35.669Z'
- updated_at: '2026-08-15T06:58:35.669Z'
+ created_at: '2026-08-14T13:22:57.773Z'
+ updated_at: '2026-08-14T13:22:57.773Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -3128,8 +3139,8 @@ paths:
id: orule_UkLWZg9DAJ
position: 2
active: false
- created_at: '2026-08-15T06:58:28.087Z'
- updated_at: '2026-08-15T06:58:35.719Z'
+ created_at: '2026-08-14T13:22:51.553Z'
+ updated_at: '2026-08-14T13:22:57.811Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -3317,8 +3328,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-15T06:58:31.186Z'
- updated_at: '2026-08-15T06:58:31.186Z'
+ created_at: '2026-08-14T13:22:53.663Z'
+ updated_at: '2026-08-14T13:22:53.663Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -3329,8 +3340,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_custom_order_notes
- created_at: '2026-08-15T06:58:31.187Z'
- updated_at: '2026-08-15T06:58:31.187Z'
+ created_at: '2026-08-14T13:22:53.664Z'
+ updated_at: '2026-08-14T13:22:53.664Z'
meta:
page: 1
limit: 25
@@ -3399,8 +3410,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_origin
- created_at: '2026-08-15T06:58:31.221Z'
- updated_at: '2026-08-15T06:58:31.221Z'
+ created_at: '2026-08-14T13:22:53.701Z'
+ updated_at: '2026-08-14T13:22:53.701Z'
requestBody:
content:
application/json:
@@ -3508,8 +3519,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-15T06:58:31.227Z'
- updated_at: '2026-08-15T06:58:31.227Z'
+ created_at: '2026-08-14T13:22:53.707Z'
+ updated_at: '2026-08-14T13:22:53.707Z'
patch:
summary: Update a custom field definition
tags:
@@ -3569,8 +3580,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-15T06:58:31.249Z'
- updated_at: '2026-08-15T06:58:31.263Z'
+ created_at: '2026-08-14T13:22:53.727Z'
+ updated_at: '2026-08-14T13:22:53.740Z'
requestBody:
content:
application/json:
@@ -3716,14 +3727,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-08-15T06:58:31.312Z'
- updated_at: '2026-08-15T06:58:31.312Z'
+ created_at: '2026-08-14T13:22:53.768Z'
+ updated_at: '2026-08-14T13:22:53.768Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-08-15T06:58:31.313Z'
- updated_at: '2026-08-15T06:58:31.313Z'
+ created_at: '2026-08-14T13:22:53.768Z'
+ updated_at: '2026-08-14T13:22:53.768Z'
meta:
page: 1
limit: 25
@@ -3812,8 +3823,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-08-15T06:58:31.379Z'
- updated_at: '2026-08-15T06:58:31.379Z'
+ created_at: '2026-08-14T13:22:53.827Z'
+ updated_at: '2026-08-14T13:22:53.827Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -3922,22 +3933,22 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-08-15T06:58:31.437Z'
- updated_at: '2026-08-15T06:58:31.437Z'
+ created_at: '2026-08-14T13:22:53.880Z'
+ updated_at: '2026-08-14T13:22:53.880Z'
customers:
- id: cust_UkLWZg9DAJ
- first_name: Danae
- last_name: Johnson
+ first_name: Shenita
+ last_name: Jacobi
phone:
accepts_email_marketing: false
- full_name: Danae Johnson
+ full_name: Shenita Jacobi
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-15T06:58:31.440Z'
- updated_at: '2026-08-15T06:58:31.440Z'
+ created_at: '2026-08-14T13:22:53.883Z'
+ updated_at: '2026-08-14T13:22:53.883Z'
tags: []
internal_note:
internal_note_html:
@@ -4017,8 +4028,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-08-15T06:58:31.495Z'
- updated_at: '2026-08-15T06:58:31.510Z'
+ created_at: '2026-08-14T13:22:53.930Z'
+ updated_at: '2026-08-14T13:22:53.944Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -4167,20 +4178,18 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
label:
metadata: {}
- created_at: '2026-08-15T06:58:31.581Z'
- updated_at: '2026-08-15T06:58:31.581Z'
+ created_at: '2026-08-14T13:22:54.027Z'
+ updated_at: '2026-08-14T13:22:54.027Z'
customer_id: cust_UkLWZg9DAJ
meta:
page: 1
@@ -4220,8 +4229,8 @@ paths:
address1: '350 Fifth Avenue',
city: 'New York',
postal_code: '10118',
- country_code: 'US',
- state_code: 'NY',
+ country_iso: 'US',
+ state_abbr: 'NY',
phone: '+1 212 555 1234',
label: 'Office',
is_default_shipping: true,
@@ -4229,7 +4238,7 @@ paths:
- lang: bash
label: Spree CLI
source: spree api post /customers/{customer_id}/addresses -d '{"first_name":"Jane","last_name":"Doe","address1":"350
- Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
+ Fifth Avenue","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1
212 555 1234","label":"Office","is_default_shipping":true}'
parameters:
- name: x-spree-api-key
@@ -4263,20 +4272,18 @@ paths:
city: New York
phone: "+12125551234"
company:
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
label: Office
metadata: {}
- created_at: '2026-08-15T06:58:31.638Z'
- updated_at: '2026-08-15T06:58:31.638Z'
+ created_at: '2026-08-14T13:22:54.081Z'
+ updated_at: '2026-08-14T13:22:54.081Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -4296,10 +4303,10 @@ paths:
type: string
postal_code:
type: string
- country_code:
+ country_iso:
type: string
description: ISO-2 country code (e.g. US)
- state_code:
+ state_abbr:
type: string
description: State/province abbreviation (e.g. NY)
phone:
@@ -4380,20 +4387,18 @@ paths:
city: Manhattan
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
label:
metadata: {}
- created_at: '2026-08-15T06:58:31.656Z'
- updated_at: '2026-08-15T06:58:31.678Z'
+ created_at: '2026-08-14T13:22:54.098Z'
+ updated_at: '2026-08-14T13:22:54.115Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -4532,8 +4537,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-15T06:58:31.745Z'
- updated_at: '2026-08-15T06:58:31.745Z'
+ created_at: '2026-08-14T13:22:54.176Z'
+ updated_at: '2026-08-14T13:22:54.176Z'
meta:
page: 1
limit: 25
@@ -4623,8 +4628,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-15T06:58:31.779Z'
- updated_at: '2026-08-15T06:58:31.779Z'
+ created_at: '2026-08-14T13:22:54.202Z'
+ updated_at: '2026-08-14T13:22:54.202Z'
delete:
summary: Delete a customer credit card
tags:
@@ -4749,8 +4754,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-08-15T06:58:31.855Z'
- updated_at: '2026-08-15T06:58:31.855Z'
+ created_at: '2026-08-14T13:22:54.268Z'
+ updated_at: '2026-08-14T13:22:54.268Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -4829,8 +4834,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-08-15T06:58:31.916Z'
- updated_at: '2026-08-15T06:58:31.916Z'
+ created_at: '2026-08-14T13:22:54.343Z'
+ updated_at: '2026-08-14T13:22:54.343Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -4925,8 +4930,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-08-15T06:58:31.942Z'
- updated_at: '2026-08-15T06:58:31.968Z'
+ created_at: '2026-08-14T13:22:54.367Z'
+ updated_at: '2026-08-14T13:22:54.386Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -5085,8 +5090,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-15T06:58:32.021Z'
- updated_at: '2026-08-15T06:58:32.021Z'
+ created_at: '2026-08-14T13:22:54.428Z'
+ updated_at: '2026-08-14T13:22:54.428Z'
tags: []
internal_note:
internal_note_html:
@@ -5169,8 +5174,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-15T06:58:32.068Z'
- updated_at: '2026-08-15T06:58:32.068Z'
+ created_at: '2026-08-14T13:22:54.467Z'
+ updated_at: '2026-08-14T13:22:54.467Z'
tags: []
internal_note:
internal_note_html:
@@ -5285,8 +5290,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-15T06:58:32.084Z'
- updated_at: '2026-08-15T06:58:32.084Z'
+ created_at: '2026-08-14T13:22:54.478Z'
+ updated_at: '2026-08-14T13:22:54.478Z'
tags: []
internal_note:
internal_note_html:
@@ -5359,8 +5364,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-15T06:58:32.107Z'
- updated_at: '2026-08-15T06:58:32.123Z'
+ created_at: '2026-08-14T13:22:54.503Z'
+ updated_at: '2026-08-14T13:22:54.519Z'
tags: []
internal_note:
internal_note_html:
@@ -5808,8 +5813,8 @@ paths:
- id: exp_UkLWZg9DAJ
number: EF1001
format: csv
- created_at: '2026-08-15T06:58:32.745Z'
- updated_at: '2026-08-15T06:58:32.745Z'
+ created_at: '2026-08-14T13:22:55.090Z'
+ updated_at: '2026-08-14T13:22:55.090Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -5882,8 +5887,8 @@ paths:
id: exp_gbHJdmfrXB
number: EF1002
format: csv
- created_at: '2026-08-15T06:58:32.784Z'
- updated_at: '2026-08-15T06:58:32.784Z'
+ created_at: '2026-08-14T13:22:55.122Z'
+ updated_at: '2026-08-14T13:22:55.122Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -5982,8 +5987,8 @@ paths:
id: exp_UkLWZg9DAJ
number: EF1001
format: csv
- created_at: '2026-08-15T06:58:32.802Z'
- updated_at: '2026-08-15T06:58:32.802Z'
+ created_at: '2026-08-14T13:22:55.137Z'
+ updated_at: '2026-08-14T13:22:55.137Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -6199,8 +6204,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:35.847Z'
- updated_at: '2026-08-15T06:58:35.858Z'
+ created_at: '2026-08-14T13:22:57.911Z'
+ updated_at: '2026-08-14T13:22:57.919Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -6293,7 +6298,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-15T06:58:36.107Z'
+ fulfilled_at: '2026-08-14T13:22:58.126Z'
tracking_status:
estimated_delivery_at:
delivered_at:
@@ -6305,8 +6310,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-15T06:58:36.067Z'
- updated_at: '2026-08-15T06:58:36.108Z'
+ created_at: '2026-08-14T13:22:58.106Z'
+ updated_at: '2026-08-14T13:22:58.127Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -6481,8 +6486,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:36.476Z'
- updated_at: '2026-08-15T06:58:36.487Z'
+ created_at: '2026-08-14T13:22:58.413Z'
+ updated_at: '2026-08-14T13:22:58.424Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -6579,8 +6584,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:36.608Z'
- updated_at: '2026-08-15T06:58:36.681Z'
+ created_at: '2026-08-14T13:22:58.550Z'
+ updated_at: '2026-08-14T13:22:58.610Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -6679,7 +6684,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-15T06:58:36.832Z'
+ fulfilled_at: '2026-08-14T13:22:58.745Z'
tracking_status:
estimated_delivery_at:
delivered_at:
@@ -6691,8 +6696,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:36.763Z'
- updated_at: '2026-08-15T06:58:36.833Z'
+ created_at: '2026-08-14T13:22:58.682Z'
+ updated_at: '2026-08-14T13:22:58.746Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -6795,8 +6800,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:36.916Z'
- updated_at: '2026-08-15T06:58:36.979Z'
+ created_at: '2026-08-14T13:22:58.825Z'
+ updated_at: '2026-08-14T13:22:58.889Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents:
@@ -6895,10 +6900,10 @@ paths:
display_tax_total: "$0.00"
status: delivered
fulfillment_type: shipping
- fulfilled_at: '2026-08-15T06:58:37.252Z'
+ fulfilled_at: '2026-08-14T13:22:59.162Z'
tracking_status:
estimated_delivery_at:
- delivered_at: '2026-08-15T06:58:37.272Z'
+ delivered_at: '2026-08-14T13:22:59.200Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -6907,8 +6912,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:37.201Z'
- updated_at: '2026-08-15T06:58:37.273Z'
+ created_at: '2026-08-14T13:22:59.084Z'
+ updated_at: '2026-08-14T13:22:59.202Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7027,8 +7032,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:37.484Z'
- updated_at: '2026-08-15T06:58:37.559Z'
+ created_at: '2026-08-14T13:22:59.475Z'
+ updated_at: '2026-08-14T13:22:59.544Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7125,8 +7130,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-15T06:58:37.652Z'
- updated_at: '2026-08-15T06:58:37.729Z'
+ created_at: '2026-08-14T13:22:59.615Z'
+ updated_at: '2026-08-14T13:22:59.677Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7234,8 +7239,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-15T06:58:37.902Z'
- updated_at: '2026-08-15T06:58:37.971Z'
+ created_at: '2026-08-14T13:22:59.826Z'
+ updated_at: '2026-08-14T13:22:59.863Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
documents: []
@@ -7336,8 +7341,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-15T06:58:32.869Z'
- updated_at: '2026-08-15T06:58:32.869Z'
+ created_at: '2026-08-14T13:22:55.207Z'
+ updated_at: '2026-08-14T13:22:55.207Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -7421,8 +7426,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-08-15T06:58:32.911Z'
- updated_at: '2026-08-15T06:58:32.911Z'
+ created_at: '2026-08-14T13:22:55.248Z'
+ updated_at: '2026-08-14T13:22:55.248Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: adm_UkLWZg9DAJ
@@ -7526,8 +7531,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-15T06:58:32.946Z'
- updated_at: '2026-08-15T06:58:32.946Z'
+ created_at: '2026-08-14T13:22:55.280Z'
+ updated_at: '2026-08-14T13:22:55.280Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -7633,7 +7638,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: EA3F8EEA3A12E35F
+ code: 521DDC5B550D3810
status: active
currency: USD
amount: '50.0'
@@ -7647,12 +7652,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-15T06:58:33.003Z'
- updated_at: '2026-08-15T06:58:33.003Z'
+ created_at: '2026-08-14T13:22:55.341Z'
+ updated_at: '2026-08-14T13:22:55.341Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: DD1437B0260E60AC
+ code: 7314CBC4F3541779
status: active
currency: USD
amount: '25.0'
@@ -7666,8 +7671,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-15T06:58:33.005Z'
- updated_at: '2026-08-15T06:58:33.005Z'
+ created_at: '2026-08-14T13:22:55.343Z'
+ updated_at: '2026-08-14T13:22:55.343Z'
customer_id:
created_by_id:
meta:
@@ -7755,7 +7760,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: D22FE8B11BBE44A4
+ code: FBB3C9A9C5D6B0B9
status: active
currency: USD
amount: '25.0'
@@ -7769,8 +7774,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-15T06:58:33.065Z'
- updated_at: '2026-08-15T06:58:33.065Z'
+ created_at: '2026-08-14T13:22:55.395Z'
+ updated_at: '2026-08-14T13:22:55.395Z'
customer_id:
created_by_id: adm_UkLWZg9DAJ
schema:
@@ -7879,7 +7884,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: E3AD2DF767AA856B
+ code: 726B10E5707D6E53
status: active
currency: USD
amount: '50.0'
@@ -7893,8 +7898,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-15T06:58:33.100Z'
- updated_at: '2026-08-15T06:58:33.100Z'
+ created_at: '2026-08-14T13:22:55.428Z'
+ updated_at: '2026-08-14T13:22:55.428Z'
customer_id:
created_by_id:
schema:
@@ -7957,7 +7962,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 1F788C1B6A71B19D
+ code: 7E8976807B8EF1F2
status: active
currency: USD
amount: '75.0'
@@ -7971,8 +7976,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-15T06:58:33.149Z'
- updated_at: '2026-08-15T06:58:33.164Z'
+ created_at: '2026-08-14T13:22:55.473Z'
+ updated_at: '2026-08-14T13:22:55.486Z'
customer_id:
created_by_id:
schema:
@@ -8077,8 +8082,8 @@ paths:
- id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
- created_at: '2026-08-15T06:58:33.245Z'
- updated_at: '2026-08-15T06:58:33.252Z'
+ created_at: '2026-08-14T13:22:55.563Z'
+ updated_at: '2026-08-14T13:22:55.570Z'
type: products
status: pending
owner_type: store
@@ -8167,6 +8172,15 @@ paths:
- name: product_type
label: Product Type
required: false
+ - name: hs_code
+ label: HS Code
+ required: false
+ - name: country_of_origin
+ label: Country of Origin
+ required: false
+ - name: customs_description
+ label: Customs Description
+ required: false
- name: image1_src
label: Image 1 URL
required: false
@@ -8256,8 +8270,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
- created_at: '2026-08-15T06:58:33.305Z'
- updated_at: '2026-08-15T06:58:33.346Z'
+ created_at: '2026-08-14T13:22:55.613Z'
+ updated_at: '2026-08-14T13:22:55.656Z'
type: products
status: mapping
owner_type: store
@@ -8346,6 +8360,15 @@ paths:
- name: product_type
label: Product Type
required: false
+ - name: hs_code
+ label: HS Code
+ required: false
+ - name: country_of_origin
+ label: Country of Origin
+ required: false
+ - name: customs_description
+ label: Customs Description
+ required: false
- name: image1_src
label: Image 1 URL
required: false
@@ -8494,50 +8517,62 @@ paths:
file_column:
required: false
- id: immap_3uWpPTcf5W
- schema_field: image1_src
+ schema_field: hs_code
file_column:
required: false
- id: immap_D6Psx31WaT
- schema_field: image2_src
+ schema_field: country_of_origin
file_column:
required: false
- id: immap_msx3nOJap6
- schema_field: image3_src
+ schema_field: customs_description
file_column:
required: false
- id: immap_5CQZnCRf8J
- schema_field: option1_name
+ schema_field: image1_src
file_column:
required: false
- id: immap_M2nyloHRUQ
- schema_field: option1_value
+ schema_field: image2_src
file_column:
required: false
- id: immap_prklVeMgbn
- schema_field: option2_name
+ schema_field: image3_src
file_column:
required: false
- id: immap_so8jaGonyx
- schema_field: option2_value
+ schema_field: option1_name
file_column:
required: false
- id: immap_rsClYtECFI
- schema_field: option3_name
+ schema_field: option1_value
file_column:
required: false
- id: immap_8DR0I7fEbw
- schema_field: option3_value
+ schema_field: option2_name
file_column:
required: false
- id: immap_aAtNvLSUAr
- schema_field: category1
+ schema_field: option2_value
file_column:
required: false
- id: immap_QiA48cIW7A
- schema_field: category2
+ schema_field: option3_name
file_column:
required: false
- id: immap_QDA48cIW7A
+ schema_field: option3_value
+ file_column:
+ required: false
+ - id: immap_8cR0I7fEbw
+ schema_field: category1
+ file_column:
+ required: false
+ - id: immap_oqlrKdXjaP
+ schema_field: category2
+ file_column:
+ required: false
+ - id: immap_48Olu6p4zZ
schema_field: category3
file_column:
required: false
@@ -8694,8 +8729,8 @@ paths:
id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
- created_at: '2026-08-15T06:58:33.565Z'
- updated_at: '2026-08-15T06:58:33.583Z'
+ created_at: '2026-08-14T13:22:55.776Z'
+ updated_at: '2026-08-14T13:22:55.783Z'
type: products
status: pending
owner_type: store
@@ -8784,6 +8819,15 @@ paths:
- name: product_type
label: Product Type
required: false
+ - name: hs_code
+ label: HS Code
+ required: false
+ - name: country_of_origin
+ label: Country of Origin
+ required: false
+ - name: customs_description
+ label: Customs Description
+ required: false
- name: image1_src
label: Image 1 URL
required: false
@@ -8931,8 +8975,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
- created_at: '2026-08-15T06:58:33.686Z'
- updated_at: '2026-08-15T06:58:33.756Z'
+ created_at: '2026-08-14T13:22:55.874Z'
+ updated_at: '2026-08-14T13:22:55.935Z'
type: products
status: completed_mapping
owner_type: store
@@ -9021,6 +9065,15 @@ paths:
- name: product_type
label: Product Type
required: false
+ - name: hs_code
+ label: HS Code
+ required: false
+ - name: country_of_origin
+ label: Country of Origin
+ required: false
+ - name: customs_description
+ label: Customs Description
+ required: false
- name: image1_src
label: Image 1 URL
required: false
@@ -9161,50 +9214,62 @@ paths:
file_column:
required: false
- id: immap_3uWpPTcf5W
+ schema_field: hs_code
+ file_column:
+ required: false
+ - id: immap_D6Psx31WaT
+ schema_field: country_of_origin
+ file_column:
+ required: false
+ - id: immap_msx3nOJap6
+ schema_field: customs_description
+ file_column:
+ required: false
+ - id: immap_5CQZnCRf8J
schema_field: image1_src
file_column: image1_src
required: false
- - id: immap_D6Psx31WaT
+ - id: immap_M2nyloHRUQ
schema_field: image2_src
file_column: image2_src
required: false
- - id: immap_msx3nOJap6
+ - id: immap_prklVeMgbn
schema_field: image3_src
file_column: image3_src
required: false
- - id: immap_5CQZnCRf8J
+ - id: immap_so8jaGonyx
schema_field: option1_name
file_column: option1_name
required: false
- - id: immap_M2nyloHRUQ
+ - id: immap_rsClYtECFI
schema_field: option1_value
file_column: option1_value
required: false
- - id: immap_prklVeMgbn
+ - id: immap_8DR0I7fEbw
schema_field: option2_name
file_column: option2_name
required: false
- - id: immap_so8jaGonyx
+ - id: immap_aAtNvLSUAr
schema_field: option2_value
file_column: option2_value
required: false
- - id: immap_rsClYtECFI
+ - id: immap_QiA48cIW7A
schema_field: option3_name
file_column: option3_name
required: false
- - id: immap_8DR0I7fEbw
+ - id: immap_QDA48cIW7A
schema_field: option3_value
file_column: option3_value
required: false
- - id: immap_aAtNvLSUAr
+ - id: immap_8cR0I7fEbw
schema_field: category1
file_column: category1
required: false
- - id: immap_QiA48cIW7A
+ - id: immap_oqlrKdXjaP
schema_field: category2
file_column: category2
required: false
- - id: immap_QDA48cIW7A
+ - id: immap_48Olu6p4zZ
schema_field: category3
file_column: category3
required: false
@@ -9267,8 +9332,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 1
- created_at: '2026-08-15T06:58:33.794Z'
- updated_at: '2026-08-15T06:58:33.814Z'
+ created_at: '2026-08-14T13:22:55.968Z'
+ updated_at: '2026-08-14T13:22:55.987Z'
type: products
status: processing
owner_type: store
@@ -9357,6 +9422,15 @@ paths:
- name: product_type
label: Product Type
required: false
+ - name: hs_code
+ label: HS Code
+ required: false
+ - name: country_of_origin
+ label: Country of Origin
+ required: false
+ - name: customs_description
+ label: Customs Description
+ required: false
- name: image1_src
label: Image 1 URL
required: false
@@ -9441,8 +9515,8 @@ paths:
row_number: 2
status: failed
validation_errors: boom
- created_at: '2026-08-15T06:58:33.842Z'
- updated_at: '2026-08-15T06:58:33.842Z'
+ created_at: '2026-08-14T13:22:56.019Z'
+ updated_at: '2026-08-14T13:22:56.019Z'
import_id: imp_UkLWZg9DAJ
item_type:
item_id:
@@ -9535,31 +9609,29 @@ paths:
example:
data:
- id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
- id: mkt_gbHJdmfrXB
name: EU
currency: USD
default_locale: en
tax_inclusive: false
default: false
- country_codes:
+ country_isos:
- DE
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:34.082Z'
- updated_at: '2026-08-15T06:58:34.082Z'
+ created_at: '2026-08-14T13:22:56.242Z'
+ updated_at: '2026-08-14T13:22:56.242Z'
meta:
page: 1
limit: 25
@@ -9592,7 +9664,7 @@ paths:
description: |-
Creates a new market for the current store.
- - `country_codes` accepts 2-letter ISO country codes (e.g. `["DE", "FR"]`);
+ - `country_isos` accepts 2-letter ISO country codes (e.g. `["DE", "FR"]`);
the market must contain at least one country. Unknown codes are
silently dropped.
- `supported_locales` accepts an array of locale codes; the
@@ -9619,11 +9691,11 @@ paths:
default_locale: 'de',
supported_locales: ['de', 'en', 'fr'],
tax_inclusive: true,
- country_codes: ['DE', 'FR', 'IT'],
+ country_isos: ['DE', 'FR', 'IT'],
})
- lang: bash
label: Spree CLI
- source: spree api post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_codes":["DE","FR","IT"]}'
+ source: spree api post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_isos":["DE","FR","IT"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -9647,14 +9719,13 @@ paths:
default_locale: fr
tax_inclusive: true
default: false
- country_codes:
+ country_isos:
- FR
supported_locales:
- en
- fr
- tax_provider:
- created_at: '2026-08-15T06:58:34.150Z'
- updated_at: '2026-08-15T06:58:34.150Z'
+ created_at: '2026-08-14T13:22:56.322Z'
+ updated_at: '2026-08-14T13:22:56.322Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -9714,7 +9785,7 @@ paths:
position:
type: integer
description: Sort order within the store; lower = first.
- country_codes:
+ country_isos:
type: array
items:
type: string
@@ -9727,7 +9798,7 @@ paths:
- name
- currency
- default_locale
- - country_codes
+ - country_isos
"/api/v3/admin/markets/{id}":
parameters:
- name: id
@@ -9786,13 +9857,12 @@ paths:
default_locale: en
tax_inclusive: false
default: false
- country_codes:
+ country_isos:
- DE
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:34.207Z'
- updated_at: '2026-08-15T06:58:34.207Z'
+ created_at: '2026-08-14T13:22:56.445Z'
+ updated_at: '2026-08-14T13:22:56.445Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -9813,7 +9883,7 @@ paths:
- api_key: []
bearer_auth: []
description: |-
- Updates an existing market. Pass `country_codes` to replace the
+ Updates an existing market. Pass `country_isos` to replace the
market's country list (full-set update), `supported_locales` to
replace the supported locales, or `position` to reorder the market
within the store.
@@ -9833,17 +9903,17 @@ paths:
secretKey: 'sk_xxx',
})
- // `country_codes` is a full-set update — the market is reconciled to match
+ // `country_isos` is a full-set update — the market is reconciled to match
// the array (adds new countries, removes ones not present). Setting
// `default: true` demotes the previous default market in the store.
const market = await client.markets.update('market_UkLWZg9DAJ', {
name: 'European Union',
tax_inclusive: true,
- country_codes: ['DE', 'FR'],
+ country_isos: ['DE', 'FR'],
})
- lang: bash
label: Spree CLI
- source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_codes":["DE","FR"]}'
+ source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_isos":["DE","FR"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -9867,13 +9937,12 @@ paths:
default_locale: en
tax_inclusive: true
default: false
- country_codes:
+ country_isos:
- DE
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:34.272Z'
- updated_at: '2026-08-15T06:58:34.289Z'
+ created_at: '2026-08-14T13:22:56.517Z'
+ updated_at: '2026-08-14T13:22:56.534Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -9911,7 +9980,7 @@ paths:
type: boolean
position:
type: integer
- country_codes:
+ country_isos:
type: array
items:
type: string
@@ -10053,8 +10122,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-15T06:58:34.575Z'
- updated_at: '2026-08-15T06:58:34.575Z'
+ created_at: '2026-08-14T13:22:56.720Z'
+ updated_at: '2026-08-14T13:22:56.720Z'
meta:
page: 1
limit: 25
@@ -10148,8 +10217,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-15T06:58:34.633Z'
- updated_at: '2026-08-15T06:58:34.633Z'
+ created_at: '2026-08-14T13:22:56.771Z'
+ updated_at: '2026-08-14T13:22:56.771Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -10273,8 +10342,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-15T06:58:34.664Z'
- updated_at: '2026-08-15T06:58:34.664Z'
+ created_at: '2026-08-14T13:22:56.798Z'
+ updated_at: '2026-08-14T13:22:56.798Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -10347,8 +10416,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-15T06:58:34.709Z'
- updated_at: '2026-08-15T06:58:34.724Z'
+ created_at: '2026-08-14T13:22:56.840Z'
+ updated_at: '2026-08-14T13:22:56.854Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -10508,12 +10577,8 @@ paths:
display_amount: "$1.50"
provider_id: internal
metadata: {}
- taxability_reason:
- country_code:
- state_code:
- data: {}
- created_at: '2026-08-15T06:58:34.967Z'
- updated_at: '2026-08-15T06:58:34.967Z'
+ created_at: '2026-08-14T13:22:57.052Z'
+ updated_at: '2026-08-14T13:22:57.052Z'
meta:
page: 1
limit: 25
@@ -10587,8 +10652,8 @@ paths:
amount: "-2.0"
display_amount: "-$2.00"
metadata: {}
- created_at: '2026-08-15T06:58:35.091Z'
- updated_at: '2026-08-15T06:58:35.091Z'
+ created_at: '2026-08-14T13:22:57.178Z'
+ updated_at: '2026-08-14T13:22:57.178Z'
meta:
page: 1
limit: 25
@@ -10668,8 +10733,8 @@ paths:
amount: "-3.0"
display_amount: "-$3.00"
metadata: {}
- created_at: '2026-08-15T06:58:35.243Z'
- updated_at: '2026-08-15T06:58:35.243Z'
+ created_at: '2026-08-14T13:22:57.302Z'
+ updated_at: '2026-08-14T13:22:57.302Z'
'422':
description: invalid discount
content:
@@ -10766,8 +10831,8 @@ paths:
amount: '4.0'
display_amount: "$4.00"
metadata: {}
- created_at: '2026-08-15T06:58:35.503Z'
- updated_at: '2026-08-15T06:58:35.503Z'
+ created_at: '2026-08-14T13:22:57.621Z'
+ updated_at: '2026-08-14T13:22:57.621Z'
'422':
description: invalid fee
content:
@@ -10799,6 +10864,7 @@ paths:
- gift_wrap
- cod
- payment
+ - duty
example: gift_wrap
description: Defaults to 'surcharge'
line_item_id:
@@ -10864,7 +10930,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: EB72080196E6198E
+ code: 01E8086A850C3F0E
status: active
currency: USD
amount: '10.0'
@@ -10878,8 +10944,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-15T06:58:38.162Z'
- updated_at: '2026-08-15T06:58:38.197Z'
+ created_at: '2026-08-14T13:22:59.953Z'
+ updated_at: '2026-08-14T13:22:59.982Z'
customer_id:
created_by_id:
requestBody:
@@ -11020,8 +11086,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 319055
- slug: product-319055
+ name: Product 311668
+ slug: product-311668
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -11053,12 +11119,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:38.403Z'
- updated_at: '2026-08-15T06:58:38.403Z'
+ created_at: '2026-08-14T13:23:00.162Z'
+ updated_at: '2026-08-14T13:23:00.162Z'
digital_links: []
metadata: {}
- created_at: '2026-08-15T06:58:38.431Z'
- updated_at: '2026-08-15T06:58:38.431Z'
+ created_at: '2026-08-14T13:23:00.204Z'
+ updated_at: '2026-08-14T13:23:00.204Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -11130,8 +11196,8 @@ paths:
preorder_ships_at:
quantity: 3
currency: USD
- name: Product 339322
- slug: product-339322
+ name: Product 337252
+ slug: product-337252
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -11163,12 +11229,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:38.584Z'
- updated_at: '2026-08-15T06:58:38.584Z'
+ created_at: '2026-08-14T13:23:00.352Z'
+ updated_at: '2026-08-14T13:23:00.352Z'
digital_links: []
metadata: {}
- created_at: '2026-08-15T06:58:38.610Z'
- updated_at: '2026-08-15T06:58:38.610Z'
+ created_at: '2026-08-14T13:23:00.375Z'
+ updated_at: '2026-08-14T13:23:00.375Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -11262,8 +11328,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 349097
- slug: product-349097
+ name: Product 345801
+ slug: product-345801
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -11295,12 +11361,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:38.707Z'
- updated_at: '2026-08-15T06:58:38.707Z'
+ created_at: '2026-08-14T13:23:00.450Z'
+ updated_at: '2026-08-14T13:23:00.450Z'
digital_links: []
metadata: {}
- created_at: '2026-08-15T06:58:38.738Z'
- updated_at: '2026-08-15T06:58:38.738Z'
+ created_at: '2026-08-14T13:23:00.479Z'
+ updated_at: '2026-08-14T13:23:00.479Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -11367,8 +11433,8 @@ paths:
preorder_ships_at:
quantity: 5
currency: USD
- name: Product 357145
- slug: product-357145
+ name: Product 352815
+ slug: product-352815
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -11400,12 +11466,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:38.816Z'
- updated_at: '2026-08-15T06:58:38.816Z'
+ created_at: '2026-08-14T13:23:00.541Z'
+ updated_at: '2026-08-14T13:23:00.541Z'
digital_links: []
metadata: {}
- created_at: '2026-08-15T06:58:38.845Z'
- updated_at: '2026-08-15T06:58:38.881Z'
+ created_at: '2026-08-14T13:23:00.568Z'
+ updated_at: '2026-08-14T13:23:00.593Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -11527,7 +11593,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -11556,24 +11622,25 @@ paths:
display_amount_due: "$60.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '50.0'
display_store_credit_total: "-$50.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11584,11 +11651,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:40.331Z'
- updated_at: '2026-08-15T06:58:40.401Z'
+ created_at: '2026-08-14T13:23:02.026Z'
+ updated_at: '2026-08-14T13:23:02.077Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -11767,7 +11832,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -11796,24 +11861,25 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total:
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11824,11 +11890,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:40.723Z'
- updated_at: '2026-08-15T06:58:40.723Z'
+ created_at: '2026-08-14T13:23:02.269Z'
+ updated_at: '2026-08-14T13:23:02.269Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -11916,8 +11980,8 @@ paths:
address2: 'Floor 42',
city: 'New York',
postal_code: '10118',
- country_code: 'US',
- state_code: 'NY',
+ country_iso: 'US',
+ state_abbr: 'NY',
phone: '+1 212 555 1234',
company: 'Acme Inc.',
},
@@ -11929,8 +11993,8 @@ paths:
address1: '350 Fifth Avenue',
city: 'New York',
postal_code: '10118',
- country_code: 'US',
- state_code: 'NY',
+ country_iso: 'US',
+ state_abbr: 'NY',
phone: '+1 212 555 1234',
},
// billing_address_id: 'addr_UkLWZg9DAJ',
@@ -11943,9 +12007,9 @@ paths:
source: spree api post /orders -d '{"email":"[email protected]","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please
leave at the front desk.","internal_note":"<p>VIP customer — handle with
care.</p>","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350
- Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
+ Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1
212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350
- Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
+ Fifth Avenue","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1
212 555 1234"},"coupon_code":"WELCOME10"}'
description: |-
Creates a new draft order in one shot. Customer, items, addresses, currency,
@@ -12013,24 +12077,25 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: draft
last_ip_address:
considered_risky: false
@@ -12041,11 +12106,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:40.868Z'
- updated_at: '2026-08-15T06:58:40.872Z'
+ created_at: '2026-08-14T13:23:02.411Z'
+ updated_at: '2026-08-14T13:23:02.421Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -12110,9 +12173,9 @@ paths:
type: string
postal_code:
type: string
- country_code:
+ country_iso:
type: string
- state_code:
+ state_abbr:
type: string
phone:
type: string
@@ -12132,9 +12195,9 @@ paths:
type: string
postal_code:
type: string
- country_code:
+ country_iso:
type: string
- state_code:
+ state_abbr:
type: string
phone:
type: string
@@ -12234,7 +12297,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -12263,24 +12326,25 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total:
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: draft
last_ip_address:
considered_risky: false
@@ -12291,11 +12355,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:40.899Z'
- updated_at: '2026-08-15T06:58:40.899Z'
+ created_at: '2026-08-14T13:23:02.451Z'
+ updated_at: '2026-08-14T13:23:02.451Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -12401,24 +12463,25 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: draft
last_ip_address:
considered_risky: false
@@ -12429,11 +12492,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:40.977Z'
- updated_at: '2026-08-15T06:58:41.001Z'
+ created_at: '2026-08-14T13:23:02.541Z'
+ updated_at: '2026-08-14T13:23:02.563Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -12474,9 +12535,9 @@ paths:
type: string
zipcode:
type: string
- country_code:
+ country_iso:
type: string
- state_code:
+ state_abbr:
type: string
phone:
type: string
@@ -12493,9 +12554,9 @@ paths:
type: string
zipcode:
type: string
- country_code:
+ country_iso:
type: string
- state_code:
+ state_abbr:
type: string
phone:
type: string
@@ -12622,7 +12683,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -12630,7 +12691,7 @@ paths:
coupon_code:
fulfillment_status: unfulfilled
payment_status: paid
- completed_at: '2026-08-15T06:58:41.164Z'
+ completed_at: '2026-08-14T13:23:02.715Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12651,24 +12712,25 @@ paths:
display_amount_due: "$0.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: placed
last_ip_address:
considered_risky: false
@@ -12679,11 +12741,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:41.101Z'
- updated_at: '2026-08-15T06:58:41.190Z'
+ created_at: '2026-08-14T13:23:02.651Z'
+ updated_at: '2026-08-14T13:23:02.754Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -12772,7 +12832,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -12780,7 +12840,7 @@ paths:
coupon_code:
fulfillment_status: canceled
payment_status: none
- completed_at: '2026-08-15T06:58:41.414Z'
+ completed_at: '2026-08-14T13:23:03.032Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12801,24 +12861,25 @@ paths:
display_amount_due: "$0.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: canceled
last_ip_address:
considered_risky: false
@@ -12827,13 +12888,11 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-15T06:58:41.446Z'
+ canceled_at: '2026-08-14T13:23:03.059Z'
approved_at:
- created_at: '2026-08-15T06:58:41.351Z'
- updated_at: '2026-08-15T06:58:41.466Z'
+ created_at: '2026-08-14T13:23:02.982Z'
+ updated_at: '2026-08-14T13:23:03.079Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -12906,7 +12965,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -12914,7 +12973,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-15T06:58:41.590Z'
+ completed_at: '2026-08-14T13:23:03.180Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12935,24 +12994,25 @@ paths:
display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: placed
last_ip_address:
considered_risky: false
@@ -12962,12 +13022,10 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-08-15T06:58:41.622Z'
- created_at: '2026-08-15T06:58:41.531Z'
- updated_at: '2026-08-15T06:58:41.589Z'
+ approved_at: '2026-08-14T13:23:03.209Z'
+ created_at: '2026-08-14T13:23:03.131Z'
+ updated_at: '2026-08-14T13:23:03.180Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -13031,7 +13089,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -13039,7 +13097,7 @@ paths:
coupon_code:
fulfillment_status: unfulfilled
payment_status: none
- completed_at: '2026-08-15T06:58:41.721Z'
+ completed_at: '2026-08-14T13:23:03.308Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -13060,24 +13118,25 @@ paths:
display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: placed
last_ip_address:
considered_risky: false
@@ -13086,13 +13145,11 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-15T06:58:41.747Z'
+ canceled_at: '2026-08-14T13:23:03.332Z'
approved_at:
- created_at: '2026-08-15T06:58:41.663Z'
- updated_at: '2026-08-15T06:58:41.795Z'
+ created_at: '2026-08-14T13:23:03.246Z'
+ updated_at: '2026-08-14T13:23:03.382Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -13156,7 +13213,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -13164,7 +13221,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-15T06:58:41.897Z'
+ completed_at: '2026-08-14T13:23:03.468Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -13185,24 +13242,25 @@ paths:
display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
- tax_provider:
- created_at: '2026-08-15T06:58:28.077Z'
- updated_at: '2026-08-15T06:58:28.077Z'
+ created_at: '2026-08-14T13:22:51.542Z'
+ updated_at: '2026-08-14T13:22:51.542Z'
status: placed
last_ip_address:
considered_risky: false
@@ -13213,11 +13271,9 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-15T06:58:41.832Z'
- updated_at: '2026-08-15T06:58:41.897Z'
+ created_at: '2026-08-14T13:23:03.419Z'
+ updated_at: '2026-08-14T13:23:03.467Z'
preferred_stock_location_id:
- company_location_id:
- company_id:
tags: []
internal_note:
internal_note_html:
@@ -13297,8 +13353,8 @@ paths:
resolved_capture_method: checkout
storefront_visible: true
position: 1
- created_at: '2026-08-15T06:58:42.012Z'
- updated_at: '2026-08-15T06:58:42.012Z'
+ created_at: '2026-08-14T13:23:03.565Z'
+ updated_at: '2026-08-14T13:23:03.565Z'
preferences: {}
preference_schema: []
meta:
@@ -13446,8 +13502,8 @@ paths:
resolved_capture_method: checkout
storefront_visible: true
position: 1
- created_at: '2026-08-15T06:58:42.067Z'
- updated_at: '2026-08-15T06:58:42.067Z'
+ created_at: '2026-08-14T13:23:03.612Z'
+ updated_at: '2026-08-14T13:23:03.612Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -13518,7 +13574,7 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-662650d8fd89
+ response_code: BGS-2976f87fae70
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -13537,14 +13593,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-15T06:58:39.104Z'
- updated_at: '2026-08-15T06:58:39.107Z'
+ created_at: '2026-08-14T13:23:00.811Z'
+ updated_at: '2026-08-14T13:23:00.814Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-15T06:58:39.105Z'
- updated_at: '2026-08-15T06:58:39.105Z'
+ created_at: '2026-08-14T13:23:00.812Z'
+ updated_at: '2026-08-14T13:23:00.812Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -13625,8 +13681,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-15T06:58:39.383Z'
- updated_at: '2026-08-15T06:58:39.383Z'
+ created_at: '2026-08-14T13:23:01.180Z'
+ updated_at: '2026-08-14T13:23:01.180Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -13719,7 +13775,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-e9f5b3e49ece
+ response_code: BGS-50b5b736692a
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -13738,14 +13794,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-15T06:58:39.496Z'
- updated_at: '2026-08-15T06:58:39.499Z'
+ created_at: '2026-08-14T13:23:01.288Z'
+ updated_at: '2026-08-14T13:23:01.290Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-15T06:58:39.498Z'
- updated_at: '2026-08-15T06:58:39.498Z'
+ created_at: '2026-08-14T13:23:01.290Z'
+ updated_at: '2026-08-14T13:23:01.290Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -13808,7 +13864,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-7a39f82da69c
+ response_code: BGS-54266d817232
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -13827,14 +13883,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-15T06:58:39.639Z'
- updated_at: '2026-08-15T06:58:39.642Z'
+ created_at: '2026-08-14T13:23:01.413Z'
+ updated_at: '2026-08-14T13:23:01.415Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-15T06:58:39.640Z'
- updated_at: '2026-08-15T06:58:39.675Z'
+ created_at: '2026-08-14T13:23:01.414Z'
+ updated_at: '2026-08-14T13:23:01.442Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -13906,7 +13962,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-56cea42c3ebd
+ response_code: void-BGS-c2af1d7367e0
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -13925,14 +13981,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-15T06:58:39.955Z'
- updated_at: '2026-08-15T06:58:39.958Z'
+ created_at: '2026-08-14T13:23:01.701Z'
+ updated_at: '2026-08-14T13:23:01.703Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-15T06:58:39.956Z'
- updated_at: '2026-08-15T06:58:39.979Z'
+ created_at: '2026-08-14T13:23:01.702Z'
+ updated_at: '2026-08-14T13:23:01.725Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -14020,8 +14076,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.117Z'
- updated_at: '2026-08-15T06:58:42.117Z'
+ created_at: '2026-08-14T13:23:03.660Z'
+ updated_at: '2026-08-14T13:23:03.660Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14035,8 +14091,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.118Z'
- updated_at: '2026-08-15T06:58:42.118Z'
+ created_at: '2026-08-14T13:23:03.662Z'
+ updated_at: '2026-08-14T13:23:03.662Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14150,8 +14206,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.354Z'
- updated_at: '2026-08-15T06:58:42.356Z'
+ created_at: '2026-08-14T13:23:03.852Z'
+ updated_at: '2026-08-14T13:23:03.854Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -14314,8 +14370,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.398Z'
- updated_at: '2026-08-15T06:58:42.398Z'
+ created_at: '2026-08-14T13:23:03.889Z'
+ updated_at: '2026-08-14T13:23:03.889Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14390,8 +14446,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.691Z'
- updated_at: '2026-08-15T06:58:42.708Z'
+ created_at: '2026-08-14T13:23:04.151Z'
+ updated_at: '2026-08-14T13:23:04.165Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14579,8 +14635,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.752Z'
- updated_at: '2026-08-15T06:58:42.775Z'
+ created_at: '2026-08-14T13:23:04.199Z'
+ updated_at: '2026-08-14T13:23:04.214Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -14643,8 +14699,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-15T06:58:42.788Z'
- updated_at: '2026-08-15T06:58:42.805Z'
+ created_at: '2026-08-14T13:23:04.224Z'
+ updated_at: '2026-08-14T13:23:04.241Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14758,8 +14814,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:42.847Z'
- updated_at: '2026-08-15T06:58:42.847Z'
+ created_at: '2026-08-14T13:23:04.284Z'
+ updated_at: '2026-08-14T13:23:04.284Z'
- id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
@@ -14770,8 +14826,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-15T06:58:42.876Z'
- updated_at: '2026-08-15T06:58:42.876Z'
+ created_at: '2026-08-14T13:23:04.308Z'
+ updated_at: '2026-08-14T13:23:04.308Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -14782,8 +14838,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-15T06:58:42.880Z'
- updated_at: '2026-08-15T06:58:42.880Z'
+ created_at: '2026-08-14T13:23:04.312Z'
+ updated_at: '2026-08-14T13:23:04.312Z'
meta:
page: 1
limit: 25
@@ -14865,8 +14921,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-08-15T06:58:43.052Z'
- updated_at: '2026-08-15T06:58:43.052Z'
+ created_at: '2026-08-14T13:23:04.443Z'
+ updated_at: '2026-08-14T13:23:04.443Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -14953,8 +15009,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-15T06:58:43.147Z'
- updated_at: '2026-08-15T06:58:43.147Z'
+ created_at: '2026-08-14T13:23:04.511Z'
+ updated_at: '2026-08-14T13:23:04.511Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -15019,8 +15075,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-15T06:58:43.329Z'
- updated_at: '2026-08-15T06:58:43.346Z'
+ created_at: '2026-08-14T13:23:04.662Z'
+ updated_at: '2026-08-14T13:23:04.679Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -15332,8 +15388,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-15T06:58:44.000Z'
- updated_at: '2026-08-15T06:58:44.000Z'
+ created_at: '2026-08-14T13:23:05.257Z'
+ updated_at: '2026-08-14T13:23:05.257Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -15403,8 +15459,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-08-15T06:58:44.083Z'
- updated_at: '2026-08-15T06:58:44.083Z'
+ created_at: '2026-08-14T13:23:05.333Z'
+ updated_at: '2026-08-14T13:23:05.333Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -15503,8 +15559,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-15T06:58:44.206Z'
- updated_at: '2026-08-15T06:58:44.206Z'
+ created_at: '2026-08-14T13:23:05.432Z'
+ updated_at: '2026-08-14T13:23:05.432Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -15568,8 +15624,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-08-15T06:58:44.269Z'
- updated_at: '2026-08-15T06:58:44.286Z'
+ created_at: '2026-08-14T13:23:05.484Z'
+ updated_at: '2026-08-14T13:23:05.500Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -15688,10 +15744,10 @@ paths:
- key: description
type: html
source: |-
- In modi adipisci aspernatur assumenda commodi. Sequi molestias voluptatum at dolorem fuga quia. Animi iusto quisquam itaque eaque quas. Consequatur iste consequuntur explicabo hic perspiciatis commodi dolores.
- Nobis tempora atque adipisci natus. Sapiente perferendis optio laborum eaque nam possimus cumque. Incidunt qui assumenda dicta voluptate modi. Suscipit cum dicta ex eaque quod. Iusto laboriosam impedit odit culpa nostrum atque.
- Architecto molestias animi itaque exercitationem. Quasi ab laborum possimus dolorem accusamus. Mollitia explicabo repudiandae minus molestias. Atque aliquam saepe eligendi cum. A laboriosam unde esse minus magni adipisci.
- Eius deleniti illo facilis sed soluta libero. Cumque architecto provident ab veniam. Atque nihil possimus optio doloremque distinctio.
+ Eos beatae consequatur quibusdam minima quam. Est eveniet quaerat molestiae ea. Enim culpa facere alias quaerat. Nemo quis assumenda quam iste quibusdam sunt saepe. Voluptatibus facilis illo quam fugiat id voluptates dignissimos.
+ Illo ipsa impedit autem error debitis. Tempora ipsa aspernatur excepturi inventore neque magnam quia. Sed atque tempora eaque et rerum deleniti. Non rerum dignissimos quod quam eius.
+ Ut eaque reiciendis deserunt laborum inventore perferendis modi. Fugiat praesentium tempore distinctio illo deleniti ab corporis. Maxime possimus dolores tempore atque laborum. Labore architecto laborum illum est adipisci sapiente.
+ Eveniet odit reprehenderit quo eligendi laborum aperiam sequi. Iure voluptatem eaque accusantium expedita ducimus asperiores sunt. Minus omnis atque eius assumenda. Minima quod quos placeat similique doloremque.
- key: slug
type: string
source: espresso-machine
@@ -15802,8 +15858,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 768575
- slug: product-768575
+ name: Product 763867
+ slug: product-763867
meta_title:
meta_description:
meta_keywords:
@@ -15815,16 +15871,24 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Cupiditate fugit nobis saepe non a. Vel quia ratione
- dignissimos sapiente magni fugit perferendis. Sapiente magnam
- nisi ullam consequuntur. Ut incidunt ab laboriosam omnis esse
- dolor. Maiores beatae ad consequuntur consectetur quia molestiae
- sunt. Ab adipisci magni repudiandae quibusdam numquam ratione.
- Laudantium sit dolorem officia vero. Dolorem possimus perferendis
- sunt vitae consectetur ab.
+ description: Asperiores repellendus minima aliquid in eligendi incidunt
+ facilis. Numquam exercitationem consequuntur saepe dolor vel vitae
+ eos in. Officia earum quia explicabo ad aut. Error eius odit eum
+ molestiae quisquam ut tempora. Maiores fugit reiciendis error
+ distinctio vitae. Voluptatum magni ducimus voluptatem ipsum perspiciatis
+ ipsa. Cum mollitia sit quis optio odio eveniet exercitationem.
+ Molestiae autem alias quibusdam doloribus sint dignissimos. Dolores
+ nisi esse porro aut iste qui adipisci nulla. Necessitatibus nemo
+ perferendis quaerat ea animi optio rem. Atque perferendis ea soluta
+ fugit est ullam magnam. Quidem facilis enim possimus blanditiis
+ architecto neque. Quis provident voluptate id explicabo reprehenderit
+ eveniet. In laborum dolorem facere assumenda voluptatem inventore
+ consectetur. Repudiandae tempora eius eaque ad excepturi.
description_html: |-
- Cupiditate fugit nobis saepe non a. Vel quia ratione dignissimos sapiente magni fugit perferendis. Sapiente magnam nisi ullam consequuntur. Ut incidunt ab laboriosam omnis esse dolor.
- Maiores beatae ad consequuntur consectetur quia molestiae sunt. Ab adipisci magni repudiandae quibusdam numquam ratione. Laudantium sit dolorem officia vero. Dolorem possimus perferendis sunt vitae consectetur ab.
+ Asperiores repellendus minima aliquid in eligendi incidunt facilis. Numquam exercitationem consequuntur saepe dolor vel vitae eos in. Officia earum quia explicabo ad aut. Error eius odit eum molestiae quisquam ut tempora.
+ Maiores fugit reiciendis error distinctio vitae. Voluptatum magni ducimus voluptatem ipsum perspiciatis ipsa. Cum mollitia sit quis optio odio eveniet exercitationem.
+ Molestiae autem alias quibusdam doloribus sint dignissimos. Dolores nisi esse porro aut iste qui adipisci nulla. Necessitatibus nemo perferendis quaerat ea animi optio rem.
+ Atque perferendis ea soluta fugit est ullam magnam. Quidem facilis enim possimus blanditiis architecto neque. Quis provident voluptate id explicabo reprehenderit eveniet. In laborum dolorem facere assumenda voluptatem inventore consectetur. Repudiandae tempora eius eaque ad excepturi.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -15839,14 +15903,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:44.577Z'
- updated_at: '2026-08-15T06:58:44.577Z'
+ created_at: '2026-08-14T13:23:05.665Z'
+ updated_at: '2026-08-14T13:23:05.665Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-15T06:58:44.564Z'
- updated_at: '2026-08-15T06:58:44.585Z'
+ created_at: '2026-08-14T13:23:05.654Z'
+ updated_at: '2026-08-14T13:23:05.673Z'
delivery_profile_id: fp_UkLWZg9DAJ
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
@@ -15984,8 +16048,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-08-15T06:58:44.730Z'
- updated_at: '2026-08-15T06:58:44.736Z'
+ created_at: '2026-08-14T13:23:05.911Z'
+ updated_at: '2026-08-14T13:23:05.916Z'
delivery_profile_id: fp_UkLWZg9DAJ
product_type_id:
tax_category_id:
@@ -16192,8 +16256,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 80456
- slug: product-80456
+ name: Product 807256
+ slug: product-807256
meta_title:
meta_description:
meta_keywords:
@@ -16205,15 +16269,28 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Cum quod porro numquam reprehenderit. Magni aut quos
- ea eum deleniti voluptas culpa. Sint asperiores eum aliquid cupiditate
- tenetur impedit. Veritatis blanditiis modi itaque ut voluptatibus
- totam voluptate ex. Quas similique ullam natus incidunt eos asperiores.
- Tempore expedita at quidem libero rem. Eius quod reprehenderit sapiente
- ducimus soluta illum repudiandae explicabo.
+ description: Unde porro distinctio ad animi minus. Eum ratione numquam
+ quos perferendis. Hic delectus quisquam error tempore porro repudiandae
+ magni consectetur. Officia fugiat eaque aut nobis illum dolorem
+ iure quidem. Ducimus odio blanditiis voluptatem libero doloremque.
+ Quibusdam possimus voluptatum veniam reprehenderit beatae delectus
+ sequi nesciunt. Molestias fugit nemo ipsum exercitationem excepturi
+ doloremque possimus. Doloribus aut repudiandae tenetur laboriosam
+ saepe pariatur aperiam libero. Dolorem vitae hic veniam odio voluptatem
+ dolor. Voluptas facilis reprehenderit quidem dolorem ex alias earum
+ iure. Eveniet praesentium ducimus sunt omnis quidem ad esse. Neque
+ dolores ab odio nam quisquam sapiente. Dolor esse distinctio corporis
+ dolores dicta suscipit eligendi voluptatem. Rerum tempore rem excepturi
+ ipsum. Illo assumenda vero ab dolorem error quia iure neque. Illum
+ laudantium est ea vel unde assumenda ipsum. Aliquid amet ducimus
+ ipsa maiores assumenda hic. Earum nemo explicabo impedit vero. Ex
+ quisquam consectetur dolor impedit. Fuga laudantium temporibus quidem
+ sint voluptate eveniet corrupti consequatur.
description_html: |-
- Cum quod porro numquam reprehenderit. Magni aut quos ea eum deleniti voluptas culpa. Sint asperiores eum aliquid cupiditate tenetur impedit. Veritatis blanditiis modi itaque ut voluptatibus totam voluptate ex.
- Quas similique ullam natus incidunt eos asperiores. Tempore expedita at quidem libero rem. Eius quod reprehenderit sapiente ducimus soluta illum repudiandae explicabo.
+ Unde porro distinctio ad animi minus. Eum ratione numquam quos perferendis. Hic delectus quisquam error tempore porro repudiandae magni consectetur. Officia fugiat eaque aut nobis illum dolorem iure quidem. Ducimus odio blanditiis voluptatem libero doloremque.
+ Quibusdam possimus voluptatum veniam reprehenderit beatae delectus sequi nesciunt. Molestias fugit nemo ipsum exercitationem excepturi doloremque possimus. Doloribus aut repudiandae tenetur laboriosam saepe pariatur aperiam libero. Dolorem vitae hic veniam odio voluptatem dolor. Voluptas facilis reprehenderit quidem dolorem ex alias earum iure.
+ Eveniet praesentium ducimus sunt omnis quidem ad esse. Neque dolores ab odio nam quisquam sapiente. Dolor esse distinctio corporis dolores dicta suscipit eligendi voluptatem. Rerum tempore rem excepturi ipsum. Illo assumenda vero ab dolorem error quia iure neque.
+ Illum laudantium est ea vel unde assumenda ipsum. Aliquid amet ducimus ipsa maiores assumenda hic. Earum nemo explicabo impedit vero. Ex quisquam consectetur dolor impedit. Fuga laudantium temporibus quidem sint voluptate eveniet corrupti consequatur.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -16228,14 +16305,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:44.841Z'
- updated_at: '2026-08-15T06:58:44.841Z'
+ created_at: '2026-08-14T13:23:06.016Z'
+ updated_at: '2026-08-14T13:23:06.016Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-15T06:58:44.832Z'
- updated_at: '2026-08-15T06:58:44.849Z'
+ created_at: '2026-08-14T13:23:06.007Z'
+ updated_at: '2026-08-14T13:23:06.023Z'
delivery_profile_id: fp_UkLWZg9DAJ
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
@@ -16307,7 +16384,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-824503
+ slug: product-827573
meta_title:
meta_description:
meta_keywords:
@@ -16319,21 +16396,28 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Cumque commodi qui veniam assumenda voluptate facere
- odit. Numquam maxime explicabo ipsa aliquam minus dolor voluptatum.
- Harum totam debitis temporibus ad ratione reiciendis esse nisi.
- Natus tempore neque similique nulla error in. Dolorem veniam animi
- fugiat suscipit aperiam. Fugit qui dolor aut animi consectetur ab.
- Quas assumenda adipisci corporis ut temporibus. Ipsam tenetur quo
- id mollitia asperiores velit harum voluptatem. Fuga nisi ab minima
- quisquam laboriosam at. Odio eum voluptates a repellendus beatae
- accusantium suscipit. Officiis hic sunt quae voluptatem velit nobis.
- Itaque repellendus error magnam ipsa deleniti. Laborum iste possimus
- ratione illo quia. Dolores culpa ipsa vitae asperiores.
+ description: Delectus suscipit hic dolorum eum. Odit ullam exercitationem
+ nam beatae officiis. Officia aliquam cumque dolores asperiores exercitationem
+ animi consequuntur. In autem consequatur harum provident. Laudantium
+ porro est consequatur omnis. Ipsa a provident accusantium nostrum.
+ Mollitia nam quam itaque porro ea recusandae neque nesciunt. Exercitationem
+ nostrum minus qui hic quaerat quibusdam aspernatur. Occaecati praesentium
+ neque rem quidem natus suscipit qui commodi. Corrupti dicta aspernatur
+ nobis ipsam. Amet reiciendis praesentium voluptatem optio quos eligendi
+ non ipsa. Dicta corporis maiores enim sed sunt deserunt laboriosam.
+ Odit dolores in inventore similique. Amet aut quas quaerat laudantium
+ molestiae nesciunt repellendus. Recusandae animi officia aspernatur
+ labore quos fugit. Sint tenetur nesciunt repudiandae cupiditate
+ at animi. Facilis maxime eaque velit ipsum molestias tenetur alias
+ eveniet. Quas optio praesentium molestiae dolorem fuga eaque dolores
+ perspiciatis. Provident debitis nulla inventore porro. Iusto sed
+ nisi dolor error veritatis.
description_html: |-
- Cumque commodi qui veniam assumenda voluptate facere odit. Numquam maxime explicabo ipsa aliquam minus dolor voluptatum. Harum totam debitis temporibus ad ratione reiciendis esse nisi. Natus tempore neque similique nulla error in. Dolorem veniam animi fugiat suscipit aperiam.
- Fugit qui dolor aut animi consectetur ab. Quas assumenda adipisci corporis ut temporibus. Ipsam tenetur quo id mollitia asperiores velit harum voluptatem. Fuga nisi ab minima quisquam laboriosam at.
- Odio eum voluptates a repellendus beatae accusantium suscipit. Officiis hic sunt quae voluptatem velit nobis. Itaque repellendus error magnam ipsa deleniti. Laborum iste possimus ratione illo quia. Dolores culpa ipsa vitae asperiores.
+ Delectus suscipit hic dolorum eum. Odit ullam exercitationem nam beatae officiis. Officia aliquam cumque dolores asperiores exercitationem animi consequuntur. In autem consequatur harum provident.
+ Laudantium porro est consequatur omnis. Ipsa a provident accusantium nostrum. Mollitia nam quam itaque porro ea recusandae neque nesciunt.
+ Exercitationem nostrum minus qui hic quaerat quibusdam aspernatur. Occaecati praesentium neque rem quidem natus suscipit qui commodi. Corrupti dicta aspernatur nobis ipsam.
+ Amet reiciendis praesentium voluptatem optio quos eligendi non ipsa. Dicta corporis maiores enim sed sunt deserunt laboriosam. Odit dolores in inventore similique. Amet aut quas quaerat laudantium molestiae nesciunt repellendus. Recusandae animi officia aspernatur labore quos fugit.
+ Sint tenetur nesciunt repudiandae cupiditate at animi. Facilis maxime eaque velit ipsum molestias tenetur alias eveniet. Quas optio praesentium molestiae dolorem fuga eaque dolores perspiciatis. Provident debitis nulla inventore porro. Iusto sed nisi dolor error veritatis.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -16348,14 +16432,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:44.984Z'
- updated_at: '2026-08-15T06:58:44.984Z'
+ created_at: '2026-08-14T13:23:06.129Z'
+ updated_at: '2026-08-14T13:23:06.129Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-15T06:58:44.972Z'
- updated_at: '2026-08-15T06:58:45.019Z'
+ created_at: '2026-08-14T13:23:06.120Z'
+ updated_at: '2026-08-14T13:23:06.156Z'
delivery_profile_id: fp_UkLWZg9DAJ
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
@@ -17300,15 +17384,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-08-15T06:58:31.156Z'
- updated_at: '2026-08-15T06:58:31.156Z'
+ created_at: '2026-08-14T13:22:53.618Z'
+ updated_at: '2026-08-14T13:22:53.618Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-08-15T06:58:31.157Z'
- updated_at: '2026-08-15T06:58:31.157Z'
+ created_at: '2026-08-14T13:22:53.618Z'
+ updated_at: '2026-08-14T13:22:53.618Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -17370,8 +17454,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:46.247Z'
- updated_at: '2026-08-15T06:58:46.247Z'
+ created_at: '2026-08-14T13:23:07.169Z'
+ updated_at: '2026-08-14T13:23:07.169Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -17435,8 +17519,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:46.324Z'
- updated_at: '2026-08-15T06:58:46.324Z'
+ created_at: '2026-08-14T13:23:07.203Z'
+ updated_at: '2026-08-14T13:23:07.203Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -17564,8 +17648,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:46.422Z'
- updated_at: '2026-08-15T06:58:46.422Z'
+ created_at: '2026-08-14T13:23:07.258Z'
+ updated_at: '2026-08-14T13:23:07.258Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -17635,8 +17719,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:46.462Z'
- updated_at: '2026-08-15T06:58:46.462Z'
+ created_at: '2026-08-14T13:23:07.337Z'
+ updated_at: '2026-08-14T13:23:07.337Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -17727,8 +17811,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:46.496Z'
- updated_at: '2026-08-15T06:58:46.512Z'
+ created_at: '2026-08-14T13:23:07.392Z'
+ updated_at: '2026-08-14T13:23:07.424Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -17836,7 +17920,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-15T06:58:46.545Z'
+ starts_at: '2026-08-14T13:23:07.485Z'
expires_at:
usage_limit:
match_policy: all
@@ -17847,8 +17931,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-15T06:58:46.545Z'
- updated_at: '2026-08-15T06:58:46.545Z'
+ created_at: '2026-08-14T13:23:07.485Z'
+ updated_at: '2026-08-14T13:23:07.485Z'
action_ids: []
rule_ids: []
meta:
@@ -17955,7 +18039,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-08-15T06:58:46.668Z'
+ starts_at: '2026-08-14T13:23:07.602Z'
expires_at:
usage_limit:
match_policy: all
@@ -17966,8 +18050,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-15T06:58:46.668Z'
- updated_at: '2026-08-15T06:58:46.688Z'
+ created_at: '2026-08-14T13:23:07.602Z'
+ updated_at: '2026-08-14T13:23:07.619Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -18133,7 +18217,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-15T06:58:46.726Z'
+ starts_at: '2026-08-14T13:23:07.678Z'
expires_at:
usage_limit:
match_policy: all
@@ -18144,8 +18228,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-15T06:58:46.726Z'
- updated_at: '2026-08-15T06:58:46.726Z'
+ created_at: '2026-08-14T13:23:07.679Z'
+ updated_at: '2026-08-14T13:23:07.679Z'
action_ids: []
rule_ids: []
patch:
@@ -18242,7 +18326,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-15T06:58:46.835Z'
+ starts_at: '2026-08-14T13:23:07.767Z'
expires_at:
usage_limit:
match_policy: all
@@ -18253,8 +18337,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-15T06:58:46.835Z'
- updated_at: '2026-08-15T06:58:46.852Z'
+ created_at: '2026-08-14T13:23:07.767Z'
+ updated_at: '2026-08-14T13:23:07.784Z'
action_ids: []
rule_ids: []
requestBody:
@@ -18516,13 +18600,13 @@ paths:
label: Country
description:
preference_schema:
- - key: country_codes
+ - key: country_isos
type: array
default: []
- key: country_id
type: integer
default:
- - key: country_code
+ - key: country_iso
type: string
default:
- type: currency
@@ -18551,9 +18635,6 @@ paths:
label: Item total
description:
preference_schema:
- - key: amount_min
- type: decimal
- default: 100.0
- key: operator_min
type: string
default: ">"
@@ -18563,6 +18644,9 @@ paths:
- key: operator_max
type: string
default: "<"
+ - key: amount_min
+ type: decimal
+ default: 100.0
- type: market
label: Market(s)
description:
@@ -18726,15 +18810,15 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-593f8c773ee8
+ transaction_id: BGS-a73c5719bd3d
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
originator_id:
originator_type:
metadata: {}
- created_at: '2026-08-15T06:58:40.295Z'
- updated_at: '2026-08-15T06:58:40.295Z'
+ created_at: '2026-08-14T13:23:01.987Z'
+ updated_at: '2026-08-14T13:23:01.987Z'
requestBody:
content:
application/json:
@@ -18878,8 +18962,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-15T06:58:47.345Z'
- updated_at: '2026-08-15T06:58:47.345Z'
+ created_at: '2026-08-14T13:23:08.251Z'
+ updated_at: '2026-08-14T13:23:08.251Z'
non_expiring: false
meta:
page: 1
@@ -18973,8 +19057,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-15T06:58:47.378Z'
- updated_at: '2026-08-15T06:58:47.378Z'
+ created_at: '2026-08-14T13:23:08.288Z'
+ updated_at: '2026-08-14T13:23:08.288Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -19068,8 +19152,8 @@ paths:
preferred_order_number_prefix: R
preferred_order_number_suffix: ''
preferred_order_number_sequence_start: 1001
- created_at: '2026-08-15T06:58:28.064Z'
- updated_at: '2026-08-15T06:58:47.432Z'
+ created_at: '2026-08-14T13:22:51.520Z'
+ updated_at: '2026-08-14T13:23:08.339Z'
order_number_sequence_started: false
url: http://www.example.com:3000
api_url: http://www.example.com:3000
@@ -19384,8 +19468,8 @@ paths:
preferred_order_number_prefix: R
preferred_order_number_suffix: ''
preferred_order_number_sequence_start: 1001
- created_at: '2026-08-15T06:58:28.064Z'
- updated_at: '2026-08-15T06:58:47.521Z'
+ created_at: '2026-08-14T13:22:51.520Z'
+ updated_at: '2026-08-14T13:23:08.418Z'
order_number_sequence_started: false
url: http://www.example.com:3000
api_url: http://www.example.com:3000
@@ -19712,24 +19796,16 @@ paths:
code: invalid_taggable_type
message: taggable_type must be one of Spree::Product, Spree::Order,
Spree::Customer
- "/api/v3/admin/tax_rates":
+ "/api/v3/admin/translatable_resources":
get:
- summary: List tax rates
+ summary: List translatable resources
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the store's tax rates. Rates are the entire configuration of
- the built-in tax provider: each pairs a tax category with a jurisdiction
- (a country, optionally narrowed to one state) and a percentage, and
- decides whether the tax is already included in the product price
- (VAT-style) or added on top (US-style).
-
- Markets using an external tax provider ignore these rows — that
- provider carries its own jurisdiction data.
-
+ Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.
**Required scope:** `read_settings` (for API-key authentication).
parameters:
@@ -19741,111 +19817,99 @@ paths:
- 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
+ description: translatable resources found
content:
application/json:
example:
data:
- - id: tax_UkLWZg9DAJ
- name: TaxRate - 563669
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
- created_at: '2026-08-15T06:58:47.622Z'
- updated_at: '2026-08-15T06:58:47.622Z'
- deleted_at:
- amount: '0.19'
- amount_percentage: 19.0
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- 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/TaxRate"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ - resource_type: option_type
+ fields:
+ - key: label
+ type: string
+ readable: true
+ - resource_type: option_value
+ fields:
+ - key: label
+ type: string
+ readable: false
+ - resource_type: product
+ fields:
+ - key: name
+ type: string
+ - key: description
+ type: html
+ - key: slug
+ type: string
+ - key: meta_description
+ type: string
+ - key: meta_title
+ type: string
+ readable: true
+ - resource_type: product_type
+ fields:
+ - key: name
+ type: string
+ readable: false
+ - resource_type: collection
+ fields:
+ - key: name
+ type: string
+ - key: description
+ type: html
+ - key: permalink
+ type: string
+ readable: false
+ - resource_type: category
+ fields:
+ - key: name
+ type: string
+ - key: pretty_name
+ type: string
+ - key: description
+ type: html
+ - key: permalink
+ type: string
+ readable: true
+ - resource_type: store
+ fields:
+ - key: name
+ type: string
+ - key: meta_description
+ type: string
+ - key: meta_keywords
+ type: string
+ - key: seo_title
+ type: string
+ - key: customer_support_email
+ type: string
+ - key: address
+ type: string
+ - key: contact_phone
+ type: string
+ readable: false
+ - resource_type: policy
+ fields:
+ - key: name
+ type: string
+ - key: body
+ type: html
+ readable: false
+ "/api/v3/admin/translations/batch":
post:
- summary: Create a tax rate
+ summary: Batch upsert translations
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a tax rate for the current store. Give either `amount` as a
- decimal (`0.19`) or `amount_percentage` as a percentage (`19`).
-
- Name the jurisdiction with `country_code` (and `state_code` for a
- state-level rate). Omitting the country makes the rate apply everywhere.
-
- Set `included_in_price` for VAT-style pricing, where the rate is backed
- out of the displayed price rather than added to it.
-
+ Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.
- **Required scope:** `write_settings` (for API-key authentication).
+ **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
@@ -19855,93 +19919,111 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
- '201':
- description: tax rate created
- content:
- application/json:
- example:
- id: tax_gbHJdmfrXB
- name: VAT
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
- created_at: '2026-08-15T06:58:47.683Z'
- updated_at: '2026-08-15T06:58:47.683Z'
- deleted_at:
- amount: '0.19'
- amount_percentage: 19.0
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- schema:
- "$ref": "#/components/schemas/TaxRate"
- '422':
- description: validation failed
+ '200':
+ description: translations upserted
content:
application/json:
example:
- error:
- code: validation_error
- message: Tax category can't be blank and Name can't be blank
- details:
- tax_category:
- - can't be blank
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ data:
+ - resource_id: opt_UkLWZg9DAJ
+ resource_type: option_type
+ translations:
+ de:
+ label: Größe
+ translated_field_count: 1
+ fr:
+ label:
+ translated_field_count: 0
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ - resource_id: optval_UkLWZg9DAJ
+ resource_type: option_value
+ translations:
+ de:
+ label: Klein
+ translated_field_count: 1
+ fr:
+ label:
+ translated_field_count: 0
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ '422':
+ description: unsupported locale rolls back the whole batch
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: 'Unsupported locale(s): es'
+ details:
+ translations:
+ '0':
+ - 'Unsupported locale(s): es'
requestBody:
content:
application/json:
schema:
type: object
- 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
+ - 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: Get a tax rate
+ summary: List staff
tags:
- - Settings
+ - Staff
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_settings` (for API-key authentication)."
+ description: |-
+ Returns admin users with at least one role assignment on the current store.
+
+ **Required scope:** `read_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 { data: staff } = await client.adminUsers.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /admin_users
parameters:
- name: x-spree-api-key
in: header
@@ -19951,39 +20033,65 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: tax rate found
+ description: staff found
content:
application/json:
example:
- id: tax_UkLWZg9DAJ
- name: TaxRate - 184154
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
- created_at: '2026-08-15T06:58:47.767Z'
- updated_at: '2026-08-15T06:58:47.767Z'
- deleted_at:
- amount: '0.19'
- amount_percentage: 19.0
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- schema:
- "$ref": "#/components/schemas/TaxRate"
- patch:
- summary: Update a tax rate
+ data:
+ - id: adm_UkLWZg9DAJ
+ first_name: Darrin
+ last_name: DuBuque
+ full_name: Darrin DuBuque
+ selected_locale:
+ created_at: '2026-08-14T13:22:51.640Z'
+ updated_at: '2026-08-14T13:22:51.640Z'
+ avatar_url:
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ stores:
+ - id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ code: spree_1
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/admin/admin_users/{id}":
+ get:
+ summary: Show a staff member
tags:
- - Settings
+ - Staff
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_settings` (for API-key authentication)."
+ description: "**Required scope:** `read_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 staff = await client.adminUsers.get('admin_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /admin_users/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -19993,65 +20101,64 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
schema:
type: string
responses:
'200':
- description: tax rate updated
+ description: staff member found
content:
application/json:
example:
- id: tax_UkLWZg9DAJ
- name: TaxRate - 842363
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
- created_at: '2026-08-15T06:58:47.837Z'
- updated_at: '2026-08-15T06:58:47.867Z'
- deleted_at:
- amount: '0.07'
- amount_percentage: 7.0
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- 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
+ id: adm_UkLWZg9DAJ
+ first_name: Audrey
+ last_name: Grant
+ full_name: Audrey Grant
+ selected_locale:
+ created_at: '2026-08-14T13:22:51.758Z'
+ updated_at: '2026-08-14T13:22:51.758Z'
+ avatar_url:
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ stores:
+ - id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ code: spree_1
+ patch:
+ summary: Update a staff member
tags:
- - Settings
+ - Staff
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.
+ 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.
- **Required scope:** `write_settings` (for API-key authentication).
+ **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 staff = await client.adminUsers.update('admin_xxx', {
+ first_name: 'Ada',
+ role_ids: ['role_xxx']
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /admin_users/{id} -d '{"first_name":"Ada","role_ids":["role_xxx"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -20059,128 +20166,79 @@ paths:
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.
-
- **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
+ - name: id
+ in: path
required: true
schema:
type: string
responses:
'200':
- description: translatable resources found
+ description: staff member updated
content:
application/json:
example:
- data:
- - resource_type: option_type
- fields:
- - key: label
- type: string
- readable: true
- - resource_type: option_value
- fields:
- - key: label
- type: string
- readable: false
- - resource_type: product
- fields:
- - key: name
- type: string
- - key: description
- type: html
- - key: slug
- type: string
- - key: meta_description
- type: string
- - key: meta_title
- type: string
- readable: true
- - resource_type: product_type
- fields:
- - key: name
- type: string
- readable: false
- - resource_type: collection
- fields:
- - key: name
- type: string
- - key: description
- type: html
- - key: permalink
- type: string
- readable: false
- - resource_type: category
- fields:
- - key: name
- type: string
- - key: pretty_name
- type: string
- - key: description
- type: html
- - key: permalink
- type: string
- readable: true
- - resource_type: store
- fields:
- - key: name
- type: string
- - key: meta_description
- type: string
- - key: meta_keywords
- type: string
- - key: seo_title
- type: string
- - key: customer_support_email
- type: string
- - key: address
- type: string
- - key: contact_phone
- type: string
- readable: false
- - resource_type: policy
- fields:
- - key: name
+ id: adm_UkLWZg9DAJ
+ first_name: Renamed
+ last_name: Harber
+ full_name: Renamed Harber
+ selected_locale:
+ created_at: '2026-08-14T13:22:51.777Z'
+ updated_at: '2026-08-14T13:22:51.788Z'
+ avatar_url:
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ stores:
+ - id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ code: spree_1
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ first_name:
+ type: string
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ role_ids:
+ type: array
+ items:
type: string
- - key: body
- type: html
- readable: false
- "/api/v3/admin/translations/batch":
- post:
- summary: Batch upsert translations
+ delete:
+ summary: Remove a staff member from this store
tags:
- - Settings
+ - Staff
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.
+ Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.
- **Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).
+ **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',
+ })
+
+ await client.adminUsers.delete('admin_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /admin_users/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20192,92 +20250,24 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
- '200':
- description: translations upserted
- content:
- application/json:
- example:
- data:
- - resource_id: opt_UkLWZg9DAJ
- resource_type: option_type
- translations:
- de:
- label: Größe
- translated_field_count: 1
- fr:
- label:
- translated_field_count: 0
- default_locale: en
- supported_locales:
- - de
- - en
- - fr
- - resource_id: optval_UkLWZg9DAJ
- resource_type: option_value
- translations:
- de:
- label: Klein
- translated_field_count: 1
- fr:
- label:
- translated_field_count: 0
- default_locale: en
- supported_locales:
- - de
- - en
- - fr
- '422':
- description: unsupported locale rolls back the whole batch
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: 'Unsupported locale(s): es'
- details:
- translations:
- '0':
- - 'Unsupported locale(s): es'
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - translations
- properties:
- translations:
- type: array
- items:
- type: object
- required:
- - resource_type
- - resource_id
- - values
- properties:
- resource_type:
- type: string
- description: Translatable resource type token, e.g. `option_type`
- resource_id:
- type: string
- description: Prefixed id of the record
- values:
- type: object
- description: 'Map of locale code to { field: value }'
- additionalProperties:
- type: object
- additionalProperties: true
- "/api/v3/admin/admin_users":
+ '204':
+ description: staff removed from store
+ "/api/v3/admin/invitations":
get:
- summary: List staff
+ summary: List invitations
tags:
- Staff
security:
- api_key: []
bearer_auth: []
description: |-
- Returns admin users with at least one role assignment on the current store.
+ Returns invitations for the current store, including pending and accepted.
**Required scope:** `read_staff` (for API-key authentication).
x-codeSamples:
@@ -20291,10 +20281,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: staff } = await client.adminUsers.list()
+ const { data: invitations } = await client.invitations.list()
- lang: bash
label: Spree CLI
- source: spree api get /admin_users
+ source: spree api get /invitations
parameters:
- name: x-spree-api-key
in: header
@@ -20308,27 +20298,25 @@ paths:
type: string
responses:
'200':
- description: staff found
+ description: invitations found
content:
application/json:
example:
data:
- - id: adm_UkLWZg9DAJ
- first_name: Alonzo
- last_name: Botsford
- full_name: Alonzo Botsford
- selected_locale:
- created_at: '2026-08-15T06:58:28.183Z'
- updated_at: '2026-08-15T06:58:28.183Z'
- avatar_url:
- roles:
- - id: role_UkLWZg9DAJ
- name: admin
- stores:
- - id: store_UkLWZg9DAJ
+ - id: inv_UkLWZg9DAJ
+ status: pending
+ created_at: '2026-08-14T13:22:56.132Z'
+ updated_at: '2026-08-14T13:22:56.132Z'
+ expires_at: '2026-08-28T13:22:56.129Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=YyR483wGF951zfm2crZASeZo"
+ invitee_exists: false
+ store:
+ id: store_UkLWZg9DAJ
name: Spree Test Store
- code: spree_1
meta:
page: 1
limit: 25
@@ -20339,15 +20327,17 @@ paths:
in: 1
previous:
next:
- "/api/v3/admin/admin_users/{id}":
- get:
- summary: Show a staff member
+ post:
+ summary: Create an invitation
tags:
- Staff
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_staff` (for API-key authentication)."
+ 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.
+
+ **Required scope:** `write_staff` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20359,274 +20349,13 @@ paths:
secretKey: 'sk_xxx',
})
- const staff = await client.adminUsers.get('admin_xxx')
+ const invitation = await client.invitations.create({
+ email: '[email protected]',
+ role_id: 'role_xxx'
+ })
- lang: bash
label: Spree CLI
- source: spree api get /admin_users/{id}
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: staff member found
- content:
- application/json:
- example:
- id: adm_UkLWZg9DAJ
- first_name: Scotty
- last_name: O'Hara
- full_name: Scotty O'Hara
- selected_locale:
- created_at: '2026-08-15T06:58:28.320Z'
- updated_at: '2026-08-15T06:58:28.320Z'
- avatar_url:
- roles:
- - id: role_UkLWZg9DAJ
- name: admin
- stores:
- - id: store_UkLWZg9DAJ
- name: Spree Test Store
- code: spree_1
- 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.
-
- **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 staff = await client.adminUsers.update('admin_xxx', {
- first_name: 'Ada',
- role_ids: ['role_xxx']
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /admin_users/{id} -d '{"first_name":"Ada","role_ids":["role_xxx"]}'
- parameters:
- - name: x-spree-api-key
- in: 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:
- example:
- id: adm_UkLWZg9DAJ
- first_name: Renamed
- last_name: Flatley
- full_name: Renamed Flatley
- selected_locale:
- created_at: '2026-08-15T06:58:28.341Z'
- updated_at: '2026-08-15T06:58:28.354Z'
- avatar_url:
- roles:
- - id: role_UkLWZg9DAJ
- name: admin
- stores:
- - id: store_UkLWZg9DAJ
- name: Spree Test Store
- code: spree_1
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- first_name:
- type: string
- example: Ada
- last_name:
- type: string
- example: Lovelace
- 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.
-
- **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',
- })
-
- await client.adminUsers.delete('admin_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /admin_users/{id}
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- 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.
-
- **Required scope:** `read_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 { data: invitations } = await client.invitations.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /invitations
- parameters:
- - 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:
- example:
- data:
- - id: inv_UkLWZg9DAJ
- status: pending
- created_at: '2026-08-15T06:58:33.962Z'
- updated_at: '2026-08-15T06:58:33.962Z'
- expires_at: '2026-08-29T06:58:33.959Z'
- role_id: role_UkLWZg9DAJ
- role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=5ehVHcJSMcs5RqgksW9WHsvv"
- invitee_exists: false
- store:
- id: store_UkLWZg9DAJ
- name: Spree Test Store
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- 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.
-
- **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 invitation = await client.invitations.create({
- email: '[email protected]',
- role_id: 'role_xxx'
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /invitations -d '{"email":"[email protected]","role_id":"role_xxx"}'
+ source: spree api post /invitations -d '{"email":"[email protected]","role_id":"role_xxx"}'
parameters:
- name: x-spree-api-key
in: header
@@ -20647,13 +20376,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-08-15T06:58:33.995Z'
- updated_at: '2026-08-15T06:58:33.995Z'
- expires_at: '2026-08-29T06:58:33.992Z'
+ created_at: '2026-08-14T13:22:56.165Z'
+ updated_at: '2026-08-14T13:22:56.165Z'
+ expires_at: '2026-08-28T13:22:56.162Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=7628NwuzKVvWy9xdwCarCT6G"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=EwwMhBJ3advYNNz16ULYr2sK"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -20766,15 +20495,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-15T06:58:34.032Z'
- updated_at: '2026-08-15T06:58:34.032Z'
- expires_at: '2026-08-29T06:58:34.030Z'
+ created_at: '2026-08-14T13:22:56.198Z'
+ updated_at: '2026-08-14T13:22:56.198Z'
+ expires_at: '2026-08-28T13:22:56.196Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=CvCpwRYnevBZVwHB9uzz2Ji4"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=2DSaXLaQ6xY6TTFtANMhdUKH"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -21119,8 +20848,8 @@ paths:
- id: role_UkLWZg9DAJ
name: admin
description:
- created_at: '2026-08-15T06:58:46.949Z'
- updated_at: '2026-08-15T06:58:46.949Z'
+ created_at: '2026-08-14T13:23:07.879Z'
+ updated_at: '2026-08-14T13:23:07.879Z'
permissions:
- read_orders
- write_orders
@@ -21220,8 +20949,8 @@ paths:
id: role_gbHJdmfrXB
name: order_manager
description: Handles daily orders
- created_at: '2026-08-15T06:58:46.985Z'
- updated_at: '2026-08-15T06:58:46.985Z'
+ created_at: '2026-08-14T13:23:07.911Z'
+ updated_at: '2026-08-14T13:23:07.911Z'
permissions:
- write_orders
- read_customers
@@ -21315,8 +21044,8 @@ paths:
id: role_gbHJdmfrXB
name: support
description:
- created_at: '2026-08-15T06:58:47.010Z'
- updated_at: '2026-08-15T06:58:47.024Z'
+ created_at: '2026-08-14T13:23:07.935Z'
+ updated_at: '2026-08-14T13:23:07.947Z'
permissions:
- read_orders
- read_customers
@@ -21490,14 +21219,14 @@ paths:
example:
data:
- id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_59
name: Brooklyn warehouse
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_59
pickup_ready_in_minutes:
pickup_instructions:
admin_name:
@@ -21512,8 +21241,8 @@ paths:
kind: warehouse
pickup_enabled: false
pickup_stock_policy: local
- created_at: '2026-08-15T06:58:47.114Z'
- updated_at: '2026-08-15T06:58:47.114Z'
+ created_at: '2026-08-14T13:23:08.030Z'
+ updated_at: '2026-08-14T13:23:08.030Z'
meta:
page: 1
limit: 25
@@ -21575,8 +21304,8 @@ paths:
const stockLocation = await client.stockLocations.create({
name: 'Brooklyn warehouse',
kind: 'warehouse',
- country_code: 'US',
- state_code: 'NY',
+ country_iso: 'US',
+ state_abbr: 'NY',
city: 'Brooklyn',
zipcode: '11201',
pickup_enabled: true,
@@ -21585,7 +21314,7 @@ paths:
})
- lang: bash
label: Spree CLI
- source: spree api post /stock_locations -d '{"name":"Brooklyn warehouse","kind":"warehouse","country_code":"US","state_code":"NY","city":"Brooklyn","zipcode":"11201","pickup_enabled":true,"pickup_stock_policy":"local","pickup_ready_in_minutes":60}'
+ source: spree api post /stock_locations -d '{"name":"Brooklyn warehouse","kind":"warehouse","country_iso":"US","state_abbr":"NY","city":"Brooklyn","zipcode":"11201","pickup_enabled":true,"pickup_stock_policy":"local","pickup_ready_in_minutes":60}'
parameters:
- name: x-spree-api-key
in: header
@@ -21605,13 +21334,13 @@ paths:
application/json:
example:
id: sloc_gbHJdmfrXB
+ state_abbr:
name: Manhattan store
address1:
city:
zipcode:
- country_code:
+ country_iso:
country_name:
- state_code:
state_text:
pickup_ready_in_minutes: 30
pickup_instructions:
@@ -21627,8 +21356,8 @@ paths:
kind: store
pickup_enabled: true
pickup_stock_policy: local
- created_at: '2026-08-15T06:58:47.165Z'
- updated_at: '2026-08-15T06:58:47.165Z'
+ created_at: '2026-08-14T13:23:08.082Z'
+ updated_at: '2026-08-14T13:23:08.082Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -21693,11 +21422,11 @@ paths:
company:
type: string
nullable: true
- country_code:
+ country_iso:
type: string
nullable: true
description: ISO-3166 alpha-2 country code (e.g. "US").
- state_code:
+ state_abbr:
type: string
nullable: true
description: State / province abbreviation (e.g. "NY"). Resolved
@@ -21783,14 +21512,14 @@ paths:
application/json:
example:
id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_63
name: Brooklyn warehouse
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_63
pickup_ready_in_minutes:
pickup_instructions:
admin_name:
@@ -21805,8 +21534,8 @@ paths:
kind: warehouse
pickup_enabled: false
pickup_stock_policy: local
- created_at: '2026-08-15T06:58:47.214Z'
- updated_at: '2026-08-15T06:58:47.214Z'
+ created_at: '2026-08-14T13:23:08.115Z'
+ updated_at: '2026-08-14T13:23:08.115Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -21873,14 +21602,14 @@ paths:
application/json:
example:
id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_65
name: Renamed warehouse
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_65
pickup_ready_in_minutes: 45
pickup_instructions:
admin_name:
@@ -21895,8 +21624,8 @@ paths:
kind: warehouse
pickup_enabled: true
pickup_stock_policy: local
- created_at: '2026-08-15T06:58:47.270Z'
- updated_at: '2026-08-15T06:58:47.287Z'
+ created_at: '2026-08-14T13:23:08.172Z'
+ updated_at: '2026-08-14T13:23:08.190Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -21955,10 +21684,10 @@ paths:
company:
type: string
nullable: true
- country_code:
+ country_iso:
type: string
nullable: true
- state_code:
+ state_abbr:
type: string
nullable: true
state_name:
@@ -22138,15 +21867,18 @@ paths:
weight_unit: lb
dimensions_unit:
backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
deleted_at:
- created_at: '2026-08-15T06:58:48.014Z'
- updated_at: '2026-08-15T06:58:48.024Z'
+ created_at: '2026-08-14T13:23:08.618Z'
+ updated_at: '2026-08-14T13:23:08.629Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1011489
+ product_name: Product 1013945
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
sku: SKU-121
@@ -22159,10 +21891,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 90.34
- height: 27.1
- width: 51.7
- depth: 6.0
+ weight: 23.3
+ height: 16.97
+ width: 5.6
+ depth: 19.82
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -22185,8 +21917,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:48.041Z'
- updated_at: '2026-08-15T06:58:48.041Z'
+ created_at: '2026-08-14T13:23:08.646Z'
+ updated_at: '2026-08-14T13:23:08.646Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -22195,15 +21927,18 @@ paths:
weight_unit: lb
dimensions_unit:
backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
deleted_at:
- created_at: '2026-08-15T06:58:48.038Z'
- updated_at: '2026-08-15T06:58:48.049Z'
+ created_at: '2026-08-14T13:23:08.644Z'
+ updated_at: '2026-08-14T13:23:08.653Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1011489
+ product_name: Product 1013945
meta:
page: 1
limit: 25
@@ -22317,8 +22052,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:48.158Z'
- updated_at: '2026-08-15T06:58:48.158Z'
+ created_at: '2026-08-14T13:23:08.767Z'
+ updated_at: '2026-08-14T13:23:08.767Z'
metadata: {}
position: 3
cost_price:
@@ -22327,15 +22062,18 @@ paths:
weight_unit: lb
dimensions_unit:
backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
deleted_at:
- created_at: '2026-08-15T06:58:48.162Z'
- updated_at: '2026-08-15T06:58:48.164Z'
+ created_at: '2026-08-14T13:23:08.772Z'
+ updated_at: '2026-08-14T13:23:08.774Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1025132
+ product_name: Product 1025259
'422':
description: validation error
content:
@@ -22522,10 +22260,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 2.54
- height: 44.43
- width: 13.0
- depth: 187.15
+ weight: 83.78
+ height: 109.4
+ width: 16.58
+ depth: 186.77
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -22548,8 +22286,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:48.313Z'
- updated_at: '2026-08-15T06:58:48.313Z'
+ created_at: '2026-08-14T13:23:08.920Z'
+ updated_at: '2026-08-14T13:23:08.920Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -22558,15 +22296,18 @@ paths:
weight_unit: lb
dimensions_unit:
backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
deleted_at:
- created_at: '2026-08-15T06:58:48.310Z'
- updated_at: '2026-08-15T06:58:48.321Z'
+ created_at: '2026-08-14T13:23:08.917Z'
+ updated_at: '2026-08-14T13:23:08.927Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1043301
+ product_name: Product 1041255
'404':
description: variant not found
content:
@@ -22650,10 +22391,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 132.31
- height: 176.4
- width: 193.39
- depth: 188.59
+ weight: 100.31
+ height: 42.72
+ width: 45.52
+ depth: 191.49
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -22676,8 +22417,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-15T06:58:48.485Z'
- updated_at: '2026-08-15T06:58:48.485Z'
+ created_at: '2026-08-14T13:23:09.065Z'
+ updated_at: '2026-08-14T13:23:09.065Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -22686,15 +22427,18 @@ paths:
weight_unit: lb
dimensions_unit:
backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
deleted_at:
- created_at: '2026-08-15T06:58:48.482Z'
- updated_at: '2026-08-15T06:58:48.519Z'
+ created_at: '2026-08-14T13:23:09.062Z'
+ updated_at: '2026-08-14T13:23:09.089Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1065267
+ product_name: Product 1063883
requestBody:
content:
application/json:
@@ -22939,9 +22683,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-15T06:58:48.659Z'
- updated_at: '2026-08-15T06:58:48.659Z'
- delivered_at: '2026-08-15T06:58:48.659Z'
+ created_at: '2026-08-14T13:23:09.266Z'
+ updated_at: '2026-08-14T13:23:09.266Z'
+ delivered_at: '2026-08-14T13:23:09.266Z'
payload:
event: order.created
data:
@@ -22957,9 +22701,9 @@ paths:
request_errors:
response_body:
success: true
- created_at: '2026-08-15T06:58:48.659Z'
- updated_at: '2026-08-15T06:58:48.659Z'
- delivered_at: '2026-08-15T06:58:48.658Z'
+ created_at: '2026-08-14T13:23:09.264Z'
+ updated_at: '2026-08-14T13:23:09.264Z'
+ delivered_at: '2026-08-14T13:23:09.264Z'
payload:
event: order.created
data:
@@ -23062,9 +22806,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-15T06:58:48.749Z'
- updated_at: '2026-08-15T06:58:48.749Z'
- delivered_at: '2026-08-15T06:58:48.749Z'
+ created_at: '2026-08-14T13:23:09.414Z'
+ updated_at: '2026-08-14T13:23:09.414Z'
+ delivered_at: '2026-08-14T13:23:09.414Z'
payload:
event: order.created
data:
@@ -23153,8 +22897,8 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-15T06:58:48.852Z'
- updated_at: '2026-08-15T06:58:48.852Z'
+ created_at: '2026-08-14T13:23:09.541Z'
+ updated_at: '2026-08-14T13:23:09.541Z'
delivered_at:
payload:
event: order.created
@@ -23257,8 +23001,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-15T06:58:48.883Z'
- updated_at: '2026-08-15T06:58:48.883Z'
+ created_at: '2026-08-14T13:23:09.570Z'
+ updated_at: '2026-08-14T13:23:09.570Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -23353,10 +23097,10 @@ paths:
subscriptions:
- order.placed
disabled_reason:
- created_at: '2026-08-15T06:58:48.989Z'
- updated_at: '2026-08-15T06:58:48.989Z'
+ created_at: '2026-08-14T13:23:09.780Z'
+ updated_at: '2026-08-14T13:23:09.780Z'
disabled_at:
- secret_key: 6c8d37ccadaa6d2542cb94d6d4cb7980ac575f2b847b69582f402d4787d3f881
+ secret_key: f919f8583dace47124ea01e64e3f717cc25a6018f099ac2302c37c5b100bd867
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -23479,8 +23223,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-15T06:58:49.064Z'
- updated_at: '2026-08-15T06:58:49.064Z'
+ created_at: '2026-08-14T13:23:09.854Z'
+ updated_at: '2026-08-14T13:23:09.854Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -23559,8 +23303,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-15T06:58:49.152Z'
- updated_at: '2026-08-15T06:58:49.169Z'
+ created_at: '2026-08-14T13:23:09.948Z'
+ updated_at: '2026-08-14T13:23:09.961Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -23717,13 +23461,13 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-15T06:58:49.311Z'
- updated_at: '2026-08-15T06:58:49.311Z'
+ created_at: '2026-08-14T13:23:10.106Z'
+ updated_at: '2026-08-14T13:23:10.106Z'
delivered_at:
payload:
- id: e2262ebb-6bf2-4753-b0f9-6f1cf0ffaa80
+ id: 181223b0-c98d-4f4f-853f-2ef4c09abca1
name: webhook.test
- created_at: '2026-08-15T06:58:49Z'
+ created_at: '2026-08-14T13:23:10Z'
data:
message: This is a test webhook from Spree.
metadata:
@@ -23792,8 +23536,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-15T06:58:49.338Z'
- updated_at: '2026-08-15T06:58:49.353Z'
+ created_at: '2026-08-14T13:23:10.134Z'
+ updated_at: '2026-08-14T13:23:10.148Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -23870,9 +23614,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-08-15T06:58:49.395Z'
- updated_at: '2026-08-15T06:58:49.409Z'
- disabled_at: '2026-08-15T06:58:49.409Z'
+ created_at: '2026-08-14T13:23:10.244Z'
+ updated_at: '2026-08-14T13:23:10.260Z'
+ disabled_at: '2026-08-14T13:23:10.260Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
@@ -23955,8 +23699,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-15T06:58:29.868Z'
- updated_at: '2026-08-15T06:58:29.868Z'
+ created_at: '2026-08-14T13:22:53.110Z'
+ updated_at: '2026-08-14T13:22:53.110Z'
meta:
page: 1
limit: 25
@@ -24024,8 +23768,8 @@ paths:
automatic: true
rules_match_policy: any
metadata: {}
- created_at: '2026-08-15T06:58:29.917Z'
- updated_at: '2026-08-15T06:58:29.919Z'
+ created_at: '2026-08-14T13:22:53.166Z'
+ updated_at: '2026-08-14T13:22:53.168Z'
schema:
"$ref": "#/components/schemas/Collection"
'422':
@@ -24152,8 +23896,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-15T06:58:29.978Z'
- updated_at: '2026-08-15T06:58:29.978Z'
+ created_at: '2026-08-14T13:22:53.252Z'
+ updated_at: '2026-08-14T13:22:53.252Z'
schema:
"$ref": "#/components/schemas/Collection"
'404':
@@ -24217,8 +23961,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-15T06:58:30.045Z'
- updated_at: '2026-08-15T06:58:30.062Z'
+ created_at: '2026-08-14T13:22:53.330Z'
+ updated_at: '2026-08-14T13:22:53.348Z'
schema:
"$ref": "#/components/schemas/Collection"
requestBody:
@@ -24291,1341 +24035,25 @@ paths:
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.
-
- **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:
- example:
- data: []
- meta:
- page: 1
- limit: 25
- count: 0
- pages: 1
- from: 0
- to: 0
- in: 0
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- post:
- summary: Add a product to a collection
- tags:
- - Collections
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Curates a product into the collection (appended to the end).
-
- **Required scope:** `write_collections` (for API-key authentication).
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: collection_id
- in: path
- required: true
- description: Collection ID
- schema:
- type: string
- responses:
- '201':
- description: product added
- content:
- application/json:
- example:
- id: prod_UkLWZg9DAJ
- name: Product 65220
- slug: product-65220
- 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: Aspernatur fuga qui quaerat incidunt. Soluta deleniti
- perspiciatis quisquam quidem a est. Voluptatem quibusdam sed culpa
- deserunt a harum. Minus voluptatibus ipsam at itaque expedita. Rerum
- nesciunt adipisci ea non illum corrupti deleniti in. Tempora nisi
- cumque asperiores adipisci veritatis repellendus. Voluptatem velit
- natus non maiores necessitatibus fugiat praesentium cumque. Placeat
- hic repudiandae consectetur suscipit iure. Quia aliquam iusto voluptate
- quos corrupti. Autem exercitationem ratione iusto quos. Ipsam ullam
- asperiores magni et officia. Soluta dolorum inventore provident
- ipsa. Amet nobis harum dolorum sint vitae. Dolorum laborum ad veritatis
- corrupti quo. Hic earum sed reprehenderit at libero et dignissimos.
- Esse maxime tempore dolorem officiis. Adipisci similique aperiam
- quos esse facilis veniam porro in. Nam voluptate iusto expedita
- laboriosam aut consequuntur soluta voluptatem. Perspiciatis tempore
- fugiat veritatis itaque. At amet facilis ullam adipisci. Modi aliquid
- unde exercitationem adipisci illum laboriosam.
- description_html: |-
- Aspernatur fuga qui quaerat incidunt. Soluta deleniti perspiciatis quisquam quidem a est. Voluptatem quibusdam sed culpa deserunt a harum.
- Minus voluptatibus ipsam at itaque expedita. Rerum nesciunt adipisci ea non illum corrupti deleniti in. Tempora nisi cumque asperiores adipisci veritatis repellendus. Voluptatem velit natus non maiores necessitatibus fugiat praesentium cumque. Placeat hic repudiandae consectetur suscipit iure.
- Quia aliquam iusto voluptate quos corrupti. Autem exercitationem ratione iusto quos. Ipsam ullam asperiores magni et officia. Soluta dolorum inventore provident ipsa.
- Amet nobis harum dolorum sint vitae. Dolorum laborum ad veritatis corrupti quo. Hic earum sed reprehenderit at libero et dignissimos. Esse maxime tempore dolorem officiis. Adipisci similique aperiam quos esse facilis veniam porro in.
- Nam voluptate iusto expedita laboriosam aut consequuntur soluta voluptatem. Perspiciatis tempore fugiat veritatis itaque. At amet facilis ullam adipisci. Modi aliquid unde exercitationem adipisci illum laboriosam.
- default_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:
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:30.159Z'
- updated_at: '2026-08-15T06:58:30.159Z'
- original_price:
- status: active
- metadata: {}
- deleted_at:
- created_at: '2026-08-15T06:58:30.147Z'
- updated_at: '2026-08-15T06:58:30.168Z'
- delivery_profile_id: fp_UkLWZg9DAJ
- product_type_id:
- tax_category_id: taxcat_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/Product"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- product_id:
- type: string
- example: prod_abc123
- required:
- - product_id
- "/api/v3/admin/collections/{collection_id}/products/{id}":
- delete:
- summary: Remove a product from a collection
- tags:
- - Collections
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Removes a product from the collection's manual curation.
-
- **Required scope:** `write_collections` (for API-key authentication).
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: collection_id
- in: path
- required: true
- description: Collection ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Product ID
- schema:
- type: string
- responses:
- '204':
- description: product removed
- "/api/v3/admin/collections/{collection_id}/products/{id}/reposition":
- patch:
- summary: Reposition a collection product
- tags:
- - Collections
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Moves a product to a new index among the collection's products.
-
- **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`.
-
- **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:
- example:
- data:
- - type: sale
- label: On sale
- description: Products currently discounted below their compare-at
- price
- preference_schema: []
- - type: available_on
- label: Recently published
- description: Products published within the last N days
- preference_schema: []
- - type: tag
- label: Tag
- description: Products carrying a matching tag
- preference_schema: []
- "/api/v3/admin/companies/{company_id}/locations":
- get:
- summary: List company locations
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Returns the branches of a business customer. Each branch owns its own addresses and the buyers authorised to purchase for it.
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: locations } = await client.companies.locations.list('comp_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /companies/{company_id}/locations
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: company_id
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: locations found
- content:
- application/json:
- example:
- data:
- - id: cloc_UkLWZg9DAJ
- name: Berlin
- external_id:
- metadata: {}
- created_at: '2026-08-15T06:58:30.459Z'
- updated_at: '2026-08-15T06:58:30.459Z'
- company_id: comp_UkLWZg9DAJ
- contacts_count: 0
- billing_address:
- shipping_address:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- post:
- summary: Create a company location
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Creates a branch. Addresses are supplied inline and belong to the branch, so editing one later changes the branch's own record rather than an address the buyer also uses.
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const location = await client.companies.locations.create('comp_UkLWZg9DAJ', {
- name: 'Hamburg warehouse',
- billing_address: {
- first_name: 'Anna',
- last_name: 'Muller',
- address1: 'Hafenstr 1',
- city: 'Hamburg',
- postal_code: '20095',
- country_code: 'DE',
- },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /companies/{company_id}/locations -d '{"name":"Hamburg
- warehouse","billing_address":{"first_name":"Anna","last_name":"Muller","address1":"Hafenstr
- 1","city":"Hamburg","postal_code":"20095","country_code":"DE"}}'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: company_id
- in: path
- required: true
- schema:
- type: string
- responses:
- '201':
- description: location created
- content:
- application/json:
- example:
- id: cloc_gbHJdmfrXB
- name: Hamburg warehouse
- external_id:
- metadata: {}
- created_at: '2026-08-15T06:58:30.507Z'
- updated_at: '2026-08-15T06:58:30.507Z'
- company_id: comp_UkLWZg9DAJ
- contacts_count: 0
- billing_address:
- id: addr_UkLWZg9DAJ
- first_name: Anna
- last_name: Muller
- full_name: Anna Muller
- address1: Hafenstr 1
- address2:
- postal_code: '20095'
- city: Hamburg
- phone:
- company:
- country_name: Germany
- country_code: DE
- state_text:
- state_code:
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr:
- country_iso: DE
- state_name:
- label:
- metadata: {}
- created_at: '2026-08-15T06:58:30.506Z'
- updated_at: '2026-08-15T06:58:30.506Z'
- customer_id:
- shipping_address:
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Hamburg warehouse
- external_id:
- type: string
- nullable: true
- example: HAM-01
- billing_address:
- type: object
- description: Created inline and owned by the branch.
- properties:
- first_name:
- type: string
- last_name:
- type: string
- address1:
- type: string
- city:
- type: string
- postal_code:
- type: string
- country_code:
- type: string
- example: DE
- required:
- - name
- "/api/v3/admin/company_locations/{id}":
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- get:
- summary: Get a company location
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Branches are addressed by their own id once you hold one — the company id is not needed.
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const location = await client.companyLocations.get('cloc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /company_locations/{id}
- responses:
- '200':
- description: location found
- content:
- application/json:
- example:
- id: cloc_UkLWZg9DAJ
- name: Berlin
- external_id:
- metadata: {}
- created_at: '2026-08-15T06:58:30.537Z'
- updated_at: '2026-08-15T06:58:30.537Z'
- company_id: comp_UkLWZg9DAJ
- contacts_count: 0
- billing_address:
- shipping_address:
- patch:
- summary: Update a company location
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Address fields sent here edit the branch's existing address in place; send only what changes.
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // Address fields edit the branch's existing address in place.
- const location = await client.companyLocations.update('cloc_UkLWZg9DAJ', {
- name: 'Berlin Mitte',
- billing_address: { city: 'Berlin' },
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /company_locations/{id} -d '{"name":"Berlin Mitte","billing_address":{"city":"Berlin"}}'
- parameters: []
- responses:
- '200':
- description: location updated
- content:
- application/json:
- example:
- id: cloc_UkLWZg9DAJ
- name: Berlin Mitte
- external_id:
- metadata: {}
- created_at: '2026-08-15T06:58:30.558Z'
- updated_at: '2026-08-15T06:58:30.572Z'
- company_id: comp_UkLWZg9DAJ
- contacts_count: 0
- billing_address:
- shipping_address:
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Berlin Mitte
- billing_address:
- type: object
- properties:
- city:
- type: string
- delete:
- summary: Delete a company location
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Removes the branch, its buyers and the addresses it owned.
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- await client.companyLocations.delete('cloc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /company_locations/{id}
- responses:
- '204':
- description: location deleted
- "/api/v3/admin/companies/{company_id}/tax_exemption_certificates":
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: company_id
- in: path
- required: true
- schema:
- type: string
- get:
- summary: List tax exemption certificates
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Returns a business's exemption evidence. `active` is the field that decides whether a certificate
- exempts a sale: a verified certificate stops counting once its expiry date passes, so the status
- alone does not answer it.
-
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: certificates } =
- await client.companies.taxExemptionCertificates.list('comp_UkLWZg9DAJ')
-
- // `active` — not `status` — answers whether one exempts a sale: a verified
- // certificate stops counting once its expiry date passes.
- const applying = certificates.filter((certificate) => certificate.active)
- - lang: bash
- label: Spree CLI
- source: spree api get /companies/{company_id}/tax_exemption_certificates
- responses:
- '200':
- description: certificates found
- content:
- application/json:
- example:
- data:
- - id: cert_UkLWZg9DAJ
- certificate_number: DE-RESALE-1
- reason_code: resale
- status: pending
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at:
- created_at: '2026-08-15T06:58:30.603Z'
- updated_at: '2026-08-15T06:58:30.603Z'
- company_id: comp_UkLWZg9DAJ
- country_code:
- state_code:
- active: false
- lapsed: false
- can_be_deleted: true
- document_filename:
- document_byte_size:
- document_url:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- 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
- until verified.
-
- `country_code` and `state_code` say where the certificate holds — omit both for one valid
- everywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage
- signed blob id obtained from `POST /api/v3/admin/direct_uploads`.
-
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // Upload the document first, then pass the signed id.
- const { signed_id } = await client.directUploads.create({
- blob: {
- filename: 'resale.pdf',
- byte_size: 18_345,
- checksum: 'Base64EncodedMD5==',
- content_type: 'application/pdf',
- },
- })
-
- const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {
- certificate_number: 'DE-RESALE-7',
- reason_code: 'resale',
- country_code: 'DE',
- document: signed_id,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /companies/{company_id}/tax_exemption_certificates
- -d '{ ... }'
- parameters: []
- responses:
- '201':
- description: certificate created
- content:
- application/json:
- example:
- id: cert_gbHJdmfrXB
- certificate_number: DE-RESALE-7
- reason_code: resale
- status: pending
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at:
- created_at: '2026-08-15T06:58:30.651Z'
- updated_at: '2026-08-15T06:58:30.652Z'
- company_id: comp_UkLWZg9DAJ
- country_code: DE
- state_code:
- active: false
- lapsed: false
- can_be_deleted: true
- document_filename: resale.pdf
- document_byte_size: 20
- document_url: "/api/v3/admin/companies/comp_UkLWZg9DAJ/tax_exemption_certificates/cert_gbHJdmfrXB/download"
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Certificate number can't be blank
- details:
- certificate_number:
- - can't be blank
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- certificate_number:
- type: string
- example: DE-RESALE-7
- reason_code:
- type: string
- description: Becomes the tax provider's entity use code.
- example: resale
- country_code:
- type: string
- nullable: true
- example: DE
- state_code:
- type: string
- nullable: true
- example: BE
- expires_at:
- type: string
- format: date-time
- nullable: true
- issuing_authority:
- type: string
- nullable: true
- example: Finanzamt Berlin
- document:
- type: string
- description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.
- example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed
- 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
- certificate can be accepted — re-accepting a revoked one would restore evidence that was
- deliberately withdrawn. An installation that checks numbers against a registry, or requires a
- second approval, can refuse here, and the refusal is returned as a validation error.
-
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // Accepting is what makes a certificate exempt sales. Only a pending one can
- // be accepted, and an installation's own checks can refuse here.
- const certificate = await client.companies.taxExemptionCertificates.verify(
- 'comp_UkLWZg9DAJ',
- 'cert_UkLWZg9DAJ',
- )
- - lang: bash
- label: Spree CLI
- source: spree api patch /companies/{company_id}/tax_exemption_certificates/{id}/verify
- -d '{ ... }'
- responses:
- '200':
- description: certificate verified
- content:
- application/json:
- example:
- id: cert_UkLWZg9DAJ
- certificate_number: DE-RESALE-1
- reason_code: resale
- status: verified
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at: '2026-08-15T06:58:30.730Z'
- created_at: '2026-08-15T06:58:30.714Z'
- updated_at: '2026-08-15T06:58:30.730Z'
- company_id: comp_UkLWZg9DAJ
- country_code:
- state_code:
- active: true
- lapsed: false
- can_be_deleted: false
- document_filename:
- document_byte_size:
- document_url:
- "/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.
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // A verified certificate cannot be deleted — how a sale was taxed has to stay
- // explainable — so revoking is the way out.
- const certificate = await client.companies.taxExemptionCertificates.revoke(
- 'comp_UkLWZg9DAJ',
- 'cert_UkLWZg9DAJ',
- )
- - lang: bash
- label: Spree CLI
- source: spree api patch /companies/{company_id}/tax_exemption_certificates/{id}/revoke
- -d '{ ... }'
- responses:
- '200':
- description: certificate revoked
- content:
- application/json:
- example:
- id: cert_gbHJdmfrXB
- certificate_number: CERT-1
- reason_code: resale
- status: revoked
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at: '2026-08-15T06:58:30.739Z'
- created_at: '2026-08-15T06:58:30.739Z'
- updated_at: '2026-08-15T06:58:30.756Z'
- company_id: comp_UkLWZg9DAJ
- country_code:
- state_code:
- active: false
- lapsed: false
- can_be_deleted: true
- document_filename:
- document_byte_size:
- document_url:
- "/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
- the same credentials apply to every read of a confidential document. Requires only read access.
-
-
- **Required scope:** `read_customers` (for API-key authentication).
- responses:
- '200':
- description: document streamed
- content:
- application/json: {}
- '422':
- description: no document attached
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Certificate has no attached document
- "/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
- over the buyer's own when a sale is for that business, because the invoice is addressed to the
- entity rather than the person who placed the order.
-
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: registrations } = await client.companies.taxIdentifiers.list('comp_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /companies/{company_id}/tax_identifiers
- responses:
- '200':
- description: registrations found
- content:
- application/json:
- example:
- data:
- - id: txi_UkLWZg9DAJ
- kind: eu_vat
- value: DE123456789
- validation_status:
- validation_evidence:
- source:
- validated_at:
- created_at: '2026-08-15T06:58:30.838Z'
- updated_at: '2026-08-15T06:58:30.838Z'
- validatable: false
- customer_id:
- cart_id:
- order_id:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- 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
- the background where a validator is installed for the kind; a stock installation registers none,
- leaving the status unattempted.
-
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // A business registration outranks the buyer's own when the sale is for that business.
- const registration = await client.companies.taxIdentifiers.create('comp_UkLWZg9DAJ', {
- kind: 'eu_vat',
- value: 'DE123456789',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /companies/{company_id}/tax_identifiers -d '{"kind":"eu_vat","value":"DE123456789"}'
- parameters: []
- responses:
- '201':
- description: registration created
- content:
- application/json:
- example:
- id: txi_gbHJdmfrXB
- kind: gb_vat
- value: GB123456789
- validation_status:
- validation_evidence:
- source:
- validated_at:
- created_at: '2026-08-15T06:58:30.886Z'
- updated_at: '2026-08-15T06:58:30.886Z'
- validatable: false
- customer_id:
- cart_id:
- order_id:
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Kind has already been taken
- details:
- kind:
- - has already been taken
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- kind:
- type: string
- description: The regime the number belongs to.
- example: gb_vat
- value:
- type: string
- example: GB123456789
- 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
- last year may have been deregistered since — and because a check that came back unavailable
- cannot otherwise be retried without editing the number.
-
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // A registry answers only "valid now", so a number verified last year may
- // have been deregistered since. The check is queued; poll for the verdict.
- const registration = await client.companies.taxIdentifiers.validate(
- 'comp_UkLWZg9DAJ',
- 'txi_UkLWZg9DAJ',
- )
- - lang: bash
- label: Spree CLI
- source: spree api post /companies/{company_id}/tax_identifiers/{id}/validate
- -d '{ ... }'
+ required: true
+ description: Collection ID
+ schema:
+ type: string
responses:
- '422':
- description: no validator installed for this kind
- content:
- application/json:
- example:
- error:
- code: tax_id_not_validatable
- message: No validator is registered for tax identifier kind 'eu_vat'
- "/api/v3/admin/companies":
+ '204':
+ description: collection deleted
+ "/api/v3/admin/collections/{collection_id}/products":
get:
- summary: List companies
+ summary: List collection products
tags:
- - Companies
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the business customers of the current store.
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Products curated in the collection, ordered by their membership position.
- const { data: companies } = await client.companies.list({ name_cont: 'Acme' })
- - lang: bash
- label: Spree CLI
- source: spree api get /companies -d '{"name_cont":"Acme"}'
+ **Required scope:** `read_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25635,61 +24063,55 @@ paths:
- 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: companies found
+ description: products found
content:
application/json:
example:
- data:
- - id: comp_UkLWZg9DAJ
- name: Acme Industrial
- external_id: ACME-1
- metadata: {}
- created_at: '2026-08-15T06:58:30.938Z'
- updated_at: '2026-08-15T06:58:30.938Z'
- locations_count: 0
+ data: []
meta:
page: 1
limit: 25
- count: 1
+ count: 0
pages: 1
- from: 1
- to: 1
- in: 1
+ from: 0
+ to: 0
+ in: 0
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Create a company
+ summary: Add a product to a collection
tags:
- - Companies
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a business customer. Exemption certificates and tax registrations hang off it.
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Curates a product into the collection (appended to the end).
- const company = await client.companies.create({
- name: 'Globex Corporation',
- external_id: 'GLBX-42',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /companies -d '{"name":"Globex Corporation","external_id":"GLBX-42"}'
+ **Required scope:** `write_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25699,272 +24121,213 @@ paths:
- 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: company created
+ description: product added
content:
application/json:
example:
- id: comp_gbHJdmfrXB
- name: Globex Corporation
- external_id: GLBX-42
+ id: prod_UkLWZg9DAJ
+ name: Product 66976
+ slug: product-66976
+ 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: Quisquam ullam vel error perspiciatis. Id iure delectus
+ eius dolore ut veniam mollitia. Porro consequatur minima doloribus
+ sit fugiat vitae. Ipsam nisi iusto quos laboriosam eligendi harum
+ aut accusamus.
+ description_html: Quisquam ullam vel error perspiciatis. Id iure delectus
+ eius dolore ut veniam mollitia. Porro consequatur minima doloribus
+ sit fugiat vitae. Ipsam nisi iusto quos laboriosam eligendi harum
+ aut accusamus.
+ default_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:
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-08-14T13:22:53.434Z'
+ updated_at: '2026-08-14T13:22:53.434Z'
+ original_price:
+ status: active
metadata: {}
- created_at: '2026-08-15T06:58:30.972Z'
- updated_at: '2026-08-15T06:58:30.972Z'
- locations_count: 0
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
+ deleted_at:
+ created_at: '2026-08-14T13:22:53.425Z'
+ updated_at: '2026-08-14T13:22:53.441Z'
+ delivery_profile_id: fp_UkLWZg9DAJ
+ product_type_id:
+ tax_category_id: taxcat_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/Product"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Globex Corporation
- external_id:
+ product_id:
type: string
- nullable: true
- description: Your own reference for this business, unique within
- the store.
- example: GLBX-42
+ example: prod_abc123
required:
- - name
- "/api/v3/admin/company_locations/{company_location_id}/contacts":
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: company_location_id
- in: path
- required: true
- schema:
- type: string
- get:
- summary: List company contacts
+ - product_id
+ "/api/v3/admin/collections/{collection_id}/products/{id}":
+ delete:
+ summary: Remove a product from a collection
tags:
- - Companies
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the customers authorised to purchase for a branch. A customer may act for more than one branch.
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Removes a product from the collection's manual curation.
- const { data: contacts } = await client.companyLocations.contacts.list('cloc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /company_locations/{company_location_id}/contacts
+ **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:
- '200':
- description: contacts found
- content:
- application/json:
- example:
- data:
- - id: cc_UkLWZg9DAJ
- role: buyer
- created_at: '2026-08-15T06:58:31.011Z'
- updated_at: '2026-08-15T06:58:31.011Z'
- company_location_id: cloc_UkLWZg9DAJ
- customer_id: cust_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- post:
- summary: Create a company contact
+ '204':
+ description: product removed
+ "/api/v3/admin/collections/{collection_id}/products/{id}/reposition":
+ patch:
+ summary: Reposition a collection product
tags:
- - Companies
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Authorises a customer to purchase for a branch. A customer who acts for exactly one branch has
- their orders attributed to it automatically; one who acts for several needs the branch set on
- the order, because guessing would invoice the wrong business.
-
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Moves a product to a new index among the collection's products.
- const contact = await client.companyLocations.contacts.create('cloc_UkLWZg9DAJ', {
- customer_id: 'cus_UkLWZg9DAJ',
- role: 'buyer',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /company_locations/{company_location_id}/contacts -d
- '{"customer_id":"cus_UkLWZg9DAJ","role":"buyer"}'
- parameters: []
+ **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:
- '201':
- description: contact created
- content:
- application/json:
- example:
- id: cc_gbHJdmfrXB
- role: admin
- created_at: '2026-08-15T06:58:31.061Z'
- updated_at: '2026-08-15T06:58:31.061Z'
- company_location_id: cloc_UkLWZg9DAJ
- customer_id: cust_gbHJdmfrXB
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Customer has already been taken
- details:
- customer_id:
- - has already been taken
+ '204':
+ description: product repositioned
requestBody:
content:
application/json:
schema:
type: object
properties:
- customer_id:
- type: string
- example: cus_UkLWZg9DAJ
- role:
- type: string
- description: Free-form label; carries no permissions in 6.0.
- example: buyer
+ new_position:
+ type: integer
+ description: 0-based index among the collection's products
required:
- - customer_id
- "/api/v3/admin/company_contacts/{id}":
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
+ - new_position
+ "/api/v3/admin/collection_rules/types":
get:
- summary: Get a company contact
+ summary: List available collection rule types
tags:
- - Companies
+ - Collections
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_customers` (for API-key authentication)."
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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`.
- const contact = await client.companyContacts.get('cc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /company_contacts/{id}
+ **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: contact found
+ description: types found
content:
application/json:
example:
- id: cc_UkLWZg9DAJ
- role: buyer
- created_at: '2026-08-15T06:58:31.100Z'
- updated_at: '2026-08-15T06:58:31.100Z'
- company_location_id: cloc_UkLWZg9DAJ
- customer_id: cust_UkLWZg9DAJ
- delete:
- summary: Delete a company contact
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Withdraws the customer's authority to purchase for the branch. The customer account itself is untouched.
-
- **Required scope:** `write_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // Withdraws the buyer's authority; the customer account is untouched.
- await client.companyContacts.delete('cc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /company_contacts/{id}
- responses:
- '204':
- description: contact deleted
+ data:
+ - type: sale
+ label: On sale
+ description: Products currently discounted below their compare-at
+ price
+ preference_schema: []
+ - type: available_on
+ label: Recently published
+ description: Products published within the last N days
+ preference_schema: []
+ - type: tag
+ label: Tag
+ description: Products carrying a matching tag
+ preference_schema: []
"/api/v3/admin/delivery_profiles":
get:
summary: List delivery profiles
@@ -26014,8 +24377,8 @@ paths:
name: General
default: true
position: 1
- created_at: '2026-08-15T06:58:28.146Z'
- updated_at: '2026-08-15T06:58:28.146Z'
+ created_at: '2026-08-14T13:22:51.608Z'
+ updated_at: '2026-08-14T13:22:51.608Z'
kind: shipping
digital: false
offers_pickup: false
@@ -26086,11 +24449,11 @@ paths:
application/json:
example:
id: fp_gbHJdmfrXB
- name: Oversized 1786777112.4575481
+ name: Oversized 1786713774.742147
default: false
position: 2
- created_at: '2026-08-15T06:58:32.461Z'
- updated_at: '2026-08-15T06:58:32.461Z'
+ created_at: '2026-08-14T13:22:54.746Z'
+ updated_at: '2026-08-14T13:22:54.746Z'
kind: shipping
digital: false
offers_pickup: false
@@ -26194,8 +24557,8 @@ paths:
id: og_EfhxLZ9ck8
name: EU warehouse
position: 2
- created_at: '2026-08-15T06:58:32.510Z'
- updated_at: '2026-08-15T06:58:32.510Z'
+ created_at: '2026-08-14T13:22:54.791Z'
+ updated_at: '2026-08-14T13:22:54.791Z'
delivery_profile_id: fp_gbHJdmfrXB
stock_location_ids:
- sloc_UkLWZg9DAJ
@@ -26270,11 +24633,11 @@ paths:
application/json:
example:
id: fp_gbHJdmfrXB
- name: Bulky 1786777112.518354
+ name: Bulky 1786713774.797332
default: false
position: 2
- created_at: '2026-08-15T06:58:32.519Z'
- updated_at: '2026-08-15T06:58:32.519Z'
+ created_at: '2026-08-14T13:22:54.797Z'
+ updated_at: '2026-08-14T13:22:54.797Z'
kind: shipping
digital: false
offers_pickup: false
@@ -26405,8 +24768,8 @@ paths:
tracking_url:
markup_flat: '0.0'
markup_percent: '0.0'
- created_at: '2026-08-15T06:58:32.592Z'
- updated_at: '2026-08-15T06:58:32.593Z'
+ created_at: '2026-08-14T13:22:54.867Z'
+ updated_at: '2026-08-14T13:22:54.869Z'
deleted_at:
services: []
rules: []
@@ -26494,8 +24857,8 @@ paths:
tracking_url:
markup_flat: '0.0'
markup_percent: '0.0'
- created_at: '2026-08-15T06:58:32.640Z'
- updated_at: '2026-08-15T06:58:32.641Z'
+ created_at: '2026-08-14T13:22:54.960Z'
+ updated_at: '2026-08-14T13:22:54.961Z'
deleted_at:
services: []
rules: []
@@ -26702,13 +25065,13 @@ paths:
const deliveryZone = await client.deliveryZones.create({
name: 'US North-East',
members: [
- { member_type: 'country', country_code: 'US' },
- { member_type: 'postal_code', country_code: 'US', postal_code_prefix: '10' },
+ { member_type: 'country', country_iso: 'US' },
+ { member_type: 'postal_code', country_iso: 'US', postal_code_prefix: '10' },
],
})
- lang: bash
label: Spree CLI
- source: spree api post /delivery_zones -d '{"name":"US North-East","members":[{"member_type":"country","country_code":"US"},{"member_type":"postal_code","country_code":"US","postal_code_prefix":"10"}]}'
+ source: spree api post /delivery_zones -d '{"name":"US North-East","members":[{"member_type":"country","country_iso":"US"},{"member_type":"postal_code","country_iso":"US","postal_code_prefix":"10"}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -26738,28 +25101,28 @@ paths:
members:
- id: dzm_UkLWZg9DAJ
member_type: country
- country_code: US
- state_code:
postal_code_prefix:
postal_code_from:
postal_code_to:
- country_name: United States
+ country_iso: US
+ country_name: United States of America
+ state_abbr:
state_name:
- created_at: '2026-08-15T06:58:32.714Z'
- updated_at: '2026-08-15T06:58:32.714Z'
+ created_at: '2026-08-14T13:22:55.061Z'
+ updated_at: '2026-08-14T13:22:55.061Z'
- id: dzm_gbHJdmfrXB
member_type: postal_code
- country_code: US
- state_code:
postal_code_prefix: '10'
postal_code_from:
postal_code_to:
- country_name: United States
+ country_iso: US
+ country_name: United States of America
+ state_abbr:
state_name:
- created_at: '2026-08-15T06:58:32.714Z'
- updated_at: '2026-08-15T06:58:32.714Z'
- created_at: '2026-08-15T06:58:32.713Z'
- updated_at: '2026-08-15T06:58:32.713Z'
+ created_at: '2026-08-14T13:22:55.062Z'
+ updated_at: '2026-08-14T13:22:55.062Z'
+ created_at: '2026-08-14T13:22:55.061Z'
+ updated_at: '2026-08-14T13:22:55.061Z'
delivery_profile_id: fp_UkLWZg9DAJ
delivery_origin_group_id: og_UkLWZg9DAJ
delivery_method_ids: []
@@ -26786,11 +25149,11 @@ paths:
- country
- state
- postal_code
- country_code:
+ country_iso:
type: string
nullable: true
example: US
- state_code:
+ state_abbr:
type: string
nullable: true
postal_code_prefix:
@@ -26854,8 +25217,8 @@ paths:
- id: int_UkLWZg9DAJ
name: Carrier
active: false
- created_at: '2026-08-15T06:58:33.862Z'
- updated_at: '2026-08-15T06:58:33.862Z'
+ created_at: '2026-08-14T13:22:56.039Z'
+ updated_at: '2026-08-14T13:22:56.039Z'
type: carrier
group: shipping
preferences:
@@ -26927,8 +25290,8 @@ paths:
id: int_UkLWZg9DAJ
name: Carrier
active: false
- created_at: '2026-08-15T06:58:33.903Z'
- updated_at: '2026-08-15T06:58:33.903Z'
+ created_at: '2026-08-14T13:22:56.072Z'
+ updated_at: '2026-08-14T13:22:56.072Z'
type: carrier
group: shipping
preferences:
@@ -27120,8 +25483,8 @@ paths:
- id: pt_UkLWZg9DAJ
name: T-Shirt
products_count: 0
- created_at: '2026-08-15T06:58:43.728Z'
- updated_at: '2026-08-15T06:58:43.728Z'
+ created_at: '2026-08-14T13:23:05.003Z'
+ updated_at: '2026-08-14T13:23:05.003Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -27196,8 +25559,8 @@ paths:
id: pt_gbHJdmfrXB
name: Hoodie
products_count: 0
- created_at: '2026-08-15T06:58:43.783Z'
- updated_at: '2026-08-15T06:58:43.783Z'
+ created_at: '2026-08-14T13:23:05.059Z'
+ updated_at: '2026-08-14T13:23:05.059Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -27297,8 +25660,8 @@ paths:
id: pt_UkLWZg9DAJ
name: T-Shirt
products_count: 0
- created_at: '2026-08-15T06:58:43.831Z'
- updated_at: '2026-08-15T06:58:43.831Z'
+ created_at: '2026-08-14T13:23:05.095Z'
+ updated_at: '2026-08-14T13:23:05.095Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -27351,8 +25714,8 @@ paths:
id: pt_UkLWZg9DAJ
name: Premium T-Shirt
products_count: 0
- created_at: '2026-08-15T06:58:43.884Z'
- updated_at: '2026-08-15T06:58:43.901Z'
+ created_at: '2026-08-14T13:23:05.140Z'
+ updated_at: '2026-08-14T13:23:05.155Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -27897,12 +26260,12 @@ components:
nullable: true
country_name:
type: string
- country_code:
+ country_iso:
type: string
state_text:
type: string
nullable: true
- state_code:
+ state_abbr:
type: string
nullable: true
quick_checkout:
@@ -27911,11 +26274,6 @@ components:
type: boolean
is_default_shipping:
type: boolean
- state_abbr:
- type: string
- nullable: true
- country_iso:
- type: string
state_name:
type: string
nullable: true
@@ -27943,14 +26301,12 @@ components:
- phone
- company
- country_name
- - country_code
+ - country_iso
- state_text
- - state_code
+ - state_abbr
- quick_checkout
- is_default_billing
- is_default_shipping
- - state_abbr
- - country_iso
- state_name
- label
- metadata
@@ -28203,6 +26559,12 @@ components:
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
@@ -28284,6 +26646,8 @@ components:
- display_amount_due
- delivery_total
- display_delivery_total
+ - fee_total
+ - display_fee_total
- store_credit_total
- display_store_credit_total
- covered_by_store_credit
@@ -28611,183 +26975,83 @@ components:
type: string
required:
- id
- - type
- - value
- - match_policy
- x-typelizer: true
- Collection:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- permalink:
- type: string
- position:
- type: number
- sort_order:
- type: string
- meta_title:
- type: string
- nullable: true
- meta_description:
- type: string
- nullable: true
- meta_keywords:
- type: string
- nullable: true
- products_count:
- type: number
- description:
- type: string
- description_html:
- type: string
- image_url:
- type: string
- nullable: true
- square_image_url:
- type: string
- nullable: true
- custom_fields:
- type: array
- items:
- "$ref": "#/components/schemas/CustomField"
- translations:
- type: object
- automatic:
- type: boolean
- rules_match_policy:
- type: string
- metadata:
- type: object
- created_at:
- type: string
- updated_at:
- type: string
- rules:
- type: array
- items:
- "$ref": "#/components/schemas/CollectionRule"
- required:
- - id
- - name
- - permalink
- - position
- - sort_order
- - meta_title
- - meta_description
- - meta_keywords
- - products_count
- - description
- - description_html
- - image_url
- - square_image_url
- - automatic
- - rules_match_policy
- - metadata
- - created_at
- - updated_at
- x-typelizer: true
- CompanyContact:
- type: object
- properties:
- id:
- type: string
- role:
- type: string
- created_at:
- type: string
- updated_at:
- type: string
- company_location_id:
- type: string
- customer_id:
- type: string
- email:
- type: string
- nullable: true
- required:
- - id
- - role
- - created_at
- - updated_at
- - company_location_id
- - customer_id
- - email
- x-typelizer: true
- CompanyLocation:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- external_id:
- type: string
- nullable: true
- metadata:
- type: object
- nullable: true
- created_at:
- type: string
- updated_at:
- type: string
- company_id:
- type: string
- contacts_count:
- type: number
- billing_address:
- "$ref": "#/components/schemas/Address"
- shipping_address:
- "$ref": "#/components/schemas/Address"
- company_contacts:
- type: array
- items:
- "$ref": "#/components/schemas/CompanyContact"
- required:
- - id
- - name
- - external_id
- - metadata
- - created_at
- - updated_at
- - company_id
- - contacts_count
- - billing_address
- - shipping_address
+ - type
+ - value
+ - match_policy
x-typelizer: true
- Company:
+ Collection:
type: object
properties:
id:
type: string
name:
type: string
- external_id:
+ permalink:
+ type: string
+ position:
+ type: number
+ sort_order:
+ type: string
+ meta_title:
+ type: string
+ nullable: true
+ meta_description:
+ type: string
+ nullable: true
+ meta_keywords:
+ type: string
+ nullable: true
+ products_count:
+ type: number
+ description:
+ type: string
+ description_html:
+ type: string
+ image_url:
+ type: string
+ nullable: true
+ square_image_url:
type: string
nullable: true
+ custom_fields:
+ type: array
+ items:
+ "$ref": "#/components/schemas/CustomField"
+ translations:
+ type: object
+ automatic:
+ type: boolean
+ rules_match_policy:
+ type: string
metadata:
type: object
- nullable: true
created_at:
type: string
updated_at:
type: string
- locations_count:
- type: number
- company_locations:
+ rules:
type: array
items:
- "$ref": "#/components/schemas/CompanyLocation"
+ "$ref": "#/components/schemas/CollectionRule"
required:
- id
- name
- - external_id
+ - 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
- - locations_count
x-typelizer: true
Country:
type: object
@@ -28810,12 +27074,18 @@ components:
allOf:
- "$ref": "#/components/schemas/Market"
nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
required:
- iso
- iso3
- name
- states_required
- zipcode_required
+ - created_at
+ - updated_at
x-typelizer: true
CouponCode:
type: object
@@ -29468,12 +27738,6 @@ components:
type: string
member_type:
type: string
- country_code:
- type: string
- nullable: true
- state_code:
- type: string
- nullable: true
postal_code_prefix:
type: string
nullable: true
@@ -29483,9 +27747,15 @@ components:
postal_code_to:
type: string
nullable: true
+ country_iso:
+ type: string
+ nullable: true
country_name:
type: string
nullable: true
+ state_abbr:
+ type: string
+ nullable: true
state_name:
type: string
nullable: true
@@ -29496,12 +27766,12 @@ components:
required:
- id
- member_type
- - country_code
- - state_code
- postal_code_prefix
- postal_code_from
- postal_code_to
+ - country_iso
- country_name
+ - state_abbr
- state_name
- created_at
- updated_at
@@ -29952,10 +28222,6 @@ components:
type: array
items:
"$ref": "#/components/schemas/DeliveryRate"
- tax_lines:
- type: array
- items:
- "$ref": "#/components/schemas/TaxLine"
metadata:
type: object
tracking_details:
@@ -30421,10 +28687,6 @@ components:
type: array
items:
"$ref": "#/components/schemas/DigitalLink"
- tax_lines:
- type: array
- items:
- "$ref": "#/components/schemas/TaxLine"
metadata:
type: object
created_at:
@@ -30493,7 +28755,7 @@ components:
type: boolean
default:
type: boolean
- country_codes:
+ country_isos:
type: array
items:
type: string
@@ -30505,9 +28767,6 @@ components:
type: array
items:
"$ref": "#/components/schemas/Country"
- tax_provider:
- type: string
- nullable: true
created_at:
type: string
updated_at:
@@ -30519,9 +28778,8 @@ components:
- default_locale
- tax_inclusive
- default
- - country_codes
+ - country_isos
- supported_locales
- - tax_provider
- created_at
- updated_at
x-typelizer: true
@@ -30840,6 +29098,12 @@ components:
type: string
display_delivery_total:
type: string
+ fee_total:
+ type: string
+ nullable: true
+ display_fee_total:
+ type: string
+ nullable: true
store_credit_total:
type: string
display_store_credit_total:
@@ -30904,12 +29168,6 @@ components:
preferred_stock_location_id:
type: string
nullable: true
- company_location_id:
- type: string
- nullable: true
- company_id:
- type: string
- nullable: true
tags:
type: array
items:
@@ -31001,6 +29259,8 @@ components:
- display_amount_due
- delivery_total
- display_delivery_total
+ - fee_total
+ - display_fee_total
- store_credit_total
- display_store_credit_total
- covered_by_store_credit
@@ -31019,8 +29279,6 @@ components:
- created_at
- updated_at
- preferred_stock_location_id
- - company_location_id
- - company_id
- tags
- internal_note
- internal_note_html
@@ -32153,9 +30411,15 @@ components:
type: string
name:
type: string
+ created_at:
+ type: string
+ updated_at:
+ type: string
required:
- abbr
- name
+ - created_at
+ - updated_at
x-typelizer: true
StockItem:
type: object
@@ -32203,6 +30467,9 @@ components:
properties:
id:
type: string
+ state_abbr:
+ type: string
+ nullable: true
name:
type: string
address1:
@@ -32214,15 +30481,12 @@ components:
zipcode:
type: string
nullable: true
- country_code:
+ country_iso:
type: string
nullable: true
country_name:
type: string
nullable: true
- state_code:
- type: string
- nullable: true
state_text:
type: string
nullable: true
@@ -32267,13 +30531,13 @@ components:
type: string
required:
- id
+ - state_abbr
- name
- address1
- city
- zipcode
- - country_code
+ - country_iso
- country_name
- - state_code
- state_text
- pickup_ready_in_minutes
- pickup_instructions
@@ -32632,129 +30896,6 @@ components:
- created_at
- updated_at
x-typelizer: true
- TaxExemptionCertificate:
- type: object
- properties:
- id:
- type: string
- certificate_number:
- type: string
- reason_code:
- type: string
- status:
- type: string
- issuing_authority:
- type: string
- nullable: true
- metadata:
- type: object
- nullable: true
- issued_at:
- type: string
- expires_at:
- type: string
- verified_at:
- type: string
- created_at:
- type: string
- updated_at:
- type: string
- company_id:
- type: string
- country_code:
- type: string
- nullable: true
- state_code:
- type: string
- nullable: true
- active:
- type: boolean
- lapsed:
- type: boolean
- can_be_deleted:
- type: boolean
- document_filename:
- type: string
- nullable: true
- document_byte_size:
- type: number
- nullable: true
- document_url:
- type: string
- nullable: true
- required:
- - id
- - certificate_number
- - reason_code
- - status
- - issuing_authority
- - metadata
- - issued_at
- - expires_at
- - verified_at
- - created_at
- - updated_at
- - company_id
- - country_code
- - state_code
- - active
- - lapsed
- - can_be_deleted
- - document_filename
- - document_byte_size
- - document_url
- x-typelizer: true
- TaxIdentifier:
- type: object
- properties:
- id:
- type: string
- kind:
- type: string
- value:
- type: string
- validation_status:
- type: string
- nullable: true
- validation_evidence:
- type: object
- nullable: true
- source:
- type: string
- nullable: true
- validated_at:
- type: string
- nullable: true
- created_at:
- type: string
- updated_at:
- type: string
- validatable:
- type: boolean
- customer_id:
- type: string
- nullable: true
- cart_id:
- type: string
- nullable: true
- order_id:
- type: string
- nullable: true
- required:
- - id
- - kind
- - value
- - validation_status
- - validation_evidence
- - source
- - validated_at
- - created_at
- - updated_at
- - validatable
- - customer_id
- - cart_id
- - order_id
- x-typelizer: true
TaxLine:
type: object
properties:
@@ -32788,18 +30929,6 @@ components:
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:
@@ -32817,66 +30946,8 @@ components:
- 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
@@ -32966,6 +31037,15 @@ components:
backorder_limit:
type: number
nullable: true
+ hs_code:
+ type: string
+ nullable: true
+ country_of_origin:
+ type: string
+ nullable: true
+ customs_description:
+ type: string
+ nullable: true
deleted_at:
type: string
nullable: true
@@ -33024,6 +31104,9 @@ components:
- weight_unit
- dimensions_unit
- backorder_limit
+ - hs_code
+ - country_of_origin
+ - customs_description
- deleted_at
- created_at
- updated_at
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 572c0e7e40..5507e799b8 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -87,16 +87,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjYxMGJlZDY4LWU0ZDgtNDY0My1iMmFjLTc3YTg4YjY5NWExYiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzgwNzI5fQ._sANbjDpQTbLDGcp6Y8T5gVSi-BUWaFjuLNUnjtZC_Y
- refresh_token: GJGcToDQ4J2tbweZsA17jm58
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjE4MzBjNDU2LWQwYTgtNDFjOS1iNzhjLWVlNzM4YTcwZmIyZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzE3MzkwfQ.hLJ1ikNwin0tBNeP3HyUG9mkYCJh9d8NWPnB6sTGFa4
+ refresh_token: aNyFSEVouMVNrovNCwy3ZU1J
user:
id: cust_UkLWZg9DAJ
- first_name: Patrica
- last_name: Fahey
+ first_name: Gerda
+ last_name: Grady
phone:
accepts_email_marketing: false
- full_name: Patrica Fahey
+ full_name: Gerda Grady
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -194,16 +194,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImM0MjI1YzA1LTlhMTQtNDhjZi04YjEzLTZhZjhiZTJhODFkZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzgwNzI5fQ.ncEG7M6stkHtmnyQUOlVp8i_LB_F4hAx4ihR9PUAHKQ
- refresh_token: My5m7fesMJp5LZqKoTfMfR4y
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjNiZmFlNzkxLWRiZDEtNDdiNS05MjU4LTVmOTA1MTJkMzVhMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzE3MzkwfQ.flJAMJbOJqQC5lyJJFVF3f88rYvaAjuy4rEGevLoH0M
+ refresh_token: Np6btqSDwtNpgspCXzeLPJKV
user:
id: cust_UkLWZg9DAJ
- first_name: Rosena
- last_name: Hettinger
+ first_name: Benny
+ last_name: Ruecker
phone:
accepts_email_marketing: false
- full_name: Rosena Hettinger
+ full_name: Benny Ruecker
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -393,16 +393,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjAzODlhZmQ1LTMxMTgtNGM0My1iYmFhLWQzYTUzMmQxODYxMiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzgwNzMzfQ.sDpzaC8rD1PIw86hca_ay43vMkEN6ZYz_HnHEcMuuLA
- refresh_token: LR96Zupa3EwiZtZhDQbd5Kxz
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImU3M2NkYzdkLTg1YjktNDVjMS05ZGIyLWRlZWZkMDk3NmQxZCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzE3Mzk0fQ.aavGfpCaOWXpmUvOSXvgBxPvNifhWbXIh7CXkYC5ux8
+ refresh_token: tVf2rTDBFm4GgHWqqFFNC81x
user:
id: cust_UkLWZg9DAJ
- first_name: Kimberlee
- last_name: Berge
+ first_name: Milo
+ last_name: Walker
phone:
accepts_email_marketing: false
- full_name: Kimberlee Berge
+ full_name: Milo Walker
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -879,8 +879,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1344
- slug: product-1344
+ name: Product 134916
+ slug: product-134916
meta_title:
meta_description:
meta_keywords:
@@ -892,23 +892,25 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Deserunt minima dicta praesentium repudiandae maxime
- beatae qui cumque. Facere enim eaque maxime rerum. Vel ipsa quos
- nam modi. Eaque perspiciatis repellat officiis commodi illo optio
- in. Sed necessitatibus similique atque aliquid explicabo saepe
- debitis fugit. A labore consectetur quaerat distinctio ex. Adipisci
- eius laudantium quam ipsam aut vero. Vero perspiciatis nulla amet
- iure mollitia perferendis magni assumenda. Assumenda quisquam
- necessitatibus voluptatibus iure asperiores animi mollitia. Inventore
- suscipit error blanditiis incidunt. Sint beatae doloremque ut
- architecto laboriosam. Facilis neque ut suscipit perspiciatis.
- Quas nisi iure earum illum. Atque natus ut mollitia saepe occaecati
- aperiam ab in.
+ description: Inventore laborum magni ullam tempore necessitatibus
+ unde incidunt quidem. Minima incidunt fuga ea impedit similique
+ quasi aperiam neque. Repellat similique vitae ut corrupti. Expedita
+ fugiat tenetur iusto libero totam id repellendus impedit. Doloribus
+ eos occaecati dicta cum at minima. Quae reprehenderit reiciendis
+ voluptates quisquam animi eos a at. Amet vero quo beatae quasi.
+ Neque quam aspernatur eius eos sit. A quaerat ipsam ea exercitationem
+ asperiores sint voluptatem voluptates. Temporibus unde ut dolore
+ quis cum. Autem ut eaque ipsum minima nulla libero non. Voluptate
+ blanditiis maiores et voluptatum ea reiciendis dolorum. Dolore
+ possimus at velit ratione dolores. Occaecati quia repellendus
+ necessitatibus quasi. Doloribus libero voluptas assumenda quia
+ error quo amet. Veritatis minus mollitia numquam pariatur distinctio.
+ Ducimus aliquid porro voluptates est quo ad.
description_html: |-
- Deserunt minima dicta praesentium repudiandae maxime beatae qui cumque. Facere enim eaque maxime rerum. Vel ipsa quos nam modi.
- Eaque perspiciatis repellat officiis commodi illo optio in. Sed necessitatibus similique atque aliquid explicabo saepe debitis fugit. A labore consectetur quaerat distinctio ex.
- Adipisci eius laudantium quam ipsam aut vero. Vero perspiciatis nulla amet iure mollitia perferendis magni assumenda. Assumenda quisquam necessitatibus voluptatibus iure asperiores animi mollitia. Inventore suscipit error blanditiis incidunt. Sint beatae doloremque ut architecto laboriosam.
- Facilis neque ut suscipit perspiciatis. Quas nisi iure earum illum. Atque natus ut mollitia saepe occaecati aperiam ab in.
+ Inventore laborum magni ullam tempore necessitatibus unde incidunt quidem. Minima incidunt fuga ea impedit similique quasi aperiam neque. Repellat similique vitae ut corrupti. Expedita fugiat tenetur iusto libero totam id repellendus impedit. Doloribus eos occaecati dicta cum at minima.
+ Quae reprehenderit reiciendis voluptates quisquam animi eos a at. Amet vero quo beatae quasi. Neque quam aspernatur eius eos sit.
+ A quaerat ipsam ea exercitationem asperiores sint voluptatem voluptates. Temporibus unde ut dolore quis cum. Autem ut eaque ipsum minima nulla libero non. Voluptate blanditiis maiores et voluptatum ea reiciendis dolorum. Dolore possimus at velit ratione dolores.
+ Occaecati quia repellendus necessitatibus quasi. Doloribus libero voluptas assumenda quia error quo amet. Veritatis minus mollitia numquam pariatur distinctio. Ducimus aliquid porro voluptates est quo ad.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -1063,8 +1065,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1798980
- slug: product-1798980
+ name: Product 1796510
+ slug: product-1796510
meta_title:
meta_description:
meta_keywords:
@@ -1093,8 +1095,8 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 1807883
- slug: product-1807883
+ name: Product 1803196
+ slug: product-1803196
meta_title:
meta_description:
meta_keywords:
@@ -1106,14 +1108,26 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Inventore laborum aspernatur officiis impedit ipsa
- optio sit beatae. Dolorem laborum deserunt sit accusantium culpa
- magnam laboriosam fuga. Officia pariatur temporibus amet minima
- numquam sapiente sed.
- description_html: Inventore laborum aspernatur officiis impedit
- ipsa optio sit beatae. Dolorem laborum deserunt sit accusantium
- culpa magnam laboriosam fuga. Officia pariatur temporibus amet
- minima numquam sapiente sed.
+ description: Eligendi architecto dicta consequatur temporibus. Tempore
+ amet ex tenetur sunt assumenda eaque modi deleniti. Distinctio
+ accusantium unde nam rem. Odio nemo ducimus reprehenderit laudantium
+ sed numquam dolorum praesentium. Unde alias laudantium hic iusto
+ iste aut non. Ea neque placeat sint unde animi iusto quos. Architecto
+ ipsa ipsam quo maiores. Magni aut asperiores quaerat omnis. Voluptate
+ non reiciendis adipisci dolorum. Voluptate deserunt totam quibusdam
+ eos doloribus eaque. Enim consequuntur animi fuga commodi quam
+ ad. Nihil hic explicabo adipisci molestias praesentium. Assumenda
+ est provident totam commodi ducimus. Laborum sed animi ex voluptatum
+ quaerat debitis. Reiciendis iusto ullam veniam fugiat nostrum
+ quam in. Quis similique amet voluptate totam suscipit tempora.
+ Sunt maxime sapiente ratione tempore debitis consequuntur totam
+ nostrum. Voluptas unde ducimus molestias mollitia porro facere
+ doloribus ab.
+ description_html: |-
+ Eligendi architecto dicta consequatur temporibus. Tempore amet ex tenetur sunt assumenda eaque modi deleniti. Distinctio accusantium unde nam rem. Odio nemo ducimus reprehenderit laudantium sed numquam dolorum praesentium. Unde alias laudantium hic iusto iste aut non.
+ Ea neque placeat sint unde animi iusto quos. Architecto ipsa ipsam quo maiores. Magni aut asperiores quaerat omnis. Voluptate non reiciendis adipisci dolorum. Voluptate deserunt totam quibusdam eos doloribus eaque.
+ Enim consequuntur animi fuga commodi quam ad. Nihil hic explicabo adipisci molestias praesentium. Assumenda est provident totam commodi ducimus. Laborum sed animi ex voluptatum quaerat debitis.
+ Reiciendis iusto ullam veniam fugiat nostrum quam in. Quis similique amet voluptate totam suscipit tempora. Sunt maxime sapiente ratione tempore debitis consequuntur totam nostrum. Voluptas unde ducimus molestias mollitia porro facere doloribus ab.
default_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -1215,8 +1229,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 207961
- slug: product-207961
+ name: Product 2073051
+ slug: product-2073051
meta_title:
meta_description:
meta_keywords:
@@ -1250,7 +1264,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-07-31T06:59:02Z'
+ recorded_at: '2026-07-30T13:23:22Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -1500,7 +1514,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_gbHJdmfrXB
- token: nMM4hK2cBpC5bcxn17eCDC4E
+ token: 87SPiSTKyoRsXETppFVLPTz3
email:
customer_note:
currency: USD
@@ -1528,6 +1542,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -1552,6 +1568,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
@@ -1559,8 +1576,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1098909
- slug: product-1098909
+ name: Product 1099095
+ slug: product-1099095
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1591,12 +1608,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -1605,7 +1622,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: qJc6nPebysuz7wYWmKnMrtk9
+ token: qCiggumGg7qksUXEMJXhGZ7A
email:
customer_note:
currency: USD
@@ -1633,6 +1650,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -1657,6 +1676,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -1664,8 +1684,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 108320
- slug: product-108320
+ name: Product 1081434
+ slug: product-1081434
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1696,12 +1716,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -1783,7 +1803,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: ZoBNKJfCnTWRc1a39eFXVB4j
+ token: 4N1DoS61UNeCowA9xVPXCHCC
email:
customer_note:
currency: USD
@@ -1811,6 +1831,8 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -1827,6 +1849,7 @@ paths:
message: Email address is required
shipping_eq_billing_address: true
discounts: []
+ fees: []
items: []
fulfillments: []
payments: []
@@ -1836,12 +1859,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -1948,7 +1971,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: 33ibYah7Ew4wcQba25e6BhHS
+ token: tBbVoqmdyMRL5KrM1TpdMzdp
email:
customer_note:
currency: USD
@@ -1956,7 +1979,7 @@ paths:
total_quantity: 0
warnings:
- code: line_item_removed
- message: Product 1138056 was removed because it was sold out
+ message: Product 11323 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
coupon_code:
@@ -1980,6 +2003,8 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -1996,6 +2021,7 @@ paths:
message: Email address is required
shipping_eq_billing_address: true
discounts: []
+ fees: []
items: []
fulfillments: []
payments: []
@@ -2005,12 +2031,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -2054,7 +2080,7 @@ paths:
address1: '123 Main St',
city: 'New York',
postal_code: '10001',
- country_code: 'US',
+ country_iso: 'US',
state_abbr: 'NY',
},
}, {
@@ -2098,7 +2124,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: cekvvTmkvdfAQUcZf4pt3ATK
+ token: bUzntgyynoxJDDdqsRuvui7c
email:
customer_note: Leave at door
currency: USD
@@ -2126,6 +2152,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -2146,6 +2174,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -2153,8 +2182,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1146888
- slug: product-1146888
+ name: Product 1149013
+ slug: product-1149013
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2185,12 +2214,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -2239,9 +2268,9 @@ paths:
type: string
company:
type: string
- country_code:
+ country_iso:
type: string
- state_code:
+ state_abbr:
type: string
shipping_address:
type: object
@@ -2262,9 +2291,9 @@ paths:
type: string
company:
type: string
- country_code:
+ country_iso:
type: string
- state_code:
+ state_abbr:
type: string
delete:
summary: Delete a cart
@@ -2373,8 +2402,8 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: ofju3DCyNTVHt9D41Zff7mSH
+ token: 8oqN42DJyk1rU7KyCK2Z9pGh
customer_note:
currency: USD
locale: en
@@ -2401,6 +2430,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -2418,6 +2449,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: false
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -2425,8 +2457,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1165794
- slug: product-1165794
+ name: Product 1162742
+ slug: product-1162742
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2462,15 +2494,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
shipping_address:
id: addr_UkLWZg9DAJ
@@ -2483,26 +2513,24 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_abbr: NY
- country_iso: US
state_name: New York
payment_methods: []
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -2585,7 +2613,7 @@ paths:
cart_id: cart_UkLWZg9DAJ
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -2593,7 +2621,7 @@ paths:
coupon_code:
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-08-15T06:58:51.143Z'
+ completed_at: '2026-08-14T13:23:11.965Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -2614,10 +2642,13 @@ paths:
display_amount_due: "$0.00"
delivery_total: '10.0'
display_delivery_total: "$10.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
+ fees: []
items:
- id: li_gbHJdmfrXB
variant_id: variant_UkLWZg9DAJ
@@ -2625,8 +2656,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1191944
- slug: product-1191944
+ name: Product 1196497
+ slug: product-1196497
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2691,14 +2722,14 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Trinh Abernathy
+ state_abbr: NY
+ name: Phyllis Veum
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: NY
pickup_ready_in_minutes:
pickup_instructions:
delivery_rates:
@@ -2731,7 +2762,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-4ef71a15e8cb
+ response_code: BGS-687fdc89035d
number: R1001-P1
amount: '20.0'
display_amount: "$20.00"
@@ -2765,15 +2796,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
shipping_address:
id: addr_OIJLhNcSbf
@@ -2786,25 +2815,23 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -2892,7 +2919,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: W4SC3fGJHvMwvvZa9E3vwicK
+ token: xe9BRFYyfjHtrB5q7nCJAGsb
email:
customer_note:
currency: USD
@@ -2920,6 +2947,8 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -2943,6 +2972,7 @@ paths:
code: save10
amount: "-10.0"
display_amount: "-$10.00"
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -2950,8 +2980,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1454488
- slug: product-1454488
+ name: Product 1459562
+ slug: product-1459562
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2982,12 +3012,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -3080,7 +3110,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: bUYUfF7zLHTV6dz47hTfatoZ
+ token: kCMeNFGg5uR5NCGBCECzww5w
email:
customer_note:
currency: USD
@@ -3108,6 +3138,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3128,6 +3160,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -3135,8 +3168,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1478248
- slug: product-1478248
+ name: Product 1473243
+ slug: product-1473243
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3167,12 +3200,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -3254,8 +3287,8 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: HiZJFqu3qJQY8C59UqJ6PUFb
+ token: j5Ffw2ZNQbrMNxyfsGRAkegM
customer_note:
currency: USD
locale: en
@@ -3282,6 +3315,8 @@ paths:
display_amount_due: "$20.00"
delivery_total: '10.0'
display_delivery_total: "$10.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3296,6 +3331,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: false
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -3303,8 +3339,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1492967
- slug: product-1492967
+ name: Product 1495288
+ slug: product-1495288
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3369,14 +3405,14 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Loyd Bayer
+ state_abbr: NY
+ name: Roxane McGlynn
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: NY
pickup_ready_in_minutes:
pickup_instructions:
delivery_rates:
@@ -3419,26 +3455,24 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
payment_methods: []
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -3534,7 +3568,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: Una2zZ9gJSeddM1sB1rEqQBr
+ token: FZxyPHfAmwNtPzHJA8TYBGGa
email:
customer_note:
currency: USD
@@ -3562,6 +3596,8 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '10.0'
display_store_credit_total: "-$10.00"
covered_by_store_credit: true
@@ -3578,6 +3614,7 @@ paths:
message: Select a delivery method for all fulfillments
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -3585,8 +3622,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1516736
- slug: product-1516736
+ name: Product 1513771
+ slug: product-1513771
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3613,7 +3650,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260815065855970251
+ response_code: 1-SC-20260814132316735815
number: cart_UkLWZg9DAJ-P1
amount: '10.0'
display_amount: "$10.00"
@@ -3663,12 +3700,12 @@ paths:
active: true
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -3770,7 +3807,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: k35GJyKxCwZ8fHBSt5Coyyo8
+ token: pafqF8saB3pakHjiZByxKnMX
email:
customer_note:
currency: USD
@@ -3798,6 +3835,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3818,6 +3857,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -3825,8 +3865,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1559114
- slug: product-1559114
+ name: Product 1556049
+ slug: product-1556049
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3853,7 +3893,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260815065856420443
+ response_code: 1-SC-20260814132317095504
number: cart_UkLWZg9DAJ-P1
amount: '10.0'
display_amount: "$10.00"
@@ -3882,12 +3922,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -3961,7 +4001,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: CEwoz62xEjeBzc9Bx9BsrMfS
+ token: oWExdYDNSLNN33qfoUpkjSE4
email:
customer_note:
currency: USD
@@ -3969,10 +4009,10 @@ paths:
total_quantity: 2
warnings:
- code: delivery_unavailable
- message: Product 1588178 cannot be delivered to the selected address
+ message: Product 1586196 cannot be delivered to the selected address
line_item_id: li_UkLWZg9DAJ
- code: delivery_unavailable
- message: Product 1596058 cannot be delivered to the selected address
+ message: Product 1591838 cannot be delivered to the selected address
line_item_id: li_gbHJdmfrXB
coupon_code:
item_total: '29.99'
@@ -3995,6 +4035,8 @@ paths:
display_amount_due: "$29.99"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4015,6 +4057,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -4022,8 +4065,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1588178
- slug: product-1588178
+ name: Product 1586196
+ slug: product-1586196
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4052,8 +4095,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1596058
- slug: product-1596058
+ name: Product 1591838
+ slug: product-1591838
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4084,12 +4127,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -4204,7 +4247,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: ZTCAYqehM1NnkR1y3tPQZCi5
+ token: NEGhavTqZkUxSb39e1q27eh1
email:
customer_note:
currency: USD
@@ -4236,6 +4279,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4256,6 +4301,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -4263,8 +4309,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1654632
- slug: product-1654632
+ name: Product 1655424
+ slug: product-1655424
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4295,12 +4341,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -4382,7 +4428,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: Kpnbw2FWwmZYsWnyW1sFvz28
+ token: zbB675c552hp6pRGnSQoQ6Ns
email:
customer_note:
currency: USD
@@ -4410,6 +4456,8 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4426,6 +4474,7 @@ paths:
message: Email address is required
shipping_eq_billing_address: true
discounts: []
+ fees: []
items: []
fulfillments: []
payments: []
@@ -4435,12 +4484,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -4522,9 +4571,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_602e3e2e5847e9b3b0ef701f
+ external_id: bogus_ca04dbfb6538507d8fbdca7a
external_data:
- client_secret: bogus_secret_dfbf296993fdecb9
+ client_secret: bogus_secret_9a5c831d2b564980
customer_external_id:
expires_at:
amount: '10.0'
@@ -4623,7 +4672,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_fae9bb258ee1c8012260118f
+ external_id: bogus_a15458dd678c5c95ee262a81
external_data:
client_secret: secret_123
customer_external_id:
@@ -4686,7 +4735,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_c492e8940f52563ce647b99a
+ external_id: bogus_b4e141b589fe03d9e669ddfb
external_data:
client_secret: secret_123
customer_external_id:
@@ -4789,7 +4838,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_342aeb8dcf67c0ce706b9b32
+ external_id: bogus_c43a878e49a5030d583d5082
external_data:
client_secret: secret_123
customer_external_id:
@@ -4997,7 +5046,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: seh1mVKYG6Ka5F4GQT6z8J4k
+ token: hjmQt6Ym4P7KSYgzweEP1Wk7
email:
customer_note:
currency: USD
@@ -5025,6 +5074,8 @@ paths:
display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '10.0'
display_store_credit_total: "-$10.00"
covered_by_store_credit: true
@@ -5041,6 +5092,7 @@ paths:
message: Select a delivery method for all fulfillments
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -5048,8 +5100,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2276396
- slug: product-2276396
+ name: Product 2274883
+ slug: product-2274883
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5076,7 +5128,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260815065903711944
+ response_code: 1-SC-20260814132323889369
number: cart_UkLWZg9DAJ-P1
amount: '10.0'
display_amount: "$10.00"
@@ -5111,12 +5163,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -5197,7 +5249,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: sxmkypAb6ppj64mZ4A6j5pAN
+ token: UTLiWaBX7NS1KtXxKgQR7Ajp
email:
customer_note:
currency: USD
@@ -5225,6 +5277,8 @@ paths:
display_amount_due: "$10.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5245,6 +5299,7 @@ paths:
message: Add a payment method
shipping_eq_billing_address: true
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -5252,8 +5307,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2293473
- slug: product-2293473
+ name: Product 2291457
+ slug: product-2291457
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5284,12 +5339,12 @@ paths:
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -5377,7 +5432,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-15T06:58:58.922Z'
+ completed_at: '2026-08-14T13:23:19.738Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -5398,10 +5453,13 @@ paths:
display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -5409,8 +5467,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1697237
- slug: product-1697237
+ name: Product 1694901
+ slug: product-1694901
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5475,14 +5533,14 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Hugo Toy
+ state_abbr: NY
+ name: Rocco Corkery
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: NY
pickup_ready_in_minutes:
pickup_instructions:
delivery_rates:
@@ -5524,15 +5582,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
shipping_address:
id: addr_gbHJdmfrXB
@@ -5545,25 +5601,23 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -5647,15 +5701,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
- id: addr_gbHJdmfrXB
first_name: John
@@ -5667,15 +5719,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
- id: addr_UkLWZg9DAJ
first_name: John
@@ -5687,15 +5737,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_abbr: NY
- country_iso: US
state_name: New York
meta:
page: 1
@@ -5751,7 +5799,7 @@ paths:
address1: '123 Main St',
city: 'New York',
postal_code: '10001',
- country_code: 'US',
+ country_iso: 'US',
state_abbr: 'NY',
phone: '+1 555 123 4567',
}, {
@@ -5784,15 +5832,13 @@ paths:
city: New York
phone: "+1 555 123 4567"
company:
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: 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/Address"
@@ -5851,11 +5897,11 @@ paths:
company:
type: string
example: Acme Inc
- country_code:
+ country_iso:
type: string
example: US
description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")
- state_code:
+ state_abbr:
type: string
example: NY
description: ISO 3166-2 subdivision code without country prefix
@@ -5878,7 +5924,7 @@ paths:
- address1
- city
- postal_code
- - country_code
+ - country_iso
"/api/v3/store/customers/me/addresses/{id}":
get:
summary: Get an address
@@ -5940,15 +5986,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: 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/Address"
@@ -6017,15 +6061,13 @@ paths:
city: Los Angeles
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: 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/Address"
@@ -6452,7 +6494,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -6460,7 +6502,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-15T06:58:53.855Z'
+ completed_at: '2026-08-14T13:23:14.355Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -6481,10 +6523,13 @@ paths:
display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -6492,8 +6537,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1359530
- slug: product-1359530
+ name: Product 1355077
+ slug: product-1355077
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6558,14 +6603,14 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Susanne Howell
+ state_abbr: NY
+ name: Lakeesha Dach
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: NY
pickup_ready_in_minutes:
pickup_instructions:
delivery_rates:
@@ -6607,15 +6652,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
shipping_address:
id: addr_VqXmZF31wY
@@ -6628,25 +6671,23 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -6748,7 +6789,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -6756,7 +6797,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-15T06:58:54.097Z'
+ completed_at: '2026-08-14T13:23:14.585Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -6777,10 +6818,13 @@ paths:
display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
+ fees: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -6788,8 +6832,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1375912
- slug: product-1375912
+ name: Product 1378628
+ slug: product-1378628
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6854,14 +6898,14 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Domonique Koelpin
+ state_abbr: NY
+ name: Stanford Kemmer
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: NY
pickup_ready_in_minutes:
pickup_instructions:
delivery_rates:
@@ -6903,15 +6947,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
shipping_address:
id: addr_VqXmZF31wY
@@ -6924,25 +6966,23 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
gift_card:
market:
id: mkt_UkLWZg9DAJ
- name: United States
+ name: United States of America
currency: USD
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -6999,8 +7039,8 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY3MDVkZTBkLWE2MGUtNDFjNS1iNGRkLWI1Yjk3ZmFhODUxYiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzgwNzM0fQ.706EmC8czoCTG6x3CjslXlYuWu8wm7NXmdcw4D2jpxM
- refresh_token: AWL3JYeXYSmoTsBZni9uxP8j
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImFhYjBkN2ExLTJjZTQtNGFiMy05YTkzLTJmYzA5YzkzMTI4ZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2NzE3Mzk0fQ.xEWWor36OOmKyKjXEZ4_-J62Tt8BJdnCsHWap-Ts9uo
+ refresh_token: WshaU6ew8E54Rmh4ToDqH8cy
user:
id: cust_UkLWZg9DAJ
@@ -7017,10 +7057,10 @@ paths:
newsletter_subscriber:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:54.286Z'
- updated_at: '2026-08-15T06:58:54.288Z'
+ created_at: '2026-08-14T13:23:14.771Z'
+ updated_at: '2026-08-14T13:23:14.772Z'
verified: true
- verified_at: '2026-08-15T06:58:54Z'
+ verified_at: '2026-08-14T13:23:14Z'
customer_id: cust_UkLWZg9DAJ
customer_groups: []
schema:
@@ -7123,12 +7163,12 @@ paths:
application/json:
example:
id: cust_UkLWZg9DAJ
- first_name: Rory
- last_name: Padberg
+ first_name: Jeffry
+ last_name: Tremblay
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Rory Padberg
+ full_name: Jeffry Tremblay
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -7142,15 +7182,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
- id: addr_UkLWZg9DAJ
first_name: John
@@ -7162,15 +7200,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_abbr: NY
- country_iso: US
state_name: New York
default_billing_address:
id: addr_gbHJdmfrXB
@@ -7183,15 +7219,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
default_shipping_address:
id: addr_UkLWZg9DAJ
@@ -7204,15 +7238,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_abbr: NY
- country_iso: US
state_name: New York
newsletter_subscriber:
customer_groups: []
@@ -7272,7 +7304,7 @@ paths:
application/json:
example:
id: cust_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -7291,15 +7323,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
- id: addr_UkLWZg9DAJ
first_name: John
@@ -7311,15 +7341,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_abbr: NY
- country_iso: US
state_name: New York
default_billing_address:
id: addr_gbHJdmfrXB
@@ -7332,15 +7360,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_abbr: NY
- country_iso: US
state_name: New York
default_shipping_address:
id: addr_UkLWZg9DAJ
@@ -7353,15 +7379,13 @@ paths:
city: New York
phone: 555-555-0199
company: Company
- country_name: United States
- country_code: US
+ country_name: United States of America
+ country_iso: US
state_text: NY
- state_code: NY
+ state_abbr: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_abbr: NY
- country_iso: US
state_name: New York
newsletter_subscriber:
customer_groups: []
@@ -7471,7 +7495,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 93E81C61FB772E62
+ code: D04817FC09B6EBB2
status: active
currency: USD
amount: '10.0'
@@ -7567,7 +7591,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: D91CFDF5C1250D33
+ code: 3607BB1ED7DC02B7
status: active
currency: USD
amount: '10.0'
@@ -7639,8 +7663,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_1ae6c22731c4b8b5985a1c2b
- external_client_secret: bogus_seti_secret_ea5a717e3c94dfda
+ external_id: bogus_seti_80c86d24c4476a7841150728
+ external_client_secret: bogus_seti_secret_eb81e6a5ef28b3b0
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7739,8 +7763,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_f6886ef27b59702fec292567
- external_client_secret: seti_secret_17af02e8de63468bd0d9b1a4
+ external_id: seti_test_df2c16765f655ec067ba4e80
+ external_client_secret: seti_secret_4719e71e2323e7bd3ccabbde
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7816,8 +7840,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_08f8850d2ba99614a0a65e89
- external_client_secret: seti_secret_76a7c6630a3e148019073570
+ external_id: seti_test_747a24303dfee2d1820a2e8a
+ external_client_secret: seti_secret_e247f267bb9b7f858a5ae6d2
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8061,13 +8085,13 @@ paths:
example:
data:
- iso: DE
- iso3: DEU
+ iso3: IS5
name: Germany
states_required: false
zipcode_required: true
- iso: US
iso3: USA
- name: United States
+ name: United States of America
states_required: true
zipcode_required: true
schema:
@@ -8137,7 +8161,7 @@ paths:
example:
iso: US
iso3: USA
- name: United States
+ name: United States of America
states_required: true
zipcode_required: true
schema:
@@ -8166,7 +8190,7 @@ paths:
example:
error:
code: record_not_found
- message: record not found
+ message: Country not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/store/currencies":
@@ -8351,7 +8375,7 @@ paths:
default_locale: en
tax_inclusive: false
default: true
- country_codes:
+ country_isos:
- US
supported_locales:
- en
@@ -8359,7 +8383,7 @@ paths:
countries:
- iso: US
iso3: USA
- name: United States
+ name: United States of America
states_required: true
zipcode_required: true
- id: mkt_gbHJdmfrXB
@@ -8368,7 +8392,7 @@ paths:
default_locale: de
tax_inclusive: true
default: false
- country_codes:
+ country_isos:
- DE
- FR
supported_locales:
@@ -8376,16 +8400,16 @@ paths:
- en
- fr
countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- iso: DE
- iso3: DEU
+ iso3: IS15
name: Germany
states_required: false
zipcode_required: true
+ - iso: FR
+ iso3: IS16
+ name: France
+ states_required: false
+ zipcode_required: true
schema:
type: object
properties:
@@ -8455,7 +8479,7 @@ paths:
default_locale: de
tax_inclusive: true
default: false
- country_codes:
+ country_isos:
- DE
- FR
supported_locales:
@@ -8463,16 +8487,16 @@ paths:
- en
- fr
countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- iso: DE
- iso3: DEU
+ iso3: IS19
name: Germany
states_required: false
zipcode_required: true
+ - iso: FR
+ iso3: IS20
+ name: France
+ states_required: false
+ zipcode_required: true
schema:
type: object
'404':
@@ -8538,7 +8562,7 @@ paths:
default_locale: de
tax_inclusive: true
default: false
- country_codes:
+ country_isos:
- DE
- FR
supported_locales:
@@ -8546,16 +8570,16 @@ paths:
- en
- fr
countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- iso: DE
- iso3: DEU
+ iso3: IS23
name: Germany
states_required: false
zipcode_required: true
+ - iso: FR
+ iso3: IS24
+ name: France
+ states_required: false
+ zipcode_required: true
schema:
type: object
'404':
@@ -8565,7 +8589,7 @@ paths:
example:
error:
code: record_not_found
- message: record not found
+ message: Country not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/store/markets/{market_id}/countries":
@@ -8616,12 +8640,12 @@ paths:
example:
data:
- iso: FR
- iso3: FRA
+ iso3: IS28
name: France
states_required: false
zipcode_required: true
- iso: DE
- iso3: DEU
+ iso3: IS27
name: Germany
states_required: false
zipcode_required: true
@@ -8686,7 +8710,7 @@ paths:
example:
iso: US
iso3: USA
- name: United States
+ name: United States of America
states_required: true
zipcode_required: true
schema:
@@ -8698,7 +8722,7 @@ paths:
example:
error:
code: record_not_found
- message: record not found
+ message: Country not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/store/wishlists":
@@ -8761,7 +8785,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: kmvxGQy6B34GePDcMFg9bK1i
+ token: CTQSpUPNUtZtb4Ud2PPj8pfL
is_default: false
is_private: true
meta:
@@ -8837,7 +8861,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: WHtJv9phiodnHTD74p76Tt3x
+ token: BBR6NYLLB6v4SoinhYRxdmwE
is_default: false
is_private: true
schema:
@@ -8938,7 +8962,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: R2kcAQjKqkwzJe8au76HHnzh
+ token: 3EuAFPdcdKC4vdPWRq1bAHCN
is_default: false
is_private: true
schema:
@@ -9000,7 +9024,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: iR3Swbo4Vc29ufKdrBDGz3Yh
+ token: hC59MwX9KZFQXUmAAvT6Wwo2
is_default: false
is_private: true
schema:
@@ -9282,11 +9306,11 @@ paths:
application/json:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:58.204Z'
- updated_at: '2026-08-15T06:58:58.205Z'
+ created_at: '2026-08-14T13:23:18.983Z'
+ updated_at: '2026-08-14T13:23:18.984Z'
verified: true
- verified_at: '2026-08-15T06:58:58Z'
+ verified_at: '2026-08-14T13:23:18Z'
customer_id: cust_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9365,10 +9389,10 @@ paths:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-15T06:58:58.229Z'
- updated_at: '2026-08-15T06:58:58.235Z'
+ created_at: '2026-08-14T13:23:19.012Z'
+ updated_at: '2026-08-14T13:23:19.019Z'
verified: true
- verified_at: '2026-08-15T06:58:58Z'
+ verified_at: '2026-08-14T13:23:19Z'
customer_id:
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9538,7 +9562,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-d283591e-861c-4628-a5dc-f04a447216d2
+ slug: privacy-policy-108a3e91-9741-4750-87eb-4d891f2ad755
body: We respect your privacy.
body_html: We respect your privacy.
- id: pol_uw2YK1rnl0
@@ -9874,14 +9898,14 @@ paths:
example:
data:
- id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_94
name: Downtown
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_94
pickup_ready_in_minutes:
pickup_instructions:
servers:
@@ -10278,12 +10302,12 @@ components:
nullable: true
country_name:
type: string
- country_code:
+ country_iso:
type: string
state_text:
type: string
nullable: true
- state_code:
+ state_abbr:
type: string
nullable: true
quick_checkout:
@@ -10292,11 +10316,6 @@ components:
type: boolean
is_default_shipping:
type: boolean
- state_abbr:
- type: string
- nullable: true
- country_iso:
- type: string
state_name:
type: string
nullable: true
@@ -10312,14 +10331,12 @@ components:
- phone
- company
- country_name
- - country_code
+ - country_iso
- state_text
- - state_code
+ - state_abbr
- quick_checkout
- is_default_billing
- is_default_shipping
- - state_abbr
- - country_iso
- state_name
x-typelizer: true
AppliedPromotion:
@@ -10458,6 +10475,12 @@ components:
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
@@ -10482,6 +10505,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/AppliedPromotion"
+ fees:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Fee"
items:
type: array
items:
@@ -10548,6 +10575,8 @@ components:
- display_amount_due
- delivery_total
- display_delivery_total
+ - fee_total
+ - display_fee_total
- store_credit_total
- display_store_credit_total
- covered_by_store_credit
@@ -10556,6 +10585,7 @@ components:
- requirements
- shipping_eq_billing_address
- discounts
+ - fees
- items
- fulfillments
- payments
@@ -11105,12 +11135,6 @@ components:
type: string
member_type:
type: string
- country_code:
- type: string
- nullable: true
- state_code:
- type: string
- nullable: true
postal_code_prefix:
type: string
nullable: true
@@ -11120,21 +11144,27 @@ components:
postal_code_to:
type: string
nullable: true
+ country_iso:
+ type: string
+ nullable: true
country_name:
type: string
nullable: true
+ state_abbr:
+ type: string
+ nullable: true
state_name:
type: string
nullable: true
required:
- id
- member_type
- - country_code
- - state_code
- postal_code_prefix
- postal_code_from
- postal_code_to
+ - country_iso
- country_name
+ - state_abbr
- state_name
x-typelizer: true
DeliveryZone:
@@ -11368,10 +11398,6 @@ components:
type: array
items:
"$ref": "#/components/schemas/DeliveryRate"
- tax_lines:
- type: array
- items:
- "$ref": "#/components/schemas/TaxLine"
required:
- id
- number
@@ -11643,10 +11669,6 @@ components:
type: array
items:
"$ref": "#/components/schemas/DigitalLink"
- tax_lines:
- type: array
- items:
- "$ref": "#/components/schemas/TaxLine"
required:
- id
- variant_id
@@ -11711,7 +11733,7 @@ components:
type: boolean
default:
type: boolean
- country_codes:
+ country_isos:
type: array
items:
type: string
@@ -11730,7 +11752,7 @@ components:
- default_locale
- tax_inclusive
- default
- - country_codes
+ - country_isos
- supported_locales
x-typelizer: true
Media:
@@ -11982,6 +12004,12 @@ components:
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
@@ -11994,6 +12022,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/AppliedPromotion"
+ fees:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Fee"
items:
type: array
items:
@@ -12057,10 +12089,13 @@ components:
- display_amount_due
- delivery_total
- display_delivery_total
+ - fee_total
+ - display_fee_total
- store_credit_total
- display_store_credit_total
- covered_by_store_credit
- discounts
+ - fees
- items
- fulfillments
- payments
@@ -12820,6 +12855,9 @@ components:
properties:
id:
type: string
+ state_abbr:
+ type: string
+ nullable: true
name:
type: string
address1:
@@ -12831,15 +12869,12 @@ components:
zipcode:
type: string
nullable: true
- country_code:
+ country_iso:
type: string
nullable: true
country_name:
type: string
nullable: true
- state_code:
- type: string
- nullable: true
state_text:
type: string
nullable: true
@@ -12851,13 +12886,13 @@ components:
nullable: true
required:
- id
+ - state_abbr
- name
- address1
- city
- zipcode
- - country_code
+ - country_iso
- country_name
- - state_code
- state_text
- pickup_ready_in_minutes
- pickup_instructions
@@ -12899,20 +12934,6 @@ components:
- display_amount_remaining
- currency
x-typelizer: true
- TaxIdentifier:
- type: object
- properties:
- id:
- type: string
- kind:
- type: string
- value:
- type: string
- required:
- - id
- - kind
- - value
- x-typelizer: true
TaxLine:
type: object
properties:
diff --git a/docs/plans/6.0-duties-and-custom-fees.md b/docs/plans/6.0-duties-and-custom-fees.md
new file mode 100644
index 0000000000..b0fa8c4553
--- /dev/null
+++ b/docs/plans/6.0-duties-and-custom-fees.md
@@ -0,0 +1,99 @@
+# Duties & Custom Fees
+
+**Status:** 6.0 scope implemented (2026-08-14); 6.1 provider gem pending
+**Target:** Spree 6.0 (core plumbing) / 6.1 (landed-cost provider gem)
+**Depends on:** `6.0-6.1-split-adjustments.md` (typed `Fee`/`TaxLine` rows — shipped), `6.0-tax-provider.md`, `6.0-integrations-admin.md`, `6.0-delivery-rate-provider.md` (EasyPost provider gem)
+**Author:** Damian Legawiec
+**Last updated:** 2026-08-14
+
+> **Shipped (2026-08-14):** all 6.0 plumbing — `hs_code`/`country_of_origin`/`customs_description` on `spree_variants` (normalized + format-validated, admin API/CSV write paths, and both dashboard editors: the per-variant sheet and the bulk spreadsheet), `duty` fee kind, `fees` + `fee_total` on the Store API cart and order, and the EasyPost customs declaration on both quotes and label purchases with an `incoterm` preference. Deferred from this pass: the internal tax provider's `duty` exclusion (that code is not yet merged to main — see Open Questions).
+
+## Summary
+
+Cross-border orders carry charges that are neither product price, delivery, nor sales tax: customs duties, brokerage and disbursement fees, and import VAT levied on top of the duty itself. Today Spree has no way to classify goods for customs (no HS code or country of origin anywhere), no way to show a shopper an itemized fee at checkout (the Store API exposes neither `fees` nor `fee_total`), and the EasyPost provider buys international labels with an empty customs declaration. This plan closes those gaps on top of the already-shipped typed `Fee` row: customs classification fields on the variant with the EasyPost customs declaration as their first consumer, a `duty` fee kind whose rows snapshot their calculation inputs, Store API visibility for fees, and a landed-cost estimation path that rides the existing `Spree.adjusters` registry + `Spree::Integration` credential surface rather than a new engine in core. A survey of the hosted market leader and the three OSS platforms (2026-08-14) shaped the design; the notable finding is that none of the OSS platforms has a usable duties story, and the hosted leader has no merchant-writable fee primitive at all — so finishing our fee surface is differentiation, not parity work.
+
+## Key Decisions (do not deviate without discussion)
+
+- **A duty is a `Fee` with `kind: 'duty'`, never a `TaxLine` and never a new table.** Duties are a customs charge, not a sales tax — recording them as tax lines corrupts tax reporting and filings (the trap one OSS platform's percentage-only tax interface forces). The `Fee` row already rolls into `fee_total`/`adjustment_total`, participates in refund math, and is line-item- or order-level-scopable. Import VAT *on* a duty works today via `TaxLine#fee_id` — the same shape the hosted leader models as tax lines on its duty object.
+- **Duty rows snapshot their calculation inputs in `metadata`** (`hs_code`, `country_of_origin`, `rate`, provider identifier, estimate vs. guaranteed). Order history must not shift when the catalog is re-classified; the hosted leader's duty object snapshots identically rather than referencing the product.
+- **Classification lives on the variant as plain columns (2026-08-14).** The variant is our stock-keeping entity (weight, dimensions, cost price already live there), matching where both platforms that store customs data put it. Product-level fallback and custom-field modeling were both considered and rejected: fallback doubles the admin/CSV surface for the same declaration, and custom fields give untyped, unvalidated values invisible to typed serializers. Accepted trade-off: multi-variant products repeat the same values per variant; bulk editing and CSV import are the answer, not a second storage level.
+- **Columns must ship with a consumer.** One OSS platform has carried `hs_code`/`origin_country` columns for years that nothing reads — inert fields deliver nothing. Our first consumer is the EasyPost provider building a customs declaration (CustomsInfo/CustomsItems) for international label purchase; today it sends `customs_info: null`.
+- **Core ships no duty calculation engine and no landed-cost guarantee.** Guaranteed landed cost requires being importer of record — a service business, not a code path (even the hosted leader resells a merchant-of-record service for it). Estimation belongs to provider gems behind the existing extension points; core ships the data model, the fee kind, and the storefront visibility.
+- **Duties enter the cart through `Spree.adjusters` (2026-08-14).** A provider gem registers a `Spree::Adjusters::Base` subclass that writes/refreshes `Fee(kind: 'duty')` rows during recalculation — zero new machinery, and the two-pass ordering already puts fees before tax estimation so import VAT lands on the duty. Extending the tax provider was rejected (couples duty availability to the merchant's tax-engine choice and blurs the duty-is-not-tax boundary); a dedicated duty-provider contract was rejected as speculative machinery — per the service-workflows doctrine it graduates only when a real provider gem proves the need for estimate/commit/void lifecycle calls. Accepted trade-off: no commit/void lifecycle for customs transactions until then.
+- **The internal tax provider excludes `kind: 'duty'` fees from its default taxing set (2026-08-14).** Domestic sales tax stacked on a customs duty is wrong in most regimes and double-counts once a duties provider writes its own import-VAT `TaxLine(fee_id: …)` rows. Duty fees are taxed only by provider-written tax lines. Accepted trade-off: a kind-based special case inside `TaxProvider::Internal`; other fee kinds stay taxed as before.
+- **Release split settled (2026-08-14): plumbing ships in 6.0, estimation in 6.1.** 6.0 = variant customs fields, `duty` fee kind, Store API fee exposure, EasyPost customs declaration + shipping-terms (incoterm) option. 6.1 = the landed-cost provider gem and the `Spree::Market` shipping-terms setting. Everything-in-6.0 was rejected for schedule risk on the least-proven piece; everything-in-6.1 was rejected because 6.0 would otherwise ship international labels with empty customs declarations and keep every fee kind invisible to shoppers.
+- **Fees become visible on the Store API** (`fees` array + `fee_total`/`display_fee_total` on cart and order serializers). Itemized display is a legal expectation for cross-border charges and the delivery channel for every fee use case (surcharge, COD, handling) — currently the store serializers expose only aggregate adjustment totals.
+- **Collecting duties at checkout must stay linked to duty-paid shipping.** Charging the customer at checkout and then shipping under terms where the carrier collects again double-charges them. Any future "collect duties" toggle is scoped to methods/labels that support duty-paid terms; until a provider gem exists, duty fees are admin-written and the burden is on the merchant.
+- **Shipping-terms selection (who is importer of record) is deferred** to the provider-gem phase; its future home is a `Spree::Market` setting, not a global.
+
+## Design Details
+
+### 1. Customs classification on the variant
+
+New columns on `spree_variants`:
+
+- `hs_code` (string, nullable) — 6–13 digit Harmonized System code, digits only, validated by format when present. One global code; per-destination overrides are a provider-gem concern if ever needed.
+- `country_of_origin` (string, nullable) — ISO 3166-1 alpha-2.
+- `customs_description` (string, nullable) — plain-language contents description for the declaration; falls back to the product name.
+
+`hs_code` is normalized to digits only and `country_of_origin` upcased, so a merchant pasting `6404.11` or `vn` stores the canonical value; the dashboard mirrors both normalizations client-side (`normalize-customs.ts`, shared by the variant edit sheet and the bulk editor) so a dotted tariff code pasted from a broker's spreadsheet is accepted rather than bounced by the format validation.
+
+**`country_of_origin` stores an ISO 3166-1 alpha-2 code, never a country record id**, and every picker is bound to ISO accordingly (the edit sheet's `CountryCombobox`, the bulk editor's select cell). Customs classification has to outlive the `spree_countries` table, which is slated for removal — an id would dangle, a code will not. It is also what carriers expect on the declaration, so no lookup sits between the stored value and the EasyPost payload. Readers on `Spree::Variant` fall back to the product-type/product level only if a later plan adds it there — in 6.0 they are variant-local. Admin API v3 variant endpoints permit and serialize the three fields (admin serializer only — the Store API never exposes customs data); note the nested `Admin::Products::VariantsController` enumerates `permitted_params` itself rather than reading the shared allowlist, so both lists need the fields. CSV import columns follow. No validation requires them: customs data is optional until an international label or a duties provider needs it, at which point the consumer raises its own actionable error.
+
+### 2. `duty` fee kind
+
+- `Spree::Fee::KINDS` gains `'duty'`.
+- Duty fees attach to line items when computed per item (the normal case — ad-valorem duty is per classified good) and may be order-level for lump-sum brokerage/disbursement charges (those may also use kind `'surcharge'` with a label).
+- `metadata` on a duty row records the snapshot: `hs_code`, `country_of_origin`, `rate`, `provider`, `guaranteed` (boolean). Nothing reads these for money math — they are the audit trail.
+- Dashboard: the existing order fee card renders the new kind via the `admin.orders.detail.adjustment_lines.fee_kind_duty` key (all locale files); the add-fee dialog offers it. No new UI.
+
+### 3. Store API fee exposure
+
+- `Spree::Api::V3::CartSerializer` and `OrderSerializer` gain `fee_total` / `display_fee_total` (money attributes, `hide_prices`-aware) and a `fees` association rendered with the existing store `FeeSerializer` (label, kind, amount, display_amount, line_item_id, fulfillment_id). `Spree::Order` was missing `fee_total` from its `money_methods` (Cart already had it) — added, or `display_fee_total` would not exist post-placement.
+- The **admin** cart and order serializers drop the inherited `fees` association rather than redeclaring it: fees reach the admin through their own `/orders/:id/fees` endpoint, which is also the write path, and an admin serializer must never render a store serializer.
+- Storefronts group and label fees themselves (e.g. one "Duties & import fees" line summing `kind: 'duty'` rows) — core provides itemized data, not presentation.
+- Full type pipeline follows (typelizer → Zod → integration specs → OpenAPI → SDK).
+
+### 4. EasyPost customs declaration (first consumer)
+
+The EasyPost fulfillment provider builds a customs declaration when origin and destination countries differ: one customs item per package line (description from `customs_description` → product name, quantity, value from the line's price, weight, `hs_code`, `origin_code` from `country_of_origin`), attached to the shipment at creation — EasyPost then produces the customs forms with the label. Missing weight or classification degrades exactly as EasyPost does (carrier-dependent — some accept declarations without HS codes); label-purchase errors surface loudly per the existing "label leads, fulfilled follows" doctrine. Contents type/restriction, customs signer, and the shipping-terms (incoterm) shipment option are `SpreeEasyPost::Integration` preferences; duty-paid billing is carrier-dependent and passes through as configuration. The incoterm preference is validated against EasyPost's enum and defaults to **DAP** (recipient pays on arrival) — `DDU` is not an accepted value despite being the common industry shorthand, and EasyPost's own default is DDP, which would silently bill the merchant for duties nobody collected. The declaration goes on rate quotes as well as label purchases, since international rates depend on declared contents. Note the boundary: EasyPost carries declarations and routes the carrier's actual duty bill under duty-paid terms — it estimates nothing, so it is a consumer of the classification fields, never a duties provider.
+
+### 5. Landed-cost estimation path (provider gems, 6.1)
+
+A duties provider gem ships the established pair:
+
+- `Spree::Integrations::<Provider>` — credentials, `can_connect?`, admin-managed via the integrations gallery.
+- A `Spree::Adjusters::Base` subclass registered in `Spree.adjusters` — during `Carts::RecalculateTotals` it reads the destination (ship address / market), each line's variant classification, and writes/refreshes line-scoped `Fee(kind: 'duty')` rows plus any import-VAT `TaxLine(fee_id: …)` rows carrying its `provider_id`.
+
+The two-pass recalculate ordering already fits: adjusters persist fees before the tax provider estimates, so duty exists when import VAT is computed. Caching against external calls is the adjuster's responsibility (the same discipline the delivery-rate provider applies). If a provider needs post-placement lifecycle calls (commit/void on the customs transaction), that graduates it toward the tax-provider-style contract — decided when the first gem is built, not speculatively.
+
+### 6. Internal tax provider and duty fees
+
+`Spree::TaxProvider::Internal` excludes `kind: 'duty'` rows from its default fee-taxing set (see Key Decisions). Import VAT on a duty exists only when a duties provider writes `TaxLine(fee_id: …)` rows alongside its duty fees, stamped with its `provider_id`.
+
+## Migration Path
+
+1. **6.0** — additive migration for the three `spree_variants` columns; `duty` kind + locale keys; store serializer fee exposure + type pipeline; EasyPost customs declaration. No data migration: all fields start empty, no existing rows change meaning.
+2. **6.1** — first landed-cost provider gem under `spree/providers/`; shipping-terms setting on `Spree::Market` if the gem needs it; per-destination HS codes only if a provider demands them.
+
+## Constraints on Current Work
+
+- New fee-producing code must write typed `Fee` rows through the adjusters registry or the order-locked fee services — never bespoke totals math (restates `6.0-6.1-split-adjustments.md`).
+- Nothing outside a duty row's `metadata` snapshot may read variant classification for money math on an existing order — recalculation of a completed order must not re-derive duty from the live catalog.
+- Store-serializer work touching cart/order money fields should not assume fees stay hidden — `fee_total` and `fees` are becoming public surface.
+- The EasyPost provider must not require customs fields for domestic shipments; international-only, degrade like the carrier API does.
+
+## Open Questions
+
+The four design questions raised by the draft (classification placement, duty write path, internal taxation of duty fees, release split) were all resolved on 2026-08-14 and moved to Key Decisions. What remains:
+
+1. **Excluding `kind: 'duty'` from `TaxProvider::Internal`'s default fee-taxing set is decided but NOT yet implemented** — that provider code is not merged to main. Unblocked by: the tax-provider branch landing. Until then a duty fee written on a store using the internal engine would be taxed like any other fee; nothing writes duty fees automatically yet, so nothing is wrong today.
+2. Deferred to the 6.1 provider-gem phase, with the gem as the unblocker: per-destination HS code overrides, the `Spree::Market` shipping-terms setting, and whether the adjuster path needs commit/void lifecycle calls.
+
+## References
+
+- `docs/plans/6.0-6.1-split-adjustments.md` — the `Fee`/`TaxLine` substrate this builds on (its manual-fee list already names customs as a fee use case)
+- `docs/plans/6.0-tax-provider.md` — provider/Integration pairing pattern, per-market provider selection
+- `docs/plans/6.0-integrations-admin.md` — credential surface for provider gems
+- `docs/plans/6.0-delivery-rate-provider.md` — EasyPost provider gem this extends with customs declarations
+- Platform survey 2026-08-14 (private session notes; per repository policy the survey itself stays out of the repo)
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 4d30a5c65b..06aecf7be7 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -2796,3 +2796,32 @@ span ingestion. The starter's own sentry initializer encapsulates the whole
recipe behind an env var (e.g. `SENTRY_OTLP_ENABLED=true`) so container
users still flip it without code. Docs:
`docs/developer/deployment/telemetry.mdx`.
+
+## 2026-08-14 — Duties are fees, not tax lines; landed cost is a provider gem, not core
+
+**Decision:** Customs duties are modeled as `Spree::Fee` rows with `kind:
+'duty'` — never `TaxLine` rows and never a new table. Duty rows snapshot their
+calculation inputs (`hs_code`, `country_of_origin`, `rate`, provider,
+guaranteed flag) in `metadata`, so re-classifying the catalog never rewrites
+order history. Classification lives as three plain nullable columns on
+`spree_variants` (`hs_code`, `country_of_origin`, `customs_description`),
+shipped together with their first consumer: the EasyPost provider's customs
+declaration on international label purchase (today it sends `customs_info:
+null`). Fees become shopper-visible — the Store API cart/order serializers
+gain `fees` + `fee_total`. Duty estimation enters the cart exclusively through
+`Spree.adjusters` (a provider gem's adjuster writes the duty fee rows during
+recalculation); core ships no calculation engine and no landed-cost guarantee
+— a guarantee requires being importer of record, which is a service business,
+not a code path. The internal tax provider excludes `kind: 'duty'` from its
+default fee-taxing set: import VAT on a duty exists only as provider-written
+`TaxLine(fee_id: …)` rows, preventing domestic tax stacking and
+double-counting. Plumbing ships in 6.0; the landed-cost provider gem and a
+`Spree::Market` shipping-terms setting are 6.1.
+
+**Consequences:** No duty math against the live catalog on existing orders —
+the `metadata` snapshot is the source of truth. New fee-producing code writes
+typed `Fee` rows via adjusters or the order-locked fee services. Store
+serializer work must not assume fees stay hidden. A dedicated duty-provider
+contract (estimate/commit/void) is deliberately NOT built — it graduates only
+if the first provider gem proves the need. Plan:
+`6.0-duties-and-custom-fees.md`.
diff --git a/packages/admin-sdk/src/types/generated/Cart.ts b/packages/admin-sdk/src/types/generated/Cart.ts
index 3f6d094206..3b5cc775ec 100644
--- a/packages/admin-sdk/src/types/generated/Cart.ts
+++ b/packages/admin-sdk/src/types/generated/Cart.ts
@@ -1,4 +1,4 @@
-// Typelizer digest ebc56cd39d3335ec091de729dbed68ee
+// Typelizer digest 5717facc24acf40387c791698a13996d
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {LineItem, Address, Market, AppliedPromotion} from '@/types'
@@ -37,6 +37,8 @@ interface Cart {
display_amount_due: string | null;
delivery_total: string | null;
display_delivery_total: string | null;
+ fee_total: string | null;
+ display_fee_total: string | null;
store_credit_total: string | null;
display_store_credit_total: string | null;
covered_by_store_credit: boolean;
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index fec655fbfa..f09e660e47 100644
--- a/packages/admin-sdk/src/types/generated/Order.ts
+++ b/packages/admin-sdk/src/types/generated/Order.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2e2618d1b70cf93bc0457d029f9c8869
+// Typelizer digest 75df61bd2909865db37451955d869747
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {LineItem, Fulfillment, Payment, Address, GiftCard, Market, AppliedPromotion, Cart, Channel, StockLocation, PaymentMethod, Customer, Return, Exchange, Claim} from '@/types'
@@ -38,6 +38,8 @@ interface Order {
display_amount_due: string;
delivery_total: string;
display_delivery_total: string;
+ fee_total: string | null;
+ display_fee_total: string | null;
store_credit_total: string;
display_store_credit_total: string;
covered_by_store_credit: boolean;
@@ -61,8 +63,6 @@ interface Order {
created_at: string;
updated_at: string;
preferred_stock_location_id: string | null;
- company_location_id: string | null;
- company_id: string | null;
tags: Array<string>;
internal_note: string | null;
internal_note_html: string | null;
diff --git a/packages/admin-sdk/src/types/generated/Variant.ts b/packages/admin-sdk/src/types/generated/Variant.ts
index 31f61b321f..93b5818954 100644
--- a/packages/admin-sdk/src/types/generated/Variant.ts
+++ b/packages/admin-sdk/src/types/generated/Variant.ts
@@ -1,4 +1,4 @@
-// Typelizer digest d796ffae294976865ef0fdb4ec0a4f34
+// Typelizer digest 7cc8ed65c8fcb83f7ce9e199a1b59cf6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Price, PriceHistory, Media, OptionValue, CustomField, StockItem} from '@/types'
@@ -35,6 +35,9 @@ interface Variant {
weight_unit: string | null;
dimensions_unit: string | null;
backorder_limit: number | null;
+ hs_code: string | null;
+ country_of_origin: string | null;
+ customs_description: string | null;
deleted_at: string | null;
created_at: string;
updated_at: string;
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index e498157683..cba58526f8 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"],"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"},"currency":{"type":"string","description":"ISO currency code for the store."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code for the store."}}}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies a product under the category (appended to the end).\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}":{"delete":{"summary":"Remove a product from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the category's manual classification.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"category_id":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resume":{"patch":{"summary":"Resume a canceled order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a previously canceled order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices, no product_ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids to seed the list with."},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server alternative to `product_ids`: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)`. Mix-and-match with `product_ids` is supported but typically unnecessary — `prices` alone tells the server which variants belong to the list and what the override amount is.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids — reconciles list membership (adds + removes)."},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store_credit_categories":{"get":{"summary":"List store credit categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured store credit categories. Categories classify\nstore credits (e.g., \"Goodwill\", \"Gift Card\", \"Refund\") and surface\nin the admin UI as a dropdown when issuing or editing a store\ncredit. Category names matching `Spree::Config[:non_expiring_credit_types]`\nare flagged via `non_expiring: true`.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credit_categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Store credit category ID","schema":{"type":"string"}}],"get":{"summary":"Get a store credit category","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single store credit category by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCreditCategory"}}}},"404":{"description":"store credit category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates a product into the collection (appended to the end).\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}":{"delete":{"summary":"Remove a product from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the collection's manual curation.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/locations":{"get":{"summary":"List company locations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the branches of a business customer. Each branch owns its own addresses and the buyers authorised to purchase for it.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a branch. Addresses are supplied inline and belong to the branch, so editing one later changes the branch's own record rather than an address the buyer also uses.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"location created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"Created inline and owned by the branch.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"}}}},"required":["name"]}}}}}},"/api/v3/admin/company_locations/{id}":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Branches are addressed by their own id once you hold one — the company id is not needed.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"location found","content":{"application/json":{}}}}},"patch":{"summary":"Update a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Address fields sent here edit the branch's existing address in place; send only what changes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"200":{"description":"location updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_address":{"type":"object","properties":{"city":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the branch, its buyers and the addresses it owned.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"204":{"description":"location deleted"}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a business customer. Exemption certificates and tax registrations hang off it.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","nullable":true,"description":"Your own reference for this business, unique within the store."}},"required":["name"]}}}}}},"/api/v3/admin/company_locations/{company_location_id}/contacts":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_location_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company contacts","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customers authorised to purchase for a branch. A customer may act for more than one branch.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"contacts found","content":{"application/json":{}}}}},"post":{"summary":"Create a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Authorises a customer to purchase for a branch. A customer who acts for exactly one branch has\ntheir orders attributed to it automatically; one who acts for several needs the branch set on\nthe order, because guessing would invoice the wrong business.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"contact created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"role":{"type":"string","description":"Free-form label; carries no permissions in 6.0."}},"required":["customer_id"]}}}}}},"/api/v3/admin/company_contacts/{id}":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"contact found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws the customer's authority to purchase for the branch. The customer account itself is untouched.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"204":{"description":"contact deleted"}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the vendor error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true}},"required":["id","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","number","token","email","customer_note","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CompanyContact":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_location_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true}},"required":["id","role","created_at","updated_at","company_location_id","customer_id","email"],"x-typelizer":true},"CompanyLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"contacts_count":{"type":"number"},"billing_address":{"$ref":"#/components/schemas/Address"},"shipping_address":{"$ref":"#/components/schemas/Address"},"company_contacts":{"type":"array","items":{"$ref":"#/components/schemas/CompanyContact"}}},"required":["id","name","external_id","metadata","created_at","updated_at","company_id","contacts_count","billing_address","shipping_address"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"locations_count":{"type":"number"},"company_locations":{"type":"array","items":{"$ref":"#/components/schemas/CompanyLocation"}}},"required":["id","name","external_id","metadata","created_at","updated_at","locations_count"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","created_at","updated_at","deleted_at","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"tracking_carrier":{"type":"string","nullable":true},"tracking_carrier_name":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"tracking_status":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"tracking_details":{"type":"object","nullable":true},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","tracking_carrier","tracking_carrier_name","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","tracking_status","estimated_delivery_at","delivered_at","items","metadata","tracking_details","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","created_at","updated_at","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"viewable_id":{"type":"string"},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string"}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","created_at","updated_at","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"company_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","number","email","customer_note","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","company_location_id","company_id","tags","internal_note","internal_note_html","approver_id","canceler_id","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","amount","display_amount","status","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","product_type_id","tax_category_id"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockItem":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","created_at","updated_at"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_item_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_item_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCreditCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"non_expiring":{"type":"boolean"}},"required":["id","name","created_at","updated_at","non_expiring"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"category_id":{"type":"string","nullable":true},"category_name":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id","category_id","category_name"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/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"],"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"},"currency":{"type":"string","description":"ISO currency code for the store."},"country_iso":{"type":"string","description":"ISO 3166-1 alpha-2 country code for the store."}}}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies a product under the category (appended to the end).\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}":{"delete":{"summary":"Remove a product from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the category's manual classification.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_abbr":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"category_id":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_isos` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_isos":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_isos"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_isos` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_isos":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resume":{"patch":{"summary":"Resume a canceled order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a previously canceled order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices, no product_ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids to seed the list with."},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server alternative to `product_ids`: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)`. Mix-and-match with `product_ids` is supported but typically unnecessary — `prices` alone tells the server which variants belong to the list and what the override amount is.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids — reconciles list membership (adds + removes)."},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store_credit_categories":{"get":{"summary":"List store credit categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured store credit categories. Categories classify\nstore credits (e.g., \"Goodwill\", \"Gift Card\", \"Refund\") and surface\nin the admin UI as a dropdown when issuing or editing a store\ncredit. Category names matching `Spree::Config[:non_expiring_credit_types]`\nare flagged via `non_expiring: true`.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credit_categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Store credit category ID","schema":{"type":"string"}}],"get":{"summary":"Get a store credit category","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single store credit category by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCreditCategory"}}}},"404":{"description":"store credit category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_abbr":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates a product into the collection (appended to the end).\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}":{"delete":{"summary":"Remove a product from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the collection's manual curation.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_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_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the vendor error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_iso":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_name":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true}},"required":["id","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_iso","state_text","state_abbr","quick_checkout","is_default_billing","is_default_shipping","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","number","token","email","customer_note","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["iso","iso3","name","states_required","zipcode_required","created_at","updated_at"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","created_at","updated_at","deleted_at","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","postal_code_prefix","postal_code_from","postal_code_to","country_iso","country_name","state_abbr","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"tracking_carrier":{"type":"string","nullable":true},"tracking_carrier_name":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"tracking_status":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"metadata":{"type":"object"},"tracking_details":{"type":"object","nullable":true},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","tracking_carrier","tracking_carrier_name","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","tracking_status","estimated_delivery_at","delivered_at","items","metadata","tracking_details","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","created_at","updated_at","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_isos","supported_locales","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"viewable_id":{"type":"string"},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string"}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","created_at","updated_at","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","number","email","customer_note","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","tags","internal_note","internal_note_html","approver_id","canceler_id","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","amount","display_amount","status","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","product_type_id","tax_category_id"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["abbr","name","created_at","updated_at"],"x-typelizer":true},"StockItem":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"state_abbr":{"type":"string","nullable":true},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","state_abbr","name","address1","city","zipcode","country_iso","country_name","state_text","pickup_ready_in_minutes","pickup_instructions","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","created_at","updated_at"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_item_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_item_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCreditCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"non_expiring":{"type":"boolean"}},"required":["id","name","created_at","updated_at","non_expiring"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"category_id":{"type":"string","nullable":true},"category_name":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id","category_id","category_name"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","created_at","updated_at"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
diff --git a/packages/dashboard-core/src/components/country-combobox.tsx b/packages/dashboard-core/src/components/country-combobox.tsx
index 535595eafe..e57e27b360 100644
--- a/packages/dashboard-core/src/components/country-combobox.tsx
+++ b/packages/dashboard-core/src/components/country-combobox.tsx
@@ -25,7 +25,11 @@ export type CountryOption = { iso: string; iso3: string; name: string }
* stable ISO code), falling back to the API's backend-locale `name` when the
* runtime lacks coverage.
*/
-function useCountryDisplayName() {
+/**
+ * Localized country name with the API's own name as fallback. Exported so
+ * every country-labelled surface (pickers, grid cells) reads the same.
+ */
+export function useCountryDisplayName() {
const displayName = useDisplayName('region')
return (country: CountryOption) => displayName(country.iso) ?? country.name
}
diff --git a/packages/dashboard-ui/src/spree/bulk-variants-table.tsx b/packages/dashboard-ui/src/spree/bulk-variants-table.tsx
index 5e1b735ffc..c9714e5fc4 100644
--- a/packages/dashboard-ui/src/spree/bulk-variants-table.tsx
+++ b/packages/dashboard-ui/src/spree/bulk-variants-table.tsx
@@ -17,6 +17,10 @@ export interface BulkVariantsRow {
preorderable?: boolean
backorderLimit?: string | null
taxCategoryId?: string | null
+ hsCode?: string | null
+ /** ISO 3166-1 alpha-2 code, never a country record id. */
+ countryOfOrigin?: string | null
+ customsDescription?: string | null
}
export type BulkVariantsField =
@@ -31,6 +35,9 @@ export type BulkVariantsField =
| 'preorderable'
| 'backorderLimit'
| 'taxCategoryId'
+ | 'hsCode'
+ | 'countryOfOrigin'
+ | 'customsDescription'
export type BulkVariantsChange =
| { field: Exclude<BulkVariantsField, 'preorderable'>; value: string | null }
@@ -50,12 +57,17 @@ export interface BulkVariantsTableLabels {
preorderable: string
backorderLimit: string
taxCategory: string
+ hsCode: string
+ countryOfOrigin: string
+ customsDescription: string
/** Placeholder for a variant row with no options text (e.g. "Default"). */
variantDefault: string
/** Shown in unit cells with no explicit value ("inherit the default"). */
unitDefault: string
/** Shown in the tax-category cell when none is set. */
taxCategoryNone: string
+ /** Shown in the country-of-origin cell when none is set. */
+ countryOfOriginNone: string
/** Aria label on the DataGrid for screen readers. */
gridAriaLabel?: string
}
@@ -68,6 +80,12 @@ export interface BulkVariantsTableProps {
dimensionUnitOptions: ReadonlyArray<{ value: string; label: string }>
/** Omit to hide the tax-category column (no tax categories configured). */
taxCategoryOptions?: ReadonlyArray<{ value: string; label: string }>
+ /**
+ * Countries as `{ value: ISO, label: name }`. Omit to hide the customs
+ * columns entirely (e.g. the country list has not loaded yet). Values are
+ * ISO codes so the stored data survives the countries table going away.
+ */
+ countryOptions?: ReadonlyArray<{ value: string; label: string }>
/** Called when the user commits a value to a cell. The id is the row id. */
onChange: (rowId: string, change: BulkVariantsChange) => void
}
@@ -97,13 +115,14 @@ export function BulkVariantsTable({
weightUnitOptions,
dimensionUnitOptions,
taxCategoryOptions,
+ countryOptions,
onChange,
}: BulkVariantsTableProps) {
const columns = useMemo<ColumnDef<BulkVariantsRow>[]>(() => {
// Keyboard column coordinates, fixed per column: variant label is
// read-only (unregistered), then sku=1, barcode=2, weight=3, unit=4,
// height=5, width=6, depth=7, unit=8, preorderable=9, backorder=10,
- // tax=11.
+ // tax=11, hs code=12, origin=13, customs description=14.
const numericHeader = (label: string) => () => <span className="block text-right">{label}</span>
const rowLabel = (r: BulkVariantsRow) => r.variantLabel ?? labels.variantDefault
@@ -224,6 +243,55 @@ export function BulkVariantsTable({
})
}
+ // Customs columns travel together — classification is only meaningful
+ // alongside the origin it is declared with.
+ if (countryOptions) {
+ defs.push(
+ {
+ id: 'hs_code',
+ header: labels.hsCode,
+ cell: ({ row }) => (
+ <TextCell
+ coords={{ row: row.index, col: 12 }}
+ value={row.original.hsCode ?? null}
+ onChange={(next) => onChange(row.original.id, { field: 'hsCode', value: next })}
+ ariaLabel={`${labels.hsCode} — ${rowLabel(row.original)}`}
+ />
+ ),
+ },
+ {
+ id: 'country_of_origin',
+ header: labels.countryOfOrigin,
+ cell: ({ row }) => (
+ <SelectCell
+ coords={{ row: row.index, col: 13 }}
+ value={row.original.countryOfOrigin ?? null}
+ options={countryOptions}
+ nullLabel={labels.countryOfOriginNone}
+ onChange={(next) =>
+ onChange(row.original.id, { field: 'countryOfOrigin', value: next })
+ }
+ ariaLabel={`${labels.countryOfOrigin} — ${rowLabel(row.original)}`}
+ />
+ ),
+ },
+ {
+ id: 'customs_description',
+ header: labels.customsDescription,
+ cell: ({ row }) => (
+ <TextCell
+ coords={{ row: row.index, col: 14 }}
+ value={row.original.customsDescription ?? null}
+ onChange={(next) =>
+ onChange(row.original.id, { field: 'customsDescription', value: next })
+ }
+ ariaLabel={`${labels.customsDescription} — ${rowLabel(row.original)}`}
+ />
+ ),
+ },
+ )
+ }
+
// Reorder to visual sequence: the coordinate map above is stable, but
// the defs array built column groups out of order for concision.
const order = [
@@ -239,9 +307,19 @@ export function BulkVariantsTable({
'preorderable',
'backorder_limit',
'tax_category',
+ 'hs_code',
+ 'country_of_origin',
+ 'customs_description',
]
return defs.sort((a, b) => order.indexOf(a.id as string) - order.indexOf(b.id as string))
- }, [onChange, labels, weightUnitOptions, dimensionUnitOptions, taxCategoryOptions])
+ }, [
+ onChange,
+ labels,
+ weightUnitOptions,
+ dimensionUnitOptions,
+ taxCategoryOptions,
+ countryOptions,
+ ])
return (
<div className="overflow-x-auto">
@@ -249,7 +327,7 @@ export function BulkVariantsTable({
rows={rows}
columns={columns}
getRowId={(row) => row.id}
- className="min-w-[1100px]"
+ className={countryOptions ? 'min-w-[1500px]' : 'min-w-[1100px]'}
aria-label={labels.gridAriaLabel}
/>
</div>
diff --git a/packages/dashboard/src/components/spree/products/bulk-variants-dialog.tsx b/packages/dashboard/src/components/spree/products/bulk-variants-dialog.tsx
index 0a1d85f690..e3efe98bcf 100644
--- a/packages/dashboard/src/components/spree/products/bulk-variants-dialog.tsx
+++ b/packages/dashboard/src/components/spree/products/bulk-variants-dialog.tsx
@@ -1,3 +1,4 @@
+import { useCountries, useCountryDisplayName } from '@spree/dashboard-core'
import {
type BulkVariantsChange,
type BulkVariantsRow,
@@ -15,6 +16,7 @@ import { useTranslation } from 'react-i18next'
import { useOptionTypes } from '../../../hooks/use-option-types'
import { useTaxCategories } from '../../../hooks/use-tax-categories'
import type { ProductFormValues, VariantFormValues } from '../../../schemas/product'
+import { normalizeCustomsDescription, normalizeHsCode } from './normalize-customs'
import { composeOptionsText } from './variants-matrix'
const WEIGHT_UNITS = ['g', 'kg', 'lb', 'oz'] as const
@@ -46,6 +48,19 @@ export function BulkVariantsDialog({ form, open, onOpenChange }: Props) {
const optionTypes = useMemo(() => optionTypesData?.data ?? [], [optionTypesData])
const { data: taxCategoriesResponse } = useTaxCategories()
const taxCategories = taxCategoriesResponse?.data ?? []
+ const { countries } = useCountries()
+ const countryName = useCountryDisplayName()
+
+ // ISO codes as values — customs data must survive the countries table, and
+ // a country record id would not.
+ const countryOptions = useMemo(
+ () =>
+ countries.map((country) => ({
+ value: country.iso,
+ label: countryName({ iso: country.iso, iso3: country.iso3, name: country.name }),
+ })),
+ [countries, countryName],
+ )
// Snapshot the variants when the dialog opens so Cancel can restore them.
// Deep-clone — `form.getValues` returns references into RHF's internal
@@ -92,6 +107,9 @@ export function BulkVariantsDialog({ form, open, onOpenChange }: Props) {
preorderable: !!v.preorderable,
backorderLimit: v.backorder_limit != null ? String(v.backorder_limit) : null,
taxCategoryId: v.tax_category_id ?? null,
+ hsCode: v.hs_code ?? null,
+ countryOfOrigin: v.country_of_origin ?? null,
+ customsDescription: v.customs_description ?? null,
})),
[variants, optionTypes],
)
@@ -120,6 +138,17 @@ export function BulkVariantsDialog({ form, open, onOpenChange }: Props) {
case 'taxCategoryId':
set(`variants.${idx}.tax_category_id`, change.value)
break
+ case 'hsCode':
+ set(`variants.${idx}.hs_code`, normalizeHsCode(change.value))
+ break
+ case 'countryOfOrigin':
+ // Already an ISO code — SelectCell resolves pasted country names
+ // against the option list before committing.
+ set(`variants.${idx}.country_of_origin`, change.value)
+ break
+ case 'customsDescription':
+ set(`variants.${idx}.customs_description`, normalizeCustomsDescription(change.value))
+ break
case 'preorderable':
set(`variants.${idx}.preorderable`, change.value)
break
@@ -186,6 +215,7 @@ export function BulkVariantsDialog({ form, open, onOpenChange }: Props) {
? taxCategories.map((c) => ({ value: c.id, label: c.name }))
: undefined
}
+ countryOptions={countryOptions.length > 0 ? countryOptions : undefined}
labels={{
variant: t('admin.pages.products.price_lists.edit_prices.columns.variant'),
sku: t('admin.fields.variant.sku.label'),
@@ -199,9 +229,13 @@ export function BulkVariantsDialog({ form, open, onOpenChange }: Props) {
preorderable: t('admin.fields.variant.preorderable.label'),
backorderLimit: t('admin.fields.variant.backorder_limit.label'),
taxCategory: t('admin.fields.tax_category_id.label'),
+ hsCode: t('admin.fields.variant.hs_code.label'),
+ countryOfOrigin: t('admin.fields.variant.country_of_origin.label'),
+ customsDescription: t('admin.fields.variant.customs_description.label'),
variantDefault: t('admin.products.variants.default_variant'),
unitDefault: '—',
taxCategoryNone: t('admin.products.variants.sheet.tax_category_placeholder'),
+ countryOfOriginNone: '—',
gridAriaLabel: t('admin.products.variants.bulk_edit.grid_aria'),
}}
/>
diff --git a/packages/dashboard/src/components/spree/products/normalize-customs.test.ts b/packages/dashboard/src/components/spree/products/normalize-customs.test.ts
new file mode 100644
index 0000000000..0b4990b272
--- /dev/null
+++ b/packages/dashboard/src/components/spree/products/normalize-customs.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeCustomsDescription, normalizeHsCode } from './normalize-customs'
+
+describe('normalizeHsCode', () => {
+ it('keeps a plain code unchanged', () => {
+ expect(normalizeHsCode('640411')).toBe('640411')
+ })
+
+ it('strips separators a broker spreadsheet would carry', () => {
+ expect(normalizeHsCode('6404.11')).toBe('640411')
+ expect(normalizeHsCode('6404 11')).toBe('640411')
+ expect(normalizeHsCode('6404-11-00')).toBe('64041100')
+ })
+
+ it('collapses an empty or symbol-only value to null', () => {
+ expect(normalizeHsCode('')).toBeNull()
+ expect(normalizeHsCode(' ')).toBeNull()
+ expect(normalizeHsCode('..')).toBeNull()
+ expect(normalizeHsCode(null)).toBeNull()
+ expect(normalizeHsCode(undefined)).toBeNull()
+ })
+
+ it('does not pad or truncate — the server owns length validation', () => {
+ expect(normalizeHsCode('123')).toBe('123')
+ })
+})
+
+describe('normalizeCustomsDescription', () => {
+ it('trims surrounding whitespace', () => {
+ expect(normalizeCustomsDescription(' Leather footwear ')).toBe('Leather footwear')
+ })
+
+ it('collapses a blank value to null so clearing the field clears it', () => {
+ expect(normalizeCustomsDescription('')).toBeNull()
+ expect(normalizeCustomsDescription(' ')).toBeNull()
+ expect(normalizeCustomsDescription(null)).toBeNull()
+ expect(normalizeCustomsDescription(undefined)).toBeNull()
+ })
+})
diff --git a/packages/dashboard/src/components/spree/products/normalize-customs.ts b/packages/dashboard/src/components/spree/products/normalize-customs.ts
new file mode 100644
index 0000000000..9582763699
--- /dev/null
+++ b/packages/dashboard/src/components/spree/products/normalize-customs.ts
@@ -0,0 +1,27 @@
+// Customs field normalization, shared by the variant edit sheet and the bulk
+// variants editor so both commit the same value for the same keystrokes.
+//
+// These mirror `Spree::Variant`'s `normalizes` declarations. Doing it in the
+// browser too means a merchant pasting a dotted tariff code from a customs
+// broker's spreadsheet sees it accepted, rather than bouncing off the
+// server's 6–13 digit format validation.
+
+/**
+ * Strips everything but digits from a Harmonized System code, so `6404.11`
+ * and `6404 11` both become `640411`.
+ *
+ * @returns the digits, or null when nothing is left (the field is optional).
+ */
+export function normalizeHsCode(value: unknown): string | null {
+ const digits = String(value ?? '').replace(/[^0-9]/g, '')
+ return digits === '' ? null : digits
+}
+
+/**
+ * Trims a customs description, collapsing a blank field to null so clearing
+ * it actually clears it rather than storing an empty string.
+ */
+export function normalizeCustomsDescription(value: unknown): string | null {
+ const trimmed = String(value ?? '').trim()
+ return trimmed === '' ? null : trimmed
+}
diff --git a/packages/dashboard/src/components/spree/products/variant-edit-sheet.tsx b/packages/dashboard/src/components/spree/products/variant-edit-sheet.tsx
index 426d0ab727..70524cf486 100644
--- a/packages/dashboard/src/components/spree/products/variant-edit-sheet.tsx
+++ b/packages/dashboard/src/components/spree/products/variant-edit-sheet.tsx
@@ -1,4 +1,4 @@
-import { StoreDatePicker } from '@spree/dashboard-core'
+import { CountryCombobox, StoreDatePicker } from '@spree/dashboard-core'
import {
Button,
Field,
@@ -23,6 +23,7 @@ import { useTranslation } from 'react-i18next'
import { useOptionTypes } from '../../../hooks/use-option-types'
import { useTaxCategories } from '../../../hooks/use-tax-categories'
import type { ProductFormValues, VariantFormValues } from '../../../schemas/product'
+import { normalizeCustomsDescription, normalizeHsCode } from './normalize-customs'
import { variantDisplayLabel } from './variants-matrix'
const WEIGHT_UNITS = ['g', 'kg', 'lb', 'oz'] as const
@@ -268,6 +269,55 @@ export function VariantEditSheet({ form, variantIndex, open, onOpenChange }: Pro
</div>
</Section>
+ <Section title={t('admin.products.variants.sheet.customs')}>
+ <p className="text-sm text-muted-foreground">
+ {t('admin.products.variants.sheet.customs_help')}
+ </p>
+ <div className="grid grid-cols-2 gap-3">
+ <Field>
+ <FieldLabel htmlFor={`variant-${variantIndex}-hs-code`}>
+ {t('admin.fields.variant.hs_code.label')}
+ </FieldLabel>
+ <Input
+ id={`variant-${variantIndex}-hs-code`}
+ inputMode="numeric"
+ placeholder={t('admin.fields.variant.hs_code.placeholder')}
+ {...form.register(`variants.${variantIndex}.hs_code`, {
+ setValueAs: normalizeHsCode,
+ })}
+ />
+ <FieldError errors={[form.formState.errors.variants?.[variantIndex]?.hs_code]} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor={`variant-${variantIndex}-country-of-origin`}>
+ {t('admin.fields.variant.country_of_origin.label')}
+ </FieldLabel>
+ <Controller
+ name={`variants.${variantIndex}.country_of_origin`}
+ control={form.control}
+ render={({ field }) => (
+ <CountryCombobox
+ value={field.value ?? null}
+ onValueChange={(iso) => field.onChange(iso || null)}
+ />
+ )}
+ />
+ </Field>
+ </div>
+ <Field>
+ <FieldLabel htmlFor={`variant-${variantIndex}-customs-description`}>
+ {t('admin.fields.variant.customs_description.label')}
+ </FieldLabel>
+ <Input
+ id={`variant-${variantIndex}-customs-description`}
+ placeholder={t('admin.fields.variant.customs_description.placeholder')}
+ {...form.register(`variants.${variantIndex}.customs_description`, {
+ setValueAs: normalizeCustomsDescription,
+ })}
+ />
+ </Field>
+ </Section>
+
<Section title={t('admin.products.variants.sheet.availability')}>
<Field>
<div className="flex items-start justify-between gap-4">
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index 87963d18c5..26b01e9d3c 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -1447,6 +1447,13 @@
"barcode": {
"label": "Barcode"
},
+ "country_of_origin": {
+ "label": "بلد المنشأ"
+ },
+ "customs_description": {
+ "label": "الوصف الجمركي",
+ "placeholder": "وصف بسيط للبضاعة"
+ },
"depth": {
"label": "العمق"
},
@@ -1456,6 +1463,10 @@
"height": {
"label": "الارتفاع"
},
+ "hs_code": {
+ "label": "رمز النظام المنسق",
+ "placeholder": "مثال: 640411"
+ },
"preorder_ships_at": {
"help": "موعد شحنك المتوقع للطلبات المسبقة. يظهر للعملاء كوعد بالتسليم؛ وينتهي الطلب المسبق بمجرد مرور هذا التاريخ.",
"label": "الشحن بحلول",
@@ -1948,6 +1959,7 @@
"discounts": "الخصومات",
"discounts_empty": "لا توجد خصومات على هذا الطلب بعد.",
"fee_kind_cod": "الدفع عند الاستلام",
+ "fee_kind_duty": "رسوم جمركية",
"fee_kind_gift_wrap": "تغليف الهدايا",
"fee_kind_handling": "رسوم المناولة",
"fee_kind_payment": "رسوم الدفع",
@@ -3321,6 +3333,8 @@
"remove_row_aria": "إزالة {{name}}",
"sheet": {
"availability": "التوفر",
+ "customs": "الجمارك",
+ "customs_help": "يُستخدم في نماذج الجمارك عند شحن هذا المنتج عبر الحدود.",
"identity": "هوية",
"tax_category_placeholder": "ترث من المنتج"
},
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index ea5dde31dc..c5787978e7 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -1436,6 +1436,13 @@
"barcode": {
"label": "Barcode"
},
+ "country_of_origin": {
+ "label": "Ursprungsland"
+ },
+ "customs_description": {
+ "label": "Zollbeschreibung",
+ "placeholder": "Einfache Beschreibung der Ware"
+ },
"depth": {
"label": "Tiefe"
},
@@ -1445,6 +1452,10 @@
"height": {
"label": "Höhe"
},
+ "hs_code": {
+ "label": "HS-Code",
+ "placeholder": "z. B. 640411"
+ },
"preorder_ships_at": {
"help": "Wann du Vorbestellungen voraussichtlich versendest. Wird Kunden als Lieferversprechen angezeigt; die Vorbestellung endet, sobald dieses Datum verstreicht.",
"label": "Versand bis",
@@ -1937,6 +1948,7 @@
"discounts": "Rabatte",
"discounts_empty": "Noch keine Rabatte für diese Bestellung.",
"fee_kind_cod": "Nachnahme",
+ "fee_kind_duty": "Zoll",
"fee_kind_gift_wrap": "Geschenkverpackung",
"fee_kind_handling": "Bearbeitung",
"fee_kind_payment": "Zahlungsgebühr",
@@ -3305,6 +3317,8 @@
"remove_row_aria": "{{name}} entfernen",
"sheet": {
"availability": "Verfügbarkeit",
+ "customs": "Zoll",
+ "customs_help": "Wird auf Zollformularen verwendet, wenn dieser Artikel eine Grenze überquert.",
"identity": "Identität",
"tax_category_placeholder": "Vom Produkt übernehmen"
},
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index af75c5b53b..e3dcd2450f 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -1436,6 +1436,13 @@
"barcode": {
"label": "Barcode"
},
+ "country_of_origin": {
+ "label": "Country of origin"
+ },
+ "customs_description": {
+ "label": "Customs description",
+ "placeholder": "Plain description of the goods"
+ },
"depth": {
"label": "Depth"
},
@@ -1445,6 +1452,10 @@
"height": {
"label": "Height"
},
+ "hs_code": {
+ "label": "HS code",
+ "placeholder": "e.g. 640411"
+ },
"preorder_ships_at": {
"help": "When you expect to ship pre-orders. Shown to customers as the delivery promise; the pre-order ends once this date passes.",
"label": "Ships by",
@@ -1937,6 +1948,7 @@
"discounts": "Discounts",
"discounts_empty": "No discounts on this order yet.",
"fee_kind_cod": "Cash on delivery",
+ "fee_kind_duty": "Duty",
"fee_kind_gift_wrap": "Gift wrap",
"fee_kind_handling": "Handling",
"fee_kind_payment": "Payment fee",
@@ -3305,6 +3317,8 @@
"remove_row_aria": "Remove {{name}}",
"sheet": {
"availability": "Availability",
+ "customs": "Customs",
+ "customs_help": "Used on customs forms when this item ships across a border.",
"identity": "Identity",
"tax_category_placeholder": "Inherit from product"
},
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index b16b2fce7b..a1c5f5ac23 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -1436,6 +1436,13 @@
"barcode": {
"label": "Code-barres"
},
+ "country_of_origin": {
+ "label": "Pays d'origine"
+ },
+ "customs_description": {
+ "label": "Description douanière",
+ "placeholder": "Description simple de la marchandise"
+ },
"depth": {
"label": "Profondeur"
},
@@ -1445,6 +1452,10 @@
"height": {
"label": "Hauteur"
},
+ "hs_code": {
+ "label": "Code SH",
+ "placeholder": "ex. 640411"
+ },
"preorder_ships_at": {
"help": "Date à laquelle vous prévoyez d'expédier les précommandes. Affichée aux clients comme promesse de livraison ; la précommande se termine une fois cette date passée.",
"label": "Expédié avant le",
@@ -1937,6 +1948,7 @@
"discounts": "Remises",
"discounts_empty": "Aucune remise sur cette commande pour le moment.",
"fee_kind_cod": "Paiement à la livraison",
+ "fee_kind_duty": "Droits de douane",
"fee_kind_gift_wrap": "Emballage cadeau",
"fee_kind_handling": "Manutention",
"fee_kind_payment": "Frais de paiement",
@@ -3305,6 +3317,8 @@
"remove_row_aria": "Retirer {{name}}",
"sheet": {
"availability": "Disponibilité",
+ "customs": "Douane",
+ "customs_help": "Utilisé sur les formulaires douaniers lorsque cet article franchit une frontière.",
"identity": "Identité",
"tax_category_placeholder": "Hériter du produit"
},
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 0fa2e79bae..61c3e0e43b 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -1450,6 +1450,13 @@
"barcode": {
"label": "Kod kreskowy"
},
+ "country_of_origin": {
+ "label": "Kraj pochodzenia"
+ },
+ "customs_description": {
+ "label": "Opis celny",
+ "placeholder": "Prosty opis towaru"
+ },
"depth": {
"label": "Głębokość"
},
@@ -1459,6 +1466,10 @@
"height": {
"label": "Wysokość"
},
+ "hs_code": {
+ "label": "Kod HS",
+ "placeholder": "np. 640411"
+ },
"preorder_ships_at": {
"help": "Kiedy planujesz wysłać zamówienia przedpremierowe. Pokazywane klientom jako obietnica dostawy; przedsprzedaż kończy się po upływie tej daty.",
"label": "Wysyłka do",
@@ -1953,6 +1964,7 @@
"discounts": "Rabaty",
"discounts_empty": "Brak rabatów dla tego zamówienia.",
"fee_kind_cod": "Płatność przy odbiorze",
+ "fee_kind_duty": "Cło",
"fee_kind_gift_wrap": "Pakowanie na prezent",
"fee_kind_handling": "Koszt obsługi",
"fee_kind_payment": "Opłata za płatność",
@@ -3359,6 +3371,8 @@
"remove_row_aria": "Usuń {{name}}",
"sheet": {
"availability": "Dostępność",
+ "customs": "Cło",
+ "customs_help": "Używane na formularzach celnych, gdy ten produkt przekracza granicę.",
"identity": "Tożsamość",
"tax_category_placeholder": "Dziedzicz z produktu"
},
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index de56e7ff5e..24c3d54ba1 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -1433,6 +1433,13 @@
"barcode": {
"label": "条形码"
},
+ "country_of_origin": {
+ "label": "原产国"
+ },
+ "customs_description": {
+ "label": "海关申报描述",
+ "placeholder": "货物的简明描述"
+ },
"depth": {
"label": "深度"
},
@@ -1442,6 +1449,10 @@
"height": {
"label": "高度"
},
+ "hs_code": {
+ "label": "HS 编码",
+ "placeholder": "例如 640411"
+ },
"preorder_ships_at": {
"help": "你预计发出预购订单的时间。作为交付承诺向顾客展示;该日期过后预购结束。",
"label": "发货时间",
@@ -1934,6 +1945,7 @@
"discounts": "折扣",
"discounts_empty": "该订单暂无折扣。",
"fee_kind_cod": "货到付款",
+ "fee_kind_duty": "关税",
"fee_kind_gift_wrap": "礼品包装",
"fee_kind_handling": "手续费",
"fee_kind_payment": "支付手续费",
@@ -3301,6 +3313,8 @@
"remove_row_aria": "移除 {{name}}",
"sheet": {
"availability": "可用性",
+ "customs": "海关",
+ "customs_help": "当该商品跨境运输时用于海关申报单。",
"identity": "标识",
"tax_category_placeholder": "继承自商品"
},
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
index 7cdbb11844..21d5e30e29 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -78,6 +78,9 @@ function variantToFormValues(variant: Variant, position: number): VariantFormVal
depth: variant.depth ?? null,
weight_unit: variant.weight_unit ?? null,
dimensions_unit: variant.dimensions_unit ?? null,
+ hs_code: variant.hs_code ?? null,
+ country_of_origin: variant.country_of_origin ?? null,
+ customs_description: variant.customs_description ?? null,
track_inventory: variant.track_inventory,
preorderable: variant.preorderable ?? false,
preorder_ships_at: variant.preorder_ships_at ?? null,
@@ -200,6 +203,9 @@ export function variantToWirePayload(v: VariantFormValues, index: number) {
weight_unit: v.weight_unit ?? null,
dimensions_unit: v.dimensions_unit ?? null,
tax_category_id: v.tax_category_id ?? null,
+ hs_code: v.hs_code ?? null,
+ country_of_origin: v.country_of_origin ?? null,
+ customs_description: v.customs_description ?? null,
}
if (v.id) payload.id = v.id
if (v.track_inventory != null) payload.track_inventory = v.track_inventory
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx
index fdbc263bb3..6c2340347c 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx
@@ -116,6 +116,9 @@ function NewProductPage() {
v.weight_unit != null ||
v.dimensions_unit != null ||
v.tax_category_id != null ||
+ v.hs_code != null ||
+ v.country_of_origin != null ||
+ v.customs_description != null ||
v.track_inventory === false ||
v.preorderable === true ||
v.preorder_ships_at != null ||
diff --git a/packages/dashboard/src/schemas/order.ts b/packages/dashboard/src/schemas/order.ts
index f97231cf30..3c261d5a44 100644
--- a/packages/dashboard/src/schemas/order.ts
+++ b/packages/dashboard/src/schemas/order.ts
@@ -40,7 +40,7 @@ export const NEW_ORDER_DEFAULTS: NewOrderFormValues = {
* Fee kinds offered when adding a manual fee to an order. The backend accepts
* any string, so this is the curated admin-facing set, not a DB constraint.
*/
-export const FEE_KINDS = ['surcharge', 'handling', 'gift_wrap', 'cod', 'payment'] as const
+export const FEE_KINDS = ['surcharge', 'handling', 'gift_wrap', 'cod', 'payment', 'duty'] as const
export type FeeKind = (typeof FEE_KINDS)[number]
diff --git a/packages/dashboard/src/schemas/product.ts b/packages/dashboard/src/schemas/product.ts
index 5e773d00e7..d70e8e7254 100644
--- a/packages/dashboard/src/schemas/product.ts
+++ b/packages/dashboard/src/schemas/product.ts
@@ -45,6 +45,9 @@ export const variantFormSchema = z.object({
depth: z.coerce.number().nullable().optional(),
weight_unit: z.string().nullable().optional(),
dimensions_unit: z.string().nullable().optional(),
+ hs_code: z.string().nullable().optional(),
+ country_of_origin: z.string().nullable().optional(),
+ customs_description: z.string().nullable().optional(),
track_inventory: z.boolean().optional(),
preorderable: z.boolean().optional(),
preorder_ships_at: z.string().nullable().optional(),
@@ -210,6 +213,9 @@ export function isPlaceholderDefaultVariant(v: VariantFormValues): boolean {
v.weight_unit == null &&
v.dimensions_unit == null &&
v.tax_category_id == null &&
+ !v.hs_code &&
+ !v.country_of_origin &&
+ !v.customs_description &&
v.preorderable !== true &&
v.preorder_ships_at == null &&
v.backorder_limit == null &&
diff --git a/packages/sdk/src/types/generated/Cart.ts b/packages/sdk/src/types/generated/Cart.ts
index c8a7676a6b..a562f6814f 100644
--- a/packages/sdk/src/types/generated/Cart.ts
+++ b/packages/sdk/src/types/generated/Cart.ts
@@ -1,7 +1,7 @@
-// Typelizer digest af64c7f107fb6df4ffcc80eac22e6d8c
+// Typelizer digest e2e515c457444f027e6ed790be6e7a63
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {AppliedPromotion, LineItem, Fulfillment, Payment, Address, PaymentMethod, GiftCard, Market} from '@/types'
+import type {AppliedPromotion, Fee, LineItem, Fulfillment, Payment, Address, PaymentMethod, GiftCard, Market} from '@/types'
interface Cart {
id: string;
@@ -37,6 +37,8 @@ interface Cart {
display_amount_due: string | null;
delivery_total: string | null;
display_delivery_total: string | null;
+ fee_total: string | null;
+ display_fee_total: string | null;
store_credit_total: string | null;
display_store_credit_total: string | null;
covered_by_store_credit: boolean;
@@ -45,6 +47,7 @@ interface Cart {
requirements: Array<{step: string, field: string, code: string, message: string}>;
shipping_eq_billing_address: boolean;
discounts: Array<AppliedPromotion>;
+ fees: Array<Fee>;
items: Array<LineItem>;
fulfillments: Array<Fulfillment>;
payments: Array<Payment>;
diff --git a/packages/sdk/src/types/generated/Order.ts b/packages/sdk/src/types/generated/Order.ts
index a022a9c34e..6cf4bfdac5 100644
--- a/packages/sdk/src/types/generated/Order.ts
+++ b/packages/sdk/src/types/generated/Order.ts
@@ -1,7 +1,7 @@
-// Typelizer digest c6899223ead7a2ef2dfef98a38dc73a3
+// Typelizer digest 2aaef3257603d48582113c6bcdea7af9
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {AppliedPromotion, LineItem, Fulfillment, Payment, Address, GiftCard, Market} from '@/types'
+import type {AppliedPromotion, Fee, LineItem, Fulfillment, Payment, Address, GiftCard, Market} from '@/types'
interface Order {
id: string;
@@ -38,10 +38,13 @@ interface Order {
display_amount_due: string | null;
delivery_total: string | null;
display_delivery_total: string | null;
+ fee_total: string | null;
+ display_fee_total: string | null;
store_credit_total: string | null;
display_store_credit_total: string | null;
covered_by_store_credit: boolean;
discounts: Array<AppliedPromotion>;
+ fees: Array<Fee>;
items: Array<LineItem>;
fulfillments: Array<Fulfillment>;
payments: Array<Payment>;
diff --git a/packages/sdk/src/zod/generated/Cart.ts b/packages/sdk/src/zod/generated/Cart.ts
index 6cf797157d..460a655b84 100644
--- a/packages/sdk/src/zod/generated/Cart.ts
+++ b/packages/sdk/src/zod/generated/Cart.ts
@@ -2,6 +2,7 @@
import { z } from 'zod';
import { AddressSchema } from './Address';
import { AppliedPromotionSchema } from './AppliedPromotion';
+import { FeeSchema } from './Fee';
import { FulfillmentSchema } from './Fulfillment';
import { GiftCardSchema } from './GiftCard';
import { LineItemSchema } from './LineItem';
@@ -43,6 +44,8 @@ export const CartSchema = z.object({
display_amount_due: z.string().nullable(),
delivery_total: z.string().nullable(),
display_delivery_total: z.string().nullable(),
+ fee_total: z.string().nullable(),
+ display_fee_total: z.string().nullable(),
store_credit_total: z.string().nullable(),
display_store_credit_total: z.string().nullable(),
covered_by_store_credit: z.boolean(),
@@ -51,6 +54,7 @@ export const CartSchema = z.object({
requirements: z.array(z.object({ step: z.string(), field: z.string(), code: z.string(), message: z.string() })),
shipping_eq_billing_address: z.boolean(),
discounts: z.array(AppliedPromotionSchema),
+ fees: z.array(FeeSchema),
items: z.array(LineItemSchema),
fulfillments: z.array(FulfillmentSchema),
payments: z.array(PaymentSchema),
diff --git a/packages/sdk/src/zod/generated/Order.ts b/packages/sdk/src/zod/generated/Order.ts
index 90f6f47678..247dbfe92f 100644
--- a/packages/sdk/src/zod/generated/Order.ts
+++ b/packages/sdk/src/zod/generated/Order.ts
@@ -2,6 +2,7 @@
import { z } from 'zod';
import { AddressSchema } from './Address';
import { AppliedPromotionSchema } from './AppliedPromotion';
+import { FeeSchema } from './Fee';
import { FulfillmentSchema } from './Fulfillment';
import { GiftCardSchema } from './GiftCard';
import { LineItemSchema } from './LineItem';
@@ -43,10 +44,13 @@ export const OrderSchema = z.object({
display_amount_due: z.string().nullable(),
delivery_total: z.string().nullable(),
display_delivery_total: z.string().nullable(),
+ fee_total: z.string().nullable(),
+ display_fee_total: z.string().nullable(),
store_credit_total: z.string().nullable(),
display_store_credit_total: z.string().nullable(),
covered_by_store_credit: z.boolean(),
discounts: z.array(AppliedPromotionSchema),
+ fees: z.array(FeeSchema),
items: z.array(LineItemSchema),
fulfillments: z.array(FulfillmentSchema),
payments: z.array(PaymentSchema),
diff --git a/spree/api/app/controllers/spree/api/v3/admin/products/variants_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products/variants_controller.rb
index c34e54af89..4642bcd59f 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/products/variants_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/products/variants_controller.rb
@@ -34,6 +34,7 @@ module Spree
:sku, :barcode,
:cost_price, :cost_currency,
:weight, :height, :width, :depth, :weight_unit, :dimensions_unit,
+ :hs_code, :country_of_origin, :customs_description,
:track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :tax_category_id, :position,
options: [:name, :value],
prices: [:amount, :compare_at_amount, :currency],
diff --git a/spree/api/app/serializers/spree/api/v3/admin/cart_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/cart_serializer.rb
index 0f6c2a9497..64ce3e07fd 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/cart_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/cart_serializer.rb
@@ -12,7 +12,7 @@ module Spree
# are redeclared with admin counterparts — admin serializers never
# reference store serializers.
class CartSerializer < V3::CartSerializer
- %i[fulfillments payments payment_methods gift_card discounts].each { |key| _attributes.delete(key) }
+ %i[fulfillments payments payment_methods gift_card discounts fees].each { |key| _attributes.delete(key) }
typelize completed_at: [:string, nullable: true]
diff --git a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
index e3ddf0d8f4..976d451111 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
@@ -93,6 +93,10 @@ module Spree
# promotion summaries carry their real name here. The inherited
# store-keyed declaration is dropped, not shadowed.
_attributes.delete(:discounts)
+ # Fees reach the admin through their own `/orders/:id/fees` endpoint,
+ # which is also the write path — embedding them here would ship the
+ # same rows twice, through a store serializer.
+ _attributes.delete(:fees)
many :order_promotions, key: :applied_promotions, resource: proc { Spree.api.admin_applied_promotion_serializer }, if: proc { expand?('applied_promotions') }
many :line_items, key: :items, resource: proc { Spree.api.admin_line_item_serializer }, if: proc { expand?('items') }
many :fulfillments, resource: proc { Spree.api.admin_fulfillment_serializer }, if: proc { expand?('fulfillments') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
index 2a0428c44b..279ddde058 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
@@ -15,11 +15,15 @@ module Spree
reserved_quantity: :number, total_on_hand: [:number, nullable: true],
preorderable: :boolean, preorder_ships_at: [:string, nullable: true],
backorder_limit: [:number, nullable: true],
+ hs_code: [:string, nullable: true],
+ country_of_origin: [:string, nullable: true],
+ customs_description: [:string, nullable: true],
deleted_at: [:string, nullable: true],
metadata: 'Record<string, unknown>'
attributes :metadata, :position, :cost_price, :cost_currency,
:barcode, :weight_unit, :dimensions_unit, :backorder_limit,
+ :hs_code, :country_of_origin, :customs_description,
preorder_ships_at: :iso8601, deleted_at: :iso8601,
created_at: :iso8601, updated_at: :iso8601
diff --git a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb b/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
index 3f8be2f514..906e98fda9 100644
--- a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
@@ -17,6 +17,7 @@ module Spree
tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],
included_tax_total: [:string, nullable: true], display_included_tax_total: [:string, nullable: true],
additional_tax_total: [:string, nullable: true], display_additional_tax_total: [:string, nullable: true],
+ fee_total: [:string, nullable: true], display_fee_total: [:string, nullable: true],
store_credit_total: [:string, nullable: true], display_store_credit_total: [:string, nullable: true],
gift_card_total: [:string, nullable: true], display_gift_card_total: [:string, nullable: true],
covered_by_store_credit: :boolean,
@@ -57,7 +58,8 @@ module Spree
: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
+ :delivery_total, :display_delivery_total,
+ :fee_total, :display_fee_total
attribute :store_credit_total do |order|
order.total_applied_store_credit.to_s unless params[:hide_prices]
@@ -88,6 +90,10 @@ module Spree
end
many :order_promotions, key: :discounts, resource: proc { Spree.api.applied_promotion_serializer }
+ # Itemized charges (duties, surcharges, COD, handling). Storefronts
+ # group and label these themselves — cross-border duty in particular
+ # has to be shown broken out rather than folded into a total.
+ many :fees, resource: proc { Spree.api.fee_serializer }
many :line_items, key: :items, resource: proc { Spree.api.line_item_serializer }
many :fulfillments, resource: proc { Spree.api.fulfillment_serializer }
many :payments, resource: proc { Spree.api.payment_serializer }
diff --git a/spree/api/app/serializers/spree/api/v3/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/order_serializer.rb
index a4d68a1c35..af1a5dd403 100644
--- a/spree/api/app/serializers/spree/api/v3/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/order_serializer.rb
@@ -18,6 +18,7 @@ module Spree
tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],
included_tax_total: [:string, nullable: true], display_included_tax_total: [:string, nullable: true],
additional_tax_total: [:string, nullable: true], display_additional_tax_total: [:string, nullable: true],
+ fee_total: [:string, nullable: true], display_fee_total: [:string, nullable: true],
store_credit_total: [:string, nullable: true], display_store_credit_total: [:string, nullable: true],
gift_card_total: [:string, nullable: true], display_gift_card_total: [:string, nullable: true],
covered_by_store_credit: :boolean,
@@ -57,7 +58,8 @@ module Spree
: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
+ :delivery_total, :display_delivery_total,
+ :fee_total, :display_fee_total
attribute :store_credit_total do |order|
order.total_applied_store_credit.to_s unless params[:hide_prices]
@@ -72,6 +74,9 @@ module Spree
end
many :order_promotions, key: :discounts, resource: proc { Spree.api.applied_promotion_serializer }
+ # Itemized charges (duties, surcharges, COD, handling) — see the cart
+ # serializer; the order keeps them visible after placement.
+ many :fees, resource: proc { Spree.api.fee_serializer }
many :line_items, key: :items, resource: proc { Spree.api.line_item_serializer }
many :fulfillments, resource: proc { Spree.api.fulfillment_serializer }
many :payments, resource: proc { Spree.api.payment_serializer }
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb
index 7f505b080b..3a523692f4 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb
@@ -190,4 +190,31 @@ RSpec.describe Spree::Api::V3::Admin::Products::VariantsController, type: :contr
expect(variant.reload.deleted_at).not_to be_nil
end
end
+
+ describe 'customs classification' do
+ it 'writes and reads back the customs fields' do
+ patch :update, params: {
+ product_id: product.prefixed_id,
+ id: variant.prefixed_id,
+ hs_code: '640411',
+ country_of_origin: 'vn',
+ customs_description: 'Leather footwear'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['hs_code']).to eq('640411')
+ expect(json_response['country_of_origin']).to eq('VN')
+ expect(json_response['customs_description']).to eq('Leather footwear')
+ end
+
+ it 'rejects a malformed hs code' do
+ patch :update, params: {
+ product_id: product.prefixed_id,
+ id: variant.prefixed_id,
+ hs_code: '123'
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
end
diff --git a/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb b/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb
index 845aa3c6cc..e183fec687 100644
--- a/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb
@@ -40,6 +40,26 @@ RSpec.describe 'v3 Store serializer price gating' do
expect(hash['total']).to be_present
expect(hash['items'].first['price']).to be_present
end
+
+ it 'nulls fee amounts and the fee total for gated guests' do
+ create(:fee, cart: cart, order: nil, amount: 7, label: 'Import duty', kind: 'duty')
+
+ hash = serialize(described_class, cart.reload, hide: true)
+
+ expect(hash['fee_total']).to be_nil
+ expect(hash['fees'].first['amount']).to be_nil
+ expect(hash['fees'].first['display_amount']).to be_nil
+ end
+
+ it 'itemizes fees so a storefront can show duties broken out' do
+ create(:fee, cart: cart, order: nil, amount: 7, label: 'Import duty', kind: 'duty')
+
+ hash = serialize(described_class, cart.reload, hide: false)
+
+ expect(hash['fee_total']).to be_present
+ expect(hash['fees'].first).to include('label' => 'Import duty', 'kind' => 'duty')
+ expect(hash['fees'].first['amount']).to be_present
+ end
end
describe Spree::Api::V3::OrderSerializer do
@@ -55,6 +75,15 @@ RSpec.describe 'v3 Store serializer price gating' do
it 'serializes totals when not gated' do
expect(serialize(described_class, hide: false)['total']).to be_present
end
+
+ it 'keeps fees itemized after placement' do
+ create(:fee, order: order, amount: 7, label: 'Import duty', kind: 'duty')
+
+ hash = serialize(described_class, order.reload, hide: false)
+
+ expect(hash['fee_total']).to be_present
+ expect(hash['fees'].first).to include('label' => 'Import duty', 'kind' => 'duty')
+ end
end
# Nested records embedded in a cart/order must honor hide_prices too, so a
diff --git a/spree/core/app/models/spree/fee.rb b/spree/core/app/models/spree/fee.rb
index 061a44af89..8cacbd6065 100644
--- a/spree/core/app/models/spree/fee.rb
+++ b/spree/core/app/models/spree/fee.rb
@@ -8,7 +8,10 @@ module Spree
include Spree::TypedAdjustmentLine
# Extensions may append their own kinds — the list is validated, not frozen.
- KINDS = %w[surcharge handling gift_wrap cod payment]
+ # `duty` rows are written by a duties provider's adjuster and snapshot the
+ # classification they were calculated from in `metadata` — never re-derive
+ # a duty from the live catalog.
+ KINDS = %w[surcharge handling gift_wrap cod payment duty]
has_prefix_id :fee
diff --git a/spree/core/app/models/spree/import_schemas/products.rb b/spree/core/app/models/spree/import_schemas/products.rb
index 51c7550aa4..8390757e0c 100644
--- a/spree/core/app/models/spree/import_schemas/products.rb
+++ b/spree/core/app/models/spree/import_schemas/products.rb
@@ -27,6 +27,9 @@ module Spree
{ name: 'inventory_backorderable', label: 'Inventory Backorderable' },
{ name: 'tax_category', label: 'Tax Category' },
{ name: 'product_type', label: 'Product Type' },
+ { name: 'hs_code', label: 'HS Code' },
+ { name: 'country_of_origin', label: 'Country of Origin' },
+ { name: 'customs_description', label: 'Customs Description' },
{ name: 'image1_src', label: 'Image 1 URL' },
{ name: 'image2_src', label: 'Image 2 URL' },
{ name: 'image3_src', label: 'Image 3 URL' },
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 4f6e71fd66..a09a4945fb 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -62,7 +62,7 @@ module Spree
:included_tax_total, :additional_tax_total, :tax_total,
:delivery_total, :discount_total, :total,
:cart_promo_total, :pre_tax_item_amount, :pre_tax_total,
- :payment_total, :amount_due
+ :payment_total, :amount_due, :fee_total
alias display_ship_total display_delivery_total
alias_attribute :ship_total, :delivery_total
diff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rb
index 14940d4874..334d2756b5 100644
--- a/spree/core/app/models/spree/variant.rb
+++ b/spree/core/app/models/spree/variant.rb
@@ -25,6 +25,8 @@ module Spree
:meta_description, :meta_keywords, :product_type, to: :product
normalizes :sku, with: ->(value) { value&.to_s&.strip }
+ normalizes :hs_code, with: ->(value) { value&.to_s&.gsub(/[^0-9]/, '') }
+ normalizes :country_of_origin, with: ->(value) { value&.to_s&.strip&.upcase }
# we need to have this callback before any dependent: :destroy associations
# https://github.com/rails/rails/issues/3458
@@ -82,6 +84,13 @@ module Spree
validates :backorder_limit, numericality: { only_integer: true, greater_than_or_equal_to: 0, allow_nil: true }
+ # Customs classification. Optional everywhere — only an international
+ # shipment or a duties provider needs it, and each raises its own error
+ # when it does. Carriers reject an HS code outside 6..13 digits, so the
+ # format is checked here rather than at the label counter.
+ validates :hs_code, format: { with: /\A\d{6,13}\z/ }, allow_blank: true
+ validates :country_of_origin, format: { with: /\A[A-Z]{2}\z/ }, allow_blank: true
+
after_create :create_stock_items
after_commit :clear_line_items_cache, on: :update
@@ -182,7 +191,7 @@ module Spree
self.whitelisted_ransackable_associations = %w[option_values product tax_category prices]
self.whitelisted_ransackable_attributes = %w[weight depth width height sku discontinue_on cost_price cost_currency track_inventory
- deleted_at product_id]
+ deleted_at product_id hs_code country_of_origin]
self.whitelisted_ransackable_scopes = %i(product_name_or_sku_cont search_by_product_name_or_sku search)
def self.product_name_or_sku_cont(query)
@@ -288,6 +297,14 @@ module Spree
option_values.any? ? "#{name} - #{options_text}" : name
end
+ # Plain-language contents description for a customs declaration. Customs
+ # authorities reject marketing names, so merchants set an explicit one;
+ # the product name is the fallback that keeps a declaration valid.
+ # @return [String, nil]
+ def customs_description_for_declaration
+ customs_description.presence || name
+ end
+
# Returns the variant's media gallery.
# Prefers product-level media linked via variant_media (5.5+) — these reuse
# a single blob across variants. Falls back to direct variant images for
diff --git a/spree/core/app/services/spree/imports/row_processors/product_variant.rb b/spree/core/app/services/spree/imports/row_processors/product_variant.rb
index eda4acf332..cd61d5fb06 100644
--- a/spree/core/app/services/spree/imports/row_processors/product_variant.rb
+++ b/spree/core/app/services/spree/imports/row_processors/product_variant.rb
@@ -30,6 +30,9 @@ module Spree
variant.width = attributes['width'] if attributes['width'].present?
variant.depth = attributes['depth'] if attributes['depth'].present?
variant.track_inventory = attributes['track_inventory'] if attributes['track_inventory'].present?
+ variant.hs_code = attributes['hs_code'] if attributes['hs_code'].present?
+ variant.country_of_origin = attributes['country_of_origin'] if attributes['country_of_origin'].present?
+ variant.customs_description = attributes['customs_description'] if attributes['customs_description'].present?
variant.option_value_variants = prepare_option_value_variants if options.any?
if attributes['tax_category'].present?
diff --git a/spree/core/db/migrate/20260814000001_add_customs_fields_to_spree_variants.rb b/spree/core/db/migrate/20260814000001_add_customs_fields_to_spree_variants.rb
new file mode 100644
index 0000000000..73d6fcab73
--- /dev/null
+++ b/spree/core/db/migrate/20260814000001_add_customs_fields_to_spree_variants.rb
@@ -0,0 +1,7 @@
+class AddCustomsFieldsToSpreeVariants < ActiveRecord::Migration[8.1]
+ def change
+ add_column :spree_variants, :hs_code, :string
+ add_column :spree_variants, :country_of_origin, :string
+ add_column :spree_variants, :customs_description, :string
+ end
+end
diff --git a/spree/core/lib/spree/permitted_attributes.rb b/spree/core/lib/spree/permitted_attributes.rb
index b62c93342d..c1fabf1d72 100644
--- a/spree/core/lib/spree/permitted_attributes.rb
+++ b/spree/core/lib/spree/permitted_attributes.rb
@@ -283,6 +283,7 @@ module Spree
:product_id, :product, :option_values_attributes,
:weight, :height, :width, :depth, :sku, :barcode, :cost_currency,
:weight_unit, :dimensions_unit,
+ :hs_code, :country_of_origin, :customs_description,
{
options: [:id, :name, :option_value_presentation, :option_value_name, :position, :_destroy],
stock_items_attributes: [:id, :count_on_hand, :stock_location_id, :backorderable, :_destroy],
diff --git a/spree/core/spec/models/spree/fee_spec.rb b/spree/core/spec/models/spree/fee_spec.rb
index 442d2dd62b..b9d38145aa 100644
--- a/spree/core/spec/models/spree/fee_spec.rb
+++ b/spree/core/spec/models/spree/fee_spec.rb
@@ -40,6 +40,18 @@ describe Spree::Fee, type: :model do
expect(fee).to be_valid
end
+ it 'accepts a customs duty attached to a line item, snapshotting its classification' do
+ line_item = order.line_items.first
+ fee = described_class.new(
+ order: order, line_item: line_item, amount: 12.5, label: 'Import duty', kind: 'duty',
+ metadata: { 'hs_code' => '640411', 'country_of_origin' => 'VN', 'rate' => '0.125' }
+ )
+
+ expect(fee).to be_valid
+ expect(fee.adjustable).to eq(line_item)
+ expect(fee.metadata['hs_code']).to eq('640411')
+ end
+
it 'destroys its tax lines with it' do
fee = create(:fee, order: order)
create(:tax_line, order: order, fee: fee, line_item: nil)
diff --git a/spree/core/spec/models/spree/variant_spec.rb b/spree/core/spec/models/spree/variant_spec.rb
index 52d1cc71ab..3537873348 100644
--- a/spree/core/spec/models/spree/variant_spec.rb
+++ b/spree/core/spec/models/spree/variant_spec.rb
@@ -1587,4 +1587,63 @@ describe Spree::Variant, type: :model do
end
end
+ describe 'customs classification' do
+ let(:variant) { build(:variant) }
+
+ it 'is valid without any customs data' do
+ variant.hs_code = nil
+ variant.country_of_origin = nil
+
+ expect(variant).to be_valid
+ end
+
+ it 'strips non-digits from the hs code' do
+ variant.hs_code = '6404.11'
+ variant.validate
+
+ expect(variant.hs_code).to eq('640411')
+ end
+
+ it 'upcases the country of origin' do
+ variant.country_of_origin = 'vn'
+ variant.validate
+
+ expect(variant.country_of_origin).to eq('VN')
+ end
+
+ it 'rejects an hs code shorter than six digits' do
+ variant.hs_code = '64041'
+
+ expect(variant).not_to be_valid
+ expect(variant.errors[:hs_code]).to be_present
+ end
+
+ it 'rejects an hs code longer than thirteen digits' do
+ variant.hs_code = '1' * 14
+
+ expect(variant).not_to be_valid
+ expect(variant.errors[:hs_code]).to be_present
+ end
+
+ it 'rejects a country of origin that is not a two-letter code' do
+ variant.country_of_origin = 'VNM'
+
+ expect(variant).not_to be_valid
+ expect(variant.errors[:country_of_origin]).to be_present
+ end
+
+ describe '#customs_description_for_declaration' do
+ it 'prefers the explicit customs description' do
+ variant.customs_description = 'Leather footwear'
+
+ expect(variant.customs_description_for_declaration).to eq('Leather footwear')
+ end
+
+ it 'falls back to the product name' do
+ variant.customs_description = nil
+
+ expect(variant.customs_description_for_declaration).to eq(variant.name)
+ end
+ end
+ end
end
diff --git a/spree/providers/easypost/app/models/spree_easypost/delivery_rate_provider.rb b/spree/providers/easypost/app/models/spree_easypost/delivery_rate_provider.rb
index 67c0871417..c7adb5bdc3 100644
--- a/spree/providers/easypost/app/models/spree_easypost/delivery_rate_provider.rb
+++ b/spree/providers/easypost/app/models/spree_easypost/delivery_rate_provider.rb
@@ -120,10 +120,25 @@ module SpreeEasyPost
def easypost_shipment(package)
cache_key = [:easypost_shipment, store.id, package.stock_location.id, package.owner.id]
Spree::Current.provider_cache[cache_key] ||= integration.client.shipment.create(
+ **shipment_params(package)
+ )
+ end
+
+ # International rates depend on the declared contents, so the customs
+ # form goes on the quote as well as the label.
+ def shipment_params(package)
+ destination = package.owner.ship_address
+ params = {
from_address: address_params(package.stock_location),
- to_address: address_params(package.owner.ship_address),
+ to_address: address_params(destination),
parcel: parcel_params(package)
+ }
+
+ customs_info = SpreeEasyPost.customs_info_params(
+ package, package.stock_location, destination, integration
)
+ params[:customs_info] = customs_info if customs_info.present?
+ params
end
def address_params(source)
diff --git a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
index 18ac496172..7825a550a3 100644
--- a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
+++ b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
@@ -92,9 +92,7 @@ module SpreeEasyPost
return if selected&.carrier.blank? || selected.service_level.blank? || address.nil?
shipment = integration.client.shipment.create(
- from_address: address_params(fulfillment.stock_location),
- to_address: address_params(address),
- parcel: requote_parcel(fulfillment)
+ **shipment_params(integration, fulfillment, address)
)
rate = shipment.rates.find do |candidate|
candidate.carrier == selected.carrier && candidate.service == selected.service_level
@@ -128,8 +126,25 @@ module SpreeEasyPost
nil
end
- def requote_parcel(fulfillment)
- SpreeEasyPost.parcel_params(fulfillment.to_package, fulfillment.order&.store)
+ # Adds the customs declaration and duty terms when the parcel crosses a
+ # border; a domestic shipment is created exactly as before.
+ def shipment_params(integration, fulfillment, address)
+ package = fulfillment.to_package
+ params = {
+ from_address: address_params(fulfillment.stock_location),
+ to_address: address_params(address),
+ parcel: SpreeEasyPost.parcel_params(package, fulfillment.order&.store)
+ }
+
+ customs_info = SpreeEasyPost.customs_info_params(
+ package, fulfillment.stock_location, address, integration
+ )
+ return params if customs_info.nil?
+
+ params[:customs_info] = customs_info
+ incoterm = integration.preferred_incoterm.presence
+ params[:options] = { incoterm: incoterm } if incoterm.present?
+ params
end
def remember_purchase(fulfillment, shipment)
diff --git a/spree/providers/easypost/app/models/spree_easypost/integration.rb b/spree/providers/easypost/app/models/spree_easypost/integration.rb
index a5c0f0efb0..e4ed059c6e 100644
--- a/spree/providers/easypost/app/models/spree_easypost/integration.rb
+++ b/spree/providers/easypost/app/models/spree_easypost/integration.rb
@@ -8,6 +8,23 @@ module SpreeEasyPost
# could otherwise mark parcels delivered, which starts return windows.
preference :webhook_secret, :password
+ # Customs declaration defaults for international labels. The signer takes
+ # legal responsibility for the declared contents, so it names a person at
+ # the merchant rather than the store.
+ preference :customs_signer, :string
+ preference :customs_contents_type, :string, default: 'merchandise'
+ # Who pays duties and taxes on arrival. Defaults to DAP — the recipient is
+ # billed by the carrier. DDP bills the merchant instead, so only choose it
+ # once duties are actually collected from the customer at checkout;
+ # otherwise the merchant absorbs them silently.
+ preference :incoterm, :string, default: 'DAP'
+
+ # EasyPost rejects any other value outright, and a rejected shipment
+ # create is a checkout with no delivery options at all.
+ INCOTERMS = %w[CFR CIF CIP CPT DAT DAP DDP EXW FAS FCA FOB].freeze
+
+ validates :preferred_incoterm, inclusion: { in: INCOTERMS }, allow_blank: true
+
# EasyPost's own documentation example address — used only to prove the
# key authenticates.
VERIFICATION_ADDRESS = {
diff --git a/spree/providers/easypost/lib/spree_easypost.rb b/spree/providers/easypost/lib/spree_easypost.rb
index da7df4da28..7a8610146a 100644
--- a/spree/providers/easypost/lib/spree_easypost.rb
+++ b/spree/providers/easypost/lib/spree_easypost.rb
@@ -96,6 +96,71 @@ module SpreeEasyPost
source.try(:name)
end
+ # Customs payload for an international shipment. Nil for domestic ones —
+ # EasyPost rejects a customs form on a domestic label, and every carrier
+ # treats "no customs_info" as the domestic case.
+ #
+ # Classification (HS code, country of origin) is sent per item when the
+ # merchant recorded it. It is deliberately not required: carriers differ on
+ # what they demand, and a rejected label carries the carrier's own message,
+ # which is more actionable than a guess made here.
+ #
+ # @param package [Spree::Stock::Package]
+ # @param origin [Spree::StockLocation, nil] where the parcel ships from
+ # @param destination [Spree::Address, nil] where it is going
+ # @param integration [SpreeEasyPost::Integration, nil] customs signer/contents preferences
+ # @return [Hash, nil] nil when the shipment is domestic or undeterminable
+ def self.customs_info_params(package, origin, destination, integration = nil)
+ return unless international?(origin, destination)
+
+ items = customs_items_params(package)
+ return if items.empty?
+
+ {
+ contents_type: integration&.preferred_customs_contents_type.presence || 'merchandise',
+ restriction_type: 'none',
+ eel_pfc: 'NOEEI 30.37(a)',
+ customs_certify: true,
+ customs_signer: integration&.preferred_customs_signer.presence,
+ customs_items: items
+ }.compact_blank
+ end
+
+ # One customs item per package line. Quantity, value and weight always;
+ # classification only when present.
+ #
+ # @param package [Spree::Stock::Package]
+ # @return [Array<Hash>]
+ def self.customs_items_params(package)
+ store = package.owner&.store
+
+ package.contents.filter_map do |item|
+ variant = item.variant
+ next if variant.nil?
+
+ {
+ description: variant.customs_description_for_declaration,
+ quantity: item.quantity,
+ value: (item.price.to_f * item.quantity).round(2),
+ weight: ounces(item.weight, store),
+ origin_country: variant.country_of_origin.presence,
+ hs_tariff_number: variant.hs_code.presence,
+ currency: package.owner&.currency
+ }.compact_blank
+ end
+ end
+
+ # A shipment crosses a customs border when its origin and destination
+ # countries differ. Unknown countries mean domestic — never attach a
+ # customs form on a guess.
+ def self.international?(origin, destination)
+ origin_iso = origin&.country&.iso
+ destination_iso = destination&.country&.iso
+ return false if origin_iso.blank? || destination_iso.blank?
+
+ origin_iso != destination_iso
+ end
+
# EndShipper payload — the party legally responsible for the shipment,
# required when buying labels on EasyPost's own carrier accounts (USPS
# refuses the purchase without one). Unlike a plain address, EasyPost
diff --git a/spree/providers/easypost/spec/models/spree_easypost/customs_params_spec.rb b/spree/providers/easypost/spec/models/spree_easypost/customs_params_spec.rb
new file mode 100644
index 0000000000..737394cf51
--- /dev/null
+++ b/spree/providers/easypost/spec/models/spree_easypost/customs_params_spec.rb
@@ -0,0 +1,102 @@
+require 'spec_helper'
+
+RSpec.describe 'SpreeEasyPost customs params' do
+ let(:store) { @default_store }
+ let(:usa) { Spree::Country.find_by(iso: 'US') || create(:country, iso: 'US') }
+ let(:canada) { Spree::Country.find_by(iso: 'CA') || create(:country, iso: 'CA', name: 'Canada') }
+
+ let(:origin) { create(:stock_location, country: usa) }
+ let(:domestic_destination) { create(:address, country: usa) }
+ let(:foreign_destination) { create(:address, country: canada, state: nil, state_name: 'Ontario', zipcode: 'K1A 0B1') }
+
+ let(:order) { create(:order_with_line_items, store: store, line_items_count: 1) }
+ let(:variant) { order.line_items.first.variant }
+
+ let(:package) do
+ fulfillment = order.fulfillments.first
+ fulfillment.to_package.tap { |pkg| pkg.owner = order }
+ end
+
+ describe '.international?' do
+ it 'is true when origin and destination countries differ' do
+ expect(SpreeEasyPost.international?(origin, foreign_destination)).to be true
+ end
+
+ it 'is false for a domestic shipment' do
+ expect(SpreeEasyPost.international?(origin, domestic_destination)).to be false
+ end
+
+ it 'is false when either country is unknown — never guess a customs form' do
+ expect(SpreeEasyPost.international?(origin, build(:address, country: nil))).to be false
+ expect(SpreeEasyPost.international?(nil, foreign_destination)).to be false
+ end
+ end
+
+ describe '.customs_info_params' do
+ it 'returns nil for a domestic shipment' do
+ expect(SpreeEasyPost.customs_info_params(package, origin, domestic_destination)).to be_nil
+ end
+
+ it 'builds a declaration for an international shipment' do
+ params = SpreeEasyPost.customs_info_params(package, origin, foreign_destination)
+
+ expect(params[:contents_type]).to eq('merchandise')
+ expect(params[:customs_certify]).to be true
+ expect(params[:customs_items].size).to eq(1)
+ end
+
+ it 'carries the variant classification when the merchant recorded it' do
+ variant.update!(hs_code: '640411', country_of_origin: 'VN', customs_description: 'Leather footwear')
+
+ item = SpreeEasyPost.customs_info_params(package, origin, foreign_destination)[:customs_items].first
+
+ expect(item[:hs_tariff_number]).to eq('640411')
+ expect(item[:origin_country]).to eq('VN')
+ expect(item[:description]).to eq('Leather footwear')
+ end
+
+ it 'omits classification that was never recorded rather than sending blanks' do
+ variant.update!(hs_code: nil, country_of_origin: nil, customs_description: nil)
+
+ item = SpreeEasyPost.customs_info_params(package, origin, foreign_destination)[:customs_items].first
+
+ expect(item).not_to have_key(:hs_tariff_number)
+ expect(item).not_to have_key(:origin_country)
+ expect(item[:description]).to eq(variant.name)
+ end
+
+ it 'takes the signer and contents type from the integration when configured' do
+ integration = SpreeEasyPost::Integration.new(
+ store: store,
+ preferences: { customs_signer: 'Jane Doe', customs_contents_type: 'gift' }
+ )
+
+ params = SpreeEasyPost.customs_info_params(package, origin, foreign_destination, integration)
+
+ expect(params[:customs_signer]).to eq('Jane Doe')
+ expect(params[:contents_type]).to eq('gift')
+ end
+
+ it 'defaults the incoterm to DAP so the recipient is billed for duties' do
+ integration = SpreeEasyPost::Integration.new(store: store)
+
+ expect(integration.preferred_incoterm).to eq('DAP')
+ end
+
+ it 'rejects an incoterm EasyPost would refuse' do
+ integration = SpreeEasyPost::Integration.new(store: store, preferences: { incoterm: 'DDU' })
+
+ expect(integration).not_to be_valid
+ expect(integration.errors[:preferred_incoterm]).to be_present
+ end
+
+ it 'declares the line value and quantity' do
+ line_item = order.line_items.first
+
+ item = SpreeEasyPost.customs_info_params(package, origin, foreign_destination)[:customs_items].first
+
+ expect(item[:quantity]).to eq(line_item.quantity)
+ expect(item[:value]).to eq((line_item.price.to_f * line_item.quantity).round(2))
+ end
+ end
+end