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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add customs duties and shopper-visible custom fees
Damian Legawiec2ed88a23c67d
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.yamlindex 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-fR29P32ZUIYUYdruCmnzIwSaVMchQskuser:id: adm_UkLWZg9DAJemail: [email protected]- first_name: Jenee- last_name: Renner- full_name: Jenee Renner+ first_name: Greg+ last_name: Effertz+ full_name: Greg Effertzselected_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_zh1OqYctFZMd0Jkp1AqePpUWwAC2eagb1Euser:id: adm_UkLWZg9DAJemail: [email protected]- first_name: Sybil- last_name: Reinger- full_name: Sybil Reinger+ first_name: Cindie+ last_name: Turcotte+ full_name: Cindie Turcotteselected_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- email: [email protected]- first_name: Michal- last_name: Welch- full_name: Michal Welch+ email: [email protected]+ first_name: Dottie+ last_name: Cormier+ full_name: Dottie Cormierselected_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- email: [email protected]- first_name: Chiquita- last_name: Tremblay- full_name: Chiquita Tremblay+ email: [email protected]+ first_name: Avery+ last_name: Jacobs+ full_name: Avery Jacobsselected_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_uWcLRMuser:id: adm_UkLWZg9DAJemail: [email protected]- first_name: Kiersten- last_name: Jenkins- full_name: Kiersten Jenkins+ first_name: Delena+ last_name: Stiedemann+ full_name: Delena Stiedemannselected_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-jPmBrXsuser:id: adm_UkLWZg9DAJemail: [email protected]@@ -712,8 +712,8 @@ paths:last_name: Ownerfull_name: Olivia Ownerselected_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: stringdescription: ISO currency code for the store.example: USD- country_code:+ country_iso:type: stringdescription: ISO 3166-1 alpha-2 country code for the store.example: US@@ -853,8 +853,8 @@ paths:data:- id: ao_UkLWZg9DAJorigin: 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: 1limit: 25@@ -938,8 +938,8 @@ paths:example:id: ao_gbHJdmfrXBorigin: 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_UkLWZg9DAJorigin: 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_UkLWZg9DAJorigin: 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: publishabletoken_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_zzvf4TQZ9KzfrBSzNNgyUMn6created_by_email:- id: key_gbHJdmfrXBname: Backend integrationkey_type: secret- token_prefix: sk_Ef9ZLtumw+ token_prefix: sk_1p982aCo1scopes:- 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: corporiskey_type: secret- token_prefix: sk_P443avskw+ token_prefix: sk_1WeBKpEnCscopes:- 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_VqXmZF31wYname: CI keykey_type: secret- token_prefix: sk_77SgLPyNB+ token_prefix: sk_gaDR5JKTRscopes:- 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 errorcontent:@@ -1401,12 +1401,12 @@ paths:key_type: publishabletoken_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_dqafZMQtfsuid4Tw2UJYmTCFcreated_by_email:patch:summary: Update an API key@@ -1460,11 +1460,11 @@ paths:id: key_gbHJdmfrXBname: Backend integration (renamed)key_type: secret- token_prefix: sk_nmHXXafaP+ token_prefix: sk_HjedJ7QLsscopes:- 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: essekey_type: secret- token_prefix: sk_n4WZVFRwi+ token_prefix: sk_eNChDqD3tscopes:- 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_gbHJdmfrXBname: Backend integrationkey_type: secret- token_prefix: sk_k9RnDkhzA+ token_prefix: sk_guScDmmePscopes:- 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: 1rgt: 2products_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: 1limit: 25@@ -1782,8 +1782,8 @@ paths:lft: 2rgt: 3products_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: 1rgt: 2products_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: 1rgt: 2products_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: 2rgt: 3products_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-18240meta_title:meta_description:meta_keywords:@@ -2202,14 +2202,25 @@ paths:in_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: activemetadata: {}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_UkLWZg9DAJproduct_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_gbHJdmfrXBname: 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_requiredpreferred_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_UkLWZg9DAJposition: 1active: 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_locationchannel_id: ch_UkLWZg9DAJpreferences: {}@@ -2954,8 +2965,8 @@ paths:- id: orule_gbHJdmfrXBposition: 2active: 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_splitschannel_id: ch_UkLWZg9DAJpreferences: {}@@ -2966,8 +2977,8 @@ paths:- id: orule_EfhxLZ9ck8position: 3active: 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_locationchannel_id: ch_UkLWZg9DAJpreferences: {}@@ -3032,8 +3043,8 @@ paths:id: orule_VqXmZF31wYposition: 3active: 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_locationchannel_id: ch_UkLWZg9DAJpreferences: {}@@ -3128,8 +3139,8 @@ paths:id: orule_UkLWZg9DAJposition: 2active: 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_locationchannel_id: ch_UkLWZg9DAJpreferences: {}@@ -3317,8 +3328,8 @@ paths:searchable: falsesortable: falsefilter_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_gbHJdmfrXBnamespace: customkey: order_notes@@ -3329,8 +3340,8 @@ paths:searchable: falsesortable: falsefilter_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: 1limit: 25@@ -3399,8 +3410,8 @@ paths:searchable: falsesortable: falsefilter_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: falsesortable: falsefilter_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 definitiontags:@@ -3569,8 +3580,8 @@ paths:searchable: falsesortable: falsefilter_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: VIPsdescription: Top spenderscustomers_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_gbHJdmfrXBname: Wholesaledescription: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: 1limit: 25@@ -3812,8 +3823,8 @@ paths:name: Wholesale 2description: B2B accountscustomers_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: VIPsdescription: Top spenderscustomers_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- email: [email protected]- first_name: Danae- last_name: Johnson+ email: [email protected]+ first_name: Shenita+ last_name: Jacobiphone:accepts_email_marketing: false- full_name: Danae Johnson+ full_name: Shenita Jacobiavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"failed_attempts: 0metadata: {}- 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 spenderscustomers_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 Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorklabel: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_UkLWZg9DAJmeta: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: bashlabel: Spree CLIsource: 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":"+1212 555 1234","label":"Office","is_default_shipping":true}'parameters:- name: x-spree-api-key@@ -4263,20 +4272,18 @@ paths:city: New Yorkphone: "+12125551234"company:- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorklabel: Officemetadata: {}- 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_UkLWZg9DAJrequestBody:content:@@ -4296,10 +4303,10 @@ paths:type: stringpostal_code:type: string- country_code:+ country_iso:type: stringdescription: ISO-2 country code (e.g. US)- state_code:+ state_abbr:type: stringdescription: State/province abbreviation (e.g. NY)phone:@@ -4380,20 +4387,18 @@ paths:city: Manhattanphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorklabel: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_UkLWZg9DAJrequestBody:content:@@ -4532,8 +4537,8 @@ paths:customer_id: cust_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJmetadata: {}- 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: 1limit: 25@@ -4623,8 +4628,8 @@ paths:customer_id: cust_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJmetadata: {}- 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 cardtags:@@ -4749,8 +4754,8 @@ paths:currency: USDmemo: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_UkLWZg9DAJcreated_by_id: adm_UkLWZg9DAJcategory_id: sccat_UkLWZg9DAJ@@ -4829,8 +4834,8 @@ paths:currency: USDmemo: Goodwillmetadata: {}- 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_UkLWZg9DAJcreated_by_id: adm_gbHJdmfrXBcategory_id: sccat_UkLWZg9DAJ@@ -4925,8 +4930,8 @@ paths:currency: USDmemo: Updatedmetadata: {}- 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_UkLWZg9DAJcreated_by_id: adm_UkLWZg9DAJcategory_id: sccat_UkLWZg9DAJ@@ -5085,8 +5090,8 @@ paths:display_available_store_credit_total: "$0.00"failed_attempts: 0metadata: {}- 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: 0metadata: {}- 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: 0metadata: {}- 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: 0metadata: {}- 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_UkLWZg9DAJnumber: EF1001format: 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: productsuser_id: adm_UkLWZg9DAJdone: false@@ -5882,8 +5887,8 @@ paths:id: exp_gbHJdmfrXBnumber: EF1002format: 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: productsuser_id: adm_UkLWZg9DAJdone: false@@ -5982,8 +5987,8 @@ paths:id: exp_UkLWZg9DAJnumber: EF1001format: 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: productsuser_id: adm_UkLWZg9DAJdone: 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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -6293,7 +6298,7 @@ paths:display_tax_total: "$0.00"status: fulfilledfulfillment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -6679,7 +6684,7 @@ paths:display_tax_total: "$0.00"status: fulfilledfulfillment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments:@@ -6895,10 +6900,10 @@ paths:display_tax_total: "$0.00"status: deliveredfulfillment_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_UkLWZg9DAJvariant_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJdocuments: []@@ -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_UkLWZg9DAJstock_location_id: sloc_gbHJdmfrXBdocuments: []@@ -7336,8 +7341,8 @@ paths:codes_count: 2currency: USDprefix: 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: 5currency: USDprefix: 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: 2currency: USDprefix: 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: 521DDC5B550D3810status: activecurrency: USDamount: '50.0'@@ -7647,12 +7652,12 @@ paths:redeemed_at:expired: falseactive: 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: 7314CBC4F3541779status: activecurrency: USDamount: '25.0'@@ -7666,8 +7671,8 @@ paths:redeemed_at:expired: falseactive: 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: FBB3C9A9C5D6B0B9status: activecurrency: USDamount: '25.0'@@ -7769,8 +7774,8 @@ paths:redeemed_at:expired: falseactive: 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_UkLWZg9DAJschema:@@ -7879,7 +7884,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: E3AD2DF767AA856B+ code: 726B10E5707D6E53status: activecurrency: USDamount: '50.0'@@ -7893,8 +7898,8 @@ paths:redeemed_at:expired: falseactive: 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: 7E8976807B8EF1F2status: activecurrency: USDamount: '75.0'@@ -7971,8 +7976,8 @@ paths:redeemed_at:expired: falseactive: 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_UkLWZg9DAJnumber: IM1001rows_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: productsstatus: pendingowner_type: store@@ -8167,6 +8172,15 @@ paths:- name: product_typelabel: Product Typerequired: 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_srclabel: Image 1 URLrequired: false@@ -8256,8 +8270,8 @@ paths:id: imp_gbHJdmfrXBnumber: IM1002rows_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: productsstatus: mappingowner_type: store@@ -8346,6 +8360,15 @@ paths:- name: product_typelabel: Product Typerequired: 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_srclabel: Image 1 URLrequired: false@@ -8494,50 +8517,62 @@ paths:file_column:required: false- id: immap_3uWpPTcf5W- schema_field: image1_src+ schema_field: hs_codefile_column:required: false- id: immap_D6Psx31WaT- schema_field: image2_src+ schema_field: country_of_originfile_column:required: false- id: immap_msx3nOJap6- schema_field: image3_src+ schema_field: customs_descriptionfile_column:required: false- id: immap_5CQZnCRf8J- schema_field: option1_name+ schema_field: image1_srcfile_column:required: false- id: immap_M2nyloHRUQ- schema_field: option1_value+ schema_field: image2_srcfile_column:required: false- id: immap_prklVeMgbn- schema_field: option2_name+ schema_field: image3_srcfile_column:required: false- id: immap_so8jaGonyx- schema_field: option2_value+ schema_field: option1_namefile_column:required: false- id: immap_rsClYtECFI- schema_field: option3_name+ schema_field: option1_valuefile_column:required: false- id: immap_8DR0I7fEbw- schema_field: option3_value+ schema_field: option2_namefile_column:required: false- id: immap_aAtNvLSUAr- schema_field: category1+ schema_field: option2_valuefile_column:required: false- id: immap_QiA48cIW7A- schema_field: category2+ schema_field: option3_namefile_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_48Olu6p4zZschema_field: category3file_column:required: false@@ -8694,8 +8729,8 @@ paths:id: imp_UkLWZg9DAJnumber: IM1001rows_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: productsstatus: pendingowner_type: store@@ -8784,6 +8819,15 @@ paths:- name: product_typelabel: Product Typerequired: 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_srclabel: Image 1 URLrequired: false@@ -8931,8 +8975,8 @@ paths:id: imp_gbHJdmfrXBnumber: IM1002rows_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: productsstatus: completed_mappingowner_type: store@@ -9021,6 +9065,15 @@ paths:- name: product_typelabel: Product Typerequired: 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_srclabel: Image 1 URLrequired: 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_5CQZnCRf8Jschema_field: image1_srcfile_column: image1_srcrequired: false- - id: immap_D6Psx31WaT+ - id: immap_M2nyloHRUQschema_field: image2_srcfile_column: image2_srcrequired: false- - id: immap_msx3nOJap6+ - id: immap_prklVeMgbnschema_field: image3_srcfile_column: image3_srcrequired: false- - id: immap_5CQZnCRf8J+ - id: immap_so8jaGonyxschema_field: option1_namefile_column: option1_namerequired: false- - id: immap_M2nyloHRUQ+ - id: immap_rsClYtECFIschema_field: option1_valuefile_column: option1_valuerequired: false- - id: immap_prklVeMgbn+ - id: immap_8DR0I7fEbwschema_field: option2_namefile_column: option2_namerequired: false- - id: immap_so8jaGonyx+ - id: immap_aAtNvLSUArschema_field: option2_valuefile_column: option2_valuerequired: false- - id: immap_rsClYtECFI+ - id: immap_QiA48cIW7Aschema_field: option3_namefile_column: option3_namerequired: false- - id: immap_8DR0I7fEbw+ - id: immap_QDA48cIW7Aschema_field: option3_valuefile_column: option3_valuerequired: false- - id: immap_aAtNvLSUAr+ - id: immap_8cR0I7fEbwschema_field: category1file_column: category1required: false- - id: immap_QiA48cIW7A+ - id: immap_oqlrKdXjaPschema_field: category2file_column: category2required: false- - id: immap_QDA48cIW7A+ - id: immap_48Olu6p4zZschema_field: category3file_column: category3required: false@@ -9267,8 +9332,8 @@ paths:id: imp_gbHJdmfrXBnumber: IM1002rows_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: productsstatus: processingowner_type: store@@ -9357,6 +9422,15 @@ paths:- name: product_typelabel: Product Typerequired: 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_srclabel: Image 1 URLrequired: false@@ -9441,8 +9515,8 @@ paths:row_number: 2status: failedvalidation_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_UkLWZg9DAJitem_type:item_id:@@ -9535,31 +9609,29 @@ paths:example:data:- id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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_gbHJdmfrXBname: EUcurrency: USDdefault_locale: entax_inclusive: falsedefault: false- country_codes:+ country_isos:- DEsupported_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: 1limit: 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 aresilently 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: bashlabel: 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-keyin: header@@ -9647,14 +9719,13 @@ paths:default_locale: frtax_inclusive: truedefault: false- country_codes:+ country_isos:- FRsupported_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: integerdescription: Sort order within the store; lower = first.- country_codes:+ country_isos:type: arrayitems: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: entax_inclusive: falsedefault: false- country_codes:+ country_isos:- DEsupported_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 themarket's country list (full-set update), `supported_locales` toreplace the supported locales, or `position` to reorder the marketwithin 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: bashlabel: 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-keyin: header@@ -9867,13 +9937,12 @@ paths:default_locale: entax_inclusive: truedefault: false- country_codes:+ country_isos:- DEsupported_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: booleanposition:type: integer- country_codes:+ country_isos:type: arrayitems:type: string@@ -10053,8 +10122,8 @@ paths:kind: dropdownmetadata: {}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: 1limit: 25@@ -10148,8 +10217,8 @@ paths:kind: dropdownmetadata: {}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: dropdownmetadata: {}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: dropdownmetadata: {}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: internalmetadata: {}- 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: 1limit: 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: 1limit: 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 discountcontent:@@ -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 feecontent:@@ -10799,6 +10864,7 @@ paths:- gift_wrap- cod- payment+ - dutyexample: gift_wrapdescription: Defaults to 'surcharge'line_item_id:@@ -10864,7 +10930,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: EB72080196E6198E+ code: 01E8086A850C3F0Estatus: activecurrency: USDamount: '10.0'@@ -10878,8 +10944,8 @@ paths:redeemed_at:expired: falseactive: 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: 2currency: USD- name: Product 319055- slug: product-319055+ name: Product 311668+ slug: product-311668options_text: 'Size: S'price: '10.0'display_price: "$10.00"@@ -11053,12 +11119,12 @@ paths:option_type_label: Sizeimage_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_UkLWZg9DAJmeta:@@ -11130,8 +11196,8 @@ paths:preorder_ships_at:quantity: 3currency: USD- name: Product 339322- slug: product-339322+ name: Product 337252+ slug: product-337252options_text: 'Size: S'price: '19.99'display_price: "$19.99"@@ -11163,12 +11229,12 @@ paths:option_type_label: Sizeimage_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_UkLWZg9DAJrequestBody:@@ -11262,8 +11328,8 @@ paths:preorder_ships_at:quantity: 2currency: USD- name: Product 349097- slug: product-349097+ name: Product 345801+ slug: product-345801options_text: 'Size: S'price: '10.0'display_price: "$10.00"@@ -11295,12 +11361,12 @@ paths:option_type_label: Sizeimage_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_UkLWZg9DAJpatch:@@ -11367,8 +11433,8 @@ paths:preorder_ships_at:quantity: 5currency: USD- name: Product 357145- slug: product-357145+ name: Product 352815+ slug: product-352815options_text: 'Size: S'price: '19.99'display_price: "$19.99"@@ -11400,12 +11466,12 @@ paths:option_type_label: Sizeimage_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_UkLWZg9DAJrequestBody:@@ -11527,7 +11593,7 @@ paths:cart_id:channel_id: ch_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: draftlast_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_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: draftlast_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":"Pleaseleave at the front desk.","internal_note":"<p>VIP customer — handle withcare.</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":"+1212 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":"+1212 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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: draftlast_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: stringpostal_code:type: string- country_code:+ country_iso:type: string- state_code:+ state_abbr:type: stringphone:type: string@@ -12132,9 +12195,9 @@ paths:type: stringpostal_code:type: string- country_code:+ country_iso:type: string- state_code:+ state_abbr:type: stringphone:type: string@@ -12234,7 +12297,7 @@ paths:cart_id:channel_id: ch_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: draftlast_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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: draftlast_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: stringzipcode:type: string- country_code:+ country_iso:type: string- state_code:+ state_abbr:type: stringphone:type: string@@ -12493,9 +12554,9 @@ paths:type: stringzipcode:type: string- country_code:+ country_iso:type: string- state_code:+ state_abbr:type: stringphone:type: string@@ -12622,7 +12683,7 @@ paths:cart_id:channel_id: ch_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: en@@ -12630,7 +12691,7 @@ paths:coupon_code:fulfillment_status: unfulfilledpayment_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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: placedlast_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_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: en@@ -12780,7 +12840,7 @@ paths:coupon_code:fulfillment_status: canceledpayment_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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: canceledlast_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_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: placedlast_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_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: en@@ -13039,7 +13097,7 @@ paths:coupon_code:fulfillment_status: unfulfilledpayment_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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: placedlast_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_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsegift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: placedlast_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: checkoutstorefront_visible: trueposition: 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: checkoutstorefront_visible: trueposition: 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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-662650d8fd89+ response_code: BGS-2976f87fae70number: R1001-P1amount: '110.0'display_amount: "$110.00"@@ -13537,14 +13593,14 @@ paths:customer_id:payment_method_id: pm_gbHJdmfrXBmetadata: {}- 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_UkLWZg9DAJmeta:@@ -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_gbHJdmfrXBrequestBody:@@ -13719,7 +13775,7 @@ paths:example:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-e9f5b3e49ece+ response_code: BGS-50b5b736692anumber: R1001-P1amount: '110.0'display_amount: "$110.00"@@ -13738,14 +13794,14 @@ paths:customer_id:payment_method_id: pm_gbHJdmfrXBmetadata: {}- 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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-7a39f82da69c+ response_code: BGS-54266d817232number: R1001-P1amount: '110.0'display_amount: "$110.00"@@ -13827,14 +13883,14 @@ paths:customer_id:payment_method_id: pm_gbHJdmfrXBmetadata: {}- 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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: void-BGS-56cea42c3ebd+ response_code: void-BGS-c2af1d7367e0number: R1001-P1amount: '110.0'display_amount: "$110.00"@@ -13925,14 +13981,14 @@ paths:customer_id:payment_method_id: pm_gbHJdmfrXBmetadata: {}- 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: falseproducts_count: 0prices_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: falseproducts_count: 0prices_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: falseproducts_count: 1prices_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: falseproducts_count: 0prices_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: falseproducts_count: 0prices_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: trueproducts_count: 0prices_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: falseproducts_count: 0prices_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_gbHJdmfrXBamount: '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_EfhxLZ9ck8amount: '5.0'amount_in_cents: 500@@ -14782,8 +14838,8 @@ paths:display_compare_at_amount:price_list_id: pl_UkLWZg9DAJvariant_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: 1limit: 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_UkLWZg9DAJvariant_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_UkLWZg9DAJvariant_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_textkey: custom.titlevalue: 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: truecustom_field_definition_id: cfdef_UkLWZg9DAJmeta:@@ -15403,8 +15459,8 @@ paths:field_type: long_textkey: custom.descriptionvalue: 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: truecustom_field_definition_id: cfdef_gbHJdmfrXB'422':@@ -15503,8 +15559,8 @@ paths:field_type: short_textkey: custom.titlevalue: 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: truecustom_field_definition_id: cfdef_UkLWZg9DAJpatch:@@ -15568,8 +15624,8 @@ paths:field_type: short_textkey: custom.titlevalue: 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: truecustom_field_definition_id: cfdef_UkLWZg9DAJrequestBody:@@ -15688,10 +15744,10 @@ paths:- key: descriptiontype: htmlsource: |-- 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: slugtype: stringsource: espresso-machine@@ -15802,8 +15858,8 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 768575- slug: product-768575+ name: Product 763867+ slug: product-763867meta_title:meta_description:meta_keywords:@@ -15815,16 +15871,24 @@ paths:in_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: activemetadata: {}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_UkLWZg9DAJproduct_type_id:tax_category_id: taxcat_UkLWZg9DAJ@@ -15984,8 +16048,8 @@ paths:status: draftmetadata: {}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_UkLWZg9DAJproduct_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-807256meta_title:meta_description:meta_keywords:@@ -16205,15 +16269,28 @@ paths:in_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: activemetadata: {}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_UkLWZg9DAJproduct_type_id:tax_category_id: taxcat_UkLWZg9DAJ@@ -16307,7 +16384,7 @@ paths:example:id: prod_UkLWZg9DAJname: Updated Name- slug: product-824503+ slug: product-827573meta_title:meta_description:meta_keywords:@@ -16319,21 +16396,28 @@ paths:in_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: activemetadata: {}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_UkLWZg9DAJproduct_type_id:tax_category_id: taxcat_UkLWZg9DAJ@@ -17300,15 +17384,15 @@ paths:- id: coupon_UkLWZg9DAJcode: AAA111state: 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_UkLWZg9DAJorder_id:- id: coupon_gbHJdmfrXBcode: BBB222state: 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_UkLWZg9DAJorder_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_shippingpromotion_id: promo_UkLWZg9DAJpreferences: {}@@ -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_shippingpromotion_id: promo_UkLWZg9DAJpreferences: {}@@ -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: currencypromotion_id: promo_UkLWZg9DAJpreferences:@@ -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: currencypromotion_id: promo_UkLWZg9DAJpreferences:@@ -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: currencypromotion_id: promo_UkLWZg9DAJpreferences:@@ -17836,7 +17920,7 @@ paths:name: Summer Saledescription: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 Fridaydescription: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 Saledescription: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 Saledescription: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: Countrydescription:preference_schema:- - key: country_codes+ - key: country_isostype: arraydefault: []- key: country_idtype: integerdefault:- - key: country_code+ - key: country_isotype: stringdefault:- type: currency@@ -18551,9 +18635,6 @@ paths:label: Item totaldescription:preference_schema:- - key: amount_min- type: decimal- default: 100.0- key: operator_mintype: stringdefault: ">"@@ -18563,6 +18644,9 @@ paths:- key: operator_maxtype: stringdefault: "<"+ - key: amount_min+ type: decimal+ default: 100.0- type: marketlabel: Market(s)description:@@ -18726,15 +18810,15 @@ paths:application/json:example:id: re_UkLWZg9DAJ- transaction_id: BGS-593f8c773ee8+ transaction_id: BGS-a73c5719bd3damount: '5.0'payment_id: py_UkLWZg9DAJrefund_reason_id: rr_UkLWZg9DAJoriginator_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_UkLWZg9DAJname: 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: falsemeta:page: 1@@ -18973,8 +19057,8 @@ paths:example:id: sccat_UkLWZg9DAJname: 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: falseschema:"$ref": "#/components/schemas/StoreCreditCategory"@@ -19068,8 +19152,8 @@ paths:preferred_order_number_prefix: Rpreferred_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: falseurl: http://www.example.com:3000api_url: http://www.example.com:3000@@ -19384,8 +19468,8 @@ paths:preferred_order_number_prefix: Rpreferred_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: falseurl: http://www.example.com:3000api_url: http://www.example.com:3000@@ -19712,24 +19796,16 @@ paths:code: invalid_taggable_typemessage: 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 resourcestags:- Settingssecurity:- 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: Authorizationin: headerrequired: 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: stringresponses:'200':- description: tax rates found+ description: translatable resources foundcontent: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 translationstags:- Settingssecurity:- 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-keyin: header@@ -19855,93 +19919,111 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:- '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 upsertedcontent: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 stafftags:- - Settings+ - Staffsecurity:- 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_usersparameters:- name: x-spree-api-keyin: header@@ -19951,39 +20033,65 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:'200':- description: tax rate found+ description: staff foundcontent: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+ email: [email protected]+ 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 membertags:- - Settings+ - Staffsecurity:- 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-keyin: header@@ -19993,65 +20101,64 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: trueschema:type: stringresponses:'200':- description: tax rate updated+ description: staff member foundcontent: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+ email: [email protected]+ 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 membertags:- - Settings+ - Staffsecurity:- 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-keyin: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header+ - name: id+ in: pathrequired: trueschema:type: stringresponses:'200':- description: translatable resources found+ description: staff member updatedcontent: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+ email: [email protected]+ 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 storetags:- - Settings+ - Staffsecurity:- 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-keyin: header@@ -20192,92 +20250,24 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '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 invitationstags:- Staffsecurity:- 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: bashlabel: Spree CLI- source: spree api get /admin_users+ source: spree api get /invitationsparameters:- name: x-spree-api-keyin: header@@ -20308,27 +20298,25 @@ paths:type: stringresponses:'200':- description: staff found+ description: invitations foundcontent:application/json:example:data:- - id: adm_UkLWZg9DAJ- email: [email protected]- 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+ email: [email protected]+ 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_UkLWZg9DAJname: Spree Test Store- code: spree_1meta:page: 1limit: 25@@ -20339,15 +20327,17 @@ paths:in: 1previous:next:- "/api/v3/admin/admin_users/{id}":- get:- summary: Show a staff member+ post:+ summary: Create an invitationtags:- Staffsecurity:- 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: javascriptlabel: 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: bashlabel: 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- email: [email protected]- 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- email: [email protected]- 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- email: [email protected]- 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-keyin: header@@ -20647,13 +20376,13 @@ paths:id: inv_gbHJdmfrXBemail: [email protected]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_UkLWZg9DAJrole_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: falsestore:id: store_UkLWZg9DAJ@@ -20766,15 +20495,15 @@ paths:application/json:example:id: inv_UkLWZg9DAJ- email: [email protected]+ email: [email protected]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_UkLWZg9DAJrole_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: falsestore:id: store_UkLWZg9DAJ@@ -21119,8 +20848,8 @@ paths:- id: role_UkLWZg9DAJname: admindescription:- 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_gbHJdmfrXBname: order_managerdescription: 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_gbHJdmfrXBname: supportdescription:- 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_59name: Brooklyn warehouseaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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_59pickup_ready_in_minutes:pickup_instructions:admin_name:@@ -21512,8 +21241,8 @@ paths:kind: warehousepickup_enabled: falsepickup_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: 1limit: 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: bashlabel: 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-keyin: header@@ -21605,13 +21334,13 @@ paths:application/json:example:id: sloc_gbHJdmfrXB+ state_abbr:name: Manhattan storeaddress1:city:zipcode:- country_code:+ country_iso:country_name:- state_code:state_text:pickup_ready_in_minutes: 30pickup_instructions:@@ -21627,8 +21356,8 @@ paths:kind: storepickup_enabled: truepickup_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: stringnullable: true- country_code:+ country_iso:type: stringnullable: truedescription: ISO-3166 alpha-2 country code (e.g. "US").- state_code:+ state_abbr:type: stringnullable: truedescription: State / province abbreviation (e.g. "NY"). Resolved@@ -21783,14 +21512,14 @@ paths:application/json:example:id: sloc_UkLWZg9DAJ+ state_abbr: STATE_ABBR_63name: Brooklyn warehouseaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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_63pickup_ready_in_minutes:pickup_instructions:admin_name:@@ -21805,8 +21534,8 @@ paths:kind: warehousepickup_enabled: falsepickup_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_65name: Renamed warehouseaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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_65pickup_ready_in_minutes: 45pickup_instructions:admin_name:@@ -21895,8 +21624,8 @@ paths:kind: warehousepickup_enabled: truepickup_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: stringnullable: true- country_code:+ country_iso:type: stringnullable: true- state_code:+ state_abbr:type: stringnullable: truestate_name:@@ -22138,15 +21867,18 @@ paths:weight_unit: lbdimensions_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: falsetax_category_id: taxcat_UkLWZg9DAJavailable_stock: 0reserved_quantity: 0total_on_hand: 0- product_name: Product 1011489+ product_name: Product 1013945- id: variant_gbHJdmfrXBproduct_id: prod_UkLWZg9DAJsku: SKU-121@@ -22159,10 +21891,10 @@ paths:in_stock: falsebackorderable: truepreorder: false- weight: 90.34- height: 27.1- width: 51.7- depth: 6.0+ weight: 23.3+ height: 16.97+ width: 5.6+ depth: 19.82price:id: price_gbHJdmfrXBamount: '19.99'@@ -22185,8 +21917,8 @@ paths:option_type_label: Sizeimage_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: 2cost_price: '17.0'@@ -22195,15 +21927,18 @@ paths:weight_unit: lbdimensions_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: falsetax_category_id: taxcat_UkLWZg9DAJavailable_stock: 0reserved_quantity: 0total_on_hand: 0- product_name: Product 1011489+ product_name: Product 1013945meta:page: 1limit: 25@@ -22317,8 +22052,8 @@ paths:option_type_label: Sizeimage_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: 3cost_price:@@ -22327,15 +22062,18 @@ paths:weight_unit: lbdimensions_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: falsetax_category_id: taxcat_UkLWZg9DAJavailable_stock: 0reserved_quantity: 0total_on_hand: 0- product_name: Product 1025132+ product_name: Product 1025259'422':description: validation errorcontent:@@ -22522,10 +22260,10 @@ paths:in_stock: falsebackorderable: truepreorder: false- weight: 2.54- height: 44.43- width: 13.0- depth: 187.15+ weight: 83.78+ height: 109.4+ width: 16.58+ depth: 186.77price:id: price_gbHJdmfrXBamount: '19.99'@@ -22548,8 +22286,8 @@ paths:option_type_label: Sizeimage_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: 2cost_price: '17.0'@@ -22558,15 +22296,18 @@ paths:weight_unit: lbdimensions_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: falsetax_category_id: taxcat_UkLWZg9DAJavailable_stock: 0reserved_quantity: 0total_on_hand: 0- product_name: Product 1043301+ product_name: Product 1041255'404':description: variant not foundcontent:@@ -22650,10 +22391,10 @@ paths:in_stock: falsebackorderable: truepreorder: false- weight: 132.31- height: 176.4- width: 193.39- depth: 188.59+ weight: 100.31+ height: 42.72+ width: 45.52+ depth: 191.49price:id: price_gbHJdmfrXBamount: '19.99'@@ -22676,8 +22417,8 @@ paths:option_type_label: Sizeimage_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: 2cost_price: '17.0'@@ -22686,15 +22427,18 @@ paths:weight_unit: lbdimensions_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: falsetax_category_id: taxcat_UkLWZg9DAJavailable_stock: 0reserved_quantity: 0total_on_hand: 0- product_name: Product 1065267+ product_name: Product 1063883requestBody: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.createddata:@@ -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.createddata:@@ -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.createddata:@@ -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.createddisabled_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.placeddisabled_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: f919f8583dace47124ea01e64e3f717cc25a6018f099ac2302c37c5b100bd867last_delivery_at:recent_delivery_count: 0recent_failure_count: 0@@ -23479,8 +23223,8 @@ paths:- order.completed- product.createddisabled_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.createddisabled_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-2ef4c09abca1name: 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.createddisabled_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.createddisabled_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: falserules_match_policy: allmetadata: {}- 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: 1limit: 25@@ -24024,8 +23768,8 @@ paths:automatic: truerules_match_policy: anymetadata: {}- 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: falserules_match_policy: allmetadata: {}- 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: falserules_match_policy: allmetadata: {}- 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: idin: 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: stringresponses:- '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 productstags:- - Companies+ - Collectionssecurity:- 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-keyin: header@@ -25635,61 +24063,55 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: collection_id+ in: path+ required: true+ description: Collection IDschema:type: stringresponses:'200':- description: companies found+ description: products foundcontent: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: 1limit: 25- count: 1+ count: 0pages: 1- from: 1- to: 1- in: 1+ from: 0+ to: 0+ in: 0previous:next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Product"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - metapost:- summary: Create a company+ summary: Add a product to a collectiontags:- - Companies+ - Collectionssecurity:- 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-keyin: header@@ -25699,272 +24121,213 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: collection_id+ in: path+ required: true+ description: Collection IDschema:type: stringresponses:'201':- description: company created+ description: product addedcontent: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: activemetadata: {}- 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: objectproperties:- 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_abc123required:- - 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 collectiontags:- - Companies+ - Collectionssecurity:- 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: stringresponses:- '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- email: [email protected]- 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 producttags:- - Companies+ - Collectionssecurity:- 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: stringresponses:- '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- email: [email protected]- '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 repositionedrequestBody:content:application/json:schema:type: objectproperties:- 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 productsrequired:- - 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 typestags:- - Companies+ - Collectionssecurity:- 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: stringresponses:'200':- description: contact found+ description: types foundcontent: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- email: [email protected]- 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: Generaldefault: trueposition: 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: shippingdigital: falseoffers_pickup: false@@ -26086,11 +24449,11 @@ paths:application/json:example:id: fp_gbHJdmfrXB- name: Oversized 1786777112.4575481+ name: Oversized 1786713774.742147default: falseposition: 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: shippingdigital: falseoffers_pickup: false@@ -26194,8 +24557,8 @@ paths:id: og_EfhxLZ9ck8name: EU warehouseposition: 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_gbHJdmfrXBstock_location_ids:- sloc_UkLWZg9DAJ@@ -26270,11 +24633,11 @@ paths:application/json:example:id: fp_gbHJdmfrXB- name: Bulky 1786777112.518354+ name: Bulky 1786713774.797332default: falseposition: 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: shippingdigital: falseoffers_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: bashlabel: 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-keyin: header@@ -26738,28 +25101,28 @@ paths:members:- id: dzm_UkLWZg9DAJmember_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_gbHJdmfrXBmember_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_UkLWZg9DAJdelivery_origin_group_id: og_UkLWZg9DAJdelivery_method_ids: []@@ -26786,11 +25149,11 @@ paths:- country- state- postal_code- country_code:+ country_iso:type: stringnullable: trueexample: US- state_code:+ state_abbr:type: stringnullable: truepostal_code_prefix:@@ -26854,8 +25217,8 @@ paths:- id: int_UkLWZg9DAJname: Carrieractive: 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: carriergroup: shippingpreferences:@@ -26927,8 +25290,8 @@ paths:id: int_UkLWZg9DAJname: Carrieractive: 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: carriergroup: shippingpreferences:@@ -27120,8 +25483,8 @@ paths:- id: pt_UkLWZg9DAJname: T-Shirtproducts_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_gbHJdmfrXBname: Hoodieproducts_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_UkLWZg9DAJname: T-Shirtproducts_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_UkLWZg9DAJname: Premium T-Shirtproducts_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: truecountry_name:type: string- country_code:+ country_iso:type: stringstate_text:type: stringnullable: true- state_code:+ state_abbr:type: stringnullable: truequick_checkout:@@ -27911,11 +26274,6 @@ components:type: booleanis_default_shipping:type: boolean- state_abbr:- type: string- nullable: true- country_iso:- type: stringstate_name:type: stringnullable: 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: stringnullable: true+ fee_total:+ type: string+ nullable: true+ display_fee_total:+ type: string+ nullable: truestore_credit_total:type: stringnullable: 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: stringrequired:- 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- 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_policyx-typelizer: true- Company:+ Collection:type: objectproperties:id:type: stringname: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: stringnullable: true+ custom_fields:+ type: array+ items:+ "$ref": "#/components/schemas/CustomField"+ translations:+ type: object+ automatic:+ type: boolean+ rules_match_policy:+ type: stringmetadata:type: object- nullable: truecreated_at:type: stringupdated_at:type: string- locations_count:- type: number- company_locations:+ rules:type: arrayitems:- "$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_countx-typelizer: trueCountry:type: object@@ -28810,12 +27074,18 @@ components:allOf:- "$ref": "#/components/schemas/Market"nullable: true+ created_at:+ type: string+ updated_at:+ type: stringrequired:- iso- iso3- name- states_required- zipcode_required+ - created_at+ - updated_atx-typelizer: trueCouponCode:type: object@@ -29468,12 +27738,6 @@ components:type: stringmember_type:type: string- country_code:- type: string- nullable: true- state_code:- type: string- nullable: truepostal_code_prefix:type: stringnullable: true@@ -29483,9 +27747,15 @@ components:postal_code_to:type: stringnullable: true+ country_iso:+ type: string+ nullable: truecountry_name:type: stringnullable: true+ state_abbr:+ type: string+ nullable: truestate_name:type: stringnullable: 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: arrayitems:"$ref": "#/components/schemas/DeliveryRate"- tax_lines:- type: array- items:- "$ref": "#/components/schemas/TaxLine"metadata:type: objecttracking_details:@@ -30421,10 +28687,6 @@ components:type: arrayitems:"$ref": "#/components/schemas/DigitalLink"- tax_lines:- type: array- items:- "$ref": "#/components/schemas/TaxLine"metadata:type: objectcreated_at:@@ -30493,7 +28755,7 @@ components:type: booleandefault:type: boolean- country_codes:+ country_isos:type: arrayitems:type: string@@ -30505,9 +28767,6 @@ components:type: arrayitems:"$ref": "#/components/schemas/Country"- tax_provider:- type: string- nullable: truecreated_at:type: stringupdated_at:@@ -30519,9 +28778,8 @@ components:- default_locale- tax_inclusive- default- - country_codes+ - country_isos- supported_locales- - tax_provider- created_at- updated_atx-typelizer: true@@ -30840,6 +29098,12 @@ components:type: stringdisplay_delivery_total:type: string+ fee_total:+ type: string+ nullable: true+ display_fee_total:+ type: string+ nullable: truestore_credit_total:type: stringdisplay_store_credit_total:@@ -30904,12 +29168,6 @@ components:preferred_stock_location_id:type: stringnullable: true- company_location_id:- type: string- nullable: true- company_id:- type: string- nullable: truetags:type: arrayitems:@@ -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: stringname:type: string+ created_at:+ type: string+ updated_at:+ type: stringrequired:- abbr- name+ - created_at+ - updated_atx-typelizer: trueStockItem:type: object@@ -32203,6 +30467,9 @@ components:properties:id:type: string+ state_abbr:+ type: string+ nullable: truename:type: stringaddress1:@@ -32214,15 +30481,12 @@ components:zipcode:type: stringnullable: true- country_code:+ country_iso:type: stringnullable: truecountry_name:type: stringnullable: true- state_code:- type: string- nullable: truestate_text:type: stringnullable: true@@ -32267,13 +30531,13 @@ components:type: stringrequired:- 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_atx-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: trueTaxLine:type: objectproperties:@@ -32788,18 +30929,6 @@ components:metadata:type: objectnullable: true- taxability_reason:- type: string- nullable: true- country_code:- type: string- nullable: true- state_code:- type: string- nullable: true- data:- type: object- nullable: truecreated_at:type: stringupdated_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_codex-typelizer: trueVariant:type: object@@ -32966,6 +31037,15 @@ components:backorder_limit:type: numbernullable: true+ hs_code:+ type: string+ nullable: true+ country_of_origin:+ type: string+ nullable: true+ customs_description:+ type: string+ nullable: truedeleted_at:type: stringnullable: true@@ -33024,6 +31104,9 @@ components:- weight_unit- dimensions_unit- backorder_limit+ - hs_code+ - country_of_origin+ - customs_description- deleted_at- created_at- updated_atdiff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 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: aNyFSEVouMVNrovNCwy3ZU1Juser:id: cust_UkLWZg9DAJemail: [email protected]- first_name: Patrica- last_name: Fahey+ first_name: Gerda+ last_name: Gradyphone:accepts_email_marketing: false- full_name: Patrica Fahey+ full_name: Gerda Gradyavailable_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: Np6btqSDwtNpgspCXzeLPJKVuser:id: cust_UkLWZg9DAJemail: [email protected]- first_name: Rosena- last_name: Hettinger+ first_name: Benny+ last_name: Rueckerphone:accepts_email_marketing: false- full_name: Rosena Hettinger+ full_name: Benny Rueckeravailable_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: tVf2rTDBFm4GgHWqqFFNC81xuser:id: cust_UkLWZg9DAJemail: [email protected]- first_name: Kimberlee- last_name: Berge+ first_name: Milo+ last_name: Walkerphone:accepts_email_marketing: false- full_name: Kimberlee Berge+ full_name: Milo Walkeravailable_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-134916meta_title:meta_description:meta_keywords:@@ -892,23 +892,25 @@ paths:in_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_url:tags: []@@ -1063,8 +1065,8 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 1798980- slug: product-1798980+ name: Product 1796510+ slug: product-1796510meta_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-1803196meta_title:meta_description:meta_keywords:@@ -1106,14 +1108,26 @@ paths:in_stock: falsebackorderable: trueavailable: 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_EfhxLZ9ck8thumbnail_url:tags: []@@ -1215,8 +1229,8 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 207961- slug: product-207961+ name: Product 2073051+ slug: product-2073051meta_title:meta_description:meta_keywords:@@ -1250,7 +1264,7 @@ paths:amount_in_cents: 999currency: USDdisplay_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_UkLWZg9DAJpreferred_stock_location_id:number: cart_gbHJdmfrXB- token: nMM4hK2cBpC5bcxn17eCDC4E+ token: 87SPiSTKyoRsXETppFVLPTz3email: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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_gbHJdmfrXBvariant_id: variant_gbHJdmfrXB@@ -1559,8 +1576,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1098909- slug: product-1098909+ name: Product 1099095+ slug: product-1099095options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -1605,7 +1622,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: qJc6nPebysuz7wYWmKnMrtk9+ token: qCiggumGg7qksUXEMJXhGZ7Aemail: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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -1664,8 +1684,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 108320- slug: product-108320+ name: Product 1081434+ slug: product-1081434options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -1783,7 +1803,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: ZoBNKJfCnTWRc1a39eFXVB4j+ token: 4N1DoS61UNeCowA9xVPXCHCCemail: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 requiredshipping_eq_billing_address: truediscounts: []+ fees: []items: []fulfillments: []payments: []@@ -1836,12 +1859,12 @@ paths:gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -1948,7 +1971,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: 33ibYah7Ew4wcQba25e6BhHS+ token: tBbVoqmdyMRL5KrM1TpdMzdpemail:customer_note:currency: USD@@ -1956,7 +1979,7 @@ paths:total_quantity: 0warnings:- code: line_item_removed- message: Product 1138056 was removed because it was sold out+ message: Product 11323 was removed because it was sold outline_item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJcoupon_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 requiredshipping_eq_billing_address: truediscounts: []+ fees: []items: []fulfillments: []payments: []@@ -2005,12 +2031,12 @@ paths:gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: cekvvTmkvdfAQUcZf4pt3ATK+ token: bUzntgyynoxJDDdqsRuvui7cemail:customer_note: Leave at doorcurrency: 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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -2153,8 +2182,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1146888- slug: product-1146888+ name: Product 1149013+ slug: product-1149013options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -2239,9 +2268,9 @@ paths:type: stringcompany:type: string- country_code:+ country_iso:type: string- state_code:+ state_abbr:type: stringshipping_address:type: object@@ -2262,9 +2291,9 @@ paths:type: stringcompany:type: string- country_code:+ country_iso:type: string- state_code:+ state_abbr:type: stringdelete:summary: Delete a cart@@ -2373,8 +2402,8 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: ofju3DCyNTVHt9D41Zff7mSH- email: [email protected]+ token: 8oqN42DJyk1rU7KyCK2Z9pGh+ email: [email protected]customer_note:currency: USDlocale: 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 methodshipping_eq_billing_address: falsediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -2425,8 +2457,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1165794- slug: product-1165794+ name: Product 1162742+ slug: product-1162742options_text: ''price: '10.0'display_price: "$10.00"@@ -2462,15 +2494,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: trueis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkshipping_address:id: addr_UkLWZg9DAJ@@ -2483,26 +2513,24 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: true- state_abbr: NY- country_iso: USstate_name: New Yorkpayment_methods: []gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -2585,7 +2613,7 @@ paths:cart_id: cart_UkLWZg9DAJchannel_id: ch_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: en@@ -2593,7 +2621,7 @@ paths:coupon_code:fulfillment_status: backorderpayment_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: falsediscounts: []+ fees: []items:- id: li_gbHJdmfrXBvariant_id: variant_UkLWZg9DAJ@@ -2625,8 +2656,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1191944- slug: product-1191944+ name: Product 1196497+ slug: product-1196497options_text: ''price: '10.0'display_price: "$10.00"@@ -2691,14 +2722,14 @@ paths:pickup_point: falsestock_location:id: sloc_UkLWZg9DAJ- name: Trinh Abernathy+ state_abbr: NY+ name: Phyllis Veumaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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: NYpickup_ready_in_minutes:pickup_instructions:delivery_rates:@@ -2731,7 +2762,7 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-4ef71a15e8cb+ response_code: BGS-687fdc89035dnumber: R1001-P1amount: '20.0'display_amount: "$20.00"@@ -2765,15 +2796,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkshipping_address:id: addr_OIJLhNcSbf@@ -2786,25 +2815,23 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkgift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -2892,7 +2919,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: W4SC3fGJHvMwvvZa9E3vwicK+ token: xe9BRFYyfjHtrB5q7nCJAGsbemail: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: save10amount: "-10.0"display_amount: "-$10.00"+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -2950,8 +2980,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1454488- slug: product-1454488+ name: Product 1459562+ slug: product-1459562options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -3080,7 +3110,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: bUYUfF7zLHTV6dz47hTfatoZ+ token: kCMeNFGg5uR5NCGBCECzww5wemail: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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -3135,8 +3168,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1478248- slug: product-1478248+ name: Product 1473243+ slug: product-1473243options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -3254,8 +3287,8 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: HiZJFqu3qJQY8C59UqJ6PUFb- email: [email protected]+ token: j5Ffw2ZNQbrMNxyfsGRAkegM+ email: [email protected]customer_note:currency: USDlocale: 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 methodshipping_eq_billing_address: falsediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -3303,8 +3339,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1492967- slug: product-1492967+ name: Product 1495288+ slug: product-1495288options_text: ''price: '10.0'display_price: "$10.00"@@ -3369,14 +3405,14 @@ paths:pickup_point: falsestock_location:id: sloc_UkLWZg9DAJ- name: Loyd Bayer+ state_abbr: NY+ name: Roxane McGlynnaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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: NYpickup_ready_in_minutes:pickup_instructions:delivery_rates:@@ -3419,26 +3455,24 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkpayment_methods: []gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -3534,7 +3568,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: Una2zZ9gJSeddM1sB1rEqQBr+ token: FZxyPHfAmwNtPzHJA8TYBGGaemail: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 fulfillmentsshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -3585,8 +3622,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1516736- slug: product-1516736+ name: Product 1513771+ slug: product-1513771options_text: ''price: '10.0'display_price: "$10.00"@@ -3613,7 +3650,7 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260815065855970251+ response_code: 1-SC-20260814132316735815number: cart_UkLWZg9DAJ-P1amount: '10.0'display_amount: "$10.00"@@ -3663,12 +3700,12 @@ paths:active: truemarket:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -3770,7 +3807,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: k35GJyKxCwZ8fHBSt5Coyyo8+ token: pafqF8saB3pakHjiZByxKnMXemail: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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -3825,8 +3865,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1559114- slug: product-1559114+ name: Product 1556049+ slug: product-1556049options_text: ''price: '10.0'display_price: "$10.00"@@ -3853,7 +3893,7 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260815065856420443+ response_code: 1-SC-20260814132317095504number: cart_UkLWZg9DAJ-P1amount: '10.0'display_amount: "$10.00"@@ -3882,12 +3922,12 @@ paths:gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -3961,7 +4001,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: CEwoz62xEjeBzc9Bx9BsrMfS+ token: oWExdYDNSLNN33qfoUpkjSE4email:customer_note:currency: USD@@ -3969,10 +4009,10 @@ paths:total_quantity: 2warnings:- code: delivery_unavailable- message: Product 1588178 cannot be delivered to the selected address+ message: Product 1586196 cannot be delivered to the selected addressline_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 addressline_item_id: li_gbHJdmfrXBcoupon_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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -4022,8 +4065,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1588178- slug: product-1588178+ name: Product 1586196+ slug: product-1586196options_text: ''price: '10.0'display_price: "$10.00"@@ -4052,8 +4095,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1596058- slug: product-1596058+ name: Product 1591838+ slug: product-1591838options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -4204,7 +4247,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: ZTCAYqehM1NnkR1y3tPQZCi5+ token: NEGhavTqZkUxSb39e1q27eh1email: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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -4263,8 +4309,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1654632- slug: product-1654632+ name: Product 1655424+ slug: product-1655424options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -4382,7 +4428,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: Kpnbw2FWwmZYsWnyW1sFvz28+ token: zbB675c552hp6pRGnSQoQ6Nsemail: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 requiredshipping_eq_billing_address: truediscounts: []+ fees: []items: []fulfillments: []payments: []@@ -4435,12 +4484,12 @@ paths:gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -4522,9 +4571,9 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_602e3e2e5847e9b3b0ef701f+ external_id: bogus_ca04dbfb6538507d8fbdca7aexternal_data:- client_secret: bogus_secret_dfbf296993fdecb9+ client_secret: bogus_secret_9a5c831d2b564980customer_external_id:expires_at:amount: '10.0'@@ -4623,7 +4672,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_fae9bb258ee1c8012260118f+ external_id: bogus_a15458dd678c5c95ee262a81external_data:client_secret: secret_123customer_external_id:@@ -4686,7 +4735,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_c492e8940f52563ce647b99a+ external_id: bogus_b4e141b589fe03d9e669ddfbexternal_data:client_secret: secret_123customer_external_id:@@ -4789,7 +4838,7 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_342aeb8dcf67c0ce706b9b32+ external_id: bogus_c43a878e49a5030d583d5082external_data:client_secret: secret_123customer_external_id:@@ -4997,7 +5046,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: seh1mVKYG6Ka5F4GQT6z8J4k+ token: hjmQt6Ym4P7KSYgzweEP1Wk7email: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 fulfillmentsshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -5048,8 +5100,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 2276396- slug: product-2276396+ name: Product 2274883+ slug: product-2274883options_text: ''price: '10.0'display_price: "$10.00"@@ -5076,7 +5128,7 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260815065903711944+ response_code: 1-SC-20260814132323889369number: cart_UkLWZg9DAJ-P1amount: '10.0'display_amount: "$10.00"@@ -5111,12 +5163,12 @@ paths:gift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -5197,7 +5249,7 @@ paths:channel_id: ch_UkLWZg9DAJpreferred_stock_location_id:number: cart_UkLWZg9DAJ- token: sxmkypAb6ppj64mZ4A6j5pAN+ token: UTLiWaBX7NS1KtXxKgQR7Ajpemail: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 methodshipping_eq_billing_address: truediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -5252,8 +5307,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 2293473- slug: product-2293473+ name: Product 2291457+ slug: product-2291457options_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 Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: falsediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -5409,8 +5467,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1697237- slug: product-1697237+ name: Product 1694901+ slug: product-1694901options_text: ''price: '10.0'display_price: "$10.00"@@ -5475,14 +5533,14 @@ paths:pickup_point: falsestock_location:id: sloc_UkLWZg9DAJ- name: Hugo Toy+ state_abbr: NY+ name: Rocco Corkeryaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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: NYpickup_ready_in_minutes:pickup_instructions:delivery_rates:@@ -5524,15 +5582,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkshipping_address:id: addr_gbHJdmfrXB@@ -5545,25 +5601,23 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkgift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -5647,15 +5701,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New York- id: addr_gbHJdmfrXBfirst_name: John@@ -5667,15 +5719,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: trueis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New York- id: addr_UkLWZg9DAJfirst_name: John@@ -5687,15 +5737,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: true- state_abbr: NY- country_iso: USstate_name: New Yorkmeta: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 Yorkphone: "+1 555 123 4567"company:- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkschema:"$ref": "#/components/schemas/Address"@@ -5851,11 +5897,11 @@ paths:company:type: stringexample: Acme Inc- country_code:+ country_iso:type: stringexample: USdescription: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")- state_code:+ state_abbr:type: stringexample: NYdescription: 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 Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkschema:"$ref": "#/components/schemas/Address"@@ -6017,15 +6061,13 @@ paths:city: Los Angelesphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkschema:"$ref": "#/components/schemas/Address"@@ -6452,7 +6494,7 @@ paths:cart_id:channel_id: ch_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -6492,8 +6537,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1359530- slug: product-1359530+ name: Product 1355077+ slug: product-1355077options_text: ''price: '10.0'display_price: "$10.00"@@ -6558,14 +6603,14 @@ paths:pickup_point: falsestock_location:id: sloc_UkLWZg9DAJ- name: Susanne Howell+ state_abbr: NY+ name: Lakeesha Dachaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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: NYpickup_ready_in_minutes:pickup_instructions:delivery_rates:@@ -6607,15 +6652,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkshipping_address:id: addr_VqXmZF31wY@@ -6628,25 +6671,23 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkgift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -6748,7 +6789,7 @@ paths:cart_id:channel_id: ch_UkLWZg9DAJnumber: R1001- email: [email protected]+ email: [email protected]customer_note:currency: USDlocale: 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: falsediscounts: []+ fees: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ@@ -6788,8 +6832,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1375912- slug: product-1375912+ name: Product 1378628+ slug: product-1378628options_text: ''price: '10.0'display_price: "$10.00"@@ -6854,14 +6898,14 @@ paths:pickup_point: falsestock_location:id: sloc_UkLWZg9DAJ- name: Domonique Koelpin+ state_abbr: NY+ name: Stanford Kemmeraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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: NYpickup_ready_in_minutes:pickup_instructions:delivery_rates:@@ -6903,15 +6947,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkshipping_address:id: addr_VqXmZF31wY@@ -6924,25 +6966,23 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkgift_card:market:id: mkt_UkLWZg9DAJ- name: United States+ name: United States of Americacurrency: USDdefault_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_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: WshaU6ew8E54Rmh4ToDqH8cyuser:id: cust_UkLWZg9DAJemail: [email protected]@@ -7017,10 +7057,10 @@ paths:newsletter_subscriber:id: sub_UkLWZg9DAJemail: [email protected]- 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_UkLWZg9DAJcustomer_groups: []schema:@@ -7123,12 +7163,12 @@ paths:application/json:example:id: cust_UkLWZg9DAJ- email: [email protected]- first_name: Rory- last_name: Padberg+ email: [email protected]+ first_name: Jeffry+ last_name: Tremblayphone: 555-555-0199accepts_email_marketing: false- full_name: Rory Padberg+ full_name: Jeffry Tremblayavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses:@@ -7142,15 +7182,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: trueis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New York- id: addr_UkLWZg9DAJfirst_name: John@@ -7162,15 +7200,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: true- state_abbr: NY- country_iso: USstate_name: New Yorkdefault_billing_address:id: addr_gbHJdmfrXB@@ -7183,15 +7219,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: trueis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkdefault_shipping_address:id: addr_UkLWZg9DAJ@@ -7204,15 +7238,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: true- state_abbr: NY- country_iso: USstate_name: New Yorknewsletter_subscriber:customer_groups: []@@ -7272,7 +7304,7 @@ paths:application/json:example:id: cust_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Namephone: 555-555-0199@@ -7291,15 +7323,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: trueis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New York- id: addr_UkLWZg9DAJfirst_name: John@@ -7311,15 +7341,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: true- state_abbr: NY- country_iso: USstate_name: New Yorkdefault_billing_address:id: addr_gbHJdmfrXB@@ -7332,15 +7360,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: trueis_default_shipping: false- state_abbr: NY- country_iso: USstate_name: New Yorkdefault_shipping_address:id: addr_UkLWZg9DAJ@@ -7353,15 +7379,13 @@ paths:city: New Yorkphone: 555-555-0199company: Company- country_name: United States- country_code: US+ country_name: United States of America+ country_iso: USstate_text: NY- state_code: NY+ state_abbr: NYquick_checkout: falseis_default_billing: falseis_default_shipping: true- state_abbr: NY- country_iso: USstate_name: New Yorknewsletter_subscriber:customer_groups: []@@ -7471,7 +7495,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: 93E81C61FB772E62+ code: D04817FC09B6EBB2status: activecurrency: USDamount: '10.0'@@ -7567,7 +7591,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: D91CFDF5C1250D33+ code: 3607BB1ED7DC02B7status: activecurrency: USDamount: '10.0'@@ -7639,8 +7663,8 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_1ae6c22731c4b8b5985a1c2b- external_client_secret: bogus_seti_secret_ea5a717e3c94dfda+ external_id: bogus_seti_80c86d24c4476a7841150728+ external_client_secret: bogus_seti_secret_eb81e6a5ef28b3b0external_data: {}payment_method_id: pm_UkLWZg9DAJpayment_source_id:@@ -7739,8 +7763,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_f6886ef27b59702fec292567- external_client_secret: seti_secret_17af02e8de63468bd0d9b1a4+ external_id: seti_test_df2c16765f655ec067ba4e80+ external_client_secret: seti_secret_4719e71e2323e7bd3ccabbdeexternal_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -7816,8 +7840,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_08f8850d2ba99614a0a65e89- external_client_secret: seti_secret_76a7c6630a3e148019073570+ external_id: seti_test_747a24303dfee2d1820a2e8a+ external_client_secret: seti_secret_e247f267bb9b7f858a5ae6d2external_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -8061,13 +8085,13 @@ paths:example:data:- iso: DE- iso3: DEU+ iso3: IS5name: Germanystates_required: falsezipcode_required: true- iso: USiso3: USA- name: United States+ name: United States of Americastates_required: truezipcode_required: trueschema:@@ -8137,7 +8161,7 @@ paths:example:iso: USiso3: USA- name: United States+ name: United States of Americastates_required: truezipcode_required: trueschema:@@ -8166,7 +8190,7 @@ paths:example:error:code: record_not_found- message: record not found+ message: Country not foundschema:"$ref": "#/components/schemas/ErrorResponse""/api/v3/store/currencies":@@ -8351,7 +8375,7 @@ paths:default_locale: entax_inclusive: falsedefault: true- country_codes:+ country_isos:- USsupported_locales:- en@@ -8359,7 +8383,7 @@ paths:countries:- iso: USiso3: USA- name: United States+ name: United States of Americastates_required: truezipcode_required: true- id: mkt_gbHJdmfrXB@@ -8368,7 +8392,7 @@ paths:default_locale: detax_inclusive: truedefault: false- country_codes:+ country_isos:- DE- FRsupported_locales:@@ -8376,16 +8400,16 @@ paths:- en- frcountries:- - iso: FR- iso3: FRA- name: France- states_required: false- zipcode_required: true- iso: DE- iso3: DEU+ iso3: IS15name: Germanystates_required: falsezipcode_required: true+ - iso: FR+ iso3: IS16+ name: France+ states_required: false+ zipcode_required: trueschema:type: objectproperties:@@ -8455,7 +8479,7 @@ paths:default_locale: detax_inclusive: truedefault: false- country_codes:+ country_isos:- DE- FRsupported_locales:@@ -8463,16 +8487,16 @@ paths:- en- frcountries:- - iso: FR- iso3: FRA- name: France- states_required: false- zipcode_required: true- iso: DE- iso3: DEU+ iso3: IS19name: Germanystates_required: falsezipcode_required: true+ - iso: FR+ iso3: IS20+ name: France+ states_required: false+ zipcode_required: trueschema:type: object'404':@@ -8538,7 +8562,7 @@ paths:default_locale: detax_inclusive: truedefault: false- country_codes:+ country_isos:- DE- FRsupported_locales:@@ -8546,16 +8570,16 @@ paths:- en- frcountries:- - iso: FR- iso3: FRA- name: France- states_required: false- zipcode_required: true- iso: DE- iso3: DEU+ iso3: IS23name: Germanystates_required: falsezipcode_required: true+ - iso: FR+ iso3: IS24+ name: France+ states_required: false+ zipcode_required: trueschema:type: object'404':@@ -8565,7 +8589,7 @@ paths:example:error:code: record_not_found- message: record not found+ message: Country not foundschema:"$ref": "#/components/schemas/ErrorResponse""/api/v3/store/markets/{market_id}/countries":@@ -8616,12 +8640,12 @@ paths:example:data:- iso: FR- iso3: FRA+ iso3: IS28name: Francestates_required: falsezipcode_required: true- iso: DE- iso3: DEU+ iso3: IS27name: Germanystates_required: falsezipcode_required: true@@ -8686,7 +8710,7 @@ paths:example:iso: USiso3: USA- name: United States+ name: United States of Americastates_required: truezipcode_required: trueschema:@@ -8698,7 +8722,7 @@ paths:example:error:code: record_not_found- message: record not found+ message: Country not foundschema:"$ref": "#/components/schemas/ErrorResponse""/api/v3/store/wishlists":@@ -8761,7 +8785,7 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: kmvxGQy6B34GePDcMFg9bK1i+ token: CTQSpUPNUtZtb4Ud2PPj8pfLis_default: falseis_private: truemeta:@@ -8837,7 +8861,7 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: WHtJv9phiodnHTD74p76Tt3x+ token: BBR6NYLLB6v4SoinhYRxdmwEis_default: falseis_private: trueschema:@@ -8938,7 +8962,7 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: R2kcAQjKqkwzJe8au76HHnzh+ token: 3EuAFPdcdKC4vdPWRq1bAHCNis_default: falseis_private: trueschema:@@ -9000,7 +9024,7 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: iR3Swbo4Vc29ufKdrBDGz3Yh+ token: hC59MwX9KZFQXUmAAvT6Wwo2is_default: falseis_private: trueschema:@@ -9282,11 +9306,11 @@ paths:application/json:example:id: sub_UkLWZg9DAJ- email: [email protected]- created_at: '2026-08-15T06:58:58.204Z'- updated_at: '2026-08-15T06:58:58.205Z'+ email: [email protected]+ 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_UkLWZg9DAJschema:"$ref": "#/components/schemas/NewsletterSubscriber"@@ -9365,10 +9389,10 @@ paths:example:id: sub_UkLWZg9DAJemail: [email protected]- 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_OIJLhNcSbfname: Privacy Policy- slug: privacy-policy-d283591e-861c-4628-a5dc-f04a447216d2+ slug: privacy-policy-108a3e91-9741-4750-87eb-4d891f2ad755body: 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_94name: Downtownaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '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_94pickup_ready_in_minutes:pickup_instructions:servers:@@ -10278,12 +10302,12 @@ components:nullable: truecountry_name:type: string- country_code:+ country_iso:type: stringstate_text:type: stringnullable: true- state_code:+ state_abbr:type: stringnullable: truequick_checkout:@@ -10292,11 +10316,6 @@ components:type: booleanis_default_shipping:type: boolean- state_abbr:- type: string- nullable: true- country_iso:- type: stringstate_name:type: stringnullable: 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_namex-typelizer: trueAppliedPromotion:@@ -10458,6 +10475,12 @@ components:display_delivery_total:type: stringnullable: true+ fee_total:+ type: string+ nullable: true+ display_fee_total:+ type: string+ nullable: truestore_credit_total:type: stringnullable: true@@ -10482,6 +10505,10 @@ components:type: arrayitems:"$ref": "#/components/schemas/AppliedPromotion"+ fees:+ type: array+ items:+ "$ref": "#/components/schemas/Fee"items:type: arrayitems:@@ -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: stringmember_type:type: string- country_code:- type: string- nullable: true- state_code:- type: string- nullable: truepostal_code_prefix:type: stringnullable: true@@ -11120,21 +11144,27 @@ components:postal_code_to:type: stringnullable: true+ country_iso:+ type: string+ nullable: truecountry_name:type: stringnullable: true+ state_abbr:+ type: string+ nullable: truestate_name:type: stringnullable: truerequired:- id- member_type- - country_code- - state_code- postal_code_prefix- postal_code_from- postal_code_to+ - country_iso- country_name+ - state_abbr- state_namex-typelizer: trueDeliveryZone:@@ -11368,10 +11398,6 @@ components:type: arrayitems:"$ref": "#/components/schemas/DeliveryRate"- tax_lines:- type: array- items:- "$ref": "#/components/schemas/TaxLine"required:- id- number@@ -11643,10 +11669,6 @@ components:type: arrayitems:"$ref": "#/components/schemas/DigitalLink"- tax_lines:- type: array- items:- "$ref": "#/components/schemas/TaxLine"required:- id- variant_id@@ -11711,7 +11733,7 @@ components:type: booleandefault:type: boolean- country_codes:+ country_isos:type: arrayitems:type: string@@ -11730,7 +11752,7 @@ components:- default_locale- tax_inclusive- default- - country_codes+ - country_isos- supported_localesx-typelizer: trueMedia:@@ -11982,6 +12004,12 @@ components:display_delivery_total:type: stringnullable: true+ fee_total:+ type: string+ nullable: true+ display_fee_total:+ type: string+ nullable: truestore_credit_total:type: stringnullable: true@@ -11994,6 +12022,10 @@ components:type: arrayitems:"$ref": "#/components/schemas/AppliedPromotion"+ fees:+ type: array+ items:+ "$ref": "#/components/schemas/Fee"items:type: arrayitems:@@ -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: truename:type: stringaddress1:@@ -12831,15 +12869,12 @@ components:zipcode:type: stringnullable: true- country_code:+ country_iso:type: stringnullable: truecountry_name:type: stringnullable: true- state_code:- type: string- nullable: truestate_text:type: stringnullable: true@@ -12851,13 +12886,13 @@ components:nullable: truerequired:- 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- currencyx-typelizer: true- TaxIdentifier:- type: object- properties:- id:- type: string- kind:- type: string- value:- type: string- required:- - id- - kind- - value- x-typelizer: trueTaxLine:type: objectproperties:diff --git a/docs/plans/6.0-duties-and-custom-fees.md b/docs/plans/6.0-duties-and-custom-fees.mdnew file mode 100644index 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.mdindex 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 wholerecipe behind an env var (e.g. `SENTRY_OTLP_ENABLED=true`) so containerusers 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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 filediff --git a/packages/dashboard-core/src/components/country-combobox.tsx b/packages/dashboard-core/src/components/country-combobox.tsxindex 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.tsxindex 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?: booleanbackorderLimit?: string | nulltaxCategoryId?: 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: stringbackorderLimit: stringtaxCategory: 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.tsxindex 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))+ breakcase '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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.tsxindex 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): VariantFormValdepth: 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.idif (v.track_inventory != null) payload.track_inventory = v.track_inventorydiff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsxindex 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.tsindex 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 constexport type FeeKind = (typeof FEE_KINDS)[number]diff --git a/packages/dashboard/src/schemas/product.ts b/packages/dashboard/src/schemas/product.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.rbindex 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.rbindex 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.rbindex 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.rbindex 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 Spreereserved_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: :iso8601diff --git a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb b/spree/api/app/serializers/spree/api/v3/cart_serializer.rbindex 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 Spreetax_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_totalattribute :store_credit_total do |order|order.total_applied_store_credit.to_s unless params[:hide_prices]@@ -88,6 +90,10 @@ module Spreeendmany :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.rbindex 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 Spreetax_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_totalattribute :store_credit_total do |order|order.total_applied_store_credit.to_s unless params[:hide_prices]@@ -72,6 +74,9 @@ module Spreeendmany :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.rbindex 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: :contrexpect(variant.reload.deleted_at).not_to be_nilendend++ 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+ endenddiff --git a/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb b/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rbindex 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' doexpect(hash['total']).to be_presentexpect(hash['items'].first['price']).to be_presentend++ 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+ endenddescribe Spree::Api::V3::OrderSerializer do@@ -55,6 +75,15 @@ RSpec.describe 'v3 Store serializer price gating' doit 'serializes totals when not gated' doexpect(serialize(described_class, hide: false)['total']).to be_presentend++ 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')+ endend# Nested records embedded in a cart/order must honor hide_prices too, so adiff --git a/spree/core/app/models/spree/fee.rb b/spree/core/app/models/spree/fee.rbindex 061a44af89..8cacbd6065 100644--- a/spree/core/app/models/spree/fee.rb+++ b/spree/core/app/models/spree/fee.rb@@ -8,7 +8,10 @@ module Spreeinclude 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 :feediff --git a/spree/core/app/models/spree/import_schemas/products.rb b/spree/core/app/models/spree/import_schemas/products.rbindex 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.rbindex 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_totalalias display_ship_total display_delivery_totalalias_attribute :ship_total, :delivery_totaldiff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rbindex 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: :productnormalizes :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 Spreevalidates :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_itemsafter_commit :clear_line_items_cache, on: :update@@ -182,7 +191,7 @@ module Spreeself.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 Spreeoption_values.any? ? "#{name} - #{options_text}" : nameend+ # 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 fordiff --git a/spree/core/app/services/spree/imports/row_processors/product_variant.rb b/spree/core/app/services/spree/imports/row_processors/product_variant.rbindex 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 Spreevariant.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.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/spree/permitted_attributes.rb b/spree/core/lib/spree/permitted_attributes.rbindex 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.rbindex 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 doexpect(fee).to be_validend+ 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' dofee = 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.rbindex 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 doendend+ 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+ endenddiff --git a/spree/providers/easypost/app/models/spree_easypost/delivery_rate_provider.rb b/spree/providers/easypost/app/models/spree_easypost/delivery_rate_provider.rbindex 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 SpreeEasyPostdef 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?+ paramsenddef 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.rbindex 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 SpreeEasyPostreturn 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 SpreeEasyPostnilend- 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?+ paramsenddef 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.rbindex 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.rbindex da7df4da28..7a8610146a 100644--- a/spree/providers/easypost/lib/spree_easypost.rb+++ b/spree/providers/easypost/lib/spree_easypost.rb@@ -96,6 +96,71 @@ module SpreeEasyPostsource.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, EasyPostdiff --git a/spree/providers/easypost/spec/models/spree_easypost/customs_params_spec.rb b/spree/providers/easypost/spec/models/spree_easypost/customs_params_spec.rbnew file mode 100644index 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