Skip to content

armgit / spree

Public Imported from GitHub
0

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

Clean up Admin Orders API

Damian Legawiecb00611fc4aa9
diff --git a/CLAUDE.md b/CLAUDE.md
index c16a66e822..f858015f40 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,6 +33,7 @@ Current plans:
- `5.4-6.0-eu-legal-compliance.md` — GDPR (data export/anonymization, consent timestamps), Omnibus (PriceHistory, lowest-in-30-days), Consumer Rights (withdrawal period). Core primitives + enterprise hooks.
+- `5.5-6.0-order-cancellation-and-approval.md` — First-class `OrderCancellation` + `OrderApproval` models, capture reasons/restock/refund decisions, polymorphic actor; 6.0 drops denormalized columns
- `5.4-disjunctive-option-faceting.md` — Per-option-type filter params with disjunctive facet counts (OR within option type, AND across)
- `5.4-option-type-enhancements.md` — Add `kind` (dropdown/color_swatch/buttons) to OptionType, `color_code` + `image` to OptionValue for swatch support
- `5.4-6.0-custom-fields-rename.md` — Rename Metafields → Custom Fields (5.4 API bridge + 6.0 model rename)
@@ -120,6 +121,16 @@ end
- One migration per feature when possible
- Data transformations go in rake tasks, never in migrations
- Soft delete: use `paranoia` gem, add `deleted_at` column yourself
+- JSON columns must work across PostgreSQL, MySQL, and SQLite. PostgreSQL supports `t.jsonb` (binary, indexable); MySQL and SQLite do not — only `t.json`. Guard with `respond_to?`:
+
+```ruby
+# JSON column — works on PostgreSQL, MySQL, SQLite
+if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+else
+ t.json :metadata
+end
+```
```ruby
class CreateSpreeMetafields < ActiveRecord::Migration[7.2]
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index a5e759a51d..a32e90366e 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -51,9 +51,9 @@ paths:
- lang: javascript
label: Spree SDK
source: |-
- import { createSpreeClient } from '@spree/sdk'
+ import { createClient } from '@spree/sdk'
- const client = createSpreeClient({
+ const client = createClient({
baseUrl: 'https://your-store.com',
publishableKey: '<api-key>',
})
@@ -74,16 +74,17 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjljM2IxZmJjLWM3YWEtNDAzZC1iNGY1LWYxYTgwNjk1ZTM1YSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzcyODg2NzAyfQ.L9_GL_zuCQgjAwALcEHR0eAAYlVpAxdzb2p2wxjIe4c
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjlmYjNmOTJhLTA1MjEtNGZlOC05MjIwLTQ4OTdkY2ZhNGFlOSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzc3NDYzMzgxfQ.8DfwCNdShTyfViR0MMrpgdSPL7OT_D3Mu3cR0TAEveU
+ refresh_token: cYt1pekRHesbvYrjq2wUzhfV
user:
id: admin_UkLWZg9DAJ
- first_name: Aurora
- last_name: Volkman
- created_at: '2026-03-07T11:31:42.311Z'
- updated_at: '2026-03-07T11:31:42.311Z'
+ first_name: Meggan
+ last_name: Murazik
+ created_at: '2026-04-29T10:49:40.718Z'
+ updated_at: '2026-04-29T10:49:40.718Z'
schema:
- "$ref": "#/components/schemas/AdminAuthResponse"
+ "$ref": "#/components/schemas/AuthResponse"
'401':
description: non-admin user
content:
@@ -121,22 +122,90 @@ paths:
- Authentication
security:
- api_key: []
- bearer_auth: []
- description: Generates a new JWT token for the authenticated admin user
+ description: Rotates a refresh token and returns a new JWT access token
x-codeSamples:
- lang: javascript
label: Spree SDK
source: |-
- import { createSpreeClient } from '@spree/sdk'
+ import { createClient } from '@spree/sdk'
- const client = createSpreeClient({
+ const client = createClient({
baseUrl: 'https://your-store.com',
publishableKey: '<api-key>',
})
const auth = await client.admin.auth.refresh({
- bearerToken: '<token>',
+ refresh_token: 'rt_xxx',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: token refreshed
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjcwNDAyYjk3LWY5MmUtNDJlNi05ZTIyLTdlZjgxYzM3ZjI3ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzc3NDYzMzgyfQ.PzqQLrMG9iIF8UMRE3E1tifuvNWbNNQengFjqjJfdas
+ refresh_token: HPw1VLyHB3SmHiCmvmXSKtCQ
+ user:
+ id: admin_UkLWZg9DAJ
+ first_name: Del
+ last_name: Hilll
+ created_at: '2026-04-29T10:49:42.182Z'
+ updated_at: '2026-04-29T10:49:42.182Z'
+ schema:
+ "$ref": "#/components/schemas/AuthResponse"
+ '401':
+ description: missing or invalid refresh token
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_refresh_token
+ message: Invalid or expired refresh token
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ refresh_token:
+ type: string
+ description: Refresh token obtained from login
+ required:
+ - refresh_token
+ "/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.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
})
+
+ const me = await client.admin.me.show()
+ if (me.permissions.some((r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'))) {
+ // show create product button
+ }
parameters:
- name: x-spree-api-key
in: header
@@ -151,22 +220,73 @@ paths:
type: string
responses:
'200':
- description: token refreshed
+ description: current admin user and permissions
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImNlMzU1MWQxLTY1YmUtNDY4Yy05YTA3LTNmNDExZmJkMWM4YyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzcyODg2NzA0fQ.zEb7pVHJXhL5DQg0xvZQonix73zbAl0FQMNpiW-rb08
user:
id: admin_UkLWZg9DAJ
- first_name: Gabriel
- last_name: Cole
- created_at: '2026-03-07T11:31:44.251Z'
- updated_at: '2026-03-07T11:31:44.251Z'
+ first_name: Nathaniel
+ last_name: Lueilwitz
+ created_at: '2026-04-29T10:49:42.478Z'
+ updated_at: '2026-04-29T10:49:42.478Z'
+ permissions:
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - all
+ has_conditions: false
+ - allow: false
+ actions:
+ - cancel
+ subjects:
+ - Spree::Order
+ has_conditions: false
+ - allow: true
+ actions:
+ - cancel
+ subjects:
+ - Spree::Order
+ has_conditions: true
+ - allow: false
+ actions:
+ - destroy
+ subjects:
+ - Spree::Order
+ has_conditions: false
+ - allow: true
+ actions:
+ - destroy
+ subjects:
+ - Spree::Order
+ has_conditions: true
+ - allow: false
+ actions:
+ - edit
+ - update
+ subjects:
+ - Spree::RefundReason
+ has_conditions: true
+ - allow: false
+ actions:
+ - edit
+ - update
+ subjects:
+ - Spree::ReimbursementType
+ has_conditions: true
+ - allow: false
+ actions:
+ - update
+ - destroy
+ subjects:
+ - Spree::Role
+ has_conditions: true
schema:
- "$ref": "#/components/schemas/AdminAuthResponse"
+ "$ref": "#/components/schemas/MeResponse"
'401':
- description: missing or invalid token
+ description: unauthorized
content:
application/json:
example:
@@ -223,11 +343,11 @@ paths:
data:
- id: opt_UkLWZg9DAJ
name: foo-size-1
- presentation: Size
+ label: Size
position: 1
- filterable: true
- created_at: '2026-03-07T11:31:44.363Z'
- updated_at: '2026-03-07T11:31:44.363Z'
+ kind: dropdown
+ created_at: '2026-04-29T10:49:42.519Z'
+ updated_at: '2026-04-29T10:49:42.519Z'
option_values: []
meta:
page: 1
@@ -245,7 +365,7 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/AdminOptionType"
+ "$ref": "#/components/schemas/OptionType"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
@@ -257,8 +377,8 @@ paths:
application/json:
example:
error:
- code: invalid_token
- message: Valid secret API key required
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
@@ -292,14 +412,14 @@ paths:
example:
id: opt_gbHJdmfrXB
name: material
- presentation: Material
+ label: Material
position: 2
- filterable: true
- created_at: '2026-03-07T11:31:45.295Z'
- updated_at: '2026-03-07T11:31:45.295Z'
+ kind: dropdown
+ created_at: '2026-04-29T10:49:43.150Z'
+ updated_at: '2026-04-29T10:49:43.150Z'
option_values: []
schema:
- "$ref": "#/components/schemas/AdminOptionType"
+ "$ref": "#/components/schemas/OptionType"
'422':
description: validation error
content:
@@ -385,14 +505,14 @@ paths:
example:
id: opt_UkLWZg9DAJ
name: foo-size-5
- presentation: Size
+ label: Size
position: 1
- filterable: true
- created_at: '2026-03-07T11:31:45.591Z'
- updated_at: '2026-03-07T11:31:45.591Z'
+ kind: dropdown
+ created_at: '2026-04-29T10:49:43.454Z'
+ updated_at: '2026-04-29T10:49:43.454Z'
option_values: []
schema:
- "$ref": "#/components/schemas/AdminOptionType"
+ "$ref": "#/components/schemas/OptionType"
'404':
description: option type not found
content:
@@ -400,7 +520,7 @@ paths:
example:
error:
code: record_not_found
- message: Couldn't find Spree::OptionType with 'id'=245546638656678833
+ message: Option type not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
@@ -437,14 +557,14 @@ paths:
example:
id: opt_UkLWZg9DAJ
name: foo-size-7
- presentation: Updated Presentation
+ label: Updated Presentation
position: 1
- filterable: true
- created_at: '2026-03-07T11:31:46.171Z'
- updated_at: '2026-03-07T11:31:46.463Z'
+ kind: dropdown
+ created_at: '2026-04-29T10:49:44.018Z'
+ updated_at: '2026-04-29T10:49:44.296Z'
option_values: []
schema:
- "$ref": "#/components/schemas/AdminOptionType"
+ "$ref": "#/components/schemas/OptionType"
'422':
description: validation error
content:
@@ -521,15 +641,15 @@ paths:
responses:
'204':
description: option type deleted
- "/api/v3/admin/orders/{order_id}/adjustments":
+ "/api/v3/admin/orders/{order_id}/fulfillments":
get:
- summary: List adjustments
+ summary: List fulfillments
tags:
- - Adjustments
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
- description: Returns all adjustments for an order.
+ description: Returns all shipments for an order.
parameters:
- name: x-spree-api-key
in: header
@@ -550,25 +670,41 @@ paths:
type: string
responses:
'200':
- description: adjustments found
+ description: fulfillments found
content:
application/json:
example:
data:
- - id: adj_UkLWZg9DAJ
- amount: '0.0'
- label: Admin discount
- eligible: true
- state: open
- included: false
- mandatory:
- created_at: '2026-03-07T11:31:47.628Z'
- updated_at: '2026-03-07T11:31:47.635Z'
- source_type: Spree::TaxRate
- source_id: tax_UkLWZg9DAJ
- adjustable_type: Spree::Order
- adjustable_id: or_UkLWZg9DAJ
+ - id: ful_UkLWZg9DAJ
+ number: H18511115464
+ tracking: U10000
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: ready
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:46.408Z'
+ updated_at: '2026-04-29T10:49:46.529Z'
+ metadata:
order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
meta:
page: 1
limit: 25
@@ -579,15 +715,15 @@ paths:
in: 1
previous:
next:
- post:
- summary: Create an adjustment
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}":
+ get:
+ summary: Show a shipment
tags:
- - Adjustments
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
- description: Creates a manual adjustment on an order (e.g., admin discount,
- fee).
+ description: Returns details of a specific shipment.
parameters:
- name: x-spree-api-key
in: header
@@ -606,51 +742,136 @@ paths:
description: Order prefixed ID
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Fulfillment prefixed ID
+ schema:
+ type: string
responses:
- '201':
- description: adjustment created
+ '200':
+ description: shipment found
content:
application/json:
example:
- id: adj_gbHJdmfrXB
- amount: "-10.0"
- label: VIP discount
- eligible: true
- state: open
- included: false
- mandatory:
- created_at: '2026-03-07T11:31:48.608Z'
- updated_at: '2026-03-07T11:31:48.608Z'
- source_type:
- source_id:
- adjustable_type: Spree::Order
- adjustable_id: or_UkLWZg9DAJ
+ id: ful_UkLWZg9DAJ
+ number: H67463310487
+ tracking: U10000
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: ready
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:47.143Z'
+ updated_at: '2026-04-29T10:49:47.205Z'
+ metadata:
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ patch:
+ summary: Update a shipment
+ tags:
+ - Fulfillments
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Updates a shipment (tracking, shipping rate).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Fulfillment prefixed ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: shipment updated
+ content:
+ application/json:
+ example:
+ id: ful_UkLWZg9DAJ
+ number: H98036370897
+ tracking: 1Z999AA10123456784
+ tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: ready
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:47.797Z'
+ updated_at: '2026-04-29T10:49:48.140Z'
+ metadata:
order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
- required:
- - amount
- - label
properties:
- amount:
- type: number
- example: -5.0
- description: Negative for discounts, positive for fees
- label:
+ tracking:
type: string
- example: Admin discount
- "/api/v3/admin/orders/{order_id}/adjustments/{id}":
- get:
- summary: Show an adjustment
+ example: 1Z999AA10123456784
+ selected_shipping_rate_id:
+ type: string
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":
+ patch:
+ summary: Fulfill a fulfillment
tags:
- - Adjustments
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
- description: Returns details of a specific adjustment.
+ description: Marks a fulfillment as fulfilled.
parameters:
- name: x-spree-api-key
in: header
@@ -672,37 +893,54 @@ paths:
- name: id
in: path
required: true
- description: Adjustment prefixed ID
+ description: Fulfillment prefixed ID
schema:
type: string
responses:
'200':
- description: adjustment found
+ description: fulfillment fulfilled
content:
application/json:
example:
- id: adj_UkLWZg9DAJ
- amount: '0.0'
- label: Admin discount
- eligible: true
- state: open
- included: false
- mandatory:
- created_at: '2026-03-07T11:31:48.905Z'
- updated_at: '2026-03-07T11:31:48.907Z'
- source_type: Spree::TaxRate
- source_id: tax_UkLWZg9DAJ
- adjustable_type: Spree::Order
- adjustable_id: or_UkLWZg9DAJ
+ id: ful_UkLWZg9DAJ
+ number: H43948061420
+ tracking: U10000
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: shipped
+ fulfillment_type: shipping
+ fulfilled_at: '2026-04-29T10:49:48Z'
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:48.449Z'
+ updated_at: '2026-04-29T10:49:48.801Z'
+ metadata:
order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
patch:
- summary: Update an adjustment
+ summary: Cancel a fulfillment
tags:
- - Adjustments
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
- description: Updates an adjustment amount or label.
+ description: Cancels a fulfillment.
parameters:
- name: x-spree-api-key
in: header
@@ -724,49 +962,54 @@ paths:
- name: id
in: path
required: true
- description: Adjustment prefixed ID
+ description: Fulfillment prefixed ID
schema:
type: string
responses:
'200':
- description: adjustment updated
+ description: fulfillment canceled
content:
application/json:
example:
- id: adj_UkLWZg9DAJ
- amount: '15.0'
- label: Updated discount
- eligible: true
- state: open
- included: false
- mandatory:
- created_at: '2026-03-07T11:31:49.583Z'
- updated_at: '2026-03-07T11:31:49.898Z'
- source_type: Spree::TaxRate
- source_id: tax_UkLWZg9DAJ
- adjustable_type: Spree::Order
- adjustable_id: or_UkLWZg9DAJ
+ id: ful_UkLWZg9DAJ
+ number: H45564658891
+ tracking: U10000
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: canceled
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:49.123Z'
+ updated_at: '2026-04-29T10:49:49.459Z'
+ metadata:
order_id: or_UkLWZg9DAJ
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- amount:
- type: number
- label:
- type: string
- eligible:
- type: boolean
- delete:
- summary: Delete an adjustment
+ stock_location_id: sloc_UkLWZg9DAJ
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
+ patch:
+ summary: Resume a fulfillment
tags:
- - Adjustments
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
- description: Deletes an adjustment from an order.
+ description: Resumes a canceled fulfillment.
parameters:
- name: x-spree-api-key
in: header
@@ -788,21 +1031,55 @@ paths:
- name: id
in: path
required: true
- description: Adjustment prefixed ID
+ description: Fulfillment prefixed ID
schema:
type: string
responses:
- '204':
- description: adjustment deleted
- "/api/v3/admin/orders/{order_id}/line_items":
- get:
- summary: List line items
+ '200':
+ description: fulfillment resumed
+ content:
+ application/json:
+ example:
+ id: ful_UkLWZg9DAJ
+ number: H14531557641
+ tracking: U10000
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: pending
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:49.778Z'
+ updated_at: '2026-04-29T10:49:50.119Z'
+ metadata:
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
+ patch:
+ summary: Split a fulfillment
tags:
- - Line Items
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
- description: Returns all line items for an order.
+ description: Transfers items from this shipment to a new shipment at a different
+ stock location.
parameters:
- name: x-spree-api-key
in: header
@@ -821,50 +1098,240 @@ paths:
description: Order prefixed ID
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Fulfillment prefixed ID
+ schema:
+ type: string
responses:
'200':
- description: line items found
+ description: fulfillment split
content:
application/json:
example:
data:
- - id: li_UkLWZg9DAJ
- variant_id: variant_gbHJdmfrXB
- quantity: 2
- currency: USD
- name: Product 13567
- slug: product-13567
- options_text: 'Size: S'
- price: '10.0'
- display_price: "$10.00"
- total: '20.0'
- display_total: "$20.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
+ - id: ful_gbHJdmfrXB
+ number: H01841103861
+ tracking:
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '20.0'
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: ready
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-04-29T10:49:50.863Z'
+ updated_at: '2026-04-29T10:49:50.907Z'
+ metadata:
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_gbHJdmfrXB
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - variant_id
+ - quantity
+ properties:
+ variant_id:
+ type: string
+ description: Variant prefixed ID
+ quantity:
+ type: integer
+ example: 1
+ stock_location_id:
+ type: string
+ description: Target stock location prefixed ID
+ "/api/v3/admin/orders/{order_id}/gift_cards":
+ post:
+ summary: Apply a gift card to an order
+ tags:
+ - Order Gift Cards
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Applies a gift card by code to the order. Returns the gift card.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ responses:
+ '201':
+ description: gift card applied
+ content:
+ application/json:
+ example:
+ id: gc_UkLWZg9DAJ
+ code: 69CD7C4799D15386
+ status: active
+ currency: USD
+ amount: '10.0'
+ amount_used: '10.0'
+ amount_authorized: '0.0'
+ amount_remaining: '0.0'
+ display_amount: "$10.00"
+ display_amount_used: "$10.00"
+ display_amount_remaining: "$0.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
+ created_at: '2026-04-29T10:49:51.247Z'
+ updated_at: '2026-04-29T10:49:51.544Z'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - code
+ properties:
+ code:
+ type: string
+ description: Gift card code
+ example: GIFT-XXXX-YYYY
+ "/api/v3/admin/orders/{order_id}/gift_cards/{id}":
+ delete:
+ summary: Remove a gift card from an order
+ tags:
+ - Order Gift Cards
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Removes the gift card from the order.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Gift card prefixed 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.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: items found
+ content:
+ application/json:
+ example:
+ data:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_gbHJdmfrXB
+ quantity: 2
+ currency: USD
+ name: Product 102972
+ slug: product-102972
+ options_text: 'Size: S'
+ price: '10.0'
+ display_price: "$10.00"
+ total: '20.0'
+ display_total: "$20.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '20.0'
display_pre_tax_amount: "$20.00"
discounted_amount: '20.0'
display_discounted_amount: "$20.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:31:51.526Z'
- updated_at: '2026-03-07T11:31:51.526Z'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
name: size-1
- presentation: S
+ label: S
position: 1
+ color_code:
option_type_name: foo-size-10
- option_type_presentation: Size
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:49:52.211Z'
+ updated_at: '2026-04-29T10:49:52.211Z'
digital_links: []
+ created_at: '2026-04-29T10:49:52.493Z'
+ updated_at: '2026-04-29T10:49:52.493Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -880,9 +1347,9 @@ paths:
previous:
next:
post:
- summary: Add a line item
+ summary: Add an item
tags:
- - Line Items
+ - Orders
security:
- api_key: []
bearer_auth: []
@@ -907,7 +1374,7 @@ paths:
type: string
responses:
'201':
- description: line item added
+ description: item added
content:
application/json:
example:
@@ -915,8 +1382,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 35964
- slug: product-35964
+ name: Product 127539
+ slug: product-127539
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -928,26 +1395,30 @@ paths:
display_additional_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
pre_tax_amount: '59.97'
display_pre_tax_amount: "$59.97"
discounted_amount: '59.97'
display_discounted_amount: "$59.97"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:31:52.624Z'
- updated_at: '2026-03-07T11:31:52.624Z'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_gbHJdmfrXB
option_type_id: opt_gbHJdmfrXB
name: size-3
- presentation: S
+ label: S
position: 1
+ color_code:
option_type_name: foo-size-12
- option_type_presentation: Size
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:49:53.417Z'
+ updated_at: '2026-04-29T10:49:53.417Z'
digital_links: []
+ created_at: '2026-04-29T10:49:53.450Z'
+ updated_at: '2026-04-29T10:49:53.450Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -966,11 +1437,11 @@ paths:
quantity:
type: integer
default: 1
- "/api/v3/admin/orders/{order_id}/line_items/{id}":
+ "/api/v3/admin/orders/{order_id}/items/{id}":
get:
- summary: Show a line item
+ summary: Show an item
tags:
- - Line Items
+ - Orders
security:
- api_key: []
bearer_auth: []
@@ -996,12 +1467,12 @@ paths:
- name: id
in: path
required: true
- description: Line item prefixed ID
+ description: Item prefixed ID
schema:
type: string
responses:
'200':
- description: line item found
+ description: item found
content:
application/json:
example:
@@ -1009,8 +1480,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 45612
- slug: product-45612
+ name: Product 133573
+ slug: product-133573
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -1022,38 +1493,42 @@ paths:
display_additional_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
pre_tax_amount: '20.0'
display_pre_tax_amount: "$20.00"
discounted_amount: '20.0'
display_discounted_amount: "$20.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:31:52.999Z'
- updated_at: '2026-03-07T11:31:52.999Z'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
name: size-4
- presentation: S
+ label: S
position: 1
+ color_code:
option_type_name: foo-size-13
- option_type_presentation: Size
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:49:53.515Z'
+ updated_at: '2026-04-29T10:49:53.515Z'
digital_links: []
+ created_at: '2026-04-29T10:49:53.796Z'
+ updated_at: '2026-04-29T10:49:53.796Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
patch:
- summary: Update a line item
+ summary: Update an item
tags:
- - Line Items
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Updates a line item quantity or metadata.
+ description: Updates an order item quantity or metadata.
parameters:
- name: x-spree-api-key
in: header
@@ -1075,12 +1550,12 @@ paths:
- name: id
in: path
required: true
- description: Line item prefixed ID
+ description: Item prefixed ID
schema:
type: string
responses:
'200':
- description: line item updated
+ description: item updated
content:
application/json:
example:
@@ -1088,8 +1563,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 54848
- slug: product-54848
+ name: Product 144758
+ slug: product-144758
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -1101,26 +1576,30 @@ paths:
display_additional_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
pre_tax_amount: '99.95'
display_pre_tax_amount: "$99.95"
discounted_amount: '99.95'
display_discounted_amount: "$99.95"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:31:53.645Z'
- updated_at: '2026-03-07T11:31:53.981Z'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
name: size-5
- presentation: S
+ label: S
position: 1
+ color_code:
option_type_name: foo-size-14
- option_type_presentation: Size
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:49:54.111Z'
+ updated_at: '2026-04-29T10:49:54.111Z'
digital_links: []
+ created_at: '2026-04-29T10:49:54.392Z'
+ updated_at: '2026-04-29T10:49:54.686Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -1134,13 +1613,13 @@ paths:
quantity:
type: integer
delete:
- summary: Remove a line item
+ summary: Remove an item
tags:
- - Line Items
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Removes a line item from the order.
+ description: Removes an item from the order.
parameters:
- name: x-spree-api-key
in: header
@@ -1162,7 +1641,7 @@ paths:
- name: id
in: path
required: true
- description: Line item prefixed ID
+ description: Item prefixed ID
schema:
type: string
responses:
@@ -1204,33 +1683,31 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- state: completed
- response_code: '12345'
- number: PE5Y1CQ6
+ response_code: BGS-9440161e4b41
+ number: PHRDBQIF
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-07T11:31:55.026Z'
- updated_at: '2026-03-07T11:31:55.026Z'
+ status: completed
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '1111'
+ brand: visa
+ last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: Spree::Gateway::Bogus
- session_required: true
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ created_at: '2026-04-29T10:49:55.643Z'
+ updated_at: '2026-04-29T10:49:55.645Z'
avs_response:
cvv_response_code:
cvv_response_message:
+ created_at: '2026-04-29T10:49:55.644Z'
+ updated_at: '2026-04-29T10:49:55.644Z'
metadata:
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
@@ -1278,25 +1755,19 @@ paths:
example:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
- state: checkout
response_code:
- number: P4W7JK5J
+ number: PFO94SE9
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-07T11:31:56.451Z'
- updated_at: '2026-03-07T11:31:56.451Z'
+ status: checkout
source_type:
source_id:
source:
- payment_method:
- id: pm_EfhxLZ9ck8
- name: Check
- description:
- type: Spree::PaymentMethod::Check
- session_required: false
avs_response:
cvv_response_code:
cvv_response_message:
+ created_at: '2026-04-29T10:49:56.908Z'
+ updated_at: '2026-04-29T10:49:56.908Z'
metadata:
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
@@ -1310,7 +1781,7 @@ paths:
properties:
payment_method_id:
type: string
- description: Payment method ID or prefixed ID
+ description: Payment method prefixed ID
amount:
type: number
example: 99.99
@@ -1358,33 +1829,31 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- state: completed
- response_code: '12345'
- number: PEBBI073
+ response_code: BGS-87c2d28a0471
+ number: P0WYM8LA
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-07T11:31:56.836Z'
- updated_at: '2026-03-07T11:31:56.836Z'
+ status: completed
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '1111'
+ brand: visa
+ last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: Spree::Gateway::Bogus
- session_required: true
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ created_at: '2026-04-29T10:49:57.265Z'
+ updated_at: '2026-04-29T10:49:57.267Z'
avs_response:
cvv_response_code:
cvv_response_message:
+ created_at: '2026-04-29T10:49:57.266Z'
+ updated_at: '2026-04-29T10:49:57.266Z'
metadata:
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
@@ -1429,33 +1898,31 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- state: completed
- response_code: '12345'
- number: PDYBX5M9
+ response_code: BGS-8b5c306e4573
+ number: PSH2AT8B
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-07T11:31:57.512Z'
- updated_at: '2026-03-07T11:31:57.860Z'
+ status: completed
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '1111'
+ brand: visa
+ last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: Spree::Gateway::Bogus
- session_required: true
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ created_at: '2026-04-29T10:49:57.912Z'
+ updated_at: '2026-04-29T10:49:57.915Z'
avs_response:
cvv_response_code:
cvv_response_message:
+ created_at: '2026-04-29T10:49:57.914Z'
+ updated_at: '2026-04-29T10:49:58.238Z'
metadata:
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
@@ -1500,33 +1967,31 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- state: void
- response_code: void-12345
- number: P689ZF08
+ response_code: void-BGS-9c6ee8fbbfa7
+ number: PPUQK015
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-07T11:31:58.237Z'
- updated_at: '2026-03-07T11:31:58.544Z'
+ status: void
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '1111'
+ brand: visa
+ last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: Spree::Gateway::Bogus
- session_required: true
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ created_at: '2026-04-29T10:49:58.598Z'
+ updated_at: '2026-04-29T10:49:58.601Z'
avs_response:
cvv_response_code:
cvv_response_message:
+ created_at: '2026-04-29T10:49:58.600Z'
+ updated_at: '2026-04-29T10:49:58.896Z'
metadata:
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
@@ -1608,14 +2073,13 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: '12345'
- created_at: '2026-03-07T11:31:59.923Z'
- updated_at: '2026-03-07T11:31:59.923Z'
+ transaction_id: BGS-4ce7094aab21
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
- metadata:
+ created_at: '2026-04-29T10:50:00.206Z'
+ updated_at: '2026-04-29T10:50:00.206Z'
requestBody:
content:
application/json:
@@ -1634,15 +2098,16 @@ paths:
refund_reason_id:
type: string
description: Refund reason prefixed ID
- "/api/v3/admin/orders/{order_id}/shipments":
- get:
- summary: List shipments
+ "/api/v3/admin/orders/{order_id}/store_credits":
+ post:
+ summary: Apply customer's store credit to an order
tags:
- - Shipments
+ - Order Store Credits
security:
- api_key: []
bearer_auth: []
- description: Returns all shipments for an order.
+ description: Applies the order customer's available store credit. When `amount`
+ is omitted, applies up to the order outstanding balance.
parameters:
- name: x-spree-api-key
in: header
@@ -1662,74 +2127,82 @@ paths:
schema:
type: string
responses:
- '200':
- description: shipments found
+ '201':
+ description: store credit applied
content:
application/json:
example:
- data:
- - id: ship_UkLWZg9DAJ
- number: H63961999053
- state: ready
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:00.284Z'
- updated_at: '2026-03-07T11:32:00.345Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_32
- name: Kina Bernhard
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_32
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- "/api/v3/admin/orders/{order_id}/shipments/{id}":
- get:
- summary: Show a shipment
+ id: or_UkLWZg9DAJ
+ market_id:
+ number: R932540585
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '60.0'
+ display_amount_due: "$60.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ store_credit_total: '50.0'
+ display_store_credit_total: "-$50.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ canceled_at:
+ approved_at:
+ created_at: '2026-04-29T10:50:00.499Z'
+ updated_at: '2026-04-29T10:50:00.543Z'
+ internal_note:
+ metadata:
+ approver_id:
+ canceler_id:
+ created_by_id:
+ customer_id: cus_UkLWZg9DAJ
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ amount:
+ type: number
+ description: Optional explicit amount; defaults to order outstanding
+ balance
+ delete:
+ summary: Remove store credit from an order
tags:
- - Shipments
+ - Order Store Credits
security:
- api_key: []
bearer_auth: []
- description: Returns details of a specific shipment.
+ description: Removes any applied store credit from the order.
parameters:
- name: x-spree-api-key
in: header
@@ -1748,69 +2221,18 @@ paths:
description: Order prefixed ID
schema:
type: string
- - name: id
- in: path
- required: true
- description: Shipment prefixed ID
- schema:
- type: string
responses:
- '200':
- description: shipment found
- content:
- application/json:
- example:
- id: ship_UkLWZg9DAJ
- number: H97411524064
- state: ready
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:00.960Z'
- updated_at: '2026-03-07T11:32:01.021Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_34
- name: Edna Medhurst
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_34
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- patch:
- summary: Update a shipment
+ '204':
+ description: store credit removed
+ "/api/v3/admin/orders":
+ get:
+ summary: List orders
tags:
- - Shipments
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Updates a shipment (tracking, shipping rate).
+ description: Returns a paginated list of orders for the current store.
parameters:
- name: x-spree-api-key
in: header
@@ -1823,87 +2245,142 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order prefixed ID
- schema:
+ - 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: id
- in: path
- required: true
- description: Shipment prefixed ID
+ - 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
responses:
'200':
- description: shipment updated
+ description: orders found
content:
application/json:
example:
- id: ship_UkLWZg9DAJ
- number: H73575509694
- state: ready
- tracking: 1Z999AA10123456784
- tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:01.618Z'
- updated_at: '2026-03-07T11:32:01.961Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_36
- name: Tomiko Roob
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_36
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- tracking:
- type: string
- example: 1Z999AA10123456784
- selected_shipping_rate_id:
- type: string
- "/api/v3/admin/orders/{order_id}/shipments/{id}/ship":
- patch:
- summary: Ship a shipment
+ data:
+ - id: or_UkLWZg9DAJ
+ market_id:
+ number: R030728080
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ item_total: '0.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ canceled_at:
+ approved_at:
+ created_at: '2026-04-29T10:50:02.264Z'
+ updated_at: '2026-04-29T10:50:02.264Z'
+ internal_note:
+ metadata:
+ approver_id:
+ canceler_id:
+ created_by_id:
+ customer_id: cus_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ post:
+ summary: Create a draft order
tags:
- - Shipments
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Marks a shipment as shipped.
+ description: |
+ Creates a new draft order in one shot. Customer, items, addresses, currency,
+ market, locale, notes, metadata, and a coupon code can all be provided inline.
+
+ Invalid coupon codes are non-fatal — the order is created and the failure
+ is reported on the service result (not in the API response body for now).
parameters:
- name: x-spree-api-key
in: header
@@ -1916,76 +2393,172 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Shipment prefixed ID
- schema:
- type: string
responses:
- '200':
- description: shipment shipped
+ '201':
+ description: order created
content:
application/json:
example:
- id: ship_UkLWZg9DAJ
- number: H93306462242
- state: shipped
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at: '2026-03-07T11:32:02.646Z'
- created_at: '2026-03-07T11:32:02.289Z'
- updated_at: '2026-03-07T11:32:02.646Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_38
- name: Frida Kub
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_38
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
+ id: or_gbHJdmfrXB
+ market_id:
+ number: R195052535
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ item_total: '0.0'
+ display_item_total: "$0.00"
adjustment_total: '0.0'
- additional_tax_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ canceled_at:
+ approved_at:
+ created_at: '2026-04-29T10:50:03.379Z'
+ updated_at: '2026-04-29T10:50:03.379Z'
+ internal_note:
metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- "/api/v3/admin/orders/{order_id}/shipments/{id}/cancel":
- patch:
- summary: Cancel a shipment
+ approver_id:
+ canceler_id:
+ created_by_id:
+ customer_id:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ customer_id:
+ type: string
+ description: 'Customer prefixed 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
+ example: USD
+ market_id:
+ type: string
+ description: Market prefixed ID
+ locale:
+ type: string
+ example: en-US
+ 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 prefixed 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 prefixed ID
+ items:
+ type: array
+ items:
+ type: object
+ required:
+ - variant_id
+ - quantity
+ properties:
+ variant_id:
+ type: string
+ description: Variant prefixed ID
+ quantity:
+ type: integer
+ example: 1
+ 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:
- - Shipments
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Cancels a pending or ready shipment.
+ description: Returns full order details including admin-only fields.
parameters:
- name: x-spree-api-key
in: header
@@ -1998,76 +2571,96 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order prefixed ID
- schema:
- type: string
- name: id
in: path
required: true
- description: Shipment prefixed ID
+ description: Order prefixed ID (e.g., or_xxx)
schema:
type: string
- responses:
- '200':
- description: shipment canceled
- content:
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., user)
+ schema:
+ type: string
+ responses:
+ '200':
+ description: order found
+ content:
application/json:
example:
- id: ship_UkLWZg9DAJ
- number: H08656001130
- state: canceled
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:02.966Z'
- updated_at: '2026-03-07T11:32:03.318Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_40
- name: Ezequiel Steuber
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_40
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
+ id: or_UkLWZg9DAJ
+ market_id:
+ number: R674454839
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ item_total: '0.0'
+ display_item_total: "$0.00"
adjustment_total: '0.0'
- additional_tax_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ canceled_at:
+ approved_at:
+ created_at: '2026-04-29T10:50:03.664Z'
+ updated_at: '2026-04-29T10:50:03.664Z'
+ internal_note:
metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- "/api/v3/admin/orders/{order_id}/shipments/{id}/resume":
+ approver_id:
+ canceler_id:
+ created_by_id:
+ customer_id: cus_UkLWZg9DAJ
+ '404':
+ description: order not found
+ content:
+ application/json:
+ example:
+ error:
+ code: order_not_found
+ message: Order not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Resume a shipment
+ summary: Update an order
tags:
- - Shipments
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Resumes a canceled shipment.
+ description: Updates an order. Supports updating email, addresses, special instructions,
+ and line items.
parameters:
- name: x-spree-api-key
in: header
@@ -2080,77 +2673,138 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order prefixed ID
- schema:
- type: string
- name: id
in: path
required: true
- description: Shipment prefixed ID
+ description: Order prefixed ID
schema:
type: string
responses:
'200':
- description: shipment resumed
+ description: order updated
content:
application/json:
example:
- id: ship_UkLWZg9DAJ
- number: H02364330432
- state: pending
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:03.668Z'
- updated_at: '2026-03-07T11:32:04.079Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_42
- name: Marita Graham
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_42
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
+ id: or_UkLWZg9DAJ
+ market_id:
+ number: R711176664
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ item_total: '0.0'
+ display_item_total: "$0.00"
adjustment_total: '0.0'
- additional_tax_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ canceled_at:
+ approved_at:
+ created_at: '2026-04-29T10:50:04.785Z'
+ updated_at: '2026-04-29T10:50:05.065Z'
+ internal_note:
metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- "/api/v3/admin/orders/{order_id}/shipments/{id}/split":
- patch:
- summary: Split a shipment
+ approver_id:
+ canceler_id:
+ created_by_id:
+ customer_id: cus_UkLWZg9DAJ
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ special_instructions:
+ type: string
+ internal_note:
+ type: string
+ 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
+ line_items:
+ type: array
+ items:
+ type: object
+ properties:
+ variant_id:
+ type: string
+ quantity:
+ type: integer
+ delete:
+ summary: Delete a draft order
tags:
- - Shipments
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Transfers items from this shipment to a new shipment at a different
- stock location.
+ description: Deletes a draft order. Completed orders cannot be deleted.
parameters:
- name: x-spree-api-key
in: header
@@ -2163,95 +2817,24 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order prefixed ID
- schema:
- type: string
- name: id
in: path
required: true
- description: Shipment prefixed ID
+ description: Order prefixed ID
schema:
type: string
responses:
- '200':
- description: shipment split
- content:
- application/json:
- example:
- data:
- - id: ship_gbHJdmfrXB
- number: H21664429230
- state: ready
- tracking:
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:04.766Z'
- updated_at: '2026-03-07T11:32:04.810Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_gbHJdmfrXB
- state_abbr: STATE_ABBR_44
- name: Warehouse 2
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_44
- shipping_rates:
- - id: shpr_uw2YK1rnl0
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_gbHJdmfrXB
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - variant_id
- - quantity
- properties:
- variant_id:
- type: string
- description: Variant prefixed ID
- quantity:
- type: integer
- example: 1
- stock_location_id:
- type: string
- description: Target stock location prefixed ID
- "/api/v3/admin/orders":
- get:
- summary: List orders
+ '204':
+ description: order deleted
+ "/api/v3/admin/orders/{id}/cancel":
+ patch:
+ summary: Cancel an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
- description: Returns a paginated list of orders for the current store.
+ description: Cancels a completed order.
parameters:
- name: x-spree-api-key
in: header
@@ -2264,166 +2847,80 @@ paths:
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
+ - name: id
+ in: path
+ required: true
+ description: Order prefixed ID
schema:
type: string
responses:
'200':
- description: orders found
- content:
- application/json:
- example:
- data:
- - id: or_UkLWZg9DAJ
- number: R113959961
- state: cart
- checkout_steps:
- - address
- - delivery
- - complete
- token: 72C8TYgVLCYFrZr1s3AkdriwQgVdk7E36t3
- special_instructions:
- currency: USD
- locale: en
- item_count: 0
- state_lock_version: 0
- shipment_state:
- payment_state:
- item_total: '0.0'
- display_item_total: "$0.00"
- ship_total: '0.0'
- display_ship_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- completed_at:
- created_at: '2026-03-07T11:32:05.092Z'
- updated_at: '2026-03-07T11:32:05.092Z'
- order_promotions: []
- line_items: []
- shipments: []
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 41 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_46
- state_abbr: STATE_ABBR_46
- quick_checkout: false
- state_name: STATE_NAME_46
- ship_address:
- payment_methods: []
- channel: spree
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
- payment_total: '0.0'
- display_payment_total: "$0.00"
- canceled_at:
- approved_at:
- metadata:
- approver_id:
- canceler_id:
- created_by_id:
- user_id: cus_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- '401':
- description: unauthorized
+ description: order canceled
content:
application/json:
example:
- error:
- code: invalid_token
- message: Valid secret API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a draft order
+ id: or_UkLWZg9DAJ
+ market_id:
+ number: R330207027
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '20.0'
+ display_total: "$20.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: "-0.0"
+ display_amount_due: "$0.00"
+ delivery_total: '10.0'
+ display_delivery_total: "$10.00"
+ fulfillment_status: canceled
+ payment_status: void
+ completed_at: '2026-04-29T10:50:05.943Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: canceled
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ canceled_at: '2026-04-29T10:50:06.232Z'
+ approved_at:
+ created_at: '2026-04-29T10:50:05.897Z'
+ updated_at: '2026-04-29T10:50:06.270Z'
+ internal_note:
+ metadata:
+ approver_id:
+ canceler_id: admin_UkLWZg9DAJ
+ created_by_id:
+ customer_id: cus_UkLWZg9DAJ
+ "/api/v3/admin/orders/{id}/approve":
+ patch:
+ summary: Approve an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
- description: Creates a new draft order. Optionally assign a user and set initial
- attributes.
+ description: Approves an order (e.g., for fraud review).
parameters:
- name: x-spree-api-key
in: header
@@ -2436,106 +2933,80 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
responses:
- '201':
- description: order created
+ '200':
+ description: order approved
content:
application/json:
example:
- id: or_gbHJdmfrXB
- number: R594081781
- state: cart
- checkout_steps:
- - address
- - delivery
- - complete
- token: Dr2-m36jKm3IYEpuywubNQ1772883126491
- special_instructions:
+ id: or_UkLWZg9DAJ
+ market_id:
+ number: R406004585
+ customer_note:
currency: USD
locale: en
- item_count: 0
- state_lock_version: 0
- shipment_state:
- payment_state:
- item_total: '0.0'
- display_item_total: "$0.00"
- ship_total: '0.0'
- display_ship_total: "$0.00"
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
tax_total: '0.0'
display_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- completed_at:
- created_at: '2026-03-07T11:32:06.492Z'
- updated_at: '2026-03-07T11:32:06.492Z'
- order_promotions: []
- line_items: []
- shipments: []
- payments: []
- bill_address:
- ship_address:
- payment_methods: []
- channel: spree
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-04-29T10:50:06.589Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 2
- created_at:
- updated_at:
- locale: en
payment_total: '0.0'
display_payment_total: "$0.00"
canceled_at:
- approved_at:
+ approved_at: '2026-04-29T10:50:06.873Z'
+ created_at: '2026-04-29T10:50:06.546Z'
+ updated_at: '2026-04-29T10:50:06.589Z'
+ internal_note:
metadata:
- approver_id:
+ approver_id: admin_UkLWZg9DAJ
canceler_id:
created_by_id:
- user_id:
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- user_id:
- type: string
- description: Prefixed user ID to assign
- currency:
- type: string
- example: USD
- channel:
- type: string
- example: admin
- internal_note:
- type: string
- "/api/v3/admin/orders/{id}":
- get:
- summary: Show an order
+ customer_id: cus_UkLWZg9DAJ
+ "/api/v3/admin/orders/{id}/resume":
+ patch:
+ summary: Resume a canceled order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
- description: Returns full order details including admin-only fields.
+ description: Resumes a previously canceled order.
parameters:
- name: x-spree-api-key
in: header
@@ -2551,122 +3022,78 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID (e.g., or_xxx)
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., user)
+ description: Order prefixed ID
schema:
type: string
responses:
'200':
- description: order found
+ description: order resumed
content:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R337788873
- state: cart
- checkout_steps:
- - address
- - delivery
- - complete
- token: 96PRA6YRFjpYjzRMkpfdjZog8ZfmV5MqwyS
- special_instructions:
+ market_id:
+ number: R618787001
+ customer_note:
currency: USD
locale: en
- item_count: 0
- state_lock_version: 0
- shipment_state:
- payment_state:
- item_total: '0.0'
- display_item_total: "$0.00"
- ship_total: '0.0'
- display_ship_total: "$0.00"
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
tax_total: '0.0'
display_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- completed_at:
- created_at: '2026-03-07T11:32:06.766Z'
- updated_at: '2026-03-07T11:32:06.766Z'
- order_promotions: []
- line_items: []
- shipments: []
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 44 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_49
- state_abbr: STATE_ABBR_49
- quick_checkout: false
- state_name: STATE_NAME_49
- ship_address:
- payment_methods: []
- channel: spree
+ total: '20.0'
+ display_total: "$20.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '20.0'
+ display_amount_due: "$20.00"
+ delivery_total: '10.0'
+ display_delivery_total: "$10.00"
+ fulfillment_status: canceled
+ payment_status: void
+ completed_at: '2026-04-29T10:50:07.206Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: canceled
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
payment_total: '0.0'
display_payment_total: "$0.00"
- canceled_at:
+ canceled_at: '2026-04-29T10:50:07.484Z'
approved_at:
+ created_at: '2026-04-29T10:50:07.150Z'
+ updated_at: '2026-04-29T10:50:07.546Z'
+ internal_note:
metadata:
approver_id:
- canceler_id:
+ canceler_id: admin_UkLWZg9DAJ
created_by_id:
- user_id: cus_UkLWZg9DAJ
- '404':
- description: order not found
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Couldn't find Spree::Order with 'id'=245546638656678833
- [WHERE "spree_orders"."store_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update an order
+ customer_id: cus_UkLWZg9DAJ
+ "/api/v3/admin/orders/{id}/resend_confirmation":
+ post:
+ summary: Resend confirmation email
tags:
- Orders
security:
- api_key: []
bearer_auth: []
- description: Updates an order. Supports updating email, addresses, special instructions,
- and line items.
+ description: Publishes the order.completed event to trigger confirmation email
+ delivery.
parameters:
- name: x-spree-api-key
in: header
@@ -2687,160 +3114,72 @@ paths:
type: string
responses:
'200':
- description: order updated
+ description: confirmation resent
content:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R077527935
- state: cart
- checkout_steps:
- - address
- - delivery
- - complete
- token: Ky8anMN786JtzXwk8DbMTKmGbu3QKH2Xysf
- special_instructions:
+ market_id:
+ number: R228062904
+ customer_note:
currency: USD
locale: en
- item_count: 0
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '0.0'
- display_item_total: "$0.00"
- ship_total: '0.0'
- display_ship_total: "$0.00"
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
tax_total: '0.0'
display_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- completed_at:
- created_at: '2026-03-07T11:32:07.903Z'
- updated_at: '2026-03-07T11:32:08.192Z'
- order_promotions: []
- line_items: []
- shipments: []
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 46 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_51
- state_abbr: STATE_ABBR_51
- quick_checkout: false
- state_name: STATE_NAME_51
- ship_address:
- payment_methods: []
- channel: spree
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-04-29T10:50:07.872Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
payment_total: '0.0'
display_payment_total: "$0.00"
canceled_at:
approved_at:
+ created_at: '2026-04-29T10:50:07.823Z'
+ updated_at: '2026-04-29T10:50:07.871Z'
+ internal_note:
metadata:
approver_id:
canceler_id:
created_by_id:
- user_id: cus_UkLWZg9DAJ
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- special_instructions:
- type: string
- internal_note:
- type: string
- channel:
- type: string
- 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
- line_items:
- type: array
- items:
- type: object
- properties:
- variant_id:
- type: string
- quantity:
- type: integer
- delete:
- summary: Delete a draft order
+ customer_id: cus_UkLWZg9DAJ
+ "/api/v3/admin/products":
+ get:
+ summary: List products
tags:
- - Orders
+ - Products
security:
- api_key: []
bearer_auth: []
- description: Deletes a draft order. Completed orders cannot be deleted.
+ description: Returns a paginated list of products for the current store.
parameters:
- name: x-spree-api-key
in: header
@@ -2853,232 +3192,146 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
- in: path
- required: true
- description: Order prefixed ID
+ - 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
- responses:
- '204':
- description: order deleted
- "/api/v3/admin/orders/{id}/cancel":
- patch:
- summary: Cancel an order
- tags:
- - Orders
- security:
- - api_key: []
- bearer_auth: []
- description: Cancels a completed order.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., variants, variants.images)
schema:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
schema:
type: string
- - name: id
- in: path
- required: true
- description: Order prefixed ID
+ - name: q[status_eq]
+ in: query
+ required: false
+ description: Filter by status
schema:
type: string
responses:
'200':
- description: order canceled
+ description: products found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R233851919
- state: canceled
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: 8ecmPZ2xEtaYkfA7ZAPYcqLwZXTNavs92gJ
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state: canceled
- payment_state: void
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '10.0'
- display_ship_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '20.0'
- display_total: "$20.00"
- completed_at: '2026-03-07T11:32:09.111Z'
- created_at: '2026-03-07T11:32:09.052Z'
- updated_at: '2026-03-07T11:32:09.443Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 222802
- slug: product-222802
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:32:09.088Z'
- updated_at: '2026-03-07T11:32:09.088Z'
- compare_at_amount:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 353214
+ slug: product-353214
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on: '2025-04-29T10:50:09.803Z'
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Nam quis placeat temporibus libero nisi in. Possimus
+ maiores maxime quam vel asperiores dolorem. Beatae occaecati animi
+ eius incidunt at. Omnis magnam non nesciunt aliquid. Odio soluta
+ id odit omnis excepturi. Dolore optio possimus sunt explicabo
+ eaque voluptatem recusandae. Minus impedit nobis distinctio accusamus.
+ Odit asperiores optio itaque laboriosam veniam. Ab et ex fuga
+ illo ducimus. Laboriosam voluptates modi magnam eligendi assumenda
+ quo quis. Quidem provident perferendis architecto vero. Illo eveniet
+ omnis reiciendis voluptatem explicabo. Unde corrupti consequuntur
+ facere quia. Pariatur eius aliquid voluptatem ut praesentium quisquam.
+ Ea delectus placeat fugiat sed voluptate perferendis consequuntur.
+ Beatae recusandae repellat quibusdam laborum velit.
+ description_html: |-
+ Nam quis placeat temporibus libero nisi in. Possimus maiores maxime quam vel asperiores dolorem. Beatae occaecati animi eius incidunt at. Omnis magnam non nesciunt aliquid.
+ Odio soluta id odit omnis excepturi. Dolore optio possimus sunt explicabo eaque voluptatem recusandae. Minus impedit nobis distinctio accusamus.
+ Odit asperiores optio itaque laboriosam veniam. Ab et ex fuga illo ducimus. Laboriosam voluptates modi magnam eligendi assumenda quo quis. Quidem provident perferendis architecto vero. Illo eveniet omnis reiciendis voluptatem explicabo.
+ Unde corrupti consequuntur facere quia. Pariatur eius aliquid voluptatem ut praesentium quisquam. Ea delectus placeat fugiat sed voluptate perferendis consequuntur. Beatae recusandae repellat quibusdam laborum velit.
+ default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
- option_values: []
- digital_links: []
- metadata:
+ 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-04-29T10:50:09.850Z'
+ updated_at: '2026-04-29T10:50:09.850Z'
+ original_price:
+ status: active
+ make_active_at: '2025-04-29T10:50:09.803Z'
+ discontinue_on:
+ deleted_at:
+ created_at: '2026-04-29T10:50:09.839Z'
+ updated_at: '2026-04-29T10:50:09.851Z'
cost_price: '17.0'
- tax_category_id: taxcat_UkLWZg9DAJ
- order_id: or_UkLWZg9DAJ
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H12260130427
- state: canceled
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:09.094Z'
- updated_at: '2026-03-07T11:32:09.441Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_53
- name: Noreen Donnelly
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_53
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 48 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_53
- state_abbr: STATE_ABBR_53
- quick_checkout: false
- state_name: STATE_NAME_53
- ship_address:
- id: addr_gbHJdmfrXB
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 49 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_54
- state_abbr: STATE_ABBR_54
- quick_checkout: false
- state_name: STATE_NAME_54
- payment_methods: []
- channel: spree
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
- payment_total: '0.0'
- display_payment_total: "$0.00"
- canceled_at: '2026-03-07T11:32:09.407Z'
- approved_at:
- metadata:
- approver_id:
- canceler_id: admin_UkLWZg9DAJ
- created_by_id:
- user_id: cus_UkLWZg9DAJ
- "/api/v3/admin/orders/{id}/approve":
- patch:
- summary: Approve an order
+ cost_currency: USD
+ 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/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ post:
+ summary: Create a product
tags:
- - Orders
+ - Products
security:
- api_key: []
bearer_auth: []
- description: Approves an order (e.g., for fraud review).
+ description: |
+ Creates a new product. Supports nested variants with prices and option types.
+
+ Option types and values are auto-created if they don't exist.
+ Prices are upserted by currency. Stock items are upserted by stock location.
parameters:
- name: x-spree-api-key
in: header
@@ -3091,202 +3344,154 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
- in: path
- required: true
- description: Order prefixed ID
- schema:
- type: string
responses:
- '200':
- description: order approved
+ '201':
+ description: product created
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R217948365
- state: complete
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: FspY8H6zJ8tJnkQo1v6arHRM2Ndy5o8PjAV
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at: '2026-03-07T11:32:09.791Z'
- created_at: '2026-03-07T11:32:09.737Z'
- updated_at: '2026-03-07T11:32:09.791Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 237239
- slug: product-237239
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:32:09.769Z'
- updated_at: '2026-03-07T11:32:09.769Z'
+ id: prod_gbHJdmfrXB
+ name: New Product
+ slug: new-product
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on:
+ purchasable: false
+ in_stock: false
+ backorderable: false
+ available: false
+ description:
+ description_html:
+ default_variant_id: variant_gbHJdmfrXB
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_gbHJdmfrXB
+ amount: '19.99'
+ amount_in_cents: 1999
compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- metadata:
- cost_price: '17.0'
- tax_category_id: taxcat_UkLWZg9DAJ
- order_id: or_UkLWZg9DAJ
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H15691854339
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-07T11:32:09.774Z'
- updated_at: '2026-03-07T11:32:09.788Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_55
- name: Terisa Klocko
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_55
- shipping_rates:
- - id: shpr_gbHJdmfrXB
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 50 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_55
- state_abbr: STATE_ABBR_55
- quick_checkout: false
- state_name: STATE_NAME_55
- ship_address:
- id: addr_gbHJdmfrXB
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 51 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_56
- state_abbr: STATE_ABBR_56
- quick_checkout: false
- state_name: STATE_NAME_56
- payment_methods: []
- channel: spree
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
- payment_total: '0.0'
- display_payment_total: "$0.00"
- canceled_at:
- approved_at: '2026-03-07T11:32:10.092Z'
- metadata:
- approver_id: admin_UkLWZg9DAJ
- canceler_id:
- created_by_id:
- user_id: cus_UkLWZg9DAJ
- "/api/v3/admin/orders/{id}/resume":
- patch:
- summary: Resume a canceled order
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-04-29T10:50:10.495Z'
+ updated_at: '2026-04-29T10:50:10.495Z'
+ original_price:
+ status: draft
+ make_active_at:
+ discontinue_on:
+ deleted_at:
+ created_at: '2026-04-29T10:50:10.493Z'
+ updated_at: '2026-04-29T10:50:10.499Z'
+ cost_price:
+ cost_currency: USD
+ schema:
+ "$ref": "#/components/schemas/Product"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Premium T-Shirt
+ price:
+ type: number
+ example: 29.99
+ description:
+ type: string
+ slug:
+ type: string
+ status:
+ type: string
+ enum:
+ - draft
+ - active
+ - archived
+ sku:
+ type: string
+ shipping_category_id:
+ type: string
+ description: Prefixed ID (e.g., sc_xxx) or integer
+ tax_category_id:
+ type: string
+ description: Prefixed ID or integer
+ taxon_ids:
+ type: array
+ items:
+ type: string
+ description: Array of prefixed taxon IDs
+ tags:
+ type: array
+ items:
+ type: string
+ example:
+ - eco
+ - sale
+ variants:
+ type: array
+ items:
+ type: object
+ properties:
+ sku:
+ type: string
+ price:
+ type: number
+ option_type:
+ type: string
+ example: Size
+ option_value:
+ type: string
+ example: Small
+ total_on_hand:
+ type: integer
+ prices:
+ type: array
+ items:
+ type: object
+ properties:
+ currency:
+ type: string
+ example: USD
+ amount:
+ type: number
+ example: 29.99
+ compare_at_amount:
+ type: number
+ example: 39.99
+ required:
+ - currency
+ - amount
+ required:
+ - name
+ - price
+ - shipping_category_id
+ "/api/v3/admin/products/{id}":
+ get:
+ summary: Get a product
tags:
- - Orders
+ - Products
security:
- api_key: []
bearer_auth: []
- description: Resumes a previously canceled order.
+ description: Returns a single product by prefixed ID.
parameters:
- name: x-spree-api-key
in: header
@@ -3302,200 +3507,85 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Product prefixed ID (e.g., prod_xxx)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., variants)
schema:
type: string
responses:
'200':
- description: order resumed
+ description: product found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R352612523
- state: resumed
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: dpdnvdo4KMBoHDJNbjHqb6d49Cr18UbxBqh
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state: canceled
- payment_state: void
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '10.0'
- display_ship_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '20.0'
- display_total: "$20.00"
- completed_at: '2026-03-07T11:32:10.442Z'
- created_at: '2026-03-07T11:32:10.384Z'
- updated_at: '2026-03-07T11:32:10.789Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 245952
- slug: product-245952
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:32:10.417Z'
- updated_at: '2026-03-07T11:32:10.760Z'
+ id: prod_UkLWZg9DAJ
+ name: Product 392371
+ slug: product-392371
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on: '2025-04-29T10:50:10.835Z'
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Doloremque ratione unde inventore cumque at nostrum.
+ Consequatur repudiandae aspernatur pariatur cum. Suscipit unde fugiat
+ sint itaque quibusdam dolorum. Maiores cupiditate alias sint quaerat
+ minus harum. Pariatur saepe veniam odio voluptas ducimus vero itaque.
+ description_html: Doloremque ratione unde inventore cumque at nostrum.
+ Consequatur repudiandae aspernatur pariatur cum. Suscipit unde fugiat
+ sint itaque quibusdam dolorum. Maiores cupiditate alias sint quaerat
+ minus harum. Pariatur saepe veniam odio voluptas ducimus vero itaque.
+ default_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- metadata:
- cost_price: '17.0'
- tax_category_id: taxcat_UkLWZg9DAJ
- order_id: or_UkLWZg9DAJ
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H66819641422
- state: pending
- tracking: U10000
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-07T11:32:10.423Z'
- updated_at: '2026-03-07T11:32:10.781Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_57
- name: Lucilla Kemmer
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_57
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 52 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_57
- state_abbr: STATE_ABBR_57
- quick_checkout: false
- state_name: STATE_NAME_57
- ship_address:
- id: addr_gbHJdmfrXB
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 53 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_58
- state_abbr: STATE_ABBR_58
- quick_checkout: false
- state_name: STATE_NAME_58
- payment_methods: []
- channel: spree
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
- payment_total: '0.0'
- display_payment_total: "$0.00"
- canceled_at: '2026-03-07T11:32:10.729Z'
- approved_at:
- metadata:
- approver_id:
- canceler_id: admin_UkLWZg9DAJ
- created_by_id:
- user_id: cus_UkLWZg9DAJ
- "/api/v3/admin/orders/{id}/resend_confirmation":
- post:
- summary: Resend confirmation email
+ 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-04-29T10:50:10.862Z'
+ updated_at: '2026-04-29T10:50:10.862Z'
+ original_price:
+ status: active
+ make_active_at: '2025-04-29T10:50:10.835Z'
+ discontinue_on:
+ deleted_at:
+ created_at: '2026-04-29T10:50:10.849Z'
+ updated_at: '2026-04-29T10:50:10.863Z'
+ cost_price: '17.0'
+ cost_currency: USD
+ schema:
+ "$ref": "#/components/schemas/Product"
+ '404':
+ description: product not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Product not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a product
tags:
- - Orders
+ - Products
security:
- api_key: []
bearer_auth: []
- description: Publishes the order.completed event to trigger confirmation email
- delivery.
+ description: Updates a product. Only provided fields are updated.
parameters:
- name: x-spree-api-key
in: header
@@ -3511,199 +3601,159 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Product prefixed ID
schema:
type: string
responses:
'200':
- description: confirmation resent
+ description: product updated
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R157765926
- state: complete
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: mmWKYkWQY5zF9uw3A3KRG5NGidk4rkx1DSU
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 0
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at: '2026-03-07T11:32:11.156Z'
- created_at: '2026-03-07T11:32:11.090Z'
- updated_at: '2026-03-07T11:32:11.156Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 256333
- slug: product-256333
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-07T11:32:11.128Z'
- updated_at: '2026-03-07T11:32:11.128Z'
+ id: prod_UkLWZg9DAJ
+ name: Updated Name
+ slug: product-419167
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on: '2025-04-29T10:50:11.469Z'
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Illo accusamus odit est doloremque eum iusto nemo amet.
+ Eos sunt voluptas iure ipsam. Quibusdam recusandae cupiditate consectetur
+ repellendus est animi neque beatae. Veritatis neque at sint hic
+ fuga occaecati officiis. Dicta sit quam exercitationem rem facilis.
+ Cupiditate consectetur est quibusdam minima consequatur sit eos
+ totam.
+ description_html: |-
+ Illo accusamus odit est doloremque eum iusto nemo amet. Eos sunt voluptas iure ipsam. Quibusdam recusandae cupiditate consectetur repellendus est animi neque beatae.
+ Veritatis neque at sint hic fuga occaecati officiis. Dicta sit quam exercitationem rem facilis. Cupiditate consectetur est quibusdam minima consequatur sit eos totam.
+ default_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- metadata:
- cost_price: '17.0'
- tax_category_id: taxcat_UkLWZg9DAJ
- order_id: or_UkLWZg9DAJ
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H48503041679
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-07T11:32:11.135Z'
- updated_at: '2026-03-07T11:32:11.153Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_59
- name: Jerri Huels
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_59
- shipping_rates:
- - id: shpr_gbHJdmfrXB
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- adjustment_total: '0.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- promo_total: '0.0'
- pre_tax_amount: '0.0'
- metadata:
- order_id: or_UkLWZg9DAJ
- stock_location_id: sloc_UkLWZg9DAJ
- payments: []
- bill_address:
- id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 54 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_59
- state_abbr: STATE_ABBR_59
- quick_checkout: false
- state_name: STATE_NAME_59
- ship_address:
- id: addr_gbHJdmfrXB
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 55 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_60
- state_abbr: STATE_ABBR_60
- quick_checkout: false
- state_name: STATE_NAME_60
- payment_methods: []
- channel: spree
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- internal_note:
- id:
- name: internal_note
- body:
- record_type: Spree::Order
- record_id: 1
- created_at:
- updated_at:
- locale: en
- payment_total: '0.0'
- display_payment_total: "$0.00"
- canceled_at:
- approved_at:
- metadata:
- approver_id:
- canceler_id:
- created_by_id:
- user_id: cus_UkLWZg9DAJ
- "/api/v3/admin/products/{product_id}/assets":
- get:
- summary: List product assets
+ 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-04-29T10:50:11.490Z'
+ updated_at: '2026-04-29T10:50:11.490Z'
+ original_price:
+ status: active
+ make_active_at: '2025-04-29T10:50:11.469Z'
+ discontinue_on:
+ deleted_at:
+ created_at: '2026-04-29T10:50:11.479Z'
+ updated_at: '2026-04-29T10:50:11.773Z'
+ cost_price: '17.0'
+ cost_currency: USD
+ schema:
+ "$ref": "#/components/schemas/Product"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Premium T-Shirt
+ price:
+ type: number
+ example: 29.99
+ description:
+ type: string
+ slug:
+ type: string
+ status:
+ type: string
+ enum:
+ - draft
+ - active
+ - archived
+ sku:
+ type: string
+ shipping_category_id:
+ type: string
+ description: Prefixed ID (e.g., sc_xxx) or integer
+ tax_category_id:
+ type: string
+ description: Prefixed ID or integer
+ taxon_ids:
+ type: array
+ items:
+ type: string
+ description: Array of prefixed taxon IDs
+ tags:
+ type: array
+ items:
+ type: string
+ example:
+ - eco
+ - sale
+ variants:
+ type: array
+ items:
+ type: object
+ properties:
+ sku:
+ type: string
+ price:
+ type: number
+ option_type:
+ type: string
+ example: Size
+ option_value:
+ type: string
+ example: Small
+ total_on_hand:
+ type: integer
+ prices:
+ type: array
+ items:
+ type: object
+ properties:
+ currency:
+ type: string
+ example: USD
+ amount:
+ type: number
+ example: 29.99
+ compare_at_amount:
+ type: number
+ example: 39.99
+ required:
+ - currency
+ - amount
+ delete:
+ summary: Delete a product
tags:
- - Product Assets
+ - Products
security:
- api_key: []
bearer_auth: []
- description: Returns a paginated list of assets (images) for a product.
+ description: Soft-deletes a product.
parameters:
- name: x-spree-api-key
in: header
@@ -3716,179 +3766,25 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
+ - name: id
in: path
required: true
description: Product prefixed 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
responses:
- '200':
- description: assets found
- content:
- application/json:
- example:
- data:
- - id: asset_UkLWZg9DAJ
- viewable_id: variant_UkLWZg9DAJ
- type:
- viewable_type: Spree::Variant
- position: 1
- alt:
- created_at: '2026-03-07T11:32:11.511Z'
- updated_at: '2026-03-07T11:32:11.513Z'
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- post:
- summary: Create a product asset
- tags:
- - Product Assets
- security:
- - api_key: []
- bearer_auth: []
- description: Creates a new asset (image) for a product.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- responses:
- '202':
- description: asset import from URL enqueued
- '422':
- description: validation error (attachment required)
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Attachment can't be blank
- details:
- attachment:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- alt:
- type: string
- example: Product front view
- position:
- type: integer
- example: 1
- type:
- type: string
- example: Spree::Image
- description: Asset type (defaults to Spree::Image)
- url:
- type: string
- example: https://example.com/image.jpg
- description: External URL to import image from (async). Returns
- 202 Accepted.
- "/api/v3/admin/products/{product_id}/assets/{id}":
- patch:
- summary: Update a product asset
- tags:
- - Product Assets
- security:
- - api_key: []
- bearer_auth: []
- description: Updates a product asset. Only provided fields are updated.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Asset prefixed ID
- schema:
- type: string
- responses:
- '200':
- description: asset updated
- content:
- application/json:
- example:
- id: asset_UkLWZg9DAJ
- viewable_id: variant_UkLWZg9DAJ
- type:
- viewable_type: Spree::Variant
- position: 1
- alt: Updated alt text
- created_at: '2026-03-07T11:32:12.512Z'
- updated_at: '2026-03-07T11:32:12.804Z'
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- alt:
- type: string
- example: Updated alt text
- position:
- type: integer
- example: 2
- delete:
- summary: Delete a product asset
+ '204':
+ description: product deleted
+ "/api/v3/admin/products/{product_id}/variants":
+ get:
+ summary: List product variants
tags:
- - Product Assets
+ - Variants
security:
- api_key: []
bearer_auth: []
- description: Deletes an asset from a product.
+ description: Returns a paginated list of variants for a product, including the
+ master variant.
parameters:
- name: x-spree-api-key
in: header
@@ -3907,36 +3803,6 @@ paths:
description: Product prefixed ID
schema:
type: string
- - name: id
- in: path
- required: true
- description: Asset prefixed ID
- schema:
- type: string
- responses:
- '204':
- description: asset deleted
- "/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.
- parameters:
- - name: x-spree-api-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
@@ -3949,60 +3815,72 @@ paths:
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, variants.images)
- 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
+ description: Comma-separated associations to expand (e.g., images, prices,
+ stock_items)
schema:
type: string
responses:
'200':
- description: products found
+ description: variants found
content:
application/json:
example:
data:
- - id: prod_UkLWZg9DAJ
- name: Product 316023
- description: |-
- Assumenda nihil debitis nulla temporibus ratione. Eius at expedita nam perferendis quos ad. Magni ducimus itaque eius dolorum.
- Doloremque fugiat nam consequuntur vel mollitia iusto amet voluptate. Harum sed eos sequi assumenda maiores beatae omnis. Numquam vero fugiat quis rem neque natus beatae eligendi. Fuga mollitia molestiae consequatur quidem. Id provident nemo amet explicabo tempora.
- Consectetur mollitia soluta facere sed. Ab eligendi dicta consequatur aut nam voluptatem iure delectus. Sapiente voluptatibus quidem perferendis ullam quae. Sint impedit dolor tenetur ipsam maiores ratione. Veritatis dolorum impedit mollitia dolores deleniti laudantium recusandae.
- Voluptatum iusto sequi excepturi laborum quasi delectus. Aliquam sint libero laboriosam error est vel quasi ex. Dolor nesciunt voluptate dolorem facilis necessitatibus excepturi. Ipsa vitae consequuntur totam debitis labore temporibus.
- slug: product-316023
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on: '2025-03-07T11:32:13.145Z'
- created_at: '2026-03-07T11:32:13.158Z'
- updated_at: '2026-03-07T11:32:13.169Z'
+ - id: variant_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-60
+ options_text: ''
+ track_inventory: true
+ media_count: 0
+ thumbnail_url:
+ purchasable: false
+ in_stock: false
+ backorderable: false
+ weight: 0.0
+ height:
+ width:
+ depth:
+ price:
+ id:
+ amount:
+ amount_in_cents: 0
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$0.00"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ option_values: []
+ position: 1
+ total_on_hand: 0
+ tax_category_id: 1
+ cost_price: '17.0'
+ cost_currency: USD
+ deleted_at:
+ created_at: '2026-04-29T10:50:14.155Z'
+ updated_at: '2026-04-29T10:50:14.167Z'
+ product_name: Product 495198
+ display_price: "$0.00"
+ - id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-61
+ options_text: 'Size: S'
+ track_inventory: true
+ media_count: 0
+ thumbnail_url:
purchasable: true
in_stock: false
backorderable: true
- available: true
- default_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
+ weight: 170.24
+ height: 136.9
+ width: 180.2
+ depth: 130.7
price:
- id: price_UkLWZg9DAJ
+ id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
compare_at_amount:
@@ -4011,61 +3889,48 @@ paths:
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-03-07T11:32:13.159Z'
- updated_at: '2026-03-07T11:32:13.159Z'
original_price:
- status: active
- make_active_at: '2025-03-07T11:32:13.145Z'
- discontinue_on:
- meta_title:
- promotionable: true
- deleted_at:
- shipping_category_id: scat_UkLWZg9DAJ
- tax_category_id: taxcat_UkLWZg9DAJ
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-12
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-21
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:50:14.175Z'
+ updated_at: '2026-04-29T10:50:14.175Z'
+ position: 2
+ total_on_hand: 0
+ tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
+ deleted_at:
+ created_at: '2026-04-29T10:50:14.173Z'
+ updated_at: '2026-04-29T10:50:14.185Z'
+ product_name: Product 495198
+ display_price: "$19.99"
meta:
page: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/AdminProduct"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid secret API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a product
+ summary: Create a variant
tags:
- - Products
+ - Variants
security:
- api_key: []
bearer_auth: []
description: |
- Creates a new product. Supports nested variants with prices and option types.
+ Creates a new variant for a product. Supports nested prices and stock items.
Option types and values are auto-created if they don't exist.
Prices are upserted by currency. Stock items are upserted by stock location.
@@ -4081,55 +3946,65 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- responses:
- '201':
- description: product created
- content:
- application/json:
+ - name: product_id
+ in: path
+ required: true
+ description: Product prefixed ID
+ schema:
+ type: string
+ responses:
+ '201':
+ description: variant created
+ content:
+ application/json:
example:
- id: prod_gbHJdmfrXB
- name: New Product
- description:
- slug: new-product
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on:
- created_at: '2026-03-07T11:32:14.115Z'
- updated_at: '2026-03-07T11:32:14.119Z'
+ id: variant_EfhxLZ9ck8
+ product_id: prod_UkLWZg9DAJ
+ sku: NEW-SKU-001
+ options_text: 'Size: XL'
+ track_inventory: true
+ media_count: 0
+ thumbnail_url:
purchasable: false
in_stock: false
backorderable: false
- available: false
- default_variant_id: variant_gbHJdmfrXB
- thumbnail_url:
- tags: []
+ weight: 0.0
+ height:
+ width:
+ depth:
price:
- id: price_gbHJdmfrXB
- amount: '19.99'
- amount_in_cents: 1999
+ id: price_EfhxLZ9ck8
+ amount: '24.99'
+ amount_in_cents: 2499
compare_at_amount:
compare_at_amount_in_cents:
currency: USD
- display_amount: "$19.99"
+ display_amount: "$24.99"
display_compare_at_amount:
price_list_id:
- variant_id: variant_gbHJdmfrXB
- created_at: '2026-03-07T11:32:14.117Z'
- updated_at: '2026-03-07T11:32:14.117Z'
original_price:
- status: draft
- make_active_at:
- discontinue_on:
- meta_title:
- promotionable: true
- deleted_at:
- shipping_category_id: scat_gbHJdmfrXB
- tax_category_id:
+ option_values:
+ - id: optval_gbHJdmfrXB
+ option_type_id: opt_gbHJdmfrXB
+ name: xl
+ label: XL
+ position: 1
+ color_code:
+ option_type_name: size
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:50:14.818Z'
+ updated_at: '2026-04-29T10:50:14.818Z'
+ position: 3
+ total_on_hand: 0
+ tax_category_id: 1
cost_price:
cost_currency: USD
- schema:
- "$ref": "#/components/schemas/AdminProduct"
+ deleted_at:
+ created_at: '2026-04-29T10:50:14.822Z'
+ updated_at: '2026-04-29T10:50:14.823Z'
+ product_name: Product 501525
+ display_price: "$24.99"
'422':
description: validation error
content:
@@ -4137,9 +4012,9 @@ paths:
example:
error:
code: validation_error
- message: Name can't be blank
+ message: Option value variants can't be blank
details:
- name:
+ option_value_variants:
- can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
@@ -4149,89 +4024,96 @@ paths:
schema:
type: object
properties:
- name:
+ sku:
type: string
- example: Premium T-Shirt
+ example: SKU-001
price:
type: number
example: 29.99
- description:
- type: string
- slug:
- type: string
- status:
+ compare_at_price:
+ type: number
+ example: 39.99
+ cost_price:
+ type: number
+ example: 10.0
+ cost_currency:
type: string
- enum:
- - draft
- - active
- - archived
- sku:
+ example: USD
+ weight:
+ type: number
+ height:
+ type: number
+ width:
+ type: number
+ depth:
+ type: number
+ weight_unit:
type: string
- shipping_category_id:
+ dimensions_unit:
type: string
- description: Prefixed ID (e.g., sc_xxx) or integer
+ track_inventory:
+ type: boolean
tax_category_id:
type: string
- description: Prefixed ID or integer
- taxon_ids:
- type: array
- items:
- type: string
- description: Array of prefixed taxon IDs
- tags:
+ options:
type: array
+ description: Option types and values (auto-created if needed)
items:
- type: string
- example:
- - eco
- - sale
- variants:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Size
+ value:
+ type: string
+ example: Large
+ required:
+ - name
+ - value
+ total_on_hand:
+ type: integer
+ example: 100
+ position:
+ type: integer
+ barcode:
+ type: string
+ prices:
type: array
items:
type: object
properties:
- sku:
+ currency:
type: string
- price:
+ example: USD
+ amount:
type: number
- option_type:
- type: string
- example: Size
- option_value:
+ example: 29.99
+ compare_at_amount:
+ type: number
+ example: 39.99
+ required:
+ - currency
+ - amount
+ stock_items:
+ type: array
+ items:
+ type: object
+ properties:
+ stock_location_id:
type: string
- example: Small
- total_on_hand:
+ count_on_hand:
type: integer
- prices:
- type: array
- items:
- type: object
- properties:
- currency:
- type: string
- example: USD
- amount:
- type: number
- example: 29.99
- compare_at_amount:
- type: number
- example: 39.99
- required:
- - currency
- - amount
- required:
- - name
- - price
- - shipping_category_id
- "/api/v3/admin/products/{id}":
+ backorderable:
+ type: boolean
+ "/api/v3/admin/products/{product_id}/variants/{id}":
get:
- summary: Get a product
+ summary: Get a variant
tags:
- - Products
+ - Variants
security:
- api_key: []
bearer_auth: []
- description: Returns a single product by prefixed ID.
+ description: Returns a single variant by prefixed ID.
parameters:
- name: x-spree-api-key
in: header
@@ -4244,46 +4126,47 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
+ - name: product_id
+ in: path
+ required: true
+ description: Product prefixed ID
+ schema:
+ type: string
- name: id
in: path
required: true
- description: Product prefixed ID (e.g., prod_xxx)
+ description: Variant prefixed ID
schema:
type: string
- name: expand
in: query
required: false
- description: Comma-separated associations to expand (e.g., variants)
+ description: Comma-separated associations to expand (e.g., images, prices,
+ stock_items)
schema:
type: string
responses:
'200':
- description: product found
+ description: variant found
content:
application/json:
example:
- id: prod_UkLWZg9DAJ
- name: Product 358866
- description: |-
- Dolor suscipit debitis dolorum fugiat dicta assumenda ratione ab. Quis ea eveniet debitis dolorem animi sed earum qui. Fuga ad at tempora voluptate nihil labore velit quos. Doloremque est vero labore quam doloribus.
- Earum sed dolore nostrum facere commodi eligendi ad. Vel in necessitatibus occaecati neque laboriosam facere asperiores sint. Nemo aperiam occaecati autem ducimus consequatur numquam nostrum.
- Suscipit enim beatae repudiandae ex sed sunt aliquid. Deserunt explicabo corporis quo omnis aspernatur. Beatae accusantium recusandae doloribus enim quo quis tempora. Voluptates similique accusamus quos laudantium nesciunt laboriosam commodi eligendi. Facilis tempore temporibus sit illo.
- slug: product-358866
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on: '2025-03-07T11:32:14.487Z'
- created_at: '2026-03-07T11:32:14.502Z'
- updated_at: '2026-03-07T11:32:14.516Z'
+ id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-67
+ options_text: 'Size: S'
+ track_inventory: true
+ media_count: 0
+ thumbnail_url:
purchasable: true
in_stock: false
backorderable: true
- available: true
- default_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
+ weight: 150.52
+ height: 82.94
+ width: 93.3
+ depth: 16.86
price:
- id: price_UkLWZg9DAJ
+ id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
compare_at_amount:
@@ -4292,42 +4175,47 @@ paths:
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-03-07T11:32:14.504Z'
- updated_at: '2026-03-07T11:32:14.504Z'
original_price:
- status: active
- make_active_at: '2025-03-07T11:32:14.487Z'
- discontinue_on:
- meta_title:
- promotionable: true
- deleted_at:
- shipping_category_id: scat_UkLWZg9DAJ
- tax_category_id: taxcat_UkLWZg9DAJ
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-15
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-24
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:50:15.207Z'
+ updated_at: '2026-04-29T10:50:15.207Z'
+ position: 2
+ total_on_hand: 0
+ tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
- schema:
- "$ref": "#/components/schemas/AdminProduct"
+ deleted_at:
+ created_at: '2026-04-29T10:50:15.205Z'
+ updated_at: '2026-04-29T10:50:15.216Z'
+ product_name: Product 527565
+ display_price: "$19.99"
'404':
- description: product not found
+ description: variant not found
content:
application/json:
example:
error:
- code: record_not_found
- message: Couldn't find Spree::Product with 'id'=245546638656678833
- [WHERE "spree_products"."deleted_at" IS NULL AND "spree_products_stores"."store_id"
- = ?]
+ code: variant_not_found
+ message: Variant not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a product
+ summary: Update a variant
tags:
- - Products
+ - Variants
security:
- api_key: []
bearer_auth: []
- description: Updates a product. Only provided fields are updated.
+ description: Updates a variant. Only provided fields are updated.
parameters:
- name: x-spree-api-key
in: header
@@ -4340,41 +4228,40 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - name: product_id
in: path
required: true
description: Product prefixed ID
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Variant prefixed ID
+ schema:
+ type: string
responses:
'200':
- description: product updated
+ description: variant updated
content:
application/json:
example:
- id: prod_UkLWZg9DAJ
- name: Updated Name
- description: |-
- Quibusdam veritatis aperiam officiis vero debitis. Assumenda impedit amet occaecati qui. Repellat amet facere quam vitae nisi. Recusandae quam minima similique minus doloremque nihil id.
- Mollitia voluptates sit asperiores soluta dolore quibusdam sequi officia. Sit repellendus commodi beatae laudantium temporibus quia ipsam. Doloremque at eum earum enim numquam quas nemo. Impedit voluptas dolor est illo. Fugit iste expedita placeat sapiente neque nostrum.
- Aspernatur quis saepe tempore dolores magnam. Numquam nisi voluptate optio quisquam. Dolores quae nobis amet ea alias.
- Voluptatem debitis necessitatibus nobis voluptas et facilis minus. Maiores rem fuga officia mollitia. Similique veritatis aliquid voluptate debitis doloribus ea animi. Perferendis exercitationem eum consequuntur quae expedita.
- slug: product-374144
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on: '2025-03-07T11:32:15.139Z'
- created_at: '2026-03-07T11:32:15.152Z'
- updated_at: '2026-03-07T11:32:15.480Z'
- purchasable: true
- in_stock: false
- backorderable: true
- available: true
- default_variant_id: variant_UkLWZg9DAJ
+ id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: UPDATED-SKU
+ options_text: 'Size: S'
+ track_inventory: true
+ media_count: 0
thumbnail_url:
- tags: []
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ weight: 39.23
+ height: 1.27
+ width: 7.62
+ depth: 169.62
price:
- id: price_UkLWZg9DAJ
+ id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
compare_at_amount:
@@ -4383,119 +4270,120 @@ paths:
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-03-07T11:32:15.154Z'
- updated_at: '2026-03-07T11:32:15.154Z'
original_price:
- status: active
- make_active_at: '2025-03-07T11:32:15.139Z'
- discontinue_on:
- meta_title:
- promotionable: true
- deleted_at:
- shipping_category_id: scat_UkLWZg9DAJ
- tax_category_id: taxcat_UkLWZg9DAJ
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-17
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-26
+ option_type_label: Size
+ image_url:
+ created_at: '2026-04-29T10:50:15.903Z'
+ updated_at: '2026-04-29T10:50:15.903Z'
+ position: 2
+ total_on_hand: 0
+ tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
- schema:
- "$ref": "#/components/schemas/AdminProduct"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ deleted_at:
+ created_at: '2026-04-29T10:50:15.900Z'
+ updated_at: '2026-04-29T10:50:16.194Z'
+ product_name: Product 545252
+ display_price: "$19.99"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ sku:
type: string
- example: Premium T-Shirt
+ example: SKU-001
price:
type: number
example: 29.99
- description:
- type: string
- slug:
- type: string
- status:
+ compare_at_price:
+ type: number
+ example: 39.99
+ cost_price:
+ type: number
+ example: 10.0
+ cost_currency:
type: string
- enum:
- - draft
- - active
- - archived
- sku:
+ example: USD
+ weight:
+ type: number
+ height:
+ type: number
+ width:
+ type: number
+ depth:
+ type: number
+ weight_unit:
type: string
- shipping_category_id:
+ dimensions_unit:
type: string
- description: Prefixed ID (e.g., sc_xxx) or integer
+ track_inventory:
+ type: boolean
tax_category_id:
type: string
- description: Prefixed ID or integer
- taxon_ids:
- type: array
- items:
- type: string
- description: Array of prefixed taxon IDs
- tags:
+ options:
type: array
items:
- type: string
- example:
- - eco
- - sale
- variants:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Size
+ value:
+ type: string
+ example: Large
+ total_on_hand:
+ type: integer
+ example: 100
+ position:
+ type: integer
+ barcode:
+ type: string
+ prices:
type: array
items:
type: object
properties:
- sku:
+ currency:
type: string
- price:
+ example: USD
+ amount:
type: number
- option_type:
- type: string
- example: Size
- option_value:
+ example: 29.99
+ compare_at_amount:
+ type: number
+ example: 39.99
+ required:
+ - currency
+ - amount
+ stock_items:
+ type: array
+ items:
+ type: object
+ properties:
+ stock_location_id:
type: string
- example: Small
- total_on_hand:
+ count_on_hand:
type: integer
- prices:
- type: array
- items:
- type: object
- properties:
- currency:
- type: string
- example: USD
- amount:
- type: number
- example: 29.99
- compare_at_amount:
- type: number
- example: 39.99
- required:
- - currency
- - amount
+ backorderable:
+ type: boolean
delete:
- summary: Delete a product
+ summary: Delete a variant
tags:
- - Products
+ - Variants
security:
- api_key: []
bearer_auth: []
- description: Soft-deletes a product.
+ description: Soft-deletes a variant.
parameters:
- name: x-spree-api-key
in: header
@@ -4508,2221 +4396,680 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - name: product_id
in: path
required: true
description: Product prefixed ID
schema:
type: string
- responses:
- '204':
- description: product deleted
- "/api/v3/admin/taxonomies":
- get:
- summary: List taxonomies
- tags:
- - Taxonomies
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a paginated list of taxonomies for the current store.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
+ - name: id
+ in: path
required: true
- description: Bearer token for admin authentication
+ description: Variant prefixed ID
schema:
type: string
- - name: page
- in: query
- required: false
- description: Page number
- schema:
+ responses:
+ '204':
+ description: variant deleted
+servers:
+- url: http://{defaultHost}
+ variables:
+ defaultHost:
+ default: localhost:3000
+tags:
+- name: Authentication
+ description: Admin user authentication
+- name: Products
+ description: Product management
+- name: Variants
+ description: Product variant management
+- name: Option Types
+ description: Option type and value management
+- name: Prices
+ description: Variant price management
+- name: Orders
+ description: Order management — list, create, update, items, complete, cancel, approve
+- name: Payments
+ description: Order payment management — capture, void, off-session charges
+- name: Refunds
+ description: Order refund management
+- name: Fulfillments
+ description: Order fulfillment management — ship, cancel, split
+- name: Order Gift Cards
+ description: Apply / remove gift cards on an order
+- name: Order Store Credits
+ description: Apply / remove customer store credit on an order
+x-tagGroups:
+- name: Authentication
+ tags:
+ - Authentication
+- name: Catalog
+ tags:
+ - Products
+ - Variants
+ - Prices
+- name: Options
+ tags:
+ - Option Types
+- name: Orders
+ tags:
+ - Orders
+ - Payments
+ - Refunds
+ - Fulfillments
+ - Order Gift Cards
+ - Order Store Credits
+components:
+ securitySchemes:
+ api_key:
+ type: apiKey
+ name: x-spree-api-key
+ in: header
+ description: Secret API key for admin access
+ bearer_auth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ description: JWT token for admin user authentication
+ schemas:
+ PaginationMeta:
+ type: object
+ properties:
+ page:
type: integer
- - name: limit
- in: query
- required: false
- description: Number of records per page
- schema:
+ example: 1
+ limit:
type: integer
- responses:
- '200':
- description: taxonomies found
- content:
- application/json:
- example:
- data:
- - id: txnmy_UkLWZg9DAJ
- name: Categories
- position: 1
- created_at: '2026-03-07T11:31:41.908Z'
- updated_at: '2026-03-07T11:31:41.929Z'
- root_id: txn_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- - id: txnmy_gbHJdmfrXB
- name: Brands
- position: 2
- created_at: '2026-03-07T11:31:41.931Z'
- updated_at: '2026-03-07T11:31:41.940Z'
- root_id: txn_gbHJdmfrXB
- store_id: store_UkLWZg9DAJ
- - id: txnmy_EfhxLZ9ck8
- name: Collections
- position: 3
- created_at: '2026-03-07T11:31:41.942Z'
- updated_at: '2026-03-07T11:31:41.999Z'
- root_id: txn_EfhxLZ9ck8
- store_id: store_UkLWZg9DAJ
- - id: txnmy_VqXmZF31wY
- name: taxonomy_1
- position: 4
- created_at: '2026-03-07T11:32:16.258Z'
- updated_at: '2026-03-07T11:32:16.268Z'
- root_id: txn_OIJLhNcSbf
- store_id: store_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 4
- pages: 1
- from: 1
- to: 4
- in: 4
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/AdminTaxonomy"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized
- content:
- application/json:
+ example: 25
+ count:
+ type: integer
+ example: 100
+ description: Total number of records
+ pages:
+ type: integer
+ example: 4
+ description: Total number of pages
+ from:
+ type: integer
+ example: 1
+ description: Index of first record on this page
+ to:
+ type: integer
+ example: 25
+ description: Index of last record on this page
+ in:
+ type: integer
+ example: 25
+ description: Number of records on this page
+ previous:
+ type: integer
+ nullable: true
+ example:
+ description: Previous page number
+ next:
+ type: integer
+ nullable: true
+ example: 2
+ description: Next page number
+ required:
+ - page
+ - limit
+ - count
+ - pages
+ - from
+ - to
+ - in
+ ErrorResponse:
+ type: object
+ properties:
+ error:
+ type: object
+ properties:
+ code:
+ type: string
+ example: record_not_found
+ message:
+ type: string
+ example: Record not found
+ details:
+ type: object
+ description: Field-specific validation errors
+ nullable: true
example:
- error:
- code: invalid_token
- message: Valid secret API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a taxonomy
- tags:
- - Taxonomies
- security:
- - api_key: []
- bearer_auth: []
- description: Creates a new taxonomy.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ name:
+ - is too short
+ - is required
+ email:
+ - is invalid
+ required:
+ - code
+ - message
+ required:
+ - error
+ example:
+ error:
+ code: validation_error
+ message: Validation failed
+ details:
+ name:
+ - is too short
+ email:
+ - is invalid
+ AuthResponse:
+ type: object
+ properties:
+ token:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ description: JWT access token
+ refresh_token:
type: string
- responses:
- '201':
- description: taxonomy created
- content:
- application/json:
- example:
- id: txnmy_uw2YK1rnl0
- name: New Taxonomy
- position: 5
- created_at: '2026-03-07T11:32:17.147Z'
- updated_at: '2026-03-07T11:32:17.156Z'
- root_id: txn_AXs1igzRC6
- store_id: store_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/AdminTaxonomy"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Categories
- position:
- type: integer
- example: 1
- required:
- - name
- "/api/v3/admin/taxonomies/{id}":
- get:
- summary: Get a taxonomy
- tags:
- - Taxonomies
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a single taxonomy by prefixed ID.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ description: Refresh token for obtaining new access tokens
+ user:
+ "$ref": "#/components/schemas/AdminUser"
+ required:
+ - token
+ - refresh_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
+ CheckoutRequirement:
+ type: object
+ properties:
+ step:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ description: Checkout step this requirement belongs to
+ example: payment
+ field:
type: string
- - name: id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
+ description: Field that needs to be satisfied
+ example: payment
+ message:
type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., root, taxons)
- schema:
+ description: Human-readable requirement message
+ example: Add a payment method
+ 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
- responses:
- '200':
- description: taxonomy found
- content:
- application/json:
- example:
- id: txnmy_VqXmZF31wY
- name: taxonomy_5
- position: 4
- created_at: '2026-03-07T11:32:17.459Z'
- updated_at: '2026-03-07T11:32:17.466Z'
- root_id: txn_OIJLhNcSbf
- store_id: store_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/AdminTaxonomy"
- '404':
- description: taxonomy not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Couldn't find Spree::Taxonomy with 'id'=245546638656678833
- [WHERE "spree_taxonomies"."store_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a taxonomy
- tags:
- - Taxonomies
- security:
- - api_key: []
- bearer_auth: []
- description: Updates a taxonomy. Only provided fields are updated.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ description: Machine-readable warning code
+ example: line_item_removed
+ message:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ description: Human-readable warning message
+ example: Blue T-Shirt was removed because it was sold out
+ line_item_id:
type: string
- - name: id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
+ nullable: true
+ description: Prefixed line item ID (when applicable)
+ example: li_abc123
+ variant_id:
type: string
- responses:
- '200':
- description: taxonomy updated
- content:
- application/json:
- example:
- id: txnmy_VqXmZF31wY
- name: Updated Taxonomy
- position: 4
- created_at: '2026-03-07T11:32:18.050Z'
- updated_at: '2026-03-07T11:32:18.346Z'
- root_id: txn_OIJLhNcSbf
- store_id: store_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/AdminTaxonomy"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Categories
- position:
- type: integer
- example: 1
- delete:
- summary: Delete a taxonomy
- tags:
- - Taxonomies
- security:
- - api_key: []
- bearer_auth: []
- description: Deletes a taxonomy.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ nullable: true
+ description: Prefixed variant ID (when applicable)
+ example: variant_abc123
+ 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
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ description: Line item prefixed ID
+ example: li_abc123
+ variant_id:
type: string
- - name: id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
+ description: Variant prefixed ID
+ example: variant_abc123
+ quantity:
+ type: integer
+ description: Quantity in this fulfillment
+ example: 2
+ required:
+ - item_id
+ - variant_id
+ - quantity
+ Address:
+ type: object
+ properties:
+ id:
type: string
- responses:
- '204':
- description: taxonomy deleted
- "/api/v3/admin/taxons":
- get:
- summary: List taxons
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a flat, paginated list of all taxons for the current store.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ first_name:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ nullable: true
+ last_name:
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:
+ nullable: true
+ full_name:
type: string
- responses:
- '200':
- description: taxons found
- content:
- application/json:
- example:
- data:
- - id: txn_UkLWZg9DAJ
- name: Categories
- permalink: categories
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:31:41.919Z'
- updated_at: '2026-03-07T11:31:41.927Z'
- parent_id:
- taxonomy_id: txnmy_UkLWZg9DAJ
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: true
- lft: 1
- rgt: 2
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- - id: txn_gbHJdmfrXB
- name: Brands
- permalink: brands
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:31:41.934Z'
- updated_at: '2026-03-07T11:31:41.939Z'
- parent_id:
- taxonomy_id: txnmy_gbHJdmfrXB
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: true
- lft: 3
- rgt: 4
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- - id: txn_EfhxLZ9ck8
- name: Collections
- permalink: collections
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 2
- created_at: '2026-03-07T11:31:41.944Z'
- updated_at: '2026-03-07T11:31:41.999Z'
- parent_id:
- taxonomy_id: txnmy_EfhxLZ9ck8
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: false
- lft: 5
- rgt: 10
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- - id: txn_VqXmZF31wY
- name: On sale
- permalink: collections/on-sale
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:31:41.956Z'
- updated_at: '2026-03-07T11:31:41.958Z'
- parent_id: txn_EfhxLZ9ck8
- taxonomy_id: txnmy_EfhxLZ9ck8
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 6
- rgt: 7
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: true
- - id: txn_uw2YK1rnl0
- name: New arrivals
- permalink: collections/new-arrivals
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:31:41.968Z'
- updated_at: '2026-03-07T11:31:41.970Z'
- parent_id: txn_EfhxLZ9ck8
- taxonomy_id: txnmy_EfhxLZ9ck8
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 8
- rgt: 9
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: true
- - id: txn_OIJLhNcSbf
- name: taxonomy_10
- permalink: taxonomy-10
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-07T11:32:18.961Z'
- updated_at: '2026-03-07T11:32:18.984Z'
- parent_id:
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: false
- lft: 11
- rgt: 14
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- - id: txn_AXs1igzRC6
- name: taxon_1
- permalink: taxonomy-10/taxon-1
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:32:18.970Z'
- updated_at: '2026-03-07T11:32:18.982Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 12
- rgt: 13
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- meta:
- page: 1
- limit: 25
- count: 7
- pages: 1
- from: 1
- to: 7
- in: 7
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/AdminTaxon"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid secret API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/taxons/{id}":
- get:
- summary: Get a taxon
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a single taxon by prefixed ID.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ address1:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ nullable: true
+ address2:
type: string
- - name: id
- in: path
- required: true
- description: Taxon prefixed ID
- schema:
+ nullable: true
+ postal_code:
type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., parent, children,
- ancestors)
- schema:
+ nullable: true
+ city:
type: string
- responses:
- '200':
- description: taxon found
- content:
- application/json:
- example:
- id: txn_AXs1igzRC6
- name: taxon_3
- permalink: taxonomy-12/taxon-3
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:32:19.607Z'
- updated_at: '2026-03-07T11:32:19.613Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 12
- rgt: 13
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- schema:
- "$ref": "#/components/schemas/AdminTaxon"
- '404':
- description: taxon not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Couldn't find Spree::Taxon with 'id'=245546638656678833
- [WHERE "spree_taxonomies"."store_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/taxonomies/{taxonomy_id}/taxons":
- get:
- summary: List taxonomy taxons
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a paginated list of taxons belonging to a taxonomy.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ nullable: true
+ phone:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ nullable: true
+ company:
type: string
- - name: taxonomy_id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
+ nullable: true
+ country_name:
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: taxons found
- content:
- application/json:
- example:
- data:
- - id: txn_OIJLhNcSbf
- name: taxonomy_14
- permalink: taxonomy-14
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-07T11:32:20.215Z'
- updated_at: '2026-03-07T11:32:20.230Z'
- parent_id:
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: false
- lft: 11
- rgt: 14
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- - id: txn_AXs1igzRC6
- name: taxon_5
- permalink: taxonomy-14/taxon-5
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:32:20.223Z'
- updated_at: '2026-03-07T11:32:20.229Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 12
- rgt: 13
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- meta:
- page: 1
- limit: 25
- count: 2
- pages: 1
- from: 1
- to: 2
- in: 2
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/AdminTaxon"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- post:
- summary: Create a taxon
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Creates a new taxon within a taxonomy.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ country_iso:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ state_text:
type: string
- - name: taxonomy_id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
+ nullable: true
+ state_abbr:
type: string
- responses:
- '201':
- description: taxon created
- content:
- application/json:
- example:
- id: txn_p6klVeMgbn
- name: New Taxon
- permalink: taxonomy-15/new-taxon
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:32:20.825Z'
- updated_at: '2026-03-07T11:32:20.832Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 14
- rgt: 15
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- schema:
- "$ref": "#/components/schemas/AdminTaxon"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank and Root conflict this taxonomy already
- has a root taxon
- details:
- name:
- - can't be blank
- root_conflict:
- - this taxonomy already has a root taxon
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: T-Shirts
- parent_id:
- type: string
- description: Parent taxon prefixed ID
- position:
- type: integer
- description:
- type: string
- permalink:
- type: string
- meta_title:
- type: string
- meta_description:
- type: string
- meta_keywords:
- type: string
- hide_from_nav:
- type: boolean
- sort_order:
- type: string
- example: manual
- required:
- - name
- "/api/v3/admin/taxonomies/{taxonomy_id}/taxons/{id}":
- get:
- summary: Get a taxonomy taxon
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a single taxon within a taxonomy.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: taxonomy_id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Taxon prefixed ID
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., parent, children,
- ancestors)
- schema:
- type: string
- responses:
- '200':
- description: taxon found
- content:
- application/json:
- example:
- id: txn_AXs1igzRC6
- name: taxon_8
- permalink: taxonomy-17/taxon-8
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:32:21.154Z'
- updated_at: '2026-03-07T11:32:21.159Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 12
- rgt: 13
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- schema:
- "$ref": "#/components/schemas/AdminTaxon"
- '404':
- description: taxon not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Couldn't find Spree::Taxon with 'id'=245546638656678833
- [WHERE "spree_taxons"."taxonomy_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a taxon
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Updates a taxon within a taxonomy. Only provided fields are updated.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: taxonomy_id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Taxon prefixed ID
- schema:
- type: string
- responses:
- '200':
- description: taxon updated
- content:
- application/json:
- example:
- id: txn_AXs1igzRC6
- name: Updated Taxon
- permalink: taxonomy-19/taxon-10
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-07T11:32:21.782Z'
- updated_at: '2026-03-07T11:32:22.074Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- lft: 12
- rgt: 13
- hide_from_nav: false
- sort_order: manual
- rules_match_policy: all
- automatic: false
- schema:
- "$ref": "#/components/schemas/AdminTaxon"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: T-Shirts
- parent_id:
- type: string
- description: Parent taxon prefixed ID
- position:
- type: integer
- description:
- type: string
- permalink:
- type: string
- meta_title:
- type: string
- meta_description:
- type: string
- meta_keywords:
- type: string
- hide_from_nav:
- type: boolean
- sort_order:
- type: string
- example: manual
- delete:
- summary: Delete a taxon
- tags:
- - Taxons
- security:
- - api_key: []
- bearer_auth: []
- description: Deletes a taxon from a taxonomy.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: taxonomy_id
- in: path
- required: true
- description: Taxonomy prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Taxon prefixed ID
- schema:
- type: string
- responses:
- '204':
- description: taxon deleted
- "/api/v3/admin/products/{product_id}/variants/{variant_id}/assets":
- get:
- summary: List variant assets
- tags:
- - Variant Assets
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a paginated list of assets (images) for a variant.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- - name: variant_id
- in: path
- required: true
- description: Variant prefixed 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
- responses:
- '200':
- description: variant assets found
- content:
- application/json:
- example:
- data:
- - id: asset_UkLWZg9DAJ
- viewable_id: variant_gbHJdmfrXB
- type:
- viewable_type: Spree::Variant
- position: 1
- alt:
- created_at: '2026-03-07T11:32:22.752Z'
- updated_at: '2026-03-07T11:32:22.755Z'
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- post:
- summary: Create a variant asset
- tags:
- - Variant Assets
- security:
- - api_key: []
- bearer_auth: []
- description: Creates a new asset (image) for a variant.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- - name: variant_id
- in: path
- required: true
- description: Variant prefixed ID
- schema:
- type: string
- responses:
- '202':
- description: variant asset import from URL enqueued
- '422':
- description: validation error (attachment required)
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Attachment can't be blank
- details:
- attachment:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- alt:
- type: string
- example: Variant image
- position:
- type: integer
- example: 1
- type:
- type: string
- example: Spree::Image
- description: Asset type (defaults to Spree::Image)
- url:
- type: string
- example: https://example.com/image.jpg
- description: External URL to import image from (async). Returns
- 202 Accepted.
- "/api/v3/admin/products/{product_id}/variants/{variant_id}/assets/{id}":
- patch:
- summary: Update a variant asset
- tags:
- - Variant Assets
- security:
- - api_key: []
- bearer_auth: []
- description: Updates a variant asset. Only provided fields are updated.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- - name: variant_id
- in: path
- required: true
- description: Variant prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Asset prefixed ID
- schema:
- type: string
- responses:
- '200':
- description: variant asset updated
- content:
- application/json:
- example:
- id: asset_UkLWZg9DAJ
- viewable_id: variant_gbHJdmfrXB
- type:
- viewable_type: Spree::Variant
- position: 1
- alt: Updated variant image
- created_at: '2026-03-07T11:32:23.817Z'
- updated_at: '2026-03-07T11:32:24.112Z'
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- alt:
- type: string
- example: Updated variant image
- position:
- type: integer
- example: 2
- delete:
- summary: Delete a variant asset
- tags:
- - Variant Assets
- security:
- - api_key: []
- bearer_auth: []
- description: Deletes an asset from a variant.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- - name: variant_id
- in: path
- required: true
- description: Variant prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Asset prefixed ID
- schema:
- type: string
- responses:
- '204':
- description: variant asset 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
- master variant.
- parameters:
- - name: x-spree-api-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 prefixed 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)
- schema:
- type: string
- responses:
- '200':
- description: variants found
- content:
- application/json:
- example:
- data:
- - id: variant_UkLWZg9DAJ
- product_id: prod_UkLWZg9DAJ
- sku: SKU-56
- is_master: true
- options_text: ''
- track_inventory: true
- image_count: 0
- created_at: '2026-03-07T11:32:24.497Z'
- updated_at: '2026-03-07T11:32:24.517Z'
- thumbnail:
- purchasable: false
- in_stock: false
- backorderable: false
- weight: 0.0
- height:
- width:
- depth:
- price:
- id:
- amount:
- amount_in_cents: 0
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$0.00"
- display_compare_at_amount:
- price_list_id:
- variant_id: variant_UkLWZg9DAJ
- created_at:
- updated_at:
- original_price:
- option_values: []
- position: 1
- tax_category_id: 1
- cost_price: '17.0'
- cost_currency: USD
- barcode:
- weight_unit: lb
- dimensions_unit:
- deleted_at:
- discontinue_on:
- total_on_hand: 0
- - id: variant_gbHJdmfrXB
- product_id: prod_UkLWZg9DAJ
- sku: SKU-57
- is_master: false
- options_text: 'Size: S'
- track_inventory: true
- image_count: 0
- created_at: '2026-03-07T11:32:24.534Z'
- updated_at: '2026-03-07T11:32:24.553Z'
- thumbnail:
- purchasable: true
- in_stock: false
- backorderable: true
- weight: 150.88
- height: 30.39
- width: 128.66
- depth: 67.13
- price:
- id: price_gbHJdmfrXB
- 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_gbHJdmfrXB
- created_at: '2026-03-07T11:32:24.535Z'
- updated_at: '2026-03-07T11:32:24.535Z'
- original_price:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-12
- presentation: S
- position: 1
- option_type_name: foo-size-21
- option_type_presentation: Size
- created_at: '2026-03-07T11:32:24.540Z'
- updated_at: '2026-03-07T11:32:24.540Z'
- position: 2
- tax_category_id: 1
- cost_price: '17.0'
- cost_currency: USD
- barcode:
- weight_unit: lb
- dimensions_unit:
- deleted_at:
- discontinue_on:
- total_on_hand: 0
- meta:
- page: 1
- limit: 25
- count: 2
- pages: 1
- from: 1
- to: 2
- in: 2
- previous:
- next:
- 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.
-
- Option types and values are auto-created if they don't exist.
- Prices are upserted by currency. Stock items are upserted by stock location.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- responses:
- '201':
- description: variant created
- content:
- application/json:
- example:
- id: variant_EfhxLZ9ck8
- product_id: prod_UkLWZg9DAJ
- sku: NEW-SKU-001
- is_master: false
- options_text: 'Size: XL'
- track_inventory: true
- image_count: 0
- created_at: '2026-03-07T11:32:25.277Z'
- updated_at: '2026-03-07T11:32:25.280Z'
- thumbnail:
- purchasable: false
- in_stock: false
- backorderable: false
- weight: 0.0
- height:
- width:
- depth:
- price:
- id: price_EfhxLZ9ck8
- amount: '24.99'
- amount_in_cents: 2499
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$24.99"
- display_compare_at_amount:
- price_list_id:
- variant_id: variant_EfhxLZ9ck8
- created_at: '2026-03-07T11:32:25.279Z'
- updated_at: '2026-03-07T11:32:25.279Z'
- original_price:
- option_values:
- - id: optval_gbHJdmfrXB
- option_type_id: opt_gbHJdmfrXB
- name: xl
- presentation: XL
- position: 1
- option_type_name: size
- option_type_presentation: Size
- created_at: '2026-03-07T11:32:25.273Z'
- updated_at: '2026-03-07T11:32:25.273Z'
- position: 3
- tax_category_id: 1
- cost_price:
- cost_currency: USD
- barcode:
- weight_unit: lb
- dimensions_unit:
- deleted_at:
- discontinue_on:
- total_on_hand: 0
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Option value variants can't be blank
- details:
- option_value_variants:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- sku:
- type: string
- example: SKU-001
- price:
- type: number
- example: 29.99
- compare_at_price:
- type: number
- example: 39.99
- cost_price:
- type: number
- example: 10.0
- cost_currency:
- type: string
- example: USD
- 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
- option_type:
- type: string
- example: Size
- description: Option type name (auto-created if needed)
- option_value:
- type: string
- example: Large
- description: Option value name (auto-created if needed)
- total_on_hand:
- type: integer
- example: 100
- position:
- type: integer
- barcode:
- type: string
- prices:
- type: array
- items:
- type: object
- properties:
- currency:
- type: string
- example: USD
- amount:
- type: number
- example: 29.99
- compare_at_amount:
- type: number
- example: 39.99
- required:
- - currency
- - amount
- stock_items:
- type: array
- items:
- type: object
- properties:
- stock_location_id:
- type: string
- 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 prefixed ID.
- parameters:
- - name: x-spree-api-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 prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Variant prefixed ID
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., images, prices,
- stock_items)
- schema:
+ nullable: true
+ quick_checkout:
+ type: boolean
+ is_default_billing:
+ type: boolean
+ is_default_shipping:
+ type: boolean
+ state_name:
type: string
- responses:
- '200':
- description: variant found
- content:
- application/json:
- example:
- id: variant_gbHJdmfrXB
- product_id: prod_UkLWZg9DAJ
- sku: SKU-63
- is_master: false
- options_text: 'Size: S'
- track_inventory: true
- image_count: 0
- created_at: '2026-03-07T11:32:25.683Z'
- updated_at: '2026-03-07T11:32:25.693Z'
- thumbnail:
- purchasable: true
- in_stock: false
- backorderable: true
- weight: 43.27
- height: 73.76
- width: 121.26
- depth: 148.3
- price:
- id: price_gbHJdmfrXB
- 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_gbHJdmfrXB
- created_at: '2026-03-07T11:32:25.684Z'
- updated_at: '2026-03-07T11:32:25.684Z'
- original_price:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-15
- presentation: S
- position: 1
- option_type_name: foo-size-24
- option_type_presentation: Size
- created_at: '2026-03-07T11:32:25.687Z'
- updated_at: '2026-03-07T11:32:25.687Z'
- position: 2
- tax_category_id: 1
- cost_price: '17.0'
- cost_currency: USD
- barcode:
- weight_unit: lb
- dimensions_unit:
- deleted_at:
- discontinue_on:
- total_on_hand: 0
- '404':
- description: variant not found
- content:
- application/json:
- example:
- error:
- code: variant_not_found
- message: Couldn't find Spree::Variant with 'id'=245546638656678833
- [WHERE "spree_variants"."deleted_at" IS NULL AND "spree_variants"."product_id"
- = ?]
- 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.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ nullable: true
+ label:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ nullable: true
+ created_at:
type: string
- - name: product_id
- in: path
- required: true
- description: Product prefixed ID
- schema:
+ updated_at:
type: string
- - name: id
- in: path
- required: true
- description: Variant prefixed ID
- schema:
+ customer_id:
type: string
- responses:
- '200':
- description: variant updated
- content:
- application/json:
- example:
- id: variant_gbHJdmfrXB
- product_id: prod_UkLWZg9DAJ
- sku: UPDATED-SKU
- is_master: false
- options_text: 'Size: S'
- track_inventory: true
- image_count: 0
- created_at: '2026-03-07T11:32:26.385Z'
- updated_at: '2026-03-07T11:32:26.697Z'
- thumbnail:
- purchasable: true
- in_stock: false
- backorderable: true
- weight: 51.81
- height: 38.57
- width: 136.5
- depth: 87.66
- price:
- id: price_gbHJdmfrXB
- 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_gbHJdmfrXB
- created_at: '2026-03-07T11:32:26.386Z'
- updated_at: '2026-03-07T11:32:26.386Z'
- original_price:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-17
- presentation: S
- position: 1
- option_type_name: foo-size-26
- option_type_presentation: Size
- created_at: '2026-03-07T11:32:26.388Z'
- updated_at: '2026-03-07T11:32:26.388Z'
- position: 2
- tax_category_id: 1
- cost_price: '17.0'
- cost_currency: USD
- barcode:
- weight_unit: lb
- dimensions_unit:
- deleted_at:
- discontinue_on:
- total_on_hand: 0
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- sku:
- type: string
- example: SKU-001
- price:
- type: number
- example: 29.99
- compare_at_price:
- type: number
- example: 39.99
- cost_price:
- type: number
- example: 10.0
- cost_currency:
- type: string
- example: USD
- 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
- option_type:
- type: string
- example: Size
- option_value:
- type: string
- example: Large
- total_on_hand:
- type: integer
- example: 100
- position:
- type: integer
- barcode:
- type: string
- prices:
- type: array
- items:
- type: object
- properties:
- currency:
- type: string
- example: USD
- amount:
- type: number
- example: 29.99
- compare_at_amount:
- type: number
- example: 39.99
- required:
- - currency
- - amount
- stock_items:
- type: array
- items:
- type: object
- properties:
- stock_location_id:
- type: string
- 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.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
+ nullable: true
+ metadata:
+ type: object
+ 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
+ - created_at
+ - updated_at
+ - customer_id
+ - metadata
+ x-typelizer: true
+ Adjustment:
+ type: object
+ properties:
+ id:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
+ label:
type: string
- - name: product_id
- in: path
- required: true
- description: Product prefixed ID
- schema:
+ display_amount:
type: string
- - name: id
- in: path
- required: true
- description: Variant prefixed ID
- schema:
+ included:
+ type: boolean
+ created_at:
type: string
- responses:
- '204':
- description: variant deleted
-servers:
-- url: http://{defaultHost}
- variables:
- defaultHost:
- default: localhost:3000
-tags:
-- name: Authentication
- description: Admin user authentication
-- name: Products
- description: Product management
-- name: Variants
- description: Product variant management
-- name: Option Types
- description: Option type and value management
-- name: Taxonomies
- description: Taxonomy management
-- name: Taxons
- description: Taxon (category) management
-- name: Assets
- description: Product image and asset management
-- name: Prices
- description: Variant price management
-x-tagGroups:
-- name: Authentication
- tags:
- - Authentication
-- name: Catalog
- tags:
- - Products
- - Variants
- - Assets
- - Prices
-- name: Categories
- tags:
- - Taxonomies
- - Taxons
-- name: Options
- tags:
- - Option Types
-components:
- securitySchemes:
- api_key:
- type: apiKey
- name: x-spree-api-key
- in: header
- description: Secret API key for admin access
- bearer_auth:
- type: http
- scheme: bearer
- bearerFormat: JWT
- description: JWT token for admin user authentication
- schemas:
- PaginationMeta:
+ updated_at:
+ type: string
+ amount:
+ type: string
+ order_id:
+ type: string
+ nullable: true
+ required:
+ - id
+ - label
+ - display_amount
+ - included
+ - created_at
+ - updated_at
+ - amount
+ - order_id
+ x-typelizer: true
+ AdminUser:
type: object
properties:
- page:
- type: integer
- example: 1
- limit:
- type: integer
- example: 25
- count:
- type: integer
- example: 100
- description: Total number of records
- pages:
- type: integer
- example: 4
- description: Total number of pages
- from:
- type: integer
- example: 1
- description: Index of first record on this page
- to:
- type: integer
- example: 25
- description: Index of last record on this page
- in:
- type: integer
- example: 25
- description: Number of records on this page
- previous:
- type: integer
+ id:
+ type: string
+ email:
+ type: string
+ first_name:
+ type: string
nullable: true
- example:
- description: Previous page number
- next:
- type: integer
+ last_name:
+ type: string
nullable: true
- example: 2
- description: Next page number
+ created_at:
+ type: string
+ updated_at:
+ type: string
required:
- - page
- - limit
- - count
- - pages
- - from
- - to
- - in
- ErrorResponse:
+ - id
+ - email
+ - first_name
+ - last_name
+ - created_at
+ - updated_at
+ x-typelizer: true
+ AllowedOrigin:
type: object
properties:
- error:
+ id:
+ type: string
+ origin:
type: object
- properties:
- code:
- type: string
- example: record_not_found
- message:
- type: string
- example: Record not found
- details:
- type: object
- description: Field-specific validation errors
- nullable: true
- example:
- name:
- - is too short
- - is required
- email:
- - is invalid
- required:
- - code
- - message
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ store_id:
+ type: string
+ required:
+ - id
+ - origin
+ - created_at
+ - updated_at
+ - store_id
+ x-typelizer: true
+ Asset:
+ type: object
+ properties:
+ id:
+ type: string
+ viewable_id:
+ type: string
+ type:
+ type: string
+ nullable: true
+ viewable_type:
+ type: string
+ position:
+ type: number
+ nullable: true
+ alt:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - viewable_id
+ - type
+ - viewable_type
+ - position
+ - alt
+ - created_at
+ - updated_at
+ 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"
+ pretty_name:
+ type: string
+ lft:
+ type: number
+ rgt:
+ type: number
+ created_at:
+ type: string
+ updated_at:
+ type: string
required:
- - error
- example:
- error:
- code: validation_error
- message: Validation failed
- details:
- name:
- - is too short
- email:
- - is invalid
- AdminAuthResponse:
+ - 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
+ - pretty_name
+ - lft
+ - rgt
+ - created_at
+ - updated_at
+ x-typelizer: true
+ Country:
type: object
properties:
- token:
+ iso:
type: string
- description: JWT access token
- user:
- "$ref": "#/components/schemas/AdminAdminUser"
+ 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: object
+ updated_at:
+ type: object
required:
- - token
- - user
- AdminAdjustment:
+ - iso
+ - iso3
+ - name
+ - states_required
+ - zipcode_required
+ - created_at
+ - updated_at
+ x-typelizer: true
+ CreditCard:
type: object
properties:
id:
type: string
- amount:
+ brand:
type: string
- label:
+ last4:
+ type: string
+ month:
+ type: number
+ year:
+ type: number
+ name:
type: string
nullable: true
- eligible:
+ default:
type: boolean
- state:
+ gateway_payment_profile_id:
+ type: string
+ nullable: true
+ customer_id:
+ type: string
+ nullable: true
+ payment_method_id:
type: string
- included:
- type: boolean
- mandatory:
- type: boolean
nullable: true
created_at:
type: string
updated_at:
type: string
- source_type:
+ required:
+ - id
+ - brand
+ - last4
+ - month
+ - year
+ - name
+ - default
+ - gateway_payment_profile_id
+ - customer_id
+ - payment_method_id
+ - created_at
+ - updated_at
+ x-typelizer: true
+ CustomField:
+ type: object
+ properties:
+ id:
type: string
- nullable: true
- source_id:
+ label:
type: string
- nullable: true
- adjustable_type:
+ type:
type: string
- nullable: true
- adjustable_id:
+ key:
type: string
- nullable: true
- order_id:
+ value:
+ type: object
+ created_at:
type: string
- nullable: true
- order:
- "$ref": "#/components/schemas/AdminOrder"
+ updated_at:
+ type: string
+ storefront_visible:
+ type: boolean
required:
- id
- - amount
- label
- - eligible
- - state
- - included
- - mandatory
+ - type
+ - key
+ - value
- created_at
- updated_at
- - source_type
- - source_id
- - adjustable_type
- - adjustable_id
- - order_id
+ - storefront_visible
x-typelizer: true
- AdminAdminUser:
+ Customer:
type: object
properties:
id:
@@ -6735,188 +5082,385 @@ components:
last_name:
type: string
nullable: true
+ phone:
+ type: string
+ nullable: true
+ accepts_email_marketing:
+ type: boolean
+ 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
+ login:
+ type: string
+ nullable: true
+ last_sign_in_at:
+ type: string
+ nullable: true
+ current_sign_in_at:
+ type: string
+ nullable: true
created_at:
type: string
updated_at:
type: string
+ sign_in_count:
+ type: number
+ failed_attempts:
+ type: number
+ last_sign_in_ip:
+ type: string
+ nullable: true
+ current_sign_in_ip:
+ type: string
+ nullable: true
+ orders:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Order"
required:
- id
- email
- first_name
- last_name
+ - phone
+ - accepts_email_marketing
+ - available_store_credit_total
+ - display_available_store_credit_total
+ - login
+ - last_sign_in_at
+ - current_sign_in_at
+ - created_at
+ - updated_at
+ - sign_in_count
+ - failed_attempts
+ - last_sign_in_ip
+ - current_sign_in_ip
+ x-typelizer: true
+ DeliveryMethod:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ code:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - name
+ - code
+ - created_at
+ - updated_at
+ 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
+ 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"
+ 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
+ - display_cost
+ - display_total
+ - display_additional_tax_total
+ - display_included_tax_total
+ - display_tax_total
+ - created_at
+ - updated_at
+ 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
- AdminAsset:
+ Discount:
type: object
properties:
id:
type: string
- viewable_id:
+ promotion_id:
type: string
- type:
+ name:
type: string
- nullable: true
- viewable_type:
+ description:
type: string
- position:
- type: number
nullable: true
- alt:
+ code:
type: string
nullable: true
+ amount:
+ type: string
+ display_amount:
+ type: string
created_at:
type: string
updated_at:
type: string
required:
- id
- - viewable_id
- - type
- - viewable_type
- - position
- - alt
+ - promotion_id
+ - name
+ - description
+ - code
+ - amount
+ - display_amount
- created_at
- updated_at
x-typelizer: true
- AdminCustomer:
+ Fulfillment:
type: object
properties:
id:
type: string
- email:
+ number:
type: string
- first_name:
+ tracking:
type: string
nullable: true
- last_name:
+ tracking_url:
type: string
nullable: true
- created_at:
+ cost:
type: string
- updated_at:
+ display_cost:
type: string
- addresses:
+ 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
+ items:
type: array
items:
- "$ref": "#/components/schemas/StoreAddress"
- default_billing_address:
- allOf:
- - "$ref": "#/components/schemas/StoreAddress"
- nullable: true
- default_shipping_address:
- allOf:
- - "$ref": "#/components/schemas/StoreAddress"
- nullable: true
- phone:
+ "$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"
+ adjustment_total:
type: string
- nullable: true
- login:
+ pre_tax_amount:
type: string
- nullable: true
- accepts_email_marketing:
- type: boolean
- last_sign_in_at:
+ created_at:
type: string
- nullable: true
- current_sign_in_at:
+ updated_at:
type: string
+ metadata:
+ type: object
nullable: true
- sign_in_count:
- type: number
- failed_attempts:
- type: number
- last_sign_in_ip:
+ order_id:
type: string
nullable: true
- current_sign_in_ip:
+ stock_location_id:
type: string
nullable: true
- orders:
+ order:
+ "$ref": "#/components/schemas/Order"
+ adjustments:
type: array
items:
- "$ref": "#/components/schemas/AdminOrder"
+ "$ref": "#/components/schemas/Adjustment"
required:
- id
- - email
- - first_name
- - last_name
+ - number
+ - tracking
+ - tracking_url
+ - 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
+ - items
+ - adjustment_total
+ - pre_tax_amount
- created_at
- updated_at
- - addresses
- - default_billing_address
- - default_shipping_address
- - phone
- - login
- - accepts_email_marketing
- - last_sign_in_at
- - current_sign_in_at
- - sign_in_count
- - failed_attempts
- - last_sign_in_ip
- - current_sign_in_ip
+ - metadata
+ - order_id
+ - stock_location_id
x-typelizer: true
- AdminImage:
+ GiftCard:
type: object
properties:
id:
type: string
- viewable_id:
+ code:
type: string
- type:
+ status:
type: string
- nullable: true
- viewable_type:
+ currency:
type: string
- position:
- type: number
- nullable: true
- alt:
+ amount:
type: string
- nullable: true
- created_at:
+ amount_used:
type: string
- updated_at:
+ amount_authorized:
type: string
- original_url:
+ amount_remaining:
type: string
- nullable: true
- mini_url:
+ display_amount:
type: string
- nullable: true
- small_url:
+ display_amount_used:
type: string
- nullable: true
- medium_url:
+ display_amount_remaining:
type: string
- nullable: true
- large_url:
+ expires_at:
type: string
nullable: true
- xlarge_url:
+ redeemed_at:
type: string
nullable: true
- og_image_url:
+ expired:
+ type: boolean
+ active:
+ type: boolean
+ created_at:
+ type: string
+ updated_at:
type: string
- nullable: true
required:
- id
- - viewable_id
- - type
- - viewable_type
- - position
- - alt
+ - 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
- - original_url
- - mini_url
- - small_url
- - medium_url
- - large_url
- - xlarge_url
- - og_image_url
x-typelizer: true
- AdminLineItem:
+ LineItem:
type: object
properties:
id:
@@ -6953,9 +5497,9 @@ components:
type: string
display_included_tax_total:
type: string
- promo_total:
+ discount_total:
type: string
- display_promo_total:
+ display_discount_total:
type: string
pre_tax_amount:
type: string
@@ -6968,10 +5512,6 @@ components:
display_compare_at_amount:
type: string
nullable: true
- created_at:
- type: string
- updated_at:
- type: string
compare_at_amount:
type: string
nullable: true
@@ -6981,11 +5521,15 @@ components:
option_values:
type: array
items:
- "$ref": "#/components/schemas/StoreOptionValue"
+ "$ref": "#/components/schemas/OptionValue"
digital_links:
type: array
items:
- "$ref": "#/components/schemas/StoreDigitalLink"
+ "$ref": "#/components/schemas/DigitalLink"
+ created_at:
+ type: string
+ updated_at:
+ type: string
metadata:
type: object
nullable: true
@@ -6999,15 +5543,15 @@ components:
type: string
nullable: true
order:
- "$ref": "#/components/schemas/AdminOrder"
+ "$ref": "#/components/schemas/Order"
variant:
- "$ref": "#/components/schemas/AdminVariant"
+ "$ref": "#/components/schemas/Variant"
tax_category:
- "$ref": "#/components/schemas/AdminTaxCategory"
+ "$ref": "#/components/schemas/TaxCategory"
adjustments:
type: array
items:
- "$ref": "#/components/schemas/AdminAdjustment"
+ "$ref": "#/components/schemas/Adjustment"
required:
- id
- variant_id
@@ -7026,39 +5570,47 @@ components:
- display_additional_tax_total
- included_tax_total
- display_included_tax_total
- - promo_total
- - display_promo_total
+ - discount_total
+ - display_discount_total
- pre_tax_amount
- display_pre_tax_amount
- discounted_amount
- display_discounted_amount
- display_compare_at_amount
- - created_at
- - updated_at
- compare_at_amount
- thumbnail_url
- option_values
- digital_links
+ - created_at
+ - updated_at
- metadata
- cost_price
- tax_category_id
- order_id
x-typelizer: true
- AdminMetafield:
+ Market:
type: object
properties:
id:
type: string
name:
type: string
- type:
- type: string
- key:
+ currency:
type: string
- value:
- type: object
- display_on:
+ default_locale:
type: string
+ tax_inclusive:
+ type: boolean
+ default:
+ type: boolean
+ supported_locales:
+ type: array
+ items:
+ type: string
+ countries:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Country"
created_at:
type: string
updated_at:
@@ -7066,26 +5618,106 @@ components:
required:
- id
- name
- - type
- - key
- - value
- - display_on
+ - currency
+ - default_locale
+ - tax_inclusive
+ - default
+ - 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
+ 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
+ - viewable_type
x-typelizer: true
- AdminOptionType:
+ OptionType:
type: object
properties:
id:
type: string
name:
type: string
- presentation:
+ label:
type: string
position:
type: number
- filterable:
- type: boolean
+ kind:
+ type: string
created_at:
type: string
updated_at:
@@ -7093,22 +5725,18 @@ components:
option_values:
type: array
items:
- "$ref": "#/components/schemas/AdminOptionValue"
- metafields:
- type: array
- items:
- "$ref": "#/components/schemas/AdminMetafield"
+ "$ref": "#/components/schemas/OptionValue"
required:
- id
- name
- - presentation
+ - label
- position
- - filterable
+ - kind
- created_at
- updated_at
- option_values
x-typelizer: true
- AdminOptionValue:
+ OptionValue:
type: object
properties:
id:
@@ -7117,54 +5745,52 @@ components:
type: string
name:
type: string
- presentation:
+ label:
type: string
position:
type: number
+ color_code:
+ type: string
+ nullable: true
option_type_name:
type: string
- option_type_presentation:
+ option_type_label:
+ type: string
+ image_url:
type: string
+ nullable: true
created_at:
type: string
updated_at:
type: string
option_type:
- "$ref": "#/components/schemas/AdminOptionType"
- metafields:
- type: array
- items:
- "$ref": "#/components/schemas/AdminMetafield"
+ "$ref": "#/components/schemas/OptionType"
required:
- id
- option_type_id
- name
- - presentation
+ - label
- position
+ - color_code
- option_type_name
- - option_type_presentation
+ - option_type_label
+ - image_url
- created_at
- updated_at
x-typelizer: true
- AdminOrder:
+ Order:
type: object
properties:
id:
type: string
- number:
- type: string
- state:
+ market_id:
type: string
- checkout_steps:
- type: array
- items:
- type: string
- token:
+ nullable: true
+ number:
type: string
email:
type: string
- nullable: true
- special_instructions:
+ customer_note:
type: string
nullable: true
currency:
@@ -7172,31 +5798,19 @@ components:
locale:
type: string
nullable: true
- item_count:
- type: number
- state_lock_version:
+ total_quantity:
type: number
- shipment_state:
- type: string
- nullable: true
- payment_state:
- type: string
- nullable: true
item_total:
type: string
display_item_total:
type: string
- ship_total:
- type: string
- display_ship_total:
- type: string
adjustment_total:
type: string
display_adjustment_total:
type: string
- promo_total:
+ discount_total:
type: string
- display_promo_total:
+ display_discount_total:
type: string
tax_total:
type: string
@@ -7214,44 +5828,67 @@ components:
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
+ fulfillment_status:
+ type: string
+ nullable: true
+ payment_status:
+ type: string
+ nullable: true
completed_at:
type: string
nullable: true
- created_at:
+ store_credit_total:
type: string
- updated_at:
+ display_store_credit_total:
type: string
- order_promotions:
+ covered_by_store_credit:
+ type: boolean
+ discounts:
type: array
items:
- "$ref": "#/components/schemas/StoreOrderPromotion"
- line_items:
+ "$ref": "#/components/schemas/Discount"
+ items:
type: array
items:
- "$ref": "#/components/schemas/AdminLineItem"
- shipments:
+ "$ref": "#/components/schemas/LineItem"
+ fulfillments:
type: array
items:
- "$ref": "#/components/schemas/AdminShipment"
+ "$ref": "#/components/schemas/Fulfillment"
payments:
type: array
items:
- "$ref": "#/components/schemas/AdminPayment"
- bill_address:
+ "$ref": "#/components/schemas/Payment"
+ billing_address:
allOf:
- - "$ref": "#/components/schemas/StoreAddress"
+ - "$ref": "#/components/schemas/Address"
nullable: true
- ship_address:
+ shipping_address:
allOf:
- - "$ref": "#/components/schemas/StoreAddress"
+ - "$ref": "#/components/schemas/Address"
nullable: true
- payment_methods:
- type: array
- items:
- "$ref": "#/components/schemas/StorePaymentMethod"
- channel:
- type: string
+ 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
@@ -7261,9 +5898,6 @@ components:
type: boolean
store_owner_notification_delivered:
type: boolean
- internal_note:
- type: string
- nullable: true
payment_total:
type: string
display_payment_total:
@@ -7274,6 +5908,13 @@ components:
approved_at:
type: string
nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ internal_note:
+ type: string
+ nullable: true
metadata:
type: object
nullable: true
@@ -7286,51 +5927,48 @@ components:
created_by_id:
type: string
nullable: true
- user_id:
+ customer_id:
type: string
nullable: true
- user:
- "$ref": "#/components/schemas/AdminCustomer"
+ payment_methods:
+ type: array
+ items:
+ "$ref": "#/components/schemas/PaymentMethod"
+ customer:
+ "$ref": "#/components/schemas/Customer"
approver:
- "$ref": "#/components/schemas/AdminCustomer"
+ "$ref": "#/components/schemas/Customer"
canceler:
- "$ref": "#/components/schemas/AdminCustomer"
+ "$ref": "#/components/schemas/Customer"
created_by:
- "$ref": "#/components/schemas/AdminCustomer"
+ "$ref": "#/components/schemas/Customer"
adjustments:
type: array
items:
- "$ref": "#/components/schemas/AdminAdjustment"
+ "$ref": "#/components/schemas/Adjustment"
return_authorizations:
type: array
items:
- "$ref": "#/components/schemas/AdminReturnAuthorization"
+ "$ref": "#/components/schemas/ReturnAuthorization"
reimbursements:
type: array
items:
- "$ref": "#/components/schemas/AdminReimbursement"
+ "$ref": "#/components/schemas/Reimbursement"
required:
- id
+ - market_id
- number
- - state
- - checkout_steps
- - token
- email
- - special_instructions
+ - customer_note
- currency
- locale
- - item_count
- - state_lock_version
- - shipment_state
- - payment_state
+ - total_quantity
- item_total
- display_item_total
- - ship_total
- - display_ship_total
- adjustment_total
- display_adjustment_total
- - promo_total
- - display_promo_total
+ - discount_total
+ - display_discount_total
- tax_total
- display_tax_total
- included_tax_total
@@ -7339,40 +5977,78 @@ components:
- display_additional_tax_total
- total
- display_total
+ - gift_card_total
+ - display_gift_card_total
+ - amount_due
+ - display_amount_due
+ - delivery_total
+ - display_delivery_total
+ - fulfillment_status
+ - payment_status
- completed_at
- - created_at
- - updated_at
- - order_promotions
- - line_items
- - shipments
- - payments
- - bill_address
- - ship_address
- - payment_methods
- - channel
+ - 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
- - internal_note
- payment_total
- display_payment_total
- canceled_at
- approved_at
+ - created_at
+ - updated_at
+ - internal_note
- metadata
- approver_id
- canceler_id
- created_by_id
- - user_id
+ - customer_id
x-typelizer: true
- AdminPayment:
+ PaymentMethod:
type: object
properties:
id:
type: string
- payment_method_id:
+ name:
+ type: string
+ description:
+ type: string
+ nullable: true
+ type:
+ type: string
+ session_required:
+ type: boolean
+ active:
+ type: boolean
+ auto_capture:
+ type: boolean
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - name
+ - description
+ - type
+ - session_required
+ - active
+ - auto_capture
+ - created_at
+ - updated_at
+ x-typelizer: true
+ Payment:
+ type: object
+ properties:
+ id:
type: string
- state:
+ payment_method_id:
type: string
response_code:
type: string
@@ -7383,9 +6059,7 @@ components:
type: string
display_amount:
type: string
- created_at:
- type: string
- updated_at:
+ status:
type: string
source_type:
type: string
@@ -7399,12 +6073,12 @@ components:
nullable: true
source:
anyOf:
- - "$ref": "#/components/schemas/StoreCreditCard"
- - "$ref": "#/components/schemas/StoreStoreCredit"
- - "$ref": "#/components/schemas/StorePaymentSource"
+ - "$ref": "#/components/schemas/CreditCard"
+ - "$ref": "#/components/schemas/StoreCredit"
+ - "$ref": "#/components/schemas/PaymentSource"
nullable: true
payment_method:
- "$ref": "#/components/schemas/StorePaymentMethod"
+ "$ref": "#/components/schemas/PaymentMethod"
avs_response:
type: string
nullable: true
@@ -7414,6 +6088,10 @@ components:
cvv_response_message:
type: string
nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
metadata:
type: object
nullable: true
@@ -7423,33 +6101,86 @@ components:
type: string
nullable: true
order:
- "$ref": "#/components/schemas/AdminOrder"
+ "$ref": "#/components/schemas/Order"
refunds:
type: array
items:
- "$ref": "#/components/schemas/AdminRefund"
+ "$ref": "#/components/schemas/Refund"
required:
- id
- payment_method_id
- - state
- response_code
- number
- amount
- display_amount
- - created_at
- - updated_at
+ - status
- source_type
- source_id
- source
- - payment_method
- avs_response
- cvv_response_code
- cvv_response_message
+ - created_at
+ - updated_at
- metadata
- captured_amount
- order_id
x-typelizer: true
- AdminPrice:
+ PaymentSource:
+ type: object
+ properties:
+ id:
+ type: string
+ gateway_payment_profile_id:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - gateway_payment_profile_id
+ - created_at
+ - updated_at
+ 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
+ Price:
type: object
properties:
id:
@@ -7486,7 +6217,7 @@ components:
updated_at:
type: string
variant:
- "$ref": "#/components/schemas/AdminVariant"
+ "$ref": "#/components/schemas/Variant"
required:
- id
- amount
@@ -7501,16 +6232,13 @@ components:
- created_at
- updated_at
x-typelizer: true
- AdminProduct:
+ Product:
type: object
properties:
id:
type: string
name:
type: string
- description:
- type: string
- nullable: true
slug:
type: string
meta_description:
@@ -7524,10 +6252,6 @@ components:
available_on:
type: string
nullable: true
- created_at:
- type: string
- updated_at:
- type: string
purchasable:
type: boolean
in_stock:
@@ -7536,6 +6260,12 @@ components:
type: boolean
available:
type: boolean
+ description:
+ type: string
+ nullable: true
+ description_html:
+ type: string
+ nullable: true
default_variant_id:
type: string
thumbnail_url:
@@ -7546,35 +6276,39 @@ components:
items:
type: string
price:
- "$ref": "#/components/schemas/AdminPrice"
+ "$ref": "#/components/schemas/Price"
original_price:
allOf:
- - "$ref": "#/components/schemas/AdminPrice"
+ - "$ref": "#/components/schemas/Price"
nullable: true
- images:
+ primary_media:
+ "$ref": "#/components/schemas/Media"
+ media:
type: array
items:
- "$ref": "#/components/schemas/AdminImage"
+ "$ref": "#/components/schemas/Media"
variants:
type: array
items:
- "$ref": "#/components/schemas/AdminVariant"
+ "$ref": "#/components/schemas/Variant"
default_variant:
- "$ref": "#/components/schemas/AdminVariant"
- master_variant:
- "$ref": "#/components/schemas/AdminVariant"
+ "$ref": "#/components/schemas/Variant"
option_types:
type: array
items:
- "$ref": "#/components/schemas/AdminOptionType"
- taxons:
+ "$ref": "#/components/schemas/OptionType"
+ categories:
type: array
items:
- "$ref": "#/components/schemas/AdminTaxon"
- metafields:
+ "$ref": "#/components/schemas/Category"
+ custom_fields:
type: array
items:
- "$ref": "#/components/schemas/AdminMetafield"
+ "$ref": "#/components/schemas/CustomField"
+ prior_price:
+ allOf:
+ - "$ref": "#/components/schemas/PriceHistory"
+ nullable: true
status:
type: string
make_active_at:
@@ -7583,45 +6317,33 @@ components:
discontinue_on:
type: string
nullable: true
- meta_title:
- type: string
- nullable: true
- promotionable:
- type: boolean
deleted_at:
type: string
nullable: true
- shipping_category_id:
+ created_at:
type: string
- nullable: true
- tax_category_id:
+ updated_at:
type: string
- nullable: true
cost_price:
type: string
nullable: true
cost_currency:
type: string
nullable: true
- shipping_category:
- "$ref": "#/components/schemas/AdminShippingCategory"
- tax_category:
- "$ref": "#/components/schemas/AdminTaxCategory"
required:
- id
- name
- - description
- slug
- meta_description
- meta_keywords
- variant_count
- available_on
- - created_at
- - updated_at
- purchasable
- in_stock
- backorderable
- available
+ - description
+ - description_html
- default_variant_id
- thumbnail_url
- tags
@@ -7630,15 +6352,13 @@ components:
- status
- make_active_at
- discontinue_on
- - meta_title
- - promotionable
- deleted_at
- - shipping_category_id
- - tax_category_id
+ - created_at
+ - updated_at
- cost_price
- cost_currency
x-typelizer: true
- AdminRefund:
+ Refund:
type: object
properties:
id:
@@ -7646,10 +6366,6 @@ components:
transaction_id:
type: string
nullable: true
- created_at:
- type: string
- updated_at:
- type: string
amount:
type: string
nullable: true
@@ -7662,21 +6378,25 @@ components:
reimbursement_id:
type: string
nullable: true
- metadata:
- type: object
- nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ payment:
+ "$ref": "#/components/schemas/Payment"
+ reimbursement:
+ "$ref": "#/components/schemas/Reimbursement"
required:
- id
- transaction_id
- - created_at
- - updated_at
- amount
- payment_id
- refund_reason_id
- reimbursement_id
- - metadata
+ - created_at
+ - updated_at
x-typelizer: true
- AdminReimbursement:
+ Reimbursement:
type: object
properties:
id:
@@ -7686,10 +6406,6 @@ components:
reimbursement_status:
type: string
nullable: true
- created_at:
- type: string
- updated_at:
- type: string
total:
type: string
nullable: true
@@ -7699,148 +6415,76 @@ components:
customer_return_id:
type: string
nullable: true
- required:
- - id
- - number
- - reimbursement_status
- - created_at
- - updated_at
- - total
- - order_id
- - customer_return_id
- x-typelizer: true
- AdminReturnAuthorization:
- type: object
- properties:
- id:
- type: string
- number:
- type: string
created_at:
type: string
updated_at:
type: string
- state:
- type: string
- order_id:
- type: string
- nullable: true
- stock_location_id:
- type: string
- nullable: true
- return_authorization_reason_id:
- type: string
- nullable: true
+ order:
+ "$ref": "#/components/schemas/Order"
required:
- id
- number
+ - reimbursement_status
+ - total
+ - order_id
+ - customer_return_id
- created_at
- updated_at
- - state
- - order_id
- - stock_location_id
- - return_authorization_reason_id
x-typelizer: true
- AdminShipment:
+ ReturnAuthorization:
type: object
properties:
id:
type: string
number:
type: string
- state:
+ status:
type: string
- tracking:
+ order_id:
type: string
nullable: true
- tracking_url:
+ stock_location_id:
type: string
nullable: true
- cost:
- type: string
- display_cost:
- type: string
- shipped_at:
+ return_authorization_reason_id:
type: string
nullable: true
created_at:
type: string
updated_at:
type: string
- shipping_method:
- "$ref": "#/components/schemas/StoreShippingMethod"
- stock_location:
- "$ref": "#/components/schemas/StoreStockLocation"
- shipping_rates:
- type: array
- items:
- "$ref": "#/components/schemas/StoreShippingRate"
- adjustment_total:
- type: string
- additional_tax_total:
- type: string
- included_tax_total:
- type: string
- promo_total:
- type: string
- pre_tax_amount:
- type: string
- metadata:
- type: object
- nullable: true
- order_id:
- type: string
- nullable: true
- stock_location_id:
- type: string
- nullable: true
order:
- "$ref": "#/components/schemas/AdminOrder"
- adjustments:
- type: array
- items:
- "$ref": "#/components/schemas/AdminAdjustment"
+ "$ref": "#/components/schemas/Order"
+ stock_location:
+ "$ref": "#/components/schemas/StockLocation"
required:
- id
- number
- - state
- - tracking
- - tracking_url
- - cost
- - display_cost
- - shipped_at
- - created_at
- - updated_at
- - shipping_method
- - stock_location
- - shipping_rates
- - adjustment_total
- - additional_tax_total
- - included_tax_total
- - promo_total
- - pre_tax_amount
- - metadata
+ - status
- order_id
- stock_location_id
+ - return_authorization_reason_id
+ - created_at
+ - updated_at
x-typelizer: true
- AdminShippingCategory:
+ State:
type: object
properties:
- id:
+ abbr:
type: string
name:
type: string
created_at:
- type: string
+ type: object
updated_at:
- type: string
+ type: object
required:
- - id
+ - abbr
- name
- created_at
- updated_at
x-typelizer: true
- AdminStockItem:
+ StockItem:
type: object
properties:
id:
@@ -7849,193 +6493,243 @@ components:
type: number
backorderable:
type: boolean
- created_at:
- type: string
- updated_at:
- type: string
stock_location_id:
type: string
nullable: true
variant_id:
type: string
nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ stock_location:
+ "$ref": "#/components/schemas/StockLocation"
+ variant:
+ "$ref": "#/components/schemas/Variant"
required:
- id
- count_on_hand
- backorderable
- - created_at
- - updated_at
- stock_location_id
- variant_id
+ - created_at
+ - updated_at
x-typelizer: true
- AdminTaxCategory:
+ StockLocation:
type: object
properties:
id:
type: string
+ state_abbr:
+ type: string
+ nullable: true
name:
type: string
- is_default:
- type: boolean
- tax_code:
+ 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
+ active:
+ type: boolean
+ default:
+ type: boolean
+ backorderable_default:
+ type: boolean
+ propagate_all_variants:
+ type: boolean
created_at:
type: string
updated_at:
type: string
required:
- id
+ - state_abbr
- name
- - is_default
- - tax_code
+ - address1
+ - city
+ - zipcode
+ - country_iso
+ - country_name
+ - state_text
+ - active
+ - default
+ - backorderable_default
+ - propagate_all_variants
- created_at
- updated_at
x-typelizer: true
- AdminTaxon:
+ StoreCredit:
type: object
properties:
id:
type: string
- name:
+ amount:
type: string
- permalink:
+ amount_used:
type: string
- position:
- type: number
- depth:
- type: number
- meta_title:
+ amount_remaining:
type: string
- nullable: true
- meta_description:
+ display_amount:
type: string
- nullable: true
- meta_keywords:
+ display_amount_used:
+ type: string
+ display_amount_remaining:
+ type: string
+ currency:
type: string
- nullable: true
- children_count:
- type: number
created_at:
type: string
updated_at:
type: string
- parent_id:
+ customer_id:
+ type: string
+ nullable: true
+ created_by_id:
+ type: string
+ nullable: true
+ metadata:
+ type: object
+ nullable: true
+ required:
+ - id
+ - amount
+ - amount_used
+ - amount_remaining
+ - display_amount
+ - display_amount_used
+ - display_amount_remaining
+ - currency
+ - created_at
+ - updated_at
+ - customer_id
+ - created_by_id
+ - metadata
+ x-typelizer: true
+ Store:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ url:
+ type: string
+ code:
+ type: string
+ mail_from_address:
+ type: string
+ customer_support_email:
type: string
nullable: true
- taxonomy_id:
+ new_order_notifications_email:
type: string
+ nullable: true
description:
type: string
- description_html:
+ nullable: true
+ address:
type: string
- image_url:
+ nullable: true
+ contact_phone:
type: string
nullable: true
- square_image_url:
+ seo_title:
type: string
nullable: true
- is_root:
- type: boolean
- is_child:
- type: boolean
- is_leaf:
+ meta_keywords:
+ type: string
+ nullable: true
+ meta_description:
+ type: string
+ nullable: true
+ default:
type: boolean
- parent:
- "$ref": "#/components/schemas/AdminTaxon"
- children:
- type: array
- items:
- "$ref": "#/components/schemas/AdminTaxon"
- ancestors:
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ default_currency:
+ type: string
+ default_locale:
+ type: string
+ supported_currencies:
type: array
items:
- "$ref": "#/components/schemas/AdminTaxon"
- metafields:
+ type: string
+ supported_locales:
type: array
items:
- "$ref": "#/components/schemas/AdminMetafield"
- lft:
- type: number
- rgt:
- type: number
- hide_from_nav:
- type: boolean
- sort_order:
+ type: string
+ logo_url:
type: string
- rules_match_policy:
+ nullable: true
+ mailer_logo_url:
type: string
- automatic:
- type: boolean
- taxonomy:
- "$ref": "#/components/schemas/AdminTaxonomy"
+ nullable: true
required:
- id
- name
- - permalink
- - position
- - depth
- - meta_title
- - meta_description
+ - url
+ - code
+ - mail_from_address
+ - customer_support_email
+ - new_order_notifications_email
+ - description
+ - address
+ - contact_phone
+ - seo_title
- meta_keywords
- - children_count
+ - meta_description
+ - default
- created_at
- updated_at
- - parent_id
- - taxonomy_id
- - description
- - description_html
- - image_url
- - square_image_url
- - is_root
- - is_child
- - is_leaf
- - lft
- - rgt
- - hide_from_nav
- - sort_order
- - rules_match_policy
- - automatic
+ - default_currency
+ - default_locale
+ - supported_currencies
+ - supported_locales
+ - logo_url
+ - mailer_logo_url
x-typelizer: true
- AdminTaxonomy:
+ TaxCategory:
type: object
properties:
id:
type: string
name:
type: string
- position:
- type: number
+ tax_code:
+ type: string
+ nullable: true
+ is_default:
+ type: boolean
created_at:
type: string
updated_at:
type: string
- root_id:
- type: string
- nullable: true
- root:
- "$ref": "#/components/schemas/AdminTaxon"
- taxons:
- type: array
- items:
- "$ref": "#/components/schemas/AdminTaxon"
- metafields:
- type: array
- items:
- "$ref": "#/components/schemas/AdminMetafield"
- store_id:
- type: string
- nullable: true
required:
- id
- name
- - position
+ - tax_code
+ - is_default
- created_at
- updated_at
- - root_id
- - store_id
x-typelizer: true
- AdminVariant:
+ Variant:
type: object
properties:
id:
@@ -8045,19 +6739,13 @@ components:
sku:
type: string
nullable: true
- is_master:
- type: boolean
options_text:
type: string
track_inventory:
type: boolean
- image_count:
+ media_count:
type: number
- created_at:
- type: string
- updated_at:
- type: string
- thumbnail:
+ thumbnail_url:
type: string
nullable: true
purchasable:
@@ -8079,25 +6767,34 @@ components:
type: number
nullable: true
price:
- "$ref": "#/components/schemas/AdminPrice"
+ "$ref": "#/components/schemas/Price"
original_price:
allOf:
- - "$ref": "#/components/schemas/AdminPrice"
+ - "$ref": "#/components/schemas/Price"
nullable: true
- images:
+ primary_media:
+ "$ref": "#/components/schemas/Media"
+ media:
type: array
items:
- "$ref": "#/components/schemas/AdminImage"
+ "$ref": "#/components/schemas/Media"
option_values:
type: array
items:
- "$ref": "#/components/schemas/AdminOptionValue"
- metafields:
+ "$ref": "#/components/schemas/OptionValue"
+ custom_fields:
type: array
items:
- "$ref": "#/components/schemas/AdminMetafield"
+ "$ref": "#/components/schemas/CustomField"
+ prior_price:
+ allOf:
+ - "$ref": "#/components/schemas/PriceHistory"
+ nullable: true
position:
type: number
+ total_on_hand:
+ type: number
+ nullable: true
tax_category_id:
type: string
nullable: true
@@ -8107,47 +6804,30 @@ components:
cost_currency:
type: string
nullable: true
- barcode:
+ deleted_at:
type: string
nullable: true
- weight_unit:
+ created_at:
type: string
- nullable: true
- dimensions_unit:
+ updated_at:
type: string
- nullable: true
- deleted_at:
+ product_name:
type: string
- nullable: true
- discontinue_on:
+ display_price:
type: string
nullable: true
- total_on_hand:
- type: number
- nullable: true
prices:
type: array
items:
- "$ref": "#/components/schemas/AdminPrice"
- stock_items:
- type: array
- items:
- "$ref": "#/components/schemas/AdminStockItem"
- product:
- "$ref": "#/components/schemas/AdminProduct"
- tax_category:
- "$ref": "#/components/schemas/AdminTaxCategory"
+ "$ref": "#/components/schemas/Price"
required:
- id
- product_id
- sku
- - is_master
- options_text
- track_inventory
- - image_count
- - created_at
- - updated_at
- - thumbnail
+ - media_count
+ - thumbnail_url
- purchasable
- in_stock
- backorderable
@@ -8159,13 +6839,13 @@ components:
- original_price
- option_values
- position
+ - total_on_hand
- tax_category_id
- cost_price
- cost_currency
- - barcode
- - weight_unit
- - dimensions_unit
- deleted_at
- - discontinue_on
- - total_on_hand
+ - created_at
+ - updated_at
+ - product_name
+ - display_price
x-typelizer: true
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index a5761f3531..9e40f17c99 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -40,6 +40,624 @@ info:
```
version: v3
paths:
+ "/api/v3/admin/orders/{order_id}/adjustments":
+ get:
+ summary: List adjustments
+ tags:
+ - Adjustments
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns all adjustments for an order. Read-only — adjustments are
+ computed from promotions, taxes, and fees.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: adjustments found
+ content:
+ application/json:
+ example:
+ data:
+ - id: adj_UkLWZg9DAJ
+ label: Admin discount
+ display_amount: "$0.00"
+ included: false
+ created_at: '2026-04-29T10:49:45.205Z'
+ updated_at: '2026-04-29T10:49:45.212Z'
+ amount: '0.0'
+ order_id: or_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/admin/orders/{order_id}/adjustments/{id}":
+ get:
+ summary: Show an adjustment
+ tags:
+ - Adjustments
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns details of a specific adjustment.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Adjustment prefixed ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: adjustment found
+ content:
+ application/json:
+ example:
+ id: adj_UkLWZg9DAJ
+ label: Admin discount
+ display_amount: "$0.00"
+ included: false
+ created_at: '2026-04-29T10:49:45.775Z'
+ updated_at: '2026-04-29T10:49:45.779Z'
+ amount: '0.0'
+ order_id: or_UkLWZg9DAJ
+ "/api/v3/admin/products/{product_id}/media":
+ get:
+ summary: List product media
+ tags:
+ - Product Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns a paginated list of media (images, video) for a product.
+ parameters:
+ - name: x-spree-api-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 prefixed 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
+ responses:
+ '200':
+ description: media found
+ content:
+ application/json:
+ example:
+ data:
+ - id: media_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ variant_ids:
+ - variant_UkLWZg9DAJ
+ position: 1
+ alt:
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg
+ created_at: '2026-04-29T10:50:08.202Z'
+ updated_at: '2026-04-29T10:50:08.204Z'
+ viewable_id: variant_UkLWZg9DAJ
+ viewable_type: Spree::Variant
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a product media item
+ tags:
+ - Product Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Creates a new media item (image, video) for a product.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ responses:
+ '202':
+ description: media import from URL enqueued
+ '422':
+ description: validation error (attachment required)
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Attachment can't be blank
+ details:
+ attachment:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ alt:
+ type: string
+ example: Product front view
+ position:
+ type: integer
+ example: 1
+ type:
+ type: string
+ example: Spree::Image
+ description: Media type (defaults to Spree::Image)
+ url:
+ type: string
+ example: https://example.com/image.jpg
+ description: External URL to import image from (async). Returns
+ 202 Accepted.
+ "/api/v3/admin/products/{product_id}/media/{id}":
+ patch:
+ summary: Update a product media item
+ tags:
+ - Product Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Updates a product media item. Only provided fields are updated.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Media prefixed ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: media updated
+ content:
+ application/json:
+ example:
+ id: media_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ variant_ids:
+ - variant_UkLWZg9DAJ
+ position: 1
+ alt: Updated alt text
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg
+ created_at: '2026-04-29T10:50:09.172Z'
+ updated_at: '2026-04-29T10:50:09.464Z'
+ viewable_id: variant_UkLWZg9DAJ
+ viewable_type: Spree::Variant
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ alt:
+ type: string
+ example: Updated alt text
+ position:
+ type: integer
+ example: 2
+ delete:
+ summary: Delete a product media item
+ tags:
+ - Product Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Deletes a media item from a product.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Media prefixed ID
+ schema:
+ type: string
+ responses:
+ '204':
+ description: media deleted
+ "/api/v3/admin/products/{product_id}/variants/{variant_id}/media":
+ get:
+ summary: List variant media
+ tags:
+ - Variant Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns a paginated list of media (images, video) for a variant.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ - name: variant_id
+ in: path
+ required: true
+ description: Variant prefixed 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
+ responses:
+ '200':
+ description: variant media found
+ content:
+ application/json:
+ example:
+ data:
+ - id: media_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ variant_ids:
+ - variant_gbHJdmfrXB
+ position: 1
+ alt:
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg
+ created_at: '2026-04-29T10:50:12.463Z'
+ updated_at: '2026-04-29T10:50:12.465Z'
+ viewable_id: variant_gbHJdmfrXB
+ viewable_type: Spree::Variant
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a variant media item
+ tags:
+ - Variant Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Creates a new media item (image, video) for a variant.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ - name: variant_id
+ in: path
+ required: true
+ description: Variant prefixed ID
+ schema:
+ type: string
+ responses:
+ '202':
+ description: variant media import from URL enqueued
+ '422':
+ description: validation error (attachment required)
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Attachment can't be blank
+ details:
+ attachment:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ alt:
+ type: string
+ example: Variant image
+ position:
+ type: integer
+ example: 1
+ type:
+ type: string
+ example: Spree::Image
+ description: Media type (defaults to Spree::Image)
+ url:
+ type: string
+ example: https://example.com/image.jpg
+ description: External URL to import image from (async). Returns
+ 202 Accepted.
+ "/api/v3/admin/products/{product_id}/variants/{variant_id}/media/{id}":
+ patch:
+ summary: Update a variant media item
+ tags:
+ - Variant Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Updates a variant media item. Only provided fields are updated.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ - name: variant_id
+ in: path
+ required: true
+ description: Variant prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Media prefixed ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: variant media updated
+ content:
+ application/json:
+ example:
+ id: media_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ variant_ids:
+ - variant_gbHJdmfrXB
+ position: 1
+ alt: Updated variant image
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg
+ created_at: '2026-04-29T10:50:13.491Z'
+ updated_at: '2026-04-29T10:50:13.774Z'
+ viewable_id: variant_gbHJdmfrXB
+ viewable_type: Spree::Variant
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ alt:
+ type: string
+ example: Updated variant image
+ position:
+ type: integer
+ example: 2
+ delete:
+ summary: Delete a variant media item
+ tags:
+ - Variant Media
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Deletes a media item from a variant.
+ parameters:
+ - name: x-spree-api-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 prefixed ID
+ schema:
+ type: string
+ - name: variant_id
+ in: path
+ required: true
+ description: Variant prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Media prefixed ID
+ schema:
+ type: string
+ responses:
+ '204':
+ description: variant media deleted
"/api/v3/store/customers/me/addresses":
get:
summary: List customer addresses
@@ -102,25 +720,25 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 3 Lovely Street
+ address1: 63 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
phone: 555-555-0199
company: Company
- country_name: NAME_1
- country_iso: I1
- state_text: STATE_ABBR_1
- state_abbr: STATE_ABBR_1
+ country_name: NAME_23
+ country_iso: I23
+ state_text: STATE_ABBR_92
+ state_abbr: STATE_ABBR_92
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_1
+ state_name: STATE_NAME_92
- id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 2 Lovely Street
+ address1: 62 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -128,17 +746,17 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_3
- state_abbr: STATE_ABBR_3
+ state_text: STATE_ABBR_94
+ state_abbr: STATE_ABBR_94
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_name: STATE_NAME_3
+ state_name: STATE_NAME_94
- id: addr_UkLWZg9DAJ
first_name: John
last_name: Doe
full_name: John Doe
- address1: 1 Lovely Street
+ address1: 61 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -146,12 +764,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_2
- state_abbr: STATE_ABBR_2
+ state_text: STATE_ABBR_93
+ state_abbr: STATE_ABBR_93
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_name: STATE_NAME_2
+ state_name: STATE_NAME_93
meta:
page: 1
limit: 25
@@ -239,14 +857,14 @@ paths:
city: New York
phone: "+1 555 123 4567"
company:
- country_name: NAME_3
- country_iso: I3
- state_text: STATE_ABBR_7
- state_abbr: STATE_ABBR_7
+ country_name: NAME_25
+ country_iso: I25
+ state_text: STATE_ABBR_98
+ state_abbr: STATE_ABBR_98
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_7
+ state_name: STATE_NAME_98
schema:
"$ref": "#/components/schemas/Address"
'422':
@@ -387,20 +1005,20 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 15 Lovely Street
+ address1: 75 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
phone: 555-555-0199
company: Company
- country_name: NAME_5
- country_iso: I5
- state_text: STATE_ABBR_13
- state_abbr: STATE_ABBR_13
+ country_name: NAME_27
+ country_iso: I27
+ state_text: STATE_ABBR_104
+ state_abbr: STATE_ABBR_104
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_13
+ state_name: STATE_NAME_104
schema:
"$ref": "#/components/schemas/Address"
'404':
@@ -462,20 +1080,20 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 21 Lovely Street
+ address1: 81 Lovely Street
address2: Northwest
postal_code: '35005'
city: Los Angeles
phone: 555-555-0199
company: Company
- country_name: NAME_7
- country_iso: I7
- state_text: STATE_ABBR_19
- state_abbr: STATE_ABBR_19
+ country_name: NAME_29
+ country_iso: I29
+ state_text: STATE_ABBR_110
+ state_abbr: STATE_ABBR_110
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_19
+ state_name: STATE_NAME_110
schema:
"$ref": "#/components/schemas/Address"
requestBody:
@@ -590,13 +1208,13 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImNjYWU3OThjLTIxNTYtNGM5Mi04YzA5LWIxMDViMDZmYTNlNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc2MTYxODIyfQ.K9UvQDyZ1Z2-NgFQ--azTRbyk8Syd4gJGR8y8Kv06NE
- refresh_token: jfUcHe3M3sksXfCJhrbgSTKV
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImIzMjVlY2M0LWQxMDYtNDNlNi05MDc4LWM5ZGI0MDc5YzAyYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDYzNDIyfQ.D8X3NHrqCn3i5fgFgdpwa2Sjfc8UG5_yUk3HuiDI-7w
+ refresh_token: JSYM5Q3NLy497JKBnAWDRSey
user:
id: cus_UkLWZg9DAJ
- first_name: Jodie
- last_name: Welch
+ first_name: Keesha
+ last_name: Robel
phone:
accepts_email_marketing: false
available_store_credit_total: '0'
@@ -671,13 +1289,13 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY0MWQ5Y2NmLTNhM2EtNDk2OS1hNWUyLWUwNWViZjdmYWIxNyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc2MTYxODIzfQ.6CIayRaSgbOgiwJyuweu92lgkwboaEufAQDHjrWCR5Y
- refresh_token: NPstvWaaAHLokJkeKyfY4TzG
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImIwZTYxNDAxLTMyMGMtNDNmOC1hMTg0LThjNzE0NDFlM2Q4MiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDYzNDIzfQ.RuLvcqp7kj2E28wmG3soWhE4deoWKew0eCPCvriyREc
+ refresh_token: tDvpvuuhRZYPLHCTj9KuE1PT
user:
id: cus_UkLWZg9DAJ
- first_name: Shiloh
- last_name: Robel
+ first_name: Coralie
+ last_name: Botsford
phone:
accepts_email_marketing: false
available_store_credit_total: '0'
@@ -843,9 +1461,9 @@ paths:
data:
- id: cart_gbHJdmfrXB
market_id:
- number: R232078179
- token: zG15ZP7pVhYDcfbgTYU4hiq8aXojPfSy4c3
+ number: R471470566
+ token: HafFjQfHw7jCvEUWDaqPy8kvQm9QbvDZpcG
customer_note:
currency: USD
locale: en
@@ -887,8 +1505,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 27264
- slug: product-27264
+ name: Product 579559
+ slug: product-579559
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -913,7 +1531,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H29082671412
+ number: H74595238338
tracking: U10000
tracking_url:
cost: '100.0'
@@ -941,14 +1559,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_32
- name: Kandace Kulas
+ state_abbr: STATE_ABBR_123
+ name: Joelle Padberg
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_32
+ state_text: STATE_ABBR_123
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_gbHJdmfrXB
@@ -974,7 +1592,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 36 Lovely Street
+ address1: 96 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -982,18 +1600,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_36
- state_abbr: STATE_ABBR_36
+ state_text: STATE_ABBR_127
+ state_abbr: STATE_ABBR_127
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_36
+ state_name: STATE_NAME_127
shipping_address:
id: addr_OIJLhNcSbf
first_name: John
last_name: Doe
full_name: John Doe
- address1: 37 Lovely Street
+ address1: 97 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1001,20 +1619,20 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_37
- state_abbr: STATE_ABBR_37
+ state_text: STATE_ABBR_128
+ state_abbr: STATE_ABBR_128
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_37
+ state_name: STATE_NAME_128
payment_methods: []
gift_card:
market:
- id: cart_UkLWZg9DAJ
market_id:
- number: R676619505
- token: JoRTMBpiuETzPG5ZjdvhR2oh3on6SLe5Esg
+ number: R719129789
+ token: hrbr967gvjnhuuDGo1inkjD3tZtz6tqboAN
customer_note:
currency: USD
locale: en
@@ -1056,8 +1674,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 12178
- slug: product-12178
+ name: Product 567610
+ slug: product-567610
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1082,7 +1700,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H94768987826
+ number: H09180957231
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1110,14 +1728,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_32
- name: Kandace Kulas
+ state_abbr: STATE_ABBR_123
+ name: Joelle Padberg
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_32
+ state_text: STATE_ABBR_123
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -1143,7 +1761,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 34 Lovely Street
+ address1: 94 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1151,18 +1769,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_34
- state_abbr: STATE_ABBR_34
+ state_text: STATE_ABBR_125
+ state_abbr: STATE_ABBR_125
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_34
+ state_name: STATE_NAME_125
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 35 Lovely Street
+ address1: 95 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1170,12 +1788,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_35
- state_abbr: STATE_ABBR_35
+ state_text: STATE_ABBR_126
+ state_abbr: STATE_ABBR_126
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_35
+ state_name: STATE_NAME_126
payment_methods: []
gift_card:
market:
@@ -1254,8 +1872,8 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R943663093
- token: FievmZcr9NHVLz13M8ohRrcBjevgVjbRbVC
+ number: R726052394
+ token: bjgtGTAwFNzmdMghbyNvSSY5Bhmphe3Yypw
email:
customer_note:
currency: USD
@@ -1410,9 +2028,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R938172735
- token: mq3o1sSWFULnd4nAKvThhRNgaEnAyNZBf5D
+ number: R422904303
+ token: Zj1VTueTADRkkBECLKgUWgjoyY4Bjjf3rp2
customer_note:
currency: USD
locale: en
@@ -1439,7 +2057,7 @@ paths:
display_delivery_total: "$0.00"
warnings:
- code: line_item_removed
- message: Product 62602 was removed because it was sold out
+ message: Product 611681 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
store_credit_total: '0.0'
@@ -1464,7 +2082,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 44 Lovely Street
+ address1: 104 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1472,18 +2090,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_44
- state_abbr: STATE_ABBR_44
+ state_text: STATE_ABBR_135
+ state_abbr: STATE_ABBR_135
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_44
+ state_name: STATE_NAME_135
shipping_address:
id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 45 Lovely Street
+ address1: 105 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1491,12 +2109,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_45
- state_abbr: STATE_ABBR_45
+ state_text: STATE_ABBR_136
+ state_abbr: STATE_ABBR_136
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_45
+ state_name: STATE_NAME_136
payment_methods: []
gift_card:
market:
@@ -1581,9 +2199,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R252724618
- token: E4K899xK1ZBq7ruLV2dwq4gxKXekKhFiVKb
+ number: R957103637
+ token: HQxdHjJrkj5DHrLzDsZrCmHh6HAnkckM4nb
customer_note: Leave at door
currency: USD
locale: en
@@ -1627,8 +2245,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 7619
- slug: product-7619
+ name: Product 624104
+ slug: product-624104
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -1653,7 +2271,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H64092938149
+ number: H86120439581
tracking:
tracking_url:
cost: '10.0'
@@ -1681,14 +2299,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_46
- name: Paige Romaguera
+ state_abbr: STATE_ABBR_137
+ name: Sook Cummerata
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_46
+ state_text: STATE_ABBR_137
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
@@ -1714,7 +2332,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 48 Lovely Street
+ address1: 108 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1722,18 +2340,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_48
- state_abbr: STATE_ABBR_48
+ state_text: STATE_ABBR_139
+ state_abbr: STATE_ABBR_139
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_48
+ state_name: STATE_NAME_139
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 49 Lovely Street
+ address1: 109 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -1741,12 +2359,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_49
- state_abbr: STATE_ABBR_49
+ state_text: STATE_ABBR_140
+ state_abbr: STATE_ABBR_140
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_49
+ state_name: STATE_NAME_140
payment_methods: []
gift_card:
market:
@@ -1919,9 +2537,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R028378406
- token: r69yQYQREesLPoT1Ga4hYFDV4DyiRMwx9mc
+ number: R786196151
+ token: e5rvddh349aEjUgBen6GeL7QLySXMZVUoD8
customer_note:
currency: USD
locale: en
@@ -1963,8 +2581,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 95368
- slug: product-95368
+ name: Product 643839
+ slug: product-643839
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1989,7 +2607,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H19674421649
+ number: H59612746246
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2017,14 +2635,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_54
- name: Kaitlin Gorczany
+ state_abbr: STATE_ABBR_145
+ name: Adelaide Jones
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_54
+ state_text: STATE_ABBR_145
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -2050,7 +2668,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 54 Lovely Street
+ address1: 114 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -2058,18 +2676,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_54
- state_abbr: STATE_ABBR_54
+ state_text: STATE_ABBR_145
+ state_abbr: STATE_ABBR_145
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_54
+ state_name: STATE_NAME_145
shipping_address:
id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 55 Lovely Street
+ address1: 115 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -2077,12 +2695,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_55
- state_abbr: STATE_ABBR_55
+ state_text: STATE_ABBR_146
+ state_abbr: STATE_ABBR_146
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_55
+ state_name: STATE_NAME_146
payment_methods: []
gift_card:
market:
@@ -2152,8 +2770,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R019572861
+ number: R100883351
customer_note:
currency: USD
locale: en
@@ -2180,7 +2798,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-04-14T09:17:10.133Z'
+ completed_at: '2026-04-29T10:50:29.089Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -2190,8 +2808,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 116185
- slug: product-116185
+ name: Product 663637
+ slug: product-663637
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2216,7 +2834,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H54059075466
+ number: H88952533523
tracking:
tracking_url:
cost: '10.0'
@@ -2244,14 +2862,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_60
- name: Nanci Ruecker
+ state_abbr: STATE_ABBR_151
+ name: Aliza Botsford
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_60
+ state_text: STATE_ABBR_151
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
@@ -2274,8 +2892,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: '12345'
- number: PCJJXDN4
+ response_code: BGS-ce1c387a56e5
+ number: PYPRN144
amount: '29.99'
display_amount: "$29.99"
status: completed
@@ -2301,7 +2919,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 62 Lovely Street
+ address1: 122 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -2309,18 +2927,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_62
- state_abbr: STATE_ABBR_62
+ state_text: STATE_ABBR_153
+ state_abbr: STATE_ABBR_153
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_62
+ state_name: STATE_NAME_153
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 63 Lovely Street
+ address1: 123 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -2328,12 +2946,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_63
- state_abbr: STATE_ABBR_63
+ state_text: STATE_ABBR_154
+ state_abbr: STATE_ABBR_154
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_63
+ state_name: STATE_NAME_154
gift_card:
market:
schema:
@@ -2622,7 +3240,7 @@ paths:
example:
data:
- iso: DE
- iso3: IS19
+ iso3: IS41
name: Germany
states_required: false
zipcode_required: true
@@ -3130,13 +3748,13 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijg2YjI5NGYxLTU4OTItNGY2YS1hOWEzLTY0ZjUwM2I0ODMxMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc2MTYxODM2fQ.k2zGOAOvYuPsD5raanWMRO6in3ogqqdMWbPMfSJgQc4
- refresh_token: qjyCdgmLNW4p3XnUDXGgfVyT
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijc5ZDhhNzJmLTk1MWItNDI3MS1iMTM0LWI4ZmY4YjJiZTlhOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDYzNDM1fQ.FRmEBHJOnv0F_FEQCxz1TLg-moXIFvKqvUR6Etg9iMo
+ refresh_token: RoHNyL7rZQNfkzTJm4Bj4Eov
user:
id: cus_UkLWZg9DAJ
- first_name: Chelsea
- last_name: Bayer
+ first_name: Darrin
+ last_name: Langosh
phone:
accepts_email_marketing: false
available_store_credit_total: '0'
@@ -3308,8 +3926,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R003163523
+ number: R199401374
customer_note:
currency: USD
locale: en
@@ -3336,7 +3954,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-14T09:17:17.539Z'
+ completed_at: '2026-04-29T10:50:36.041Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3346,8 +3964,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 205526
- slug: product-205526
+ name: Product 752016
+ slug: product-752016
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3372,7 +3990,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H84142443892
+ number: H91888025843
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3400,14 +4018,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_87
- name: Annita Deckow
+ state_abbr: STATE_ABBR_178
+ name: Merrill Lemke
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_87
+ state_text: STATE_ABBR_178
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
@@ -3433,7 +4051,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 82 Lovely Street
+ address1: 142 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3441,18 +4059,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_89
- state_abbr: STATE_ABBR_89
+ state_text: STATE_ABBR_180
+ state_abbr: STATE_ABBR_180
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_89
+ state_name: STATE_NAME_180
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 83 Lovely Street
+ address1: 143 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3460,12 +4078,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_90
- state_abbr: STATE_ABBR_90
+ state_text: STATE_ABBR_181
+ state_abbr: STATE_ABBR_181
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_90
+ state_name: STATE_NAME_181
gift_card:
market:
meta:
@@ -3563,8 +4181,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R701124602
+ number: R192684346
customer_note:
currency: USD
locale: en
@@ -3591,7 +4209,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-14T09:17:18.250Z'
+ completed_at: '2026-04-29T10:50:36.721Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3601,8 +4219,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 222299
- slug: product-222299
+ name: Product 777387
+ slug: product-777387
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3627,7 +4245,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H01807094479
+ number: H03244332837
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3655,14 +4273,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_93
- name: Sonya Smitham
+ state_abbr: STATE_ABBR_184
+ name: Ceola Heathcote
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_93
+ state_text: STATE_ABBR_184
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
@@ -3688,7 +4306,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 88 Lovely Street
+ address1: 148 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3696,18 +4314,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_95
- state_abbr: STATE_ABBR_95
+ state_text: STATE_ABBR_186
+ state_abbr: STATE_ABBR_186
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_95
+ state_name: STATE_NAME_186
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 89 Lovely Street
+ address1: 149 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3715,12 +4333,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_96
- state_abbr: STATE_ABBR_96
+ state_text: STATE_ABBR_187
+ state_abbr: STATE_ABBR_187
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_96
+ state_name: STATE_NAME_187
gift_card:
market:
schema:
@@ -3776,8 +4394,8 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImM1NGU5MzRhLWEyYTYtNDNiYi05MzA4LWNlYWY1ODE1YTMxZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc2MTYxODM5fQ.2_yHXmEz6hPyIQ4SBR74_XKxhkvtwDEuNQEu5dlOEOE
- refresh_token: YsK6yzNeTHiYRJXeWGioxm64
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjI3YmM5YjBlLTFiZjEtNDU5Ny1iMWYxLTk5N2Q2OGRkZjFjOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDYzNDM3fQ.uA9BQYSznjc35ScHblb6KCqvbB9doDnTu2mo5XlA3a8
+ refresh_token: MUk9YT6q227ADbBesnF8VxHD
user:
id: cus_UkLWZg9DAJ
@@ -3890,9 +4508,9 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Heath
- last_name: Roberts
+ first_name: Meaghan
+ last_name: Ebert
phone: 555-555-0199
accepts_email_marketing: false
available_store_credit_total: '0'
@@ -3902,7 +4520,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 95 Lovely Street
+ address1: 155 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3910,17 +4528,17 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_102
- state_abbr: STATE_ABBR_102
+ state_text: STATE_ABBR_193
+ state_abbr: STATE_ABBR_193
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_name: STATE_NAME_102
+ state_name: STATE_NAME_193
- id: addr_UkLWZg9DAJ
first_name: John
last_name: Doe
full_name: John Doe
- address1: 94 Lovely Street
+ address1: 154 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3928,18 +4546,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_101
- state_abbr: STATE_ABBR_101
+ state_text: STATE_ABBR_192
+ state_abbr: STATE_ABBR_192
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_name: STATE_NAME_101
+ state_name: STATE_NAME_192
default_billing_address:
id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 95 Lovely Street
+ address1: 155 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3947,18 +4565,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_102
- state_abbr: STATE_ABBR_102
+ state_text: STATE_ABBR_193
+ state_abbr: STATE_ABBR_193
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_name: STATE_NAME_102
+ state_name: STATE_NAME_193
default_shipping_address:
id: addr_UkLWZg9DAJ
first_name: John
last_name: Doe
full_name: John Doe
- address1: 94 Lovely Street
+ address1: 154 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -3966,12 +4584,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_101
- state_abbr: STATE_ABBR_101
+ state_text: STATE_ABBR_192
+ state_abbr: STATE_ABBR_192
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_name: STATE_NAME_101
+ state_name: STATE_NAME_192
schema:
"$ref": "#/components/schemas/Customer"
'401':
@@ -4028,7 +4646,7 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -4040,7 +4658,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 97 Lovely Street
+ address1: 157 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4048,17 +4666,17 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_104
- state_abbr: STATE_ABBR_104
+ state_text: STATE_ABBR_195
+ state_abbr: STATE_ABBR_195
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_name: STATE_NAME_104
+ state_name: STATE_NAME_195
- id: addr_UkLWZg9DAJ
first_name: John
last_name: Doe
full_name: John Doe
- address1: 96 Lovely Street
+ address1: 156 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4066,18 +4684,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_103
- state_abbr: STATE_ABBR_103
+ state_text: STATE_ABBR_194
+ state_abbr: STATE_ABBR_194
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_name: STATE_NAME_103
+ state_name: STATE_NAME_194
default_billing_address:
id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 97 Lovely Street
+ address1: 157 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4085,18 +4703,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_104
- state_abbr: STATE_ABBR_104
+ state_text: STATE_ABBR_195
+ state_abbr: STATE_ABBR_195
quick_checkout: false
is_default_billing: true
is_default_shipping: false
- state_name: STATE_NAME_104
+ state_name: STATE_NAME_195
default_shipping_address:
id: addr_UkLWZg9DAJ
first_name: John
last_name: Doe
full_name: John Doe
- address1: 96 Lovely Street
+ address1: 156 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4104,12 +4722,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_103
- state_abbr: STATE_ABBR_103
+ state_text: STATE_ABBR_194
+ state_abbr: STATE_ABBR_194
quick_checkout: false
is_default_billing: false
is_default_shipping: true
- state_name: STATE_NAME_103
+ state_name: STATE_NAME_194
schema:
"$ref": "#/components/schemas/Customer"
'422':
@@ -4267,9 +4885,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R081079159
- token: bccBaE7xBqXGz9538mnxTfsvesKQpsfSc1z
+ number: R379896415
+ token: Pt7j1jUzgy5J9dJuWnrLUMCUZ5DT6TD38oo
customer_note:
currency: USD
locale: en
@@ -4318,8 +4936,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 301628
- slug: product-301628
+ name: Product 853932
+ slug: product-853932
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4344,7 +4962,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H99376630233
+ number: H76685276530
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4372,14 +4990,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_119
- name: Jenee Stroman
+ state_abbr: STATE_ABBR_210
+ name: Andera Barrows
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_119
+ state_text: STATE_ABBR_210
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -4405,7 +5023,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 114 Lovely Street
+ address1: 174 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4413,18 +5031,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_121
- state_abbr: STATE_ABBR_121
+ state_text: STATE_ABBR_212
+ state_abbr: STATE_ABBR_212
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_121
+ state_name: STATE_NAME_212
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 115 Lovely Street
+ address1: 175 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4432,12 +5050,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_122
- state_abbr: STATE_ABBR_122
+ state_text: STATE_ABBR_213
+ state_abbr: STATE_ABBR_213
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_122
+ state_name: STATE_NAME_213
payment_methods: []
gift_card:
market:
@@ -4527,9 +5145,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R083155091
- token: gQqNxRcp1rMrwRE7sPnXsWSqDzXzqRMfaJ3
+ number: R743152262
+ token: 4g5Rd89j2tekAsqrBM5rHFiKYJrEhCY1jyv
customer_note:
currency: USD
locale: en
@@ -4571,8 +5189,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 328702
- slug: product-328702
+ name: Product 872597
+ slug: product-872597
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4597,7 +5215,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H74829810268
+ number: H00373340716
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4625,14 +5243,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_127
- name: Carrol Lindgren
+ state_abbr: STATE_ABBR_218
+ name: Bea Schultz
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_127
+ state_text: STATE_ABBR_218
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -4658,7 +5276,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 122 Lovely Street
+ address1: 182 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4666,18 +5284,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_129
- state_abbr: STATE_ABBR_129
+ state_text: STATE_ABBR_220
+ state_abbr: STATE_ABBR_220
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_129
+ state_name: STATE_NAME_220
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 123 Lovely Street
+ address1: 183 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4685,12 +5303,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_130
- state_abbr: STATE_ABBR_130
+ state_text: STATE_ABBR_221
+ state_abbr: STATE_ABBR_221
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_130
+ state_name: STATE_NAME_221
payment_methods: []
gift_card:
market:
@@ -4769,9 +5387,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R848172025
- token: CCiBRx13RfPPoNcrsBw9ScuBBCJNx1QXDRv
+ number: R104959955
+ token: aMgNdSuL7EPtwsCPZG1AoCRQWo2jRkKV5HL
customer_note:
currency: USD
locale: en
@@ -4815,8 +5433,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 34283
- slug: product-34283
+ name: Product 893232
+ slug: product-893232
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4841,7 +5459,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H99037479862
+ number: H32040529041
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4869,14 +5487,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_135
- name: Newton Ferry
+ state_abbr: STATE_ABBR_226
+ name: Treasa Kuhn
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_135
+ state_text: STATE_ABBR_226
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -4902,7 +5520,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 130 Lovely Street
+ address1: 190 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4910,18 +5528,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_137
- state_abbr: STATE_ABBR_137
+ state_text: STATE_ABBR_228
+ state_abbr: STATE_ABBR_228
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_137
+ state_name: STATE_NAME_228
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 131 Lovely Street
+ address1: 191 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4929,12 +5547,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_138
- state_abbr: STATE_ABBR_138
+ state_text: STATE_ABBR_229
+ state_abbr: STATE_ABBR_229
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_138
+ state_name: STATE_NAME_229
payment_methods: []
gift_card:
market:
@@ -5027,9 +5645,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R534636874
- token: 4nAvGyaWaG5svaQmWXzEYbw2Cqr5PLHbGrX
+ number: R999279559
+ token: QHzk9caWQYRLB5xisENjfm95gSMvD1df2Lx
customer_note:
currency: USD
locale: en
@@ -5068,8 +5686,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 36180
- slug: product-36180
+ name: Product 911122
+ slug: product-911122
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5094,7 +5712,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H46529036013
+ number: H62216687249
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5122,14 +5740,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_143
- name: Grazyna Bednar
+ state_abbr: STATE_ABBR_234
+ name: Heide Hansen
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_143
+ state_text: STATE_ABBR_234
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -5152,8 +5770,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260414091727979773
- number: PKI8ZMEE
+ response_code: 1-SC-20260429105046678898
+ number: PD180RFA
amount: '50.0'
display_amount: "$50.00"
status: checkout
@@ -5179,7 +5797,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 138 Lovely Street
+ address1: 198 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5187,18 +5805,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_145
- state_abbr: STATE_ABBR_145
+ state_text: STATE_ABBR_236
+ state_abbr: STATE_ABBR_236
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_145
+ state_name: STATE_NAME_236
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 139 Lovely Street
+ address1: 199 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5206,12 +5824,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_146
- state_abbr: STATE_ABBR_146
+ state_text: STATE_ABBR_237
+ state_abbr: STATE_ABBR_237
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_146
+ state_name: STATE_NAME_237
payment_methods:
- id: pm_UkLWZg9DAJ
name: Store Credit
@@ -5330,9 +5948,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R219045203
- token: rrFzEu6kvs9YuBXJpZR7oBq3KXXHEaBacoY
+ number: R659207348
+ token: o3FM6PoYwtZRFdpaprtgnbgUXMbojhaaRmn
customer_note:
currency: USD
locale: en
@@ -5374,8 +5992,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 406611
- slug: product-406611
+ name: Product 95217
+ slug: product-95217
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5400,7 +6018,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H26467945449
+ number: H45267185219
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5428,14 +6046,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_159
- name: Hermine Mertz
+ state_abbr: STATE_ABBR_250
+ name: Lindsay Bosco
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_159
+ state_text: STATE_ABBR_250
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -5458,8 +6076,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260414091730492369
- number: P20ASZJU
+ response_code: 1-SC-20260429105049202019
+ number: PPL7OPNI
amount: '50.0'
display_amount: "$50.00"
status: invalid
@@ -5485,7 +6103,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 154 Lovely Street
+ address1: 214 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5493,18 +6111,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_161
- state_abbr: STATE_ABBR_161
+ state_text: STATE_ABBR_252
+ state_abbr: STATE_ABBR_252
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_161
+ state_name: STATE_NAME_252
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 155 Lovely Street
+ address1: 215 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5512,12 +6130,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_162
- state_abbr: STATE_ABBR_162
+ state_text: STATE_ABBR_253
+ state_abbr: STATE_ABBR_253
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_162
+ state_name: STATE_NAME_253
payment_methods: []
gift_card:
market:
@@ -5582,7 +6200,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: F164794534BBCB57
+ code: 7130BB409ABC20D8
status: active
currency: USD
amount: '10.0'
@@ -5678,7 +6296,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 60BC446DEE5E15E9
+ code: E41BF12E6A00C9BA
status: active
currency: USD
amount: '10.0'
@@ -5769,9 +6387,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R687543473
- token: 3b8VvuGTnXJzPfb77oxZv1M7r535AjPRkBu
+ number: R738376524
+ token: zoXK6oAmUiuyfM4JqfVfrj1estkPocer8Fi
customer_note:
currency: USD
locale: en
@@ -5819,8 +6437,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 438369
- slug: product-438369
+ name: Product 985403
+ slug: product-985403
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5847,8 +6465,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 441414
- slug: product-441414
+ name: Product 995517
+ slug: product-995517
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -5878,7 +6496,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 169 Lovely Street
+ address1: 229 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5886,12 +6504,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_176
- state_abbr: STATE_ABBR_176
+ state_text: STATE_ABBR_267
+ state_abbr: STATE_ABBR_267
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_176
+ state_name: STATE_NAME_267
shipping_address:
payment_methods: []
gift_card:
@@ -5991,9 +6609,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R771412472
- token: h7K1rG2JFmAQqoBHJ48gHSANyRC2gPenQj3
+ number: R136473536
+ token: Tdvb8Y6Y3ewiJijNpgm4vwNR4si2ry3Curb
customer_note:
currency: USD
locale: en
@@ -6038,8 +6656,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 47215
- slug: product-47215
+ name: Product 1023331
+ slug: product-1023331
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6069,7 +6687,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 178 Lovely Street
+ address1: 238 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -6077,12 +6695,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_185
- state_abbr: STATE_ABBR_185
+ state_text: STATE_ABBR_276
+ state_abbr: STATE_ABBR_276
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_185
+ state_name: STATE_NAME_276
shipping_address:
payment_methods: []
gift_card:
@@ -6162,9 +6780,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R491965603
- token: PWpMqwAT7tSwZjLCus2TaUEQ1NhDtaWX8Wq
+ number: R118751837
+ token: A1CvoYBtS1kjJ2HEDgU3MTNjcctFDrmhiDm
customer_note:
currency: USD
locale: en
@@ -6215,7 +6833,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 181 Lovely Street
+ address1: 241 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -6223,12 +6841,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_188
- state_abbr: STATE_ABBR_188
+ state_text: STATE_ABBR_279
+ state_abbr: STATE_ABBR_279
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_188
+ state_name: STATE_NAME_279
shipping_address:
payment_methods: []
gift_card:
@@ -6376,12 +6994,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS46
+ iso3: IS68
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS47
+ iso3: IS69
name: France
states_required: false
zipcode_required: true
@@ -6460,12 +7078,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS50
+ iso3: IS72
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS51
+ iso3: IS73
name: France
states_required: false
zipcode_required: true
@@ -6540,12 +7158,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS54
+ iso3: IS76
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS55
+ iso3: IS77
name: France
states_required: false
zipcode_required: true
@@ -6609,12 +7227,12 @@ paths:
example:
data:
- iso: FR
- iso3: IS59
+ iso3: IS81
name: France
states_required: false
zipcode_required: true
- iso: DE
- iso3: IS58
+ iso3: IS80
name: Germany
states_required: false
zipcode_required: true
@@ -6765,7 +7383,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R652984046
+ number: R107458949
customer_note:
currency: USD
@@ -6793,7 +7411,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-14T09:17:38.381Z'
+ completed_at: '2026-04-29T10:50:57.067Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6803,8 +7421,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 513431
- slug: product-513431
+ name: Product 1066551
+ slug: product-1066551
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6829,7 +7447,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H55045226861
+ number: H25115000054
tracking: U10000
tracking_url:
cost: '100.0'
@@ -6857,14 +7475,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_196
- name: Dessie Rau
+ state_abbr: STATE_ABBR_287
+ name: Madonna Roob
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_196
+ state_text: STATE_ABBR_287
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
@@ -6890,7 +7508,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 189 Lovely Street
+ address1: 249 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -6898,18 +7516,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_196
- state_abbr: STATE_ABBR_196
+ state_text: STATE_ABBR_287
+ state_abbr: STATE_ABBR_287
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_196
+ state_name: STATE_NAME_287
shipping_address:
id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 190 Lovely Street
+ address1: 250 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -6917,12 +7535,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_197
- state_abbr: STATE_ABBR_197
+ state_text: STATE_ABBR_288
+ state_abbr: STATE_ABBR_288
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_197
+ state_name: STATE_NAME_288
gift_card:
market:
schema:
@@ -7003,9 +7621,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_7646d7977296a750908aeb2b
+ external_id: bogus_ae7d1a1ff0a0beb194aa3443
external_data:
- client_secret: bogus_secret_34c9e32090fc0919
+ client_secret: bogus_secret_7db742b773345c67
customer_external_id:
expires_at:
amount: '110.0'
@@ -7102,7 +7720,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_a9f87fd5747a1a113465fbfe
+ external_id: bogus_7018c5066dfe2f5eb9cb4250
external_data:
client_secret: secret_123
customer_external_id:
@@ -7163,7 +7781,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_0a88d0a1804df8a9597e7706
+ external_id: bogus_3a664db563f40c4715880d9e
external_data:
client_secret: secret_123
customer_external_id:
@@ -7264,7 +7882,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_5c1f2729cc6141351419a0ae
+ external_id: bogus_dcee48f27758a45d58fa7ac7
external_data:
client_secret: secret_123
customer_external_id:
@@ -7348,8 +7966,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_12499847aa63bb365aa96b1f
- external_client_secret: bogus_seti_secret_2187772c688095e0
+ external_id: bogus_seti_daa821c21a77241b20325bd9
+ external_client_secret: bogus_seti_secret_ac6eda78228e2b69
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7447,8 +8065,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_36bc96c3ae7f7ee42898e09b
- external_client_secret: seti_secret_b06993b3d5ebe39aa50cb8e0
+ external_id: seti_test_5de54867a27e5f854231ff0e
+ external_client_secret: seti_secret_652723a3cd866daacc01d898
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7523,8 +8141,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_108edeef19b71f5183ee50bd
- external_client_secret: seti_secret_a9d0807f1b231b12dca14135
+ external_id: seti_test_a790e6fc19873d08e23219b4
+ external_client_secret: seti_secret_303ab6a822fb5afdd4eae7ef
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7617,7 +8235,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: P2D5OQFR
+ number: P8RVG2ZC
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -7712,7 +8330,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-e900c731-47af-4aef-b495-58ca93b269c0
+ slug: privacy-policy-1de8e153-7a63-406c-a4f6-636435567a59
body: We respect your privacy.
body_html: |
<div class="trix-content">
@@ -7956,12 +8574,12 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 618621
- slug: product-618621
+ name: Product 1165108
+ slug: product-1165108
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-04-14T09:17:48.624Z'
+ available_on: '2025-04-29T10:51:07.777Z'
purchasable: true
in_stock: false
backorderable: true
@@ -7983,24 +8601,26 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 621163
- slug: product-621163
+ name: Product 1178746
+ slug: product-1178746
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-14T09:17:48.696Z'
+ available_on: '2025-04-29T10:51:07.830Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Nihil nisi harum nostrum inventore pariatur exercitationem
- animi numquam. Aspernatur atque id provident recusandae nobis
- dolorum. Praesentium harum quasi fugiat modi esse tempore rem
- omnis.
- description_html: Nihil nisi harum nostrum inventore pariatur exercitationem
- animi numquam. Aspernatur atque id provident recusandae nobis
- dolorum. Praesentium harum quasi fugiat modi esse tempore rem
- omnis.
+ description: Expedita quo laborum molestias cumque ullam culpa molestiae.
+ Quae temporibus quia unde corporis nisi illum numquam asperiores.
+ A non soluta voluptatibus excepturi nihil odit. Sapiente impedit
+ deserunt sit molestiae. Repellat animi nostrum possimus officiis
+ dolorem dolore placeat. Porro eum sequi sed vel. Hic commodi doloremque
+ facilis debitis reprehenderit dolorem accusamus. Labore dolorem
+ quisquam vel iusto maxime.
+ description_html: |-
+ Expedita quo laborum molestias cumque ullam culpa molestiae. Quae temporibus quia unde corporis nisi illum numquam asperiores. A non soluta voluptatibus excepturi nihil odit. Sapiente impedit deserunt sit molestiae.
+ Repellat animi nostrum possimus officiis dolorem dolore placeat. Porro eum sequi sed vel. Hic commodi doloremque facilis debitis reprehenderit dolorem accusamus. Labore dolorem quisquam vel iusto maxime.
default_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -8102,12 +8722,12 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 896469
- slug: product-896469
+ name: Product 1445184
+ slug: product-1445184
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-04-14T09:17:50.257Z'
+ available_on: '2025-04-29T10:51:09.354Z'
purchasable: true
in_stock: false
backorderable: true
@@ -8134,7 +8754,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-03-30T09:17:50Z'
+ recorded_at: '2026-04-14T10:51:09Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -8509,9 +9129,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R867928889
- token: hbBeuh8TR96gYoT5qvyJL1gMxP1n6QKWKte
+ number: R020356036
+ token: GHnHfacc14zgYkeFCtTp8q6SQMLJUzeDEYH
customer_note:
currency: USD
locale: en
@@ -8550,8 +9170,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1096667
- slug: product-1096667
+ name: Product 1646644
+ slug: product-1646644
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8576,7 +9196,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H50340603568
+ number: H39848763315
tracking: U10000
tracking_url:
cost: '100.0'
@@ -8604,14 +9224,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_270
- name: Kimi Keebler
+ state_abbr: STATE_ABBR_361
+ name: Eliza Johnson
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_270
+ state_text: STATE_ABBR_361
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -8634,8 +9254,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260414091755508264
- number: PU2F8H3T
+ response_code: 1-SC-20260429105114663503
+ number: PX5MHHHA
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -8661,7 +9281,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 253 Lovely Street
+ address1: 313 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -8669,18 +9289,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_272
- state_abbr: STATE_ABBR_272
+ state_text: STATE_ABBR_363
+ state_abbr: STATE_ABBR_363
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_272
+ state_name: STATE_NAME_363
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 254 Lovely Street
+ address1: 314 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -8688,12 +9308,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_273
- state_abbr: STATE_ABBR_273
+ state_text: STATE_ABBR_364
+ state_abbr: STATE_ABBR_364
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_273
+ state_name: STATE_NAME_364
payment_methods:
- id: pm_UkLWZg9DAJ
name: Store Credit
@@ -8776,9 +9396,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R367608340
- token: F2PVDNgqjZfuZ12mrWwEyxEopJYjVKh56hv
+ number: R169499153
+ token: BiKX4rq41Qyxxq2UcdbhD3mXEKbp8iZsKG3
customer_note:
currency: USD
locale: en
@@ -8820,8 +9440,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1114779
- slug: product-1114779
+ name: Product 1662939
+ slug: product-1662939
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8846,7 +9466,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H75926459512
+ number: H07475797758
tracking: U10000
tracking_url:
cost: '100.0'
@@ -8874,14 +9494,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_278
- name: Lawerence Fritsch
+ state_abbr: STATE_ABBR_369
+ name: Hilma Spencer
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_278
+ state_text: STATE_ABBR_369
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -8907,7 +9527,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 261 Lovely Street
+ address1: 321 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -8915,18 +9535,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_280
- state_abbr: STATE_ABBR_280
+ state_text: STATE_ABBR_371
+ state_abbr: STATE_ABBR_371
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_280
+ state_name: STATE_NAME_371
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 262 Lovely Street
+ address1: 322 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -8934,12 +9554,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_281
- state_abbr: STATE_ABBR_281
+ state_text: STATE_ABBR_372
+ state_abbr: STATE_ABBR_372
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_281
+ state_name: STATE_NAME_372
payment_methods: []
gift_card:
market:
@@ -9005,7 +9625,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: 3z9Ht2V3YetVi5yEUfrhukAA
+ token: Z7DaDpsmubLfKkyNfx21PsbY
is_default: false
is_private: true
meta:
@@ -9081,7 +9701,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: cVNoCgEmKvvAXmRskBtVnHeW
+ token: 3hdDht5j3dMfvXahEcDmUKNb
is_default: false
is_private: true
schema:
@@ -9177,7 +9797,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: TJtUtkZ4FdnWqRSN2SKhBsZ8
+ token: ubLMnj4paswMWgoZV6TmuPSC
is_default: false
is_private: true
schema:
@@ -9239,7 +9859,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: N9xNqw4gESzcvUn52WBT9yax
+ token: AdgqhhL8PxMQyeqZrB5ZqVda
is_default: false
is_private: true
schema:
@@ -9354,7 +9974,7 @@ paths:
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-133
+ sku: SKU-206
options_text: ''
track_inventory: true
media_count: 0
@@ -9611,6 +10231,46 @@ components:
- token
- refresh_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
CheckoutRequirement:
type: object
properties:
diff --git a/docs/plans/5.5-6.0-order-cancellation-and-approval.md b/docs/plans/5.5-6.0-order-cancellation-and-approval.md
new file mode 100644
index 0000000000..b29c1cd5eb
--- /dev/null
+++ b/docs/plans/5.5-6.0-order-cancellation-and-approval.md
@@ -0,0 +1,252 @@
+# Order Cancellation & Approval Models
+
+**Status:** Draft
+**Target:** Spree 5.5 (models + API) and 6.0 (drop denormalized columns, B2B order-side approvals)
+**Depends on:** `6.0-admin-api.md`, `6.0-channels-catalogs-b2b.md`, `6.0-cart-order-split.md`
+**Author:** Damian + Claude
+**Last updated:** 2026-04-29
+
+## Summary
+
+Replace the current denormalized `canceled_at` / `canceler_id` / `approved_at` / `approver_id` columns on `Spree::Order` with first-class `Spree::OrderCancellation` and `Spree::OrderApproval` models. Captures cancellation reasons, restock decisions, refund coupling, multi-level B2B approvals, and full history (cancel → resume → cancel-again preserves prior records).
+
+5.5 ships the models and API alongside the existing columns (denormalized columns mirror the latest record for fast queries). 6.0 drops the denormalized columns entirely — clients and internal callers read the last record directly. This is a deliberate breaking change in 6.0 to eliminate the out-of-sync risk that denormalization always carries.
+
+B2B approvals are scoped to two sides:
+- **Cart/draft side (buyer organization)** — buyers in a `Spree::Company` need internal sign-off before submitting an order. Lives on `Cart` (post-`6.0-cart-order-split`) — **deferred to 6.0**.
+- **Order side (store owner)** — merchants sometimes need to approve placed orders before fulfillment (high-value, fraud check, finance hold). Lives on `Order`. Ships in 5.5 with a single-approval flow; multi-level (`manager` / `finance` / `admin`) ships in 6.0.
+
+## Key Decisions (do not deviate without discussion)
+
+1. **Two new models in 5.5**: `Spree::OrderCancellation` and `Spree::OrderApproval`. Each is a separate table with FKs to `Spree::Order`, append-only history.
+
+2. **5.5 keeps denormalized columns** (`canceled_at`, `canceler_id`, `approved_at`, `approver_id`) for backward compatibility and fast queries. They mirror the **latest** record in each respective collection.
+
+3. **6.0 drops the denormalized columns.** Reads come from `order.cancellations.order(:created_at).last` and `order.approvals.order(:created_at).last`. This is a **breaking change** for any direct DB consumer or extension that reads these columns; the API surface (`canceled_at`, `approver_id`) stays stable but is now derived.
+
+4. **`Order#status` ('draft' / 'placed' / 'canceled') is the source of truth** for "is this order canceled right now." The cancellation record is history; the status column is current state. Cancel: `status: 'canceled'` + new `OrderCancellation` row. Resume (5.5 only — see open questions): `status: 'placed'` + previous cancellation row preserved.
+
+5. **B2B cart-side approvals are out of scope for 5.5.** They land in 6.0 alongside `Spree::Company`, `Spree::CompanyContact`, and the `Cart` model split. The cart-side approval is a different concept (buyer organization internal sign-off) than the merchant-side order approval shipping in 5.5.
+
+6. **Approval is opt-in per-store.** No flow forces approvals; they're a hook for merchants who want them. `Spree::Order#requires_approval?` is a method merchants override (or a per-store config); when true, `status: 'placed'` does not auto-fulfill — fulfillments wait for an `OrderApproval { status: 'approved' }`.
+
+7. **Reasons follow Shopify's enum** (string-stored): `customer`, `declined`, `fraud`, `inventory`, `staff`, `other`, `expired`. Stored as strings, not Rails enums (per CLAUDE.md "Use string columns instead of enums").
+
+8. **Cancellation drives downstream actions transactionally.** When `restock_items: true`, the same transaction creates `Spree::StockMovement` rows. When `refund_payments: true`, refunds are issued up to `refund_amount`. Failures roll back the cancellation record.
+
+9. **Polymorphic actor.** `canceled_by` and `approver` are polymorphic (`Spree::AdminUser`, `Spree::User`, `Spree::CompanyContact` in 6.0, or nil for system actions). Replaces the existing `canceler_id` / `approver_id` integer FKs that assumed `Spree.admin_user_class`.
+
+## Design Details
+
+### `Spree::OrderCancellation`
+
+```
+spree_order_cancellations
+ id string (prefixed: cncl_)
+ order_id string (FK → spree_orders)
+ reason string (NOT NULL) -- Shopify enum, stored as string
+ note text -- staff-facing note
+ restock_items boolean (default false)
+ refund_payments boolean (default false)
+ refund_amount decimal(10,2) -- nullable; used when refund_payments: true
+ notify_customer boolean (default false)
+ canceled_by_id string -- polymorphic
+ canceled_by_type string -- polymorphic
+ metadata jsonb (default {})
+ created_at datetime
+ updated_at datetime
+
+ index: order_id
+ index: canceled_by_id, canceled_by_type
+ index: created_at
+```
+
+Spree::Order association:
+```ruby
+has_many :cancellations, class_name: 'Spree::OrderCancellation', dependent: :destroy
+```
+
+### `Spree::OrderApproval`
+
+```
+spree_order_approvals
+ id string (prefixed: appr_)
+ order_id string (FK → spree_orders)
+ status string (NOT NULL) -- 'pending' | 'approved' | 'rejected'
+ level string -- nullable in 5.5; for 6.0 multi-level: 'manager' | 'finance' | 'admin'
+ note text
+ approver_id string -- polymorphic; nullable while status='pending'
+ approver_type string -- polymorphic
+ decided_at datetime -- nullable while status='pending'
+ metadata jsonb (default {})
+ created_at datetime
+ updated_at datetime
+
+ index: order_id, status
+ index: approver_id, approver_type
+```
+
+### Service updates (additive, backward-compatible)
+
+We **reuse the existing `Spree::Orders::Cancel` and `Spree::Orders::Approve` services**. The existing keyword arguments stay valid; the new ones are optional. Existing callers (storefront resume/cancel flows, admin engine, internal code) keep working without changes.
+
+`Spree::Orders::Cancel` (file: `spree/core/app/services/spree/orders/cancel.rb`):
+
+```ruby
+# Existing signature — STAYS VALID
+Spree.order_cancel_service.call(
+ order: order,
+ canceler: current_admin, # legacy keyword preserved
+ canceled_at: Time.current
+)
+
+# New signature — accepts new keywords additively
+Spree.order_cancel_service.call(
+ order: order,
+ canceler: current_admin, # still works
+ reason: 'inventory', # NEW (defaults to 'other' if omitted)
+ note: 'Out of stock', # NEW
+ restock_items: true, # NEW
+ refund_payments: true, # NEW
+ refund_amount: order.total, # NEW
+ notify_customer: false, # NEW
+ canceled_at: Time.current
+)
+```
+
+Internal flow (additive, single transaction):
+1. Create `Spree::OrderCancellation` record with provided params (`reason: 'other'` if omitted)
+2. Update Order denormalized columns (`canceled_at`, `canceler_id`) — existing behavior
+3. `order.cancel!` (existing state machine transition) — existing behavior
+4. If `restock_items: true`: create `Spree::StockMovement` rows
+5. If `refund_payments: true`: issue refunds up to `refund_amount` (defaults to `order.payment_total`)
+6. Publish `order.canceled` event with `cancellation_id` in payload
+
+`Spree::Orders::Approve` (file: `spree/core/app/services/spree/orders/approve.rb`) similarly:
+
+```ruby
+# Existing signature — STAYS VALID
+Spree.order_approve_service.call(order: order, approver: current_admin)
+
+# New signature
+Spree.order_approve_service.call(
+ order: order,
+ approver: current_admin, # still works
+ level: 'manager', # NEW — 6.0 multi-level; 5.5 stores it but ignores routing logic
+ note: 'Approved per phone call' # NEW
+)
+```
+
+Internal flow:
+1. Create `Spree::OrderApproval` record (`status: 'approved'`, `decided_at: Time.current`)
+2. Update Order denormalized columns (`approved_at`, `approver_id`) — existing behavior
+3. Publish `order.approved` event with `approval_id` in payload
+
+**Backward compat requirement:** all existing specs covering `Spree::Orders::Cancel`/`Approve` must continue to pass without changes. The new behavior is purely additive — new records get written under the hood when these services run, regardless of whether the new keywords are provided.
+
+### API endpoints
+
+`PATCH /api/v3/admin/orders/:id/cancel` — body accepts the new params. Returns the order with the new cancellation record nested if `?expand=cancellations`.
+
+`PATCH /api/v3/admin/orders/:id/approve` — body accepts `level` and `note`. Returns the order with the new approval record nested if `?expand=approvals`.
+
+New read-only endpoints (5.5):
+
+```
+GET /api/v3/admin/orders/:order_id/cancellations
+GET /api/v3/admin/orders/:order_id/cancellations/:id
+GET /api/v3/admin/orders/:order_id/approvals
+GET /api/v3/admin/orders/:order_id/approvals/:id
+```
+
+### Serializer fields
+
+`OrderCancellationSerializer`:
+```
+id, order_id, reason, note, restock_items, refund_payments, refund_amount,
+notify_customer, canceled_by_id, canceled_by_type, metadata, created_at
+```
+
+`OrderApprovalSerializer`:
+```
+id, order_id, status, level, note, approver_id, approver_type,
+decided_at, metadata, created_at
+```
+
+Existing `Admin::OrderSerializer` keeps `canceled_at`, `canceler_id`, `approved_at`, `approver_id` fields. In 5.5 they're column reads; in 6.0 they become method reads (`order.canceled_at` becomes `order.cancellations.order(:created_at).last&.created_at`). The API contract is unchanged.
+
+## Migration Path
+
+### 5.5
+
+1. **Migration 1**: create `spree_order_cancellations` and `spree_order_approvals` tables.
+
+2. **Migration 2 (data)**: backfill one row per existing `canceled_at`/`approved_at` (rake task, not in migration per CLAUDE.md):
+ - For each `Order WHERE canceled_at IS NOT NULL`: create `OrderCancellation { reason: 'other', canceled_by_id: canceler_id, canceled_by_type: Spree.admin_user_class.to_s, created_at: canceled_at }`.
+ - For each `Order WHERE approved_at IS NOT NULL`: create `OrderApproval { status: 'approved', approver_id: approver_id, approver_type: Spree.admin_user_class.to_s, decided_at: approved_at, created_at: approved_at }`.
+
+3. **Service updates**: `Spree::Orders::Cancel` and `Spree::Orders::Approve` write both the new record AND the denormalized columns in one transaction.
+
+4. **Model methods**: `Order#canceled_at`, `Order#canceler_id`, `Order#approved_at`, `Order#approver_id` continue to read from columns (unchanged).
+
+5. **API**: ship the four new GET endpoints and the new POST/PATCH params.
+
+### 6.0 (breaking change)
+
+1. **Migration 3**: drop `canceled_at`, `canceler_id`, `approved_at`, `approver_id` columns from `spree_orders`.
+
+2. **Replace column accessors with method reads:**
+ ```ruby
+ def canceled_at
+ cancellations.order(:created_at).last&.created_at
+ end
+
+ def canceler
+ cancellations.order(:created_at).last&.canceled_by
+ end
+
+ def approved_at
+ latest_approval = approvals.where(status: 'approved').order(:decided_at).last
+ latest_approval&.decided_at
+ end
+
+ def approver
+ approvals.where(status: 'approved').order(:decided_at).last&.approver
+ end
+ ```
+
+3. **Eager-loading**: list endpoints `preload(:cancellations, :approvals)` to avoid N+1.
+
+4. **API contract stays stable** — `canceled_at`, `canceler_id`, `approved_at`, `approver_id` are still serialized fields. The data path is just methods instead of columns.
+
+5. **Multi-level approvals**: `OrderApproval#level` becomes meaningful. `Spree::Order#fully_approved?` checks all required levels per `Spree::Store#required_approval_levels`. Buyer-side cart approvals (`Spree::Cart` model post `6.0-cart-order-split.md`) get a parallel `Spree::CartApproval` model — separate from `OrderApproval`.
+
+### Constraints on Current Work
+
+- **Don't add new code reading `Order#canceler_id` or `Order#approver_id` as integers.** They become methods returning prefixed IDs in 6.0. Use `Order#canceler` / `Order#approver` (the polymorphic association).
+- **New cancel/approve flows must go through the services**, not direct column updates. Direct `update_column(:canceled_at, ...)` will be invalid in 6.0 (column won't exist).
+- **Don't add B2B order-side approvals before 6.0** without considering the 6.0 multi-level design — adding single-level approvals now and migrating to multi-level later is OK.
+- **Don't add cart-side (buyer org) approvals in 5.5** — wait for `6.0-cart-order-split.md` and `6.0-channels-catalogs-b2b.md` to land. Doing so prematurely will require rework once `Cart` and `Company` exist.
+
+## Open Questions
+
+1. **Resume semantics in 5.5.** Today `Spree::Order#resume!` flips state from `canceled` back to `complete`. With the new model, does resume create an "anti-cancellation" record, or just a status flip? Lean toward status flip for now; the cancellation row stays as historical record. In 6.0 `resume` may be deprecated entirely.
+
+2. **Cancellation by line item.** Vendure supports partial cancellations (cancel specific lines, keep others). Current Spree doesn't. Defer to 6.0 alongside `6.0-returns-exchanges-claims.md` — the line-item-cancel use case overlaps with returns/refunds.
+
+3. **Approval requirement signal.** How does `Order#requires_approval?` decide? Per-store config (`store.require_order_approval`)? Per-order metadata flag? Per-customer-group rule? Defer to 6.0 channels/catalogs/B2B work.
+
+4. **Bulk operations.** Cancel-all and approve-all endpoints — defer per `6.0-admin-api.md` open question on bulk envelope.
+
+5. **`OrderCancellation#refund_amount` semantics.** When `refund_payments: true` and `refund_amount` is omitted — refund the full order total, or only payments captured to date? Recommend: full payment_total (`order.payment_total`), matching what merchants actually expect.
+
+6. **Cancellation event payload.** `order.canceled` event currently carries the order's prefixed ID. Should the new event payload carry the cancellation's prefixed ID too (so subscribers can read the reason without re-querying)? Lean yes — payload includes `cancellation_id`.
+
+## References
+
+- `/Users/damian/spree/docs/plans/6.0-admin-api.md` — Orders endpoint list (canc/appr stay under `/admin/orders/:id/cancel` + `/approve`)
+- `/Users/damian/spree/docs/plans/6.0-channels-catalogs-b2b.md` — buyer-org approvals (cart-side, 6.0)
+- `/Users/damian/spree/docs/plans/6.0-cart-order-split.md` — Cart model arrives in 6.0
+- `/Users/damian/spree/docs/plans/6.0-platform-auth.md` — `Spree.admin_user_class` polymorphism
+- Shopify [`OrderCancelReason`](https://shopify.dev/docs/api/admin-graphql/latest/enums/ordercancelreason) — enum values reference
+- Medusa [B2B Approval module](https://medusajs.com/blog/b2b-starter-update-mar25/) — multi-level approval pattern
diff --git a/docs/plans/5.5-admin-customers-api.md b/docs/plans/5.5-admin-customers-api.md
new file mode 100644
index 0000000000..cc7b249c63
--- /dev/null
+++ b/docs/plans/5.5-admin-customers-api.md
@@ -0,0 +1,381 @@
+# Admin Customers API
+
+**Status:** Draft
+**Target:** Spree 5.5
+**Depends on:** `6.0-admin-api.md`, `6.0-platform-auth.md`, `5.4-6.0-eu-legal-compliance.md`
+**Author:** damian
+**Last updated:** 2026-04-28
+
+## Summary
+
+Ship the `/api/v3/admin/customers/*` endpoint family in 5.5 — list, retrieve, create, update, destroy plus nested addresses and store credits. The model under the hood is still `Spree::User` (renamed to `Spree::Customer` in 6.0 per `6.0-platform-auth.md`); the URL, prefix, and serializer names are already "customer" so the 6.0 rename is a model swap with no API surface churn. This is the merchant-facing version of the Store API customer endpoints — same record, different visibility, full CRUD scoped to the current store.
+
+Competitor study: Shopify (REST + GraphQL), Medusa v2, Vendure, Saleor. We borrow Shopify's tags + marketing-consent timestamp shape, Medusa's address sub-resource pattern, and Saleor's metadata split. Customer groups, tags, segments, and GDPR endpoints are deferred to follow-up plans.
+
+## Key Decisions (do not deviate without discussion)
+
+1. **Prefix is `cus_` in 5.5, becomes `cust_` in 6.0.** `Spree::UserMethods` already declares `has_prefix_id :cus`. The 6.0 rename to `cust_` happens with the model rename — both prefixes must resolve through the SDK type during the transition. Do NOT introduce `cust_` early.
+2. **URL is `/customers` from day one.** Matches existing Store API URL (`/api/v3/store/customers`, `/api/v3/store/customer`). Hides the `Spree::User` legacy table name from API consumers.
+3. **CRUD is admin-scoped via the per-store join.** The list endpoint filters to users with at least one order in `current_store` OR linked via `Spree::CustomerGroupUser` (when groups land) OR with a `store_id`-tagged role. Never returns admin users. Never returns users from other stores.
+4. **Addresses are a sub-resource, not nested attributes.** `POST /customers/:id/addresses` per Medusa's pattern. Default billing/shipping is a flag on the address (`is_default_billing`, `is_default_shipping`), not a separate FK write target. Setting one rotates the previous default in the same transaction.
+5. **`default_billing_address_id` and `default_shipping_address_id` are read-only on the customer payload.** Writes happen by `PATCH`-ing the address with `is_default_billing: true`. Aligns with how `Spree::UserAddress` already works.
+6. **Search is one combined `?q[search]=` Ransack scope plus per-field `_cont`/`_eq`.** `Spree::User.search` already searches email + first_name + last_name. We expose it via Ransack scope plus structured filters so merchants can do both "type a name" and "filter by tag list".
+7. **Order history surfaces via three derived fields plus `?expand=orders`.** `orders_count`, `total_spent`, `last_order_completed_at` are computed (cacheable) attributes on the serializer — same pattern as Shopify's `numberOfOrders` / `amountSpent` / `lastOrder`. Full list comes from `?expand=orders` or the existing `GET /api/v3/admin/orders?q[user_id_eq]=cus_xxx`.
+8. **Tags ship in 5.5.** `acts_as_taggable_on :tags` is already on `Spree::User` (line 38 of `user_methods.rb`). Exposing it in the admin payload is free. Customer groups and segments do not ship in 5.5.
+9. **Marketing consent surfaces the timestamp from `5.4-6.0-eu-legal-compliance.md`.** Both `accepts_email_marketing` (boolean) and `email_marketing_consent_updated_at` are returned. Setting the boolean updates the timestamp (already wired in that plan).
+10. **GDPR endpoints (`/anonymize`, `/export`) are out of scope for 5.5.** They land in Phase 2 of the EU compliance plan. The plan reserves the URLs in `6.0-admin-api.md` lines 508-509; we do not implement them here.
+11. **No bulk endpoints in 5.5.** Per `6.0-admin-api.md` "Open Questions" — bulk envelope is unresolved. Merchants who need bulk operations issue a loop client-side.
+12. **Two API surfaces, one record.** `Spree::Api::V3::CustomerSerializer` (Store) is the customer self-view. `Spree::Api::V3::Admin::CustomerSerializer` (Admin) extends it with merchant-only fields (login, sign-in audit, internal_note, tags, computed order stats, timestamps). Never duplicate Store fields.
+
+## Competitor Comparison
+
+| Capability | Shopify | Medusa v2 | Vendure | Saleor | **Spree 5.5** |
+|---|---|---|---|---|---|
+| List `/customers` | ✅ | ✅ | ✅ (`customers` query) | ✅ (`customers` query) | ✅ |
+| Search syntax | `query=tag:VIP email:foo` | `q=` plus structured `$and`/`$or` | `CustomerFilterParameter` with `contains`/`eq` | `where` + `search` | Ransack `?q[search]=` + `q[email_cont]` |
+| Addresses sub-resource | Embedded array | ✅ separate endpoints | `createCustomerAddress` mutation | `addressCreate` mutation | ✅ separate endpoints (Medusa-style) |
+| Default billing/shipping | One `default_address` (single) | `is_default_shipping`/`is_default_billing` flags | `defaultShippingAddress`/`defaultBillingAddress` | Same as Vendure | **Two flags on address** (Medusa-style, matches existing Spree split) |
+| Tags | ✅ | ❌ (uses groups) | ❌ (uses groups) | ❌ (uses groups) | ✅ (already on model) |
+| Customer groups | ❌ (uses tags + segments) | ✅ | ✅ | ✅ (permission groups) | Deferred (table exists, API later) |
+| Segments | ✅ (segment query language) | ❌ | ❌ | ❌ | Deferred |
+| Marketing consent | `email_marketing_consent` object with state + timestamp + opt-in level + source | ❌ (custom only) | ❌ (custom only) | ❌ (custom only) | `accepts_email_marketing` + `email_marketing_consent_updated_at` (boolean + timestamp; opt-in level + source deferred) |
+| Order count + spend | `numberOfOrders`, `amountSpent` | Via expand | Via `orders` connection | Via `orders` connection | `orders_count` + `total_spent` + `last_order_completed_at` (computed) |
+| Order history endpoint | `/customers/:id/orders` | Via expand | Via expand | Via expand | `?expand=orders` + existing `/orders?q[user_id_eq]=` |
+| Internal note | ✅ (`note`) | ❌ | ❌ | ✅ (`note`, requires permission) | ✅ (`internal_note` rich text — already on model) |
+| Tax exempt | ✅ | ❌ | ❌ | ❌ | Deferred (B2B plan owns it) |
+| Account state | `enabled`/`disabled`/`invited` | `has_account` (registered vs guest) | n/a (Customer always has User) | `isActive` | `has_account` (mirror Medusa: present if `encrypted_password.present?`) |
+| Anonymize / export | Privacy API (deletion request, data request) | ❌ | ❌ | ❌ | Deferred to Phase 2 (EU compliance plan) |
+| Send invite / activation URL | ✅ | ❌ | ❌ | `redirectUrl` on create | Deferred (uses existing password-reset email flow) |
+| Bulk delete / update | ✅ (REST has none, GraphQL has bulk operations) | ❌ | ❌ | `customerBulkDelete` | Deferred |
+| Avatar / image | ✅ (`image`) | ❌ | ❌ | ✅ (`avatar`) | ✅ (`avatar` — already on model) |
+| Public/private metadata split | Metafields | `metadata` | `customFields` | `metadata` + `privateMetadata` | `public_metadata` + `private_metadata` (already on model) |
+
+**Where competitors disagree, we recommend:**
+
+- **Default address:** Shopify's single `default_address` is too restrictive — most merchants want different default ship vs bill (especially B2B). Medusa/Vendure/Saleor split. Spree already has `bill_address_id` + `ship_address_id` on the user. **Adopt the split. Use Medusa-style flag-based PATCH semantics so writes are address-local instead of customer-local.**
+- **Search ergonomics:** Shopify's `tag:VIP email:foo` query string is great for end users but clashes with our Ransack convention. Medusa's `$and`/`$or` JSON is overkill for the URL. **Use Ransack throughout (`?q[search]=`, `?q[email_cont]=`, `?q[tags_name_in][]=VIP`). Document a "common queries" cookbook in the OpenAPI spec.**
+- **Order count / total spent:** Computing on every request will N+1. Shopify and Vendure both lazy-compute (sometimes async-stale). **Compute via SQL aggregation lazily, cache for 5 minutes per customer key (`customer/:id/stats`).** Acceptable staleness for an admin dashboard.
+
+## Design Details
+
+### CustomerSerializer fields
+
+**Store API base (`Spree::Api::V3::CustomerSerializer` — already exists, no changes):**
+
+```
+id, email, first_name, last_name, phone,
+accepts_email_marketing, email_marketing_consent_updated_at, # ← add timestamp (Phase 1 EU plan)
+available_store_credit_total, display_available_store_credit_total,
+default_billing_address (one), default_shipping_address (one),
+addresses (many)
+```
+
+**Admin extension (`Spree::Api::V3::Admin::CustomerSerializer` — extend the existing file):**
+
+| Field | Source | Rationale |
+|---|---|---|
+| `login` | `user.login` | Distinct from email if customer username is supported |
+| `has_account` | `user.encrypted_password.present?` | Differentiates registered vs guest checkouts (Medusa parity) |
+| `created_at`, `updated_at` | column | Audit |
+| `last_sign_in_at`, `current_sign_in_at`, `sign_in_count` | columns | Already in current admin serializer |
+| `last_sign_in_ip`, `current_sign_in_ip` | columns | Already in current admin serializer |
+| `failed_attempts` | column | Already in current admin serializer (Devise; lockout in 6.0 platform-auth plan) |
+| `tags` | `tag_list` | Merchant-tagging, not facing storefront |
+| `internal_note_html` | `internal_note.body.to_s` | Sanitised HTML; matches `description_html` pattern in `6.0-rich-text-descriptions.md` |
+| `public_metadata` | column | Customer-readable metadata |
+| `private_metadata` | column | Admin-only metadata |
+| `orders_count` | `SELECT COUNT(*) FROM orders WHERE user_id=?` (cached) | Computed |
+| `total_spent` | `SELECT SUM(total) FROM orders WHERE user_id=? AND state='complete'` (cached, returned as string per Alba `:oj_rails`) | Computed |
+| `display_total_spent` | `Spree::Money.new(total_spent, currency).to_s` | Human format |
+| `last_order_completed_at` | `MAX(completed_at) WHERE state='complete'` | Drives "last seen" admin column |
+| `default_billing_address_id` | `bill_address&.prefixed_id` | Read-only convenience |
+| `default_shipping_address_id` | `ship_address&.prefixed_id` | Read-only convenience |
+| `default_billing_address` | one (admin address serializer) | `?expand=default_billing_address` only |
+| `default_shipping_address` | one | `?expand=default_shipping_address` only |
+| `addresses` | many | `?expand=addresses` only — full address book |
+| `orders` | many | `?expand=orders` only — paginated externally; this returns up to last 25, embedded |
+| `store_credits` | many | `?expand=store_credits` only |
+
+**Omit from admin payload:**
+
+- `available_store_credit_total` — store-aware aggregate that requires a currency context. Keep on Store API for the customer's own view; admins use the nested `/store_credits` endpoint instead (which gives full per-credit breakdown).
+- `password_digest` / `encrypted_password` / `password_salt` / `reset_password_token` — never expose.
+- `confirmation_token`, `unlock_token` — never expose.
+- `avatar_url` — defer until the SPA needs it (Customer detail page may surface it via `?expand=avatar` returning an ActiveStorage signed URL — track in 6.0 SPA plan, not here).
+
+### Endpoint list (extends `6.0-admin-api.md` lines 502-525)
+
+#### `GET /api/v3/admin/customers`
+
+List with Ransack + sort + paginate.
+
+```http
+GET /api/v3/admin/customers?q[search]=jane&q[tags_name_in][]=VIP&sort=-last_order_completed_at&per_page=50
+```
+
+```json
+{
+ "data": [
+ {
+ "id": "cus_5kJ3pRq8",
+ "email": "[email protected]",
+ "first_name": "Jane",
+ "last_name": "Doe",
+ "phone": "+15551234567",
+ "has_account": true,
+ "tags": ["VIP", "newsletter-2024"],
+ "accepts_email_marketing": true,
+ "email_marketing_consent_updated_at": "2026-02-11T09:14:22Z",
+ "orders_count": 12,
+ "total_spent": "1450.00",
+ "display_total_spent": "$1,450.00",
+ "last_order_completed_at": "2026-04-12T18:21:08Z",
+ "default_billing_address_id": "addr_aB1c2D3e",
+ "default_shipping_address_id": "addr_aB1c2D3e",
+ "created_at": "2024-08-01T12:00:00Z",
+ "updated_at": "2026-04-12T18:21:09Z"
+ }
+ ],
+ "meta": { "total_count": 1, "page": 1, "pages": 1, "limit": 50 }
+}
+```
+
+**Ransack filters exposed (whitelist additions on `Spree::User`):**
+
+| Filter | Example | Maps to |
+|---|---|---|
+| `q[search]` | `?q[search]=jane` | `Spree::User.search` scope (email + first/last name) |
+| `q[email_cont]` | `?q[email_cont][email protected]` | substring email |
+| `q[email_eq]` | exact email | |
+| `q[first_name_cont]`, `q[last_name_cont]` | | substring |
+| `q[phone_cont]` | | |
+| `q[accepts_email_marketing_eq]` | `=true` | newsletter only |
+| `q[tags_name_in][]` | repeat per tag | inner-join `acts_as_taggable_on` |
+| `q[created_at_gteq]`, `q[created_at_lteq]` | ISO datetime | range |
+| `q[orders_completed_at_gteq]` | last-active range — joins orders | already supported via `whitelisted_ransackable_associations` adding `orders` |
+| `q[orders_total_gteq]` | total spend filter (joins orders, sums via Ransack scope) | Ransack scope `with_min_total_spent` (new — server-side aggregate) |
+| `q[has_account_eq]` | `=true` (computed) | Ransack scope `registered`/`guest` (new) |
+
+`sort=-last_order_completed_at` — JSON:API style. Supported sorts: `created_at`, `email`, `last_sign_in_at`, `orders_count`, `total_spent`, `last_order_completed_at`.
+
+#### `GET /api/v3/admin/customers/:id`
+
+```http
+GET /api/v3/admin/customers/cus_5kJ3pRq8?expand=addresses,orders,store_credits
+```
+
+Returns the full admin payload plus `addresses`, `orders` (last 25 complete), `store_credits` arrays.
+
+#### `POST /api/v3/admin/customers`
+
+```json
+{
+ "email": "[email protected]",
+ "first_name": "Sam",
+ "last_name": "Johnson",
+ "phone": "+15555550199",
+ "accepts_email_marketing": false,
+ "tags": ["wholesale"],
+ "internal_note_html": "<p>Met at trade show.</p>",
+ "public_metadata": { "referral": "tradeshow-2026" }
+}
+```
+
+201 Created → returns the new customer payload. **No password is set.** A welcome / password-reset email is NOT sent automatically — that's a separate explicit action (deferred; aligns with `redirectUrl` semantics from Saleor, but we keep it out of 5.5 to avoid a default-on email). Merchants who want one POST to `/auth/password_resets` after creation.
+
+#### `PATCH /api/v3/admin/customers/:id`
+
+Same body shape as create, all fields optional. Setting `accepts_email_marketing` toggles the timestamp via the model callback (per EU compliance plan).
+
+#### `DELETE /api/v3/admin/customers/:id`
+
+Hard delete only if `customer.can_be_deleted?` (no completed orders) — already enforced by `Spree::UserMethods#check_completed_orders`. Returns 204 on success, 422 with code `customer_has_orders` otherwise. **Anonymisation is the right path for customers with order history; deferred to Phase 2.**
+
+#### `GET /api/v3/admin/customers/:customer_id/addresses`
+
+```json
+{
+ "data": [
+ {
+ "id": "addr_aB1c2D3e",
+ "label": "Home",
+ "first_name": "Jane",
+ "last_name": "Doe",
+ "address1": "123 Main St",
+ "address2": null,
+ "city": "Brooklyn",
+ "postal_code": "11201",
+ "phone": "+15551234567",
+ "company": null,
+ "state_name": "New York",
+ "state_abbr": "NY",
+ "country_iso": "US",
+ "country_name": "United States",
+ "is_default_billing": true,
+ "is_default_shipping": true,
+ "metadata": null,
+ "customer_id": "cus_5kJ3pRq8",
+ "created_at": "2024-08-01T12:00:00Z",
+ "updated_at": "2026-04-12T18:21:08Z"
+ }
+ ],
+ "meta": { "total_count": 1, "page": 1, "pages": 1, "limit": 50 }
+}
+```
+
+#### `POST /api/v3/admin/customers/:customer_id/addresses`
+
+```json
+{
+ "label": "Office",
+ "first_name": "Jane",
+ "last_name": "Doe",
+ "address1": "456 5th Ave",
+ "city": "New York",
+ "postal_code": "10001",
+ "country_iso": "US",
+ "state_abbr": "NY",
+ "phone": "+15551234567",
+ "is_default_shipping": true
+}
+```
+
+201 Created. If `is_default_shipping: true`, the previous default ship address loses the flag in the same transaction. Same rule for billing. Validation runs on write — incomplete addresses (missing required country/state per country rules) return 422.
+
+#### `PATCH /api/v3/admin/customers/:customer_id/addresses/:id`
+
+Toggle defaults via `{ "is_default_billing": true }`. Soft-deletes (`paranoia` on `Spree::Address`) are honoured.
+
+#### `DELETE /api/v3/admin/customers/:customer_id/addresses/:id`
+
+Soft-delete via `paranoia`. If it was a default, the customer loses that default (no auto-promotion of another address — merchant decides next).
+
+#### `GET /api/v3/admin/customers/:customer_id/store_credits`
+
+Returns full per-credit breakdown (amount, amount_used, amount_remaining, currency, category, created_by, memo). Existing `Spree::Api::V3::Admin::StoreCreditSerializer` covers it.
+
+#### `POST /api/v3/admin/customers/:customer_id/store_credits`
+
+```json
+{
+ "amount": "50.00",
+ "currency": "USD",
+ "category_id": "scc_xxx",
+ "memo": "Goodwill credit"
+}
+```
+
+`created_by_id` is set automatically from the authenticated admin.
+
+#### `PATCH /api/v3/admin/customers/:customer_id/store_credits/:id`
+
+Update memo, category, amount (only if `amount_used == 0`).
+
+#### `DELETE /api/v3/admin/customers/:customer_id/store_credits/:id`
+
+Allowed only if `amount_used == 0`. Otherwise 422 `store_credit_in_use`.
+
+### Address management — alignment with existing AddressBook
+
+`Spree::User` has `bill_address_id` + `ship_address_id` (singletons) AND `Spree::UserAddress` join (the address book — multiple addresses per user). The existing `Spree::Address` serializer already exposes `is_default_billing` / `is_default_shipping` flags computed from the user's bill/ship FKs.
+
+Three rules:
+1. **Always read defaults from the join through the FKs.** `is_default_billing = (address.id == address.user.bill_address_id)`. Already implemented.
+2. **Writing `is_default_billing: true` updates the user's `bill_address_id`** in a transaction and clears the flag from any other address. Implementation: a controller-level service `Spree::Customers::SetDefaultAddress.call(customer, address, kind:)`. No new model concern needed.
+3. **Address validation is strict on admin writes.** No "skip validation" escape hatch. If a merchant pastes a half-formed address, they get 422 with field-level errors — same `details` shape as the rest of the admin API.
+
+### Search/filter — what merchants actually search
+
+From competitor parity + research:
+
+1. **Type-ahead** on email/name/phone — `?q[search]=jane`. Single param, full-text-ish.
+2. **Tag chip filter** — `?q[tags_name_in][]=VIP&q[tags_name_in][]=wholesale`. AND between facets, OR within (Ransack default for `_in`).
+3. **Last activity** — `?q[orders_completed_at_gteq]=2026-01-01` (active in 2026). `?sort=-last_order_completed_at`.
+4. **High value** — `?q[orders_total_gteq]=1000` (lifetime spend ≥ $1000). New Ransack scope, joins + sums orders.
+5. **Newsletter** — `?q[accepts_email_marketing_eq]=true`.
+6. **Registered vs guest** — `?q[has_account_eq]=true`. New Ransack scope.
+7. **Date filters** — `?q[created_at_gteq]=...&q[created_at_lteq]=...`.
+
+We do not implement a Shopify-style `query=tag:VIP` parser. Ransack is the convention; the SDK can build query strings from a typed filter object on the client side.
+
+### Forward-compat to 6.0
+
+| Today (5.5) | 6.0 |
+|---|---|
+| `Spree::User` | `Spree::Customer` |
+| `cus_xxx` prefix | `cust_xxx` prefix |
+| `Spree.user_class` | `Spree.customer_class` |
+| `bill_address_id`, `ship_address_id` columns | same column names — no migration |
+| `internal_note` (ActionText) | `internal_note_html` field stored as text per `6.0-rich-text-descriptions.md` |
+| `accepts_email_marketing` | unchanged |
+| URL `/customers` | unchanged |
+| `customer_id` field on Address admin payload | unchanged (already `customer_id`, not `user_id`, in current admin address serializer) |
+| `ransackable_attributes` includes `id email first_name last_name accepts_email_marketing` | extended with `phone`, `created_at`, `last_sign_in_at` |
+| No `customer_groups` field | adds `customer_group_ids` array (groups plan ships post-5.5) |
+| No `failed_attempts` lockout admin | platform-auth lockout adds `locked_at` field |
+
+**Field renames triggered by other plans:**
+- Already aligned: `firstname → first_name`, `lastname → last_name`, `zipcode → postal_code` are renames on `Spree::Address`, owned by `5.4-store-api-naming-standardization.md`. Customer addresses use the renamed fields.
+- `metafield` → `custom_field` rename (`5.4-6.0-custom-fields-rename.md`) — the `public_metadata` / `private_metadata` JSON columns are not affected; only the polymorphic `Metafield` records are. No customer payload change.
+
+**SDK consumers must:** treat the prefix as opaque. Type definitions in `@spree/admin-sdk` use a branded string (`type CustomerId = string & { __brand: 'CustomerId' }`), so the `cus_` → `cust_` swap in 6.0 is invisible at the type level.
+
+### Out of scope for 5.5
+
+These are reserved in `6.0-admin-api.md` and the EU compliance plan; do not implement them in 5.5:
+
+- `POST /api/v3/admin/customers/:id/anonymize` (Phase 2 GDPR — `5.4-6.0-eu-legal-compliance.md` §1.9)
+- `GET /api/v3/admin/customers/:id/export` (Phase 2 GDPR — same plan §1.8)
+- `POST /api/v3/admin/customers/:id/send_invite` (no spec, no design — defer)
+- `POST /api/v3/admin/customers/bulk` / `bulk_update` / `bulk_destroy` (per `6.0-admin-api.md` Open Questions)
+- `/api/v3/admin/customer_groups/*` and `/customer_groups/:id/members` (already listed in `6.0-admin-api.md` lines 535-545; ship after 5.5 in their own PR)
+- `GET /api/v3/admin/newsletter_subscribers` (`6.0-admin-api.md` lines 548-549; separate)
+- Customer segmentation (Shopify-style; not on Spree roadmap)
+- Marketing consent opt-in level + collection source (Shopify-style; deferred — `accepts_email_marketing` boolean is enough for MVP)
+- Tax-exempt customer flag (B2B `6.0-channels-catalogs-b2b.md` owns it via Company)
+- Avatar in payload (UI-only need, deferred to admin SPA plan)
+
+## Migration Path
+
+This is a new endpoint family. No backfills, no data migration.
+
+1. **Extend `Spree::User` whitelisted ransack attributes** with `phone`, `created_at`, `last_sign_in_at`, `tags` (already includes the rest). Add scopes `with_min_total_spent`, `registered`, `guest`. One PR.
+2. **Extend `Spree::Api::V3::Admin::CustomerSerializer`** with the new fields above. Run typelizer + zod regeneration per CLAUDE.md pipeline.
+3. **Add `Spree::Api::V3::Admin::CustomersController`** inheriting from `ResourceController`. Override `model_class`, `serializer_class`, `scope` (filter to current_store via order or role join), `permitted_params` (use `Spree::PermittedAttributes.user_attributes`).
+4. **Add `Spree::Api::V3::Admin::Customers::AddressesController`** (`/customers/:customer_id/addresses`). Uses existing `Spree::PermittedAttributes.address_attributes`. Implements default-flag rotation in a service `Spree::Customers::SetDefaultAddress`.
+5. **Add `Spree::Api::V3::Admin::Customers::StoreCreditsController`** (`/customers/:customer_id/store_credits`). Existing serializer is reusable.
+6. **Add cache key `customer/:id/stats`** with 5-minute TTL for the computed `orders_count`, `total_spent`, `last_order_completed_at` triple. Bust on `order.completed`, `order.canceled`, `order.refunded` events via subscriber.
+7. **Add SDK resources** in `@spree/admin-sdk`: `client.customers.list/retrieve/create/update/destroy`, `client.customers.addresses.{list,create,update,destroy}`, `client.customers.storeCredits.{list,retrieve,create,update,destroy}`.
+8. **Flip the seven checkboxes** in `6.0-admin-api.md` lines 503-507, 514-517, 520-524 as endpoints ship.
+
+## Constraints on Current Work
+
+- **Use `Spree.user_class`** in controller code; do not hardcode `Spree::User` or `Spree::Customer`. The 6.0 rename swaps the constant.
+- **Never expose `encrypted_password`, `password_salt`, `reset_password_token`, `confirmation_token`, `unlock_token`** in any serializer.
+- **Never write to `bill_address_id` / `ship_address_id` directly from a customer-payload PATCH.** Always go through the address PATCH path. This keeps the audit cleaner and matches how the storefront writes default addresses.
+- **Address validation is server-side only.** The SDK does not pre-validate; expect 422 with field-level errors.
+- **All datetimes are ISO 8601 UTC strings** with the `iso8601` Alba directive.
+- **`total_spent` is a string**, per `Alba :oj_rails` BigDecimal-as-string convention.
+- **List endpoint must use `accessible_by(current_ability, :show)`** before any other scoping — admin role gating is upstream of store filtering.
+
+## Open Questions
+
+1. **Store filtering scope.** What's the right "this customer belongs to this store" rule? Candidates: (a) has any order in the store, (b) is in any `CustomerGroup` scoped to the store, (c) has a store-scoped role. Today all three exist. **Proposed:** `current_store.users` association = `has_many :through` orders + groups + roles, cached. Implement once and reuse.
+2. **Welcome / invitation email on POST.** Saleor passes `redirectUrl`. Shopify has `send_invite`. Spree's pattern is "do nothing automatic; merchant calls password-reset endpoint." Confirm or revise.
+3. **`internal_note_html` direction.** ActionText is being phased out (`6.0-rich-text-descriptions.md`). For 5.5, do we accept ActionText storage but expose `internal_note_html` (sanitised) as the API contract? **Proposed:** yes — same shape as products' `description_html`.
+4. **Order count + spend cache invalidation.** A subscriber on `order.*` events keying off `customer_id` is straightforward. Confirm event payload includes `prefixed_id` so the cache key matches.
+5. **Tags write semantics.** Replace vs append? Shopify replaces. Vendure has separate `add`/`remove` mutations. **Proposed:** `tags: [...]` in PATCH replaces the full set. Concise, matches our flat-JSON convention.
+
+## References
+
+- `docs/plans/6.0-admin-api.md` — endpoint placeholders this plan fills in (lines 502-525)
+- `docs/plans/6.0-platform-auth.md` — `Spree.user_class` → `Spree.customer_class`, `cus_` → `cust_` prefix
+- `docs/plans/5.4-6.0-eu-legal-compliance.md` — marketing-consent timestamp, deferred anonymise/export endpoints
+- `docs/plans/5.4-store-api-naming-standardization.md` — address field renames already applied
+- `spree/api/app/serializers/spree/api/v3/customer_serializer.rb` — Store API base (read-only reference)
+- `spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb` — current admin serializer to extend
+- `spree/api/app/serializers/spree/api/v3/admin/address_serializer.rb` — sub-resource serializer (already exists)
+- `spree/api/app/serializers/spree/api/v3/admin/store_credit_serializer.rb` — sub-resource serializer (already exists)
+- `spree/core/app/models/concerns/spree/user_methods.rb` — model concern, ransack whitelist, `has_prefix_id :cus`
+- `spree/core/lib/spree/permitted_attributes.rb` lines 300-303 — `user_attributes` allowlist (reuse as-is)
+- Shopify Admin REST customer reference, Admin GraphQL Customer type, Medusa v2 admin customer SDK, Vendure Customer GraphQL type, Saleor User GraphQL type — competitor study sources
diff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.md
index ccc0d791ce..b71357395b 100644
--- a/docs/plans/6.0-admin-api.md
+++ b/docs/plans/6.0-admin-api.md
@@ -409,11 +409,12 @@ Managed via nested variant params — no standalone endpoints.
> **6.0:** Order state machine dropped (derived status from line items + fulfillments + payments — see `6.0-cart-order-split.md`). `PATCH /next` and `/advance` no longer apply and have been removed from the 5.x admin API ahead of the 6.0 cart/order split. Cart and Order are separate models; `LineItem.owner` is polymorphic. Order gains `channel_id`, `company_location_id`, `withdrawal_eligible_until` FKs.
-### Line Items (nested under Orders)
-- [x] `GET /api/v3/admin/orders/:order_id/line_items`
-- [x] `POST /api/v3/admin/orders/:order_id/line_items`
-- [x] `PATCH /api/v3/admin/orders/:order_id/line_items/:id`
-- [x] `DELETE /api/v3/admin/orders/:order_id/line_items/:id`
+### Items (nested under Orders — matches Store API `/carts/:id/items` convention)
+- [x] `GET /api/v3/admin/orders/:order_id/items`
+- [x] `GET /api/v3/admin/orders/:order_id/items/:id`
+- [x] `POST /api/v3/admin/orders/:order_id/items`
+- [x] `PATCH /api/v3/admin/orders/:order_id/items/:id`
+- [x] `DELETE /api/v3/admin/orders/:order_id/items/:id`
### Fulfillments (nested under Orders; replaces Shipments)
- [x] `GET /api/v3/admin/orders/:order_id/fulfillments`
@@ -430,10 +431,12 @@ Managed via nested variant params — no standalone endpoints.
### Payments (nested under Orders)
- [x] `GET /api/v3/admin/orders/:order_id/payments`
- [x] `GET /api/v3/admin/orders/:order_id/payments/:id`
-- [x] `POST /api/v3/admin/orders/:order_id/payments`
+- [x] `POST /api/v3/admin/orders/:order_id/payments` — supports off-session admin charges via `source_id` (saved `Spree::CreditCard` belonging to the order's customer)
- [x] `PATCH /api/v3/admin/orders/:order_id/payments/:id/capture`
- [x] `PATCH /api/v3/admin/orders/:order_id/payments/:id/void`
+> **Off-session charges:** pass `{ payment_method_id, source_id, amount }` to charge a saved card. There is no separate "PaymentSession" endpoint on the admin side — the cart/store API has `payment_sessions` for SCA/3DS storefront flows; admin-initiated charges use saved sources directly.
+
### Refunds (nested under Orders)
- [x] `GET /api/v3/admin/orders/:order_id/refunds`
- [x] `POST /api/v3/admin/orders/:order_id/refunds` — with `payment_id` in body
@@ -457,8 +460,18 @@ Managed via nested variant params — no standalone endpoints.
> **6.0:** Polymorphic `Spree::Adjustment` is dropped. Tax, discount, and fee data is returned via typed, read-only endpoints. See `6.0-split-adjustments.md`.
### Order Customer Assignment
-- [ ] `PUT /api/v3/admin/orders/:order_id/customer` — assign customer
-- [ ] `DELETE /api/v3/admin/orders/:order_id/customer` — remove customer
+
+Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id` endpoint with `customer_id` in the body. No dedicated endpoint. Pass `customer_id: null` to unassign.
+
+- [x] `PATCH /api/v3/admin/orders/:id { customer_id }` — assign / reassign / unassign customer (5.x bridge: also accepts `user_id`)
+
+### Order Gift Cards (nested under Orders)
+- [x] `POST /api/v3/admin/orders/:order_id/gift_cards { code }` — apply a gift card by code
+- [x] `DELETE /api/v3/admin/orders/:order_id/gift_cards/:id` — remove the applied gift card
+
+### Order Store Credits (nested under Orders)
+- [x] `POST /api/v3/admin/orders/:order_id/store_credits { amount? }` — apply customer's available store credit (auto up to balance, or a specific `amount`)
+- [x] `DELETE /api/v3/admin/orders/:order_id/store_credits` — remove store credit application
### Order Discounts (promotion application)
- [ ] `POST /api/v3/admin/orders/:order_id/discounts` — apply promotion or coupon
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index d7d7deef5b..5669b24669 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -73,7 +73,13 @@ import type { Store, Product, Order, Media, Category, TaxCategory, Country, Vari
import type {
StoreUpdateParams,
ProductUpdateParams,
+ OrderCreateParams,
OrderUpdateParams,
+ OrderCompleteParams,
+ OrderCancelParams,
+ OrderApproveParams,
+ GiftCardApplyParams,
+ StoreCreditApplyParams,
MediaCreateParams,
MediaUpdateParams,
LineItemCreateParams,
@@ -194,24 +200,55 @@ export class AdminClient {
params: getParams(params),
}),
+ create: (params: OrderCreateParams, options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('POST', '/orders', { ...options, body: params }),
+
update: (id: string, params: OrderUpdateParams | Record<string, unknown>, options?: RequestOptions): Promise<Order> =>
this.request<Order>('PATCH', `/orders/${id}`, { ...options, body: params }),
- cancel: (id: string, options?: RequestOptions): Promise<Order> =>
- this.request<Order>('PATCH', `/orders/${id}/cancel`, options),
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/orders/${id}`, options),
+
+ complete: (id: string, params?: OrderCompleteParams, options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('PATCH', `/orders/${id}/complete`, { ...options, body: params }),
+
+ cancel: (id: string, params?: OrderCancelParams, options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('PATCH', `/orders/${id}/cancel`, { ...options, body: params }),
+
+ approve: (id: string, params?: OrderApproveParams, options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('PATCH', `/orders/${id}/approve`, { ...options, body: params }),
+
+ resume: (id: string, options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('PATCH', `/orders/${id}/resume`, options),
resendConfirmation: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('POST', `/orders/${id}/resend_confirmation`, options),
- lineItems: {
+ giftCards: {
+ apply: (orderId: string, params: GiftCardApplyParams, options?: RequestOptions): Promise<unknown> =>
+ this.request('POST', `/orders/${orderId}/gift_cards`, { ...options, body: params }),
+
+ remove: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/orders/${orderId}/gift_cards/${id}`, options),
+ },
+
+ storeCredits: {
+ apply: (orderId: string, params?: StoreCreditApplyParams, options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('POST', `/orders/${orderId}/store_credits`, { ...options, body: params }),
+
+ remove: (orderId: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/orders/${orderId}/store_credits`, options),
+ },
+
+ items: {
create: (orderId: string, params: LineItemCreateParams, options?: RequestOptions): Promise<unknown> =>
- this.request('POST', `/orders/${orderId}/line_items`, { ...options, body: params }),
+ this.request('POST', `/orders/${orderId}/items`, { ...options, body: params }),
update: (orderId: string, id: string, params: LineItemUpdateParams, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/line_items/${id}`, { ...options, body: params }),
+ this.request('PATCH', `/orders/${orderId}/items/${id}`, { ...options, body: params }),
delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
- this.request<void>('DELETE', `/orders/${orderId}/line_items/${id}`, options),
+ this.request<void>('DELETE', `/orders/${orderId}/items/${id}`, options),
},
fulfillments: {
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 6afb519c62..4eda7febce 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -70,45 +70,81 @@ export interface FulfillmentUpdateParams {
selected_delivery_rate_id?: string;
}
+export interface AddressInputParams {
+ first_name?: string;
+ last_name?: string;
+ address1?: string;
+ address2?: string;
+ city?: string;
+ postal_code?: string;
+ country_iso?: string;
+ state_abbr?: string;
+ phone?: string;
+}
+
export interface OrderCreateParams {
email?: string;
+ customer_id?: string;
user_id?: string;
+ use_customer_default_address?: boolean;
currency?: string;
- channel?: string;
+ market_id?: string;
+ locale?: string;
+ customer_note?: string;
internal_note?: string;
+ metadata?: Record<string, unknown>;
+ shipping_address?: AddressInputParams;
+ shipping_address_id?: string;
+ billing_address?: AddressInputParams;
+ billing_address_id?: string;
+ items?: Array<{
+ variant_id: string;
+ quantity: number;
+ metadata?: Record<string, unknown>;
+ }>;
+ coupon_code?: string;
}
export interface OrderUpdateParams {
email?: string;
- special_instructions?: string;
+ customer_id?: string;
+ customer_note?: string;
internal_note?: string;
- channel?: string;
- ship_address?: {
- firstname?: string;
- lastname?: string;
- address1?: string;
- city?: string;
- zipcode?: string;
- country_iso?: string;
- state_abbr?: string;
- phone?: string;
- };
- bill_address?: {
- firstname?: string;
- lastname?: string;
- address1?: string;
- city?: string;
- zipcode?: string;
- country_iso?: string;
- state_abbr?: string;
- phone?: string;
- };
+ ship_address?: AddressInputParams;
+ bill_address?: AddressInputParams;
line_items?: Array<{
variant_id?: string;
quantity?: number;
}>;
}
+export interface OrderCompleteParams {
+ payment_pending?: boolean;
+ notify_customer?: boolean;
+}
+
+export interface OrderCancelParams {
+ reason?: 'customer' | 'declined' | 'fraud' | 'inventory' | 'staff' | 'other' | 'expired';
+ note?: string;
+ restock_items?: boolean;
+ refund_payments?: boolean;
+ refund_amount?: number;
+ notify_customer?: boolean;
+}
+
+export interface OrderApproveParams {
+ level?: string;
+ note?: string;
+}
+
+export interface GiftCardApplyParams {
+ code: string;
+}
+
+export interface StoreCreditApplyParams {
+ amount?: number;
+}
+
export interface DirectUploadCreateParams {
blob: {
filename: string;
diff --git a/packages/admin-sdk/src/types/generated/GiftCard.ts b/packages/admin-sdk/src/types/generated/GiftCard.ts
index 22c841fd04..c7a794c122 100644
--- a/packages/admin-sdk/src/types/generated/GiftCard.ts
+++ b/packages/admin-sdk/src/types/generated/GiftCard.ts
@@ -1,4 +1,4 @@
-// Typelizer digest d7c7d61e3b834d978f207cd7c311d3c5
+// Typelizer digest 47121a3f3103923c6389104d95eb4a23
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -18,7 +18,6 @@ interface GiftCard {
redeemed_at: string | null;
expired: boolean;
active: boolean;
- metadata: Record<string, unknown> | null;
created_at: string;
updated_at: string;
}
diff --git a/packages/admin-sdk/src/types/generated/LineItem.ts b/packages/admin-sdk/src/types/generated/LineItem.ts
index 96f55cd95a..05d399a0bb 100644
--- a/packages/admin-sdk/src/types/generated/LineItem.ts
+++ b/packages/admin-sdk/src/types/generated/LineItem.ts
@@ -1,7 +1,7 @@
-// Typelizer digest 225c8426a63ada3623bc7974910926d4
+// Typelizer digest 6e76e5b742f88ca476af53f830dd13a5
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {OptionValue, DigitalLink, Order, Variant, TaxCategory, Adjustment} from '@/types'
+import type {OptionValue, DigitalLink, Variant, TaxCategory, Adjustment} from '@/types'
interface LineItem {
id: string;
@@ -37,8 +37,6 @@ interface LineItem {
metadata: Record<string, unknown> | null;
cost_price: string | null;
tax_category_id: string | null;
- order_id: string | null;
- order?: Order;
variant?: Variant;
tax_category?: TaxCategory;
adjustments?: Array<Adjustment>;
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index 07ce167ce8..4e6ecb8f70 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 d3a5534b8bae8ed6140eeb3e4a855f65
+// Typelizer digest 3411cae469bcef40969f70ce7963aab9
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Discount, LineItem, Fulfillment, Payment, Address, GiftCard, Market, PaymentMethod, Customer, Adjustment, ReturnAuthorization, Reimbursement} from '@/types'
@@ -46,6 +46,7 @@ interface Order {
shipping_address?: Address | null;
gift_card: GiftCard | null;
market: Market | null;
+ status: string;
last_ip_address: string | null;
considered_risky: boolean;
confirmation_delivered: boolean;
diff --git a/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx b/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
index cb2f4ac64c..5788127e8e 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
@@ -161,7 +161,7 @@ function OrderHeader({ order }: { order: Order }) {
const backFallback = order.completed_at ? 'orders' : 'orders/drafts'
const cancelMutation = useOrderMutation(orderId, () =>
- adminClient.orders.cancel(orderId, {}),
+ adminClient.orders.cancel(orderId),
)
const resendMutation = useOrderMutation(orderId, () =>
adminClient.orders.resendConfirmation(orderId, {}),
@@ -206,7 +206,7 @@ function OrderHeader({ order }: { order: Order }) {
<DropdownMenuSeparator />
</>
)}
- {(order as any).state !== 'canceled' && (
+ {order.status !== 'canceled' && (
<DropdownMenuItem
className="text-destructive focus:text-destructive"
onClick={async () => {
@@ -254,7 +254,7 @@ function AddLineItemDialog({
const variants = variantsData?.data ?? []
const mutation = useOrderMutation(orderId, (params: { variant_id: string; quantity: number }) =>
- adminClient.orders.lineItems.create(orderId, params),
+ adminClient.orders.items.create(orderId, params),
)
function handleSubmit(e: FormEvent<HTMLFormElement>) {
@@ -385,7 +385,7 @@ function EditQuantityDialog({
}) {
const mutation = useOrderMutation(orderId, (params: { quantity: number }) =>
- adminClient.orders.lineItems.update(orderId, lineItemId, params),
+ adminClient.orders.items.update(orderId, lineItemId, params),
)
function handleSubmit(e: FormEvent<HTMLFormElement>) {
@@ -442,7 +442,7 @@ function LineItemsCard({ order }: { order: Order }) {
const [editItem, setEditItem] = useState<{ id: string; quantity: number } | null>(null)
const deleteMutation = useOrderMutation(orderId, (lineItemId: string) =>
- adminClient.orders.lineItems.delete(orderId, lineItemId),
+ adminClient.orders.items.delete(orderId, lineItemId),
)
return (
diff --git a/packages/admin/src/tables/orders.tsx b/packages/admin/src/tables/orders.tsx
index 5b8e0cff7f..d36f3dd2c3 100644
--- a/packages/admin/src/tables/orders.tsx
+++ b/packages/admin/src/tables/orders.tsx
@@ -102,24 +102,18 @@ defineTable('orders', {
render: (order) => order.display_total ?? '—',
},
{
- key: 'state',
- label: 'State',
+ key: 'status',
+ label: 'Status',
sortable: true,
filterable: true,
default: false,
filterType: 'status',
filterOptions: [
- { value: 'cart', label: 'Cart' },
- { value: 'address', label: 'Address' },
- { value: 'delivery', label: 'Delivery' },
- { value: 'payment', label: 'Payment' },
- { value: 'confirm', label: 'Confirm' },
- { value: 'complete', label: 'Complete' },
+ { value: 'draft', label: 'Draft' },
+ { value: 'placed', label: 'Placed' },
{ value: 'canceled', label: 'Canceled' },
- { value: 'returned', label: 'Returned' },
- { value: 'resumed', label: 'Resumed' },
],
- render: (order) => <StatusBadge status={order.state} />,
+ render: (order) => <StatusBadge status={order.status} />,
},
{
key: 'created_at',
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/gift_cards_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/gift_cards_controller.rb
new file mode 100644
index 0000000000..2af7b7dbf7
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/gift_cards_controller.rb
@@ -0,0 +1,77 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ class GiftCardsController < BaseController
+ skip_before_action :set_resource, raise: false
+
+ # POST /api/v3/admin/orders/:order_id/gift_cards
+ #
+ # Body: { code: String }
+ def create
+ with_order_lock do
+ gift_card = find_gift_card!
+ return unless gift_card
+
+ result = @parent.apply_gift_card(gift_card)
+
+ if result.success?
+ render json: serializer_class.new(gift_card).to_h, status: :created
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ # DELETE /api/v3/admin/orders/:order_id/gift_cards/:id
+ def destroy
+ with_order_lock do
+ result = @parent.remove_gift_card
+
+ if result.success?
+ head :no_content
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::GiftCard
+ end
+
+ def serializer_class
+ Spree.api.admin_gift_card_serializer
+ end
+
+ private
+
+ def find_gift_card!
+ gift_card = current_store.gift_cards.find_by(code: params[:code]&.downcase)
+
+ if gift_card.nil?
+ render_error(code: ERROR_CODES[:gift_card_not_found], message: Spree.t(:gift_card_not_found), status: :not_found)
+ return
+ end
+
+ if gift_card.expired?
+ render_error(code: ERROR_CODES[:gift_card_expired], message: Spree.t(:gift_card_expired), status: :unprocessable_content)
+ return
+ end
+
+ if gift_card.redeemed?
+ render_error(code: ERROR_CODES[:gift_card_already_redeemed], message: Spree.t(:gift_card_already_redeemed), status: :unprocessable_content)
+ return
+ end
+
+ gift_card
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/line_items_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rb
similarity index 91%
rename from spree/api/app/controllers/spree/api/v3/admin/orders/line_items_controller.rb
rename to spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rb
index cdf6921c72..965a651b94 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/orders/line_items_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rb
@@ -3,8 +3,8 @@ module Spree
module V3
module Admin
module Orders
- class LineItemsController < BaseController
- # POST /api/v3/admin/orders/:order_id/line_items
+ class ItemsController < BaseController
+ # POST /api/v3/admin/orders/:order_id/items
def create
with_order_lock do
result = Spree.cart_add_item_service.call(
@@ -22,7 +22,7 @@ module Spree
end
end
- # PATCH /api/v3/admin/orders/:order_id/line_items/:id
+ # PATCH /api/v3/admin/orders/:order_id/items/:id
def update
with_order_lock do
if permitted_params[:quantity].present?
@@ -47,7 +47,7 @@ module Spree
end
end
- # DELETE /api/v3/admin/orders/:order_id/line_items/:id
+ # DELETE /api/v3/admin/orders/:order_id/items/:id
def destroy
with_order_lock do
Spree.cart_remove_line_item_service.call(
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb
index 63fc479891..85a1499603 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb
@@ -7,16 +7,20 @@ module Spree
before_action :set_resource, only: [:show, :capture, :void]
# POST /api/v3/admin/orders/:order_id/payments
+ #
+ # Supports off-session admin charges by passing `source_id` referencing a
+ # saved payment source (e.g. a Spree::CreditCard owned by the order's customer).
+ # The source must belong to the customer assigned to the order.
def create
with_order_lock do
- payment_method = Spree::PaymentMethod.find(params[:payment_method_id])
+ payment_method = Spree::PaymentMethod.find_by_prefix_id!(params[:payment_method_id])
@resource = @parent.payments.build(
amount: params[:amount] || @parent.order_total_after_store_credit,
payment_method: payment_method
)
if params[:source_id].present? && payment_method.source_required?
- @resource.source = payment_method.payment_source_class.find_by_prefix_id!(params[:source_id])
+ @resource.source = find_source!(payment_method, params[:source_id])
end
authorize_resource!(@resource, :create)
@@ -67,6 +71,15 @@ module Spree
def permitted_params
params.permit(*Spree::PermittedAttributes.payment_attributes, :source_id)
end
+
+ # Saved-source charges require an order customer — sources are scoped
+ # to that customer to prevent attaching customer A's card to
+ # customer B's order. Refuse if no customer is assigned.
+ def find_source!(payment_method, source_id)
+ raise ActiveRecord::RecordNotFound unless @parent.user
+
+ @parent.user.credit_cards.find_by_prefix_id!(source_id)
+ end
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/store_credits_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/store_credits_controller.rb
new file mode 100644
index 0000000000..aa6cff7429
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/store_credits_controller.rb
@@ -0,0 +1,57 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ class StoreCreditsController < BaseController
+ skip_before_action :set_resource, raise: false
+
+ # POST /api/v3/admin/orders/:order_id/store_credits
+ #
+ # Body: { amount: Number (optional) }
+ #
+ # When `amount` is omitted, applies the customer's available store
+ # credit up to the order total.
+ def create
+ with_order_lock do
+ result = Spree.checkout_add_store_credit_service.call(
+ order: @parent,
+ amount: params[:amount].try(:to_f)
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ # DELETE /api/v3/admin/orders/:order_id/store_credits
+ def destroy
+ with_order_lock do
+ result = Spree.checkout_remove_store_credit_service.call(order: @parent)
+
+ if result.success?
+ head :no_content
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Order
+ end
+
+ def serializer_class
+ Spree.api.admin_order_serializer
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb
index 74665cd98c..11c11ebebd 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb
@@ -12,11 +12,10 @@ module Spree
def create
authorize!(:create, Spree::Order)
- result = Spree.cart_create_service.call(
- user: resolve_user,
+ result = Spree.order_create_service.call(
store: current_store,
- currency: params[:currency] || current_store.default_currency,
- order_params: order_create_params
+ user: resolve_user,
+ params: order_create_params
)
if result.success?
@@ -30,10 +29,15 @@ module Spree
# PATCH /api/v3/admin/orders/:id
def update
with_order_lock do
- if @resource.update(order_update_params)
- render json: serialize_resource(@resource.reload)
+ result = Spree.order_update_service.call(
+ order: @resource,
+ params: order_update_params
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value)
else
- render_validation_error(@resource.errors)
+ render_validation_error(@resource.errors.presence || result.error)
end
end
end
@@ -48,7 +52,11 @@ module Spree
# PATCH /api/v3/admin/orders/:id/complete
def complete
with_order_lock do
- result = Spree.checkout_complete_service.call(order: @resource)
+ result = Spree.order_complete_service.call(
+ order: @resource,
+ payment_pending: ActiveModel::Type::Boolean.new.cast(params[:payment_pending]),
+ notify_customer: ActiveModel::Type::Boolean.new.cast(params[:notify_customer])
+ )
if result.success?
render json: serialize_resource(@resource.reload)
@@ -127,25 +135,33 @@ module Spree
private
def resolve_user
- return unless params[:user_id].present?
+ customer_param = params[:customer_id].presence || params[:user_id].presence
+ return unless customer_param
- Spree.user_class.find_by_param!(params[:user_id])
+ Spree.user_class.find_by_param!(customer_param)
end
def order_create_params
- {
- email: params[:email],
- channel: params[:channel],
- internal_note: params[:internal_note]
- }.compact
+ params.permit(
+ :email, :customer_id, :user_id, :use_customer_default_address,
+ :currency, :market_id, :locale,
+ :customer_note, :internal_note,
+ :shipping_address_id, :billing_address_id,
+ :coupon_code,
+ metadata: {},
+ shipping_address: Spree::PermittedAttributes.address_attributes,
+ billing_address: Spree::PermittedAttributes.address_attributes,
+ items: [:variant_id, :quantity, { metadata: {} }]
+ )
end
def order_update_params
params.permit(
*Spree::PermittedAttributes.checkout_attributes,
+ :customer_id,
ship_address: Spree::PermittedAttributes.address_attributes,
bill_address: Spree::PermittedAttributes.address_attributes,
- line_items: Spree::PermittedAttributes.line_item_attributes
+ items: [:variant_id, :quantity, { metadata: {} }]
)
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/gift_card_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/gift_card_serializer.rb
index b3dc9527d6..4b027fb238 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/gift_card_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/gift_card_serializer.rb
@@ -3,12 +3,6 @@ module Spree
module V3
module Admin
class GiftCardSerializer < V3::GiftCardSerializer
- typelize metadata: 'Record<string, unknown> | null'
-
- attribute :metadata do |gift_card|
- gift_card.metadata.presence
- end
-
attributes created_at: :iso8601, updated_at: :iso8601
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb
index 918d8f202d..df27f796f0 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb
@@ -7,8 +7,7 @@ module Spree
class LineItemSerializer < V3::LineItemSerializer
typelize metadata: 'Record<string, unknown> | null',
cost_price: [:string, nullable: true],
- tax_category_id: [:string, nullable: true],
- order_id: [:string, nullable: true]
+ tax_category_id: [:string, nullable: true]
attributes created_at: :iso8601, updated_at: :iso8601
@@ -24,18 +23,10 @@ module Spree
line_item.tax_category&.prefixed_id
end
- attribute :order_id do |line_item|
- line_item.order&.prefixed_id
- end
-
# Override inherited associations to use admin serializers
many :option_values, resource: Spree.api.admin_option_value_serializer
many :digital_links, resource: Spree.api.admin_digital_link_serializer
- one :order,
- resource: Spree.api.admin_order_serializer,
- if: proc { expand?('order') }
-
one :variant,
resource: Spree.api.admin_variant_serializer,
if: proc { expand?('variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
index 3d4fbc884e..7ef5f91fba 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
@@ -6,7 +6,8 @@ module Spree
# Full order data including admin-only fields
class OrderSerializer < V3::OrderSerializer
- typelize last_ip_address: [:string, nullable: true],
+ typelize status: :string,
+ last_ip_address: [:string, nullable: true],
considered_risky: :boolean, confirmation_delivered: :boolean,
store_owner_notification_delivered: :boolean,
internal_note: [:string, nullable: true], approver_id: [:string, nullable: true],
@@ -17,7 +18,7 @@ module Spree
metadata: 'Record<string, unknown> | null'
# Admin-only attributes
- attributes :last_ip_address, :considered_risky,
+ attributes :status, :last_ip_address, :considered_risky,
:confirmation_delivered, :store_owner_notification_delivered,
:payment_total, :display_payment_total,
canceled_at: :iso8601, approved_at: :iso8601,
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index c746475d07..079d2c7570 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -145,7 +145,7 @@ Spree::Core::Engine.add_routes do
post :resend_confirmation
end
- resources :line_items, controller: 'orders/line_items'
+ resources :items, only: [:index, :show, :create, :update, :destroy], controller: 'orders/items'
resources :fulfillments, controller: 'orders/fulfillments', only: [:index, :show, :update] do
member do
patch :fulfill
@@ -162,6 +162,8 @@ Spree::Core::Engine.add_routes do
end
resources :refunds, controller: 'orders/refunds', only: [:index, :create]
resources :adjustments, controller: 'orders/adjustments', only: [:index, :show]
+ resources :gift_cards, controller: 'orders/gift_cards', only: [:create, :destroy]
+ resource :store_credits, controller: 'orders/store_credits', only: [:create, :destroy]
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/gift_cards_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/gift_cards_controller_spec.rb
new file mode 100644
index 0000000000..abbe460ddf
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/gift_cards_controller_spec.rb
@@ -0,0 +1,150 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::GiftCardsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:order_with_line_items, store: store, state: 'cart') }
+ let!(:gift_card) { create(:gift_card, store: store) }
+ let!(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'POST #create' do
+ it 'applies the gift card to the order and returns the gift card' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['id']).to eq(gift_card.prefixed_id)
+ expect(order.reload.gift_card).to eq(gift_card)
+ end
+
+ context 'when the code is provided in lowercase' do
+ it 'matches case-insensitively' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code.downcase }, as: :json
+
+ expect(response).to have_http_status(:created)
+ end
+ end
+
+ context 'when gift card code is unknown' do
+ it 'returns 404' do
+ post :create, params: { order_id: order.prefixed_id, code: 'UNKNOWN-CODE' }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ context 'when gift card belongs to a different store' do
+ let!(:other_store) { create(:store) }
+ let!(:gift_card) { create(:gift_card, store: other_store) }
+
+ it 'returns 404 (cross-store leakage prevented)' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ context 'when gift card is expired' do
+ let!(:gift_card) { create(:gift_card, store: store, expires_at: 1.day.ago) }
+
+ it 'returns 422' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when gift card is fully redeemed' do
+ let!(:gift_card) { create(:gift_card, :redeemed, store: store) }
+
+ it 'returns 422' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when the order already has store credit applied (mutual exclusion)' do
+ let(:customer) { create(:user) }
+ let!(:order) { create(:order_with_line_items, store: store, user: customer) }
+ let!(:store_credit) { create(:store_credit, store: store, user: customer, amount: 100) }
+
+ before { Spree.checkout_add_store_credit_service.call(order: order) }
+
+ it 'returns 422 (cannot mix gift card and store credit)' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when gift card currency does not match order currency' do
+ let!(:gift_card) { create(:gift_card, store: store, currency: 'EUR') }
+
+ it 'returns 422' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when gift card is restricted to a specific user but order has none' do
+ let(:gift_card_owner) { create(:user) }
+ let!(:gift_card) { create(:gift_card, store: store, user: gift_card_owner) }
+
+ it 'returns 422' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when gift card is restricted to a different user than the order' do
+ let(:gift_card_owner) { create(:user) }
+ let(:order_customer) { create(:user) }
+ let!(:order) { create(:order_with_line_items, store: store, user: order_customer) }
+ let!(:gift_card) { create(:gift_card, store: store, user: gift_card_owner) }
+
+ it 'returns 422' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when order belongs to a different store' do
+ let!(:other_store) { create(:store) }
+ let!(:order) { create(:order_with_line_items, store: other_store) }
+
+ it 'returns 404 from the parent order lookup' do
+ post :create, params: { order_id: order.prefixed_id, code: gift_card.code }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ before { order.update_column(:gift_card_id, gift_card.id) }
+
+ it 'removes the gift card from the order' do
+ delete :destroy, params: { order_id: order.prefixed_id, id: gift_card.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(order.reload.gift_card).to be_nil
+ end
+
+ context 'when the order has no gift card applied' do
+ before { order.update_column(:gift_card_id, nil) }
+
+ it 'still returns 204 (idempotent)' do
+ delete :destroy, params: { order_id: order.prefixed_id, id: gift_card.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/line_items_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb
similarity index 95%
rename from spree/api/spec/controllers/spree/api/v3/admin/orders/line_items_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb
index 6ef6c7010f..c11fb67232 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/line_items_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Admin::Orders::LineItemsController, type: :controller do
+RSpec.describe Spree::Api::V3::Admin::Orders::ItemsController, type: :controller do
render_views
include_context 'API v3 Admin authenticated'
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
index c49c6cd452..9e5b0385f7 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
@@ -28,6 +28,12 @@ RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :control
expect(json_response['id']).to eq(payment.prefixed_id)
expect(json_response['status']).to be_present
end
+
+ it 'returns 404 for unknown payment id' do
+ get :show, params: { order_id: order_with_payment.prefixed_id, id: 'pay_unknown' }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
end
describe 'POST #create' do
@@ -37,13 +43,102 @@ RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :control
it 'creates a payment' do
post :create, params: {
order_id: order.prefixed_id,
- payment_method_id: payment_method.id,
+ payment_method_id: payment_method.prefixed_id,
amount: order.total
}, as: :json
expect(response).to have_http_status(:created)
expect(json_response['status']).to be_present
end
+
+ it 'returns 404 for unknown payment_method prefixed id' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: 'pm_unknown',
+ amount: order.total
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+
+ context 'when payment_method does not require a source' do
+ it 'ignores source_id silently' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: payment_method.prefixed_id,
+ source_id: 'card_doesnt_matter',
+ amount: order.total
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ payment = order.payments.find_by_prefix_id(json_response['id'])
+ expect(payment.source).to be_nil
+ end
+ end
+
+ context 'off-session charge against a saved credit card (source_id)' do
+ let(:customer) { create(:user) }
+ let(:order) { create(:completed_order_with_totals, store: store, user: customer) }
+ let(:credit_card_method) { create(:credit_card_payment_method, stores: [store]) }
+ let(:saved_card) { create(:credit_card, user: customer, payment_method: credit_card_method) }
+
+ it 'attaches the saved card as the payment source' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: credit_card_method.prefixed_id,
+ source_id: saved_card.prefixed_id,
+ amount: order.total
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ payment = order.payments.find_by_prefix_id(json_response['id'])
+ expect(payment.source).to eq(saved_card)
+ expect(payment.payment_method).to eq(credit_card_method)
+ end
+
+ context 'when source belongs to a different customer' do
+ let(:other_customer) { create(:user) }
+ let(:other_card) { create(:credit_card, user: other_customer, payment_method: credit_card_method) }
+
+ it 'returns 404 to prevent cross-customer use' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: credit_card_method.prefixed_id,
+ source_id: other_card.prefixed_id,
+ amount: order.total
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(order.reload.payments.count).to eq(0)
+ end
+ end
+
+ context 'with invalid source prefix id' do
+ it 'returns 404' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: credit_card_method.prefixed_id,
+ source_id: 'card_doesnt_exist',
+ amount: order.total
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ context 'when amount is missing' do
+ it 'defaults to order total after store credit' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: payment_method.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ payment = order.payments.find_by_prefix_id(json_response['id'])
+ expect(payment.amount).to eq(order.order_total_after_store_credit)
+ end
+ end
end
describe 'PATCH #capture' do
@@ -59,6 +154,20 @@ RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :control
expect(response).to have_http_status(:ok)
end
+
+ context 'when payment is already completed' do
+ before { payment.update_column(:state, 'completed') }
+
+ it 'is a no-op (state machine treats this as success)' do
+ patch :capture, params: {
+ order_id: order_with_payment.prefixed_id,
+ id: payment.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(payment.reload.state).to eq('completed')
+ end
+ end
end
describe 'PATCH #void' do
@@ -70,5 +179,19 @@ RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :control
expect(response).to have_http_status(:ok)
end
+
+ context 'when payment is already voided' do
+ before { payment.update_column(:state, 'void') }
+
+ it 'is a no-op (state machine treats this as success)' do
+ patch :void, params: {
+ order_id: order_with_payment.prefixed_id,
+ id: payment.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(payment.reload.state).to eq('void')
+ end
+ end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb
new file mode 100644
index 0000000000..9bec35c47f
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb
@@ -0,0 +1,99 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::StoreCreditsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let(:customer) { create(:user) }
+ let!(:order) { create(:order_with_line_items, store: store, user: customer) }
+ let!(:store_credit) { create(:store_credit, store: store, user: customer, amount: 50.00) }
+ let!(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'POST #create' do
+ it 'applies store credit to the order' do
+ post :create, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(order.reload.payments.store_credits.any?).to be true
+ end
+
+ context 'with explicit amount' do
+ it 'applies up to the requested amount' do
+ post :create, params: { order_id: order.prefixed_id, amount: 5.00 }, as: :json
+
+ expect(response).to have_http_status(:created)
+ applied = order.reload.payments.store_credits.sum(:amount)
+ expect(applied).to eq(5.00)
+ end
+ end
+
+ context 'when explicit amount exceeds available balance' do
+ it 'caps at the available store credit balance' do
+ post :create, params: { order_id: order.prefixed_id, amount: 9999.99 }, as: :json
+
+ expect(response).to have_http_status(:created)
+ applied = order.reload.payments.store_credits.sum(:amount)
+ # Available balance ($50), capped at order outstanding ($110), so $50 applies
+ expect(applied).to eq(store_credit.amount)
+ end
+ end
+
+ context 'when the customer has no store credit balance' do
+ let(:customer) { create(:user) }
+ let!(:store_credit) { nil }
+
+ it 'returns 422' do
+ post :create, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when the order has no customer' do
+ let!(:order) { create(:order_with_line_items, store: store, user: nil) }
+
+ it 'returns 422 (no customer means no store credit)' do
+ post :create, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when order belongs to a different store' do
+ let!(:other_store) { create(:store) }
+ let!(:order) { create(:order_with_line_items, store: other_store, user: customer) }
+
+ it 'returns 404' do
+ post :create, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ context 'when store credit was applied' do
+ before do
+ Spree.checkout_add_store_credit_service.call(order: order)
+ end
+
+ it 'removes store credit from the order' do
+ delete :destroy, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(order.reload.payments.store_credits.valid).to be_empty
+ end
+ end
+
+ context 'when no store credit was applied' do
+ it 'returns 204 (idempotent)' do
+ delete :destroy, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb
index c5ae362384..261789166b 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb
@@ -98,7 +98,7 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
expect(json_response['email']).to eq('[email protected]')
end
- context 'with user assignment' do
+ context 'with user assignment via user_id' do
let(:customer) { create(:user) }
let(:create_params) { { user_id: customer.prefixed_id } }
@@ -110,6 +110,89 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
expect(created_order.user).to eq(customer)
end
end
+
+ context 'with customer assignment via customer_id' do
+ let(:customer) { create(:user) }
+ let(:create_params) { { customer_id: customer.prefixed_id } }
+
+ it 'creates order assigned to the customer' do
+ subject
+
+ expect(response).to have_http_status(:created)
+ created_order = Spree::Order.find_by_prefix_id(json_response['id'])
+ expect(created_order.user).to eq(customer)
+ end
+ end
+
+ context 'with inline items' do
+ let(:variant) { create(:variant, prices: [build(:price, currency: 'USD', amount: 19.99)]) }
+ let(:create_params) do
+ {
+ email: '[email protected]',
+ items: [{ variant_id: variant.prefixed_id, quantity: 3 }]
+ }
+ end
+
+ it 'creates the order with the line items' do
+ subject
+
+ expect(response).to have_http_status(:created)
+ created = Spree::Order.find_by_prefix_id(json_response['id'])
+ expect(created.line_items.count).to eq(1)
+ expect(created.line_items.first.variant).to eq(variant)
+ expect(created.line_items.first.quantity).to eq(3)
+ end
+ end
+
+ context 'with use_customer_default_address' do
+ let(:address) { create(:address) }
+ let(:customer) { create(:user, bill_address: address, ship_address: address) }
+ let(:create_params) do
+ {
+ customer_id: customer.prefixed_id,
+ use_customer_default_address: true
+ }
+ end
+
+ it 'copies the customer default addresses onto the order' do
+ subject
+
+ expect(response).to have_http_status(:created)
+ created = Spree::Order.find_by_prefix_id(json_response['id'])
+ expect(created.bill_address).to be_present
+ expect(created.ship_address).to be_present
+ expect(created.bill_address.address1).to eq(address.address1)
+ end
+ end
+
+ context 'with metadata' do
+ let(:create_params) do
+ {
+ email: '[email protected]',
+ metadata: { external_reference: 'subscription-12345', source: 'recurring' }
+ }
+ end
+
+ it 'stores metadata on the order' do
+ subject
+
+ expect(response).to have_http_status(:created)
+ created = Spree::Order.find_by_prefix_id(json_response['id'])
+ expect(created.metadata['external_reference']).to eq('subscription-12345')
+ expect(created.metadata['source']).to eq('recurring')
+ end
+ end
+
+ context 'creates order with status draft' do
+ it 'sets status to draft' do
+ subject
+
+ expect(response).to have_http_status(:created)
+ created = Spree::Order.find_by_prefix_id(json_response['id'])
+ expect(created.status).to eq('draft')
+ expect(created.completed_at).to be_nil
+ end
+ end
end
describe 'PATCH #update' do
@@ -123,6 +206,31 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
expect(response).to have_http_status(:ok)
expect(json_response['email']).to eq('[email protected]')
end
+
+ context 'with customer assignment via customer_id' do
+ let(:customer) { create(:user) }
+
+ it 'assigns the customer' do
+ patch :update, params: { id: order.prefixed_id, customer_id: customer.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(order.reload.user).to eq(customer)
+ expect(json_response['customer_id']).to eq(customer.prefixed_id)
+ end
+ end
+
+ context 'with customer reassignment via customer_id' do
+ let(:original_customer) { create(:user) }
+ let(:new_customer) { create(:user) }
+ let!(:order) { create(:order, store: store, state: 'cart', user: original_customer) }
+
+ it 'reassigns to the new customer' do
+ patch :update, params: { id: order.prefixed_id, customer_id: new_customer.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(order.reload.user).to eq(new_customer)
+ end
+ end
end
describe 'DELETE #destroy' do
@@ -145,6 +253,52 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
end
end
+ describe 'PATCH #complete' do
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+
+ before { request.headers.merge!(headers) }
+
+ it 'completes the order' do
+ patch :complete, params: { id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(order.reload.completed_at).to be_present
+ end
+
+ it 'accepts payment_pending flag without re-processing payments' do
+ patch :complete, params: { id: order.prefixed_id, payment_pending: true }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(order.reload.completed_at).to be_present
+ end
+
+ it 'passes notify_customer flag to the service' do
+ service_double = instance_double(Spree::Orders::Complete)
+ allow(Spree).to receive(:order_complete_service).and_return(service_double)
+ expect(service_double).to receive(:call).with(
+ hash_including(order: order, notify_customer: true)
+ ).and_return(Spree::ServiceModule::Result.new(true, order, nil))
+
+ patch :complete, params: { id: order.prefixed_id, notify_customer: true }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ it 'omits notify_customer when not given (service defaults to false)' do
+ service_double = instance_double(Spree::Orders::Complete)
+ allow(Spree).to receive(:order_complete_service).and_return(service_double)
+ expect(service_double).to receive(:call) do |args|
+ expect(args[:notify_customer]).to be_nil # service default kicks in (false)
+ expect(args[:order]).to eq(order)
+ Spree::ServiceModule::Result.new(true, order, nil)
+ end
+
+ patch :complete, params: { id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+
describe 'PATCH #cancel' do
let!(:order) { create(:completed_order_with_totals, store: store) }
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb
index b948b85edf..218ff6f7d6 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb
@@ -2,7 +2,10 @@
require 'swagger_helper'
-RSpec.describe 'Admin Order Adjustments API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+# NOTE: This spec exercises the API but is excluded from the OpenAPI doc until 6.0
+# typed adjustments split (TaxLine/Discount/Fee) is finalized.
+# See docs/plans/6.0-split-adjustments.md.
+RSpec.describe 'Admin Order Adjustments API', type: :request do
include_context 'API v3 Admin'
let!(:order) { create(:order, store: store, state: 'cart') }
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rb
new file mode 100644
index 0000000000..c65be28373
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rb
@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Gift Cards API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order_with_line_items, store: store, state: 'cart') }
+ let!(:gift_card) { create(:gift_card, store: store) }
+ let!(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/gift_cards' do
+ let(:order_id) { order.prefixed_id }
+
+ post 'Apply a gift card to an order' do
+ tags 'Order Gift Cards'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Applies a gift card by code to the order. Returns the gift card.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[code],
+ properties: {
+ code: { type: :string, description: 'Gift card code', example: 'GIFT-XXXX-YYYY' }
+ }
+ }
+
+ response '201', 'gift card applied' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { code: gift_card.code } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(gift_card.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/gift_cards/{id}' do
+ let(:order_id) { order.prefixed_id }
+ let(:id) { gift_card.prefixed_id }
+
+ delete 'Remove a gift card from an order' do
+ tags 'Order Gift Cards'
+ security [api_key: [], bearer_auth: []]
+ description 'Removes the gift card from the order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Gift card prefixed ID'
+
+ response '204', 'gift card removed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ before { order.update_column(:gift_card_id, gift_card.id) }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/line_items_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rb
similarity index 85%
rename from spree/api/spec/integration/spree/api/v3/admin/orders/line_items_spec.rb
rename to spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rb
index c71f07c779..58cf3bf317 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders/line_items_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rb
@@ -11,11 +11,11 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
let!(:line_item) { create(:line_item, order: order, variant: variant, quantity: 2) }
let(:Authorization) { "Bearer #{admin_jwt_token}" }
- path '/api/v3/admin/orders/{order_id}/line_items' do
+ path '/api/v3/admin/orders/{order_id}/items' do
let(:order_id) { order.prefixed_id }
- get 'List line items' do
- tags 'Line Items'
+ get 'List order items' do
+ tags 'Orders'
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns all line items for an order.'
@@ -26,7 +26,7 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
parameter name: :order_id, in: :path, type: :string, required: true,
description: 'Order prefixed ID'
- response '200', 'line items found' do
+ response '200', 'items found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
run_test! do |response|
@@ -37,8 +37,8 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
end
end
- post 'Add a line item' do
- tags 'Line Items'
+ post 'Add an item' do
+ tags 'Orders'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
@@ -58,7 +58,7 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
}
}
- response '201', 'line item added' do
+ response '201', 'item added' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
let(:new_variant) { create(:variant, product: create(:product, stores: [store])) }
let(:body) { { variant_id: new_variant.prefixed_id, quantity: 3 } }
@@ -71,12 +71,12 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
end
end
- path '/api/v3/admin/orders/{order_id}/line_items/{id}' do
+ path '/api/v3/admin/orders/{order_id}/items/{id}' do
let(:order_id) { order.prefixed_id }
let(:id) { line_item.prefixed_id }
- get 'Show a line item' do
- tags 'Line Items'
+ get 'Show an item' do
+ tags 'Orders'
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns details of a specific line item.'
@@ -87,9 +87,9 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
parameter name: :order_id, in: :path, type: :string, required: true,
description: 'Order prefixed ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Line item prefixed ID'
+ description: 'Item prefixed ID'
- response '200', 'line item found' do
+ response '200', 'item found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
run_test! do |response|
@@ -99,12 +99,12 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
end
end
- patch 'Update a line item' do
- tags 'Line Items'
+ patch 'Update an item' do
+ tags 'Orders'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Updates a line item quantity or metadata.'
+ description 'Updates an order item quantity or metadata.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -112,7 +112,7 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
parameter name: :order_id, in: :path, type: :string, required: true,
description: 'Order prefixed ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Line item prefixed ID'
+ description: 'Item prefixed ID'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -120,7 +120,7 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
}
}
- response '200', 'line item updated' do
+ response '200', 'item updated' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
let(:body) { { quantity: 5 } }
@@ -131,10 +131,10 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
end
end
- delete 'Remove a line item' do
- tags 'Line Items'
+ delete 'Remove an item' do
+ tags 'Orders'
security [api_key: [], bearer_auth: []]
- description 'Removes a line item from the order.'
+ description 'Removes an item from the order.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -142,7 +142,7 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-r
parameter name: :order_id, in: :path, type: :string, required: true,
description: 'Order prefixed ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Line item prefixed ID'
+ description: 'Item prefixed ID'
response '204', 'line item removed' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb
index 826ba84191..97b744797b 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb
@@ -51,7 +51,7 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-ref
type: :object,
required: %w[payment_method_id],
properties: {
- payment_method_id: { type: :string, description: 'Payment method ID or prefixed ID' },
+ payment_method_id: { type: :string, description: 'Payment method prefixed ID' },
amount: { type: :number, example: 99.99 },
source_id: { type: :string, description: 'Payment source prefixed ID' }
}
@@ -62,7 +62,7 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-ref
let(:order_without_payment) { create(:completed_order_with_totals, store: store) }
let(:order_id) { order_without_payment.prefixed_id }
let(:payment_method) { create(:check_payment_method, stores: [store]) }
- let(:body) { { payment_method_id: payment_method.id, amount: order_without_payment.total } }
+ let(:body) { { payment_method_id: payment_method.prefixed_id, amount: order_without_payment.total } }
run_test! do |response|
data = JSON.parse(response.body)
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rb
new file mode 100644
index 0000000000..56c628925b
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rb
@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Store Credits API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:customer) { create(:user) }
+ let!(:order) { create(:order_with_line_items, store: store, user: customer) }
+ let!(:store_credit) { create(:store_credit, store: store, user: customer, amount: 50.00) }
+ let!(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/store_credits' do
+ let(:order_id) { order.prefixed_id }
+
+ post "Apply customer's store credit to an order" do
+ tags 'Order Store Credits'
+ consumes 'application/json'
+ produces 'application/json'
+ 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.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ amount: { type: :number, description: 'Optional explicit amount; defaults to order outstanding balance' }
+ }
+ }
+
+ response '201', 'store credit applied' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { {} }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(order.prefixed_id)
+ end
+ end
+ end
+
+ delete "Remove store credit from an order" do
+ tags 'Order Store Credits'
+ security [api_key: [], bearer_auth: []]
+ description "Removes any applied store credit from the order."
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+
+ response '204', 'store credit removed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ before { Spree.checkout_add_store_credit_service.call(order: order) }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb
index c055f74d15..3d895916fa 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb
@@ -56,7 +56,13 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Creates a new draft order. Optionally assign a user and set initial attributes.'
+ description <<~DESC
+ Creates a new draft order in one shot. Customer, items, addresses, currency,
+ market, locale, notes, metadata, and a coupon code can all be provided inline.
+
+ Invalid coupon codes are non-fatal — the order is created and the failure
+ is reported on the service result (not in the API response body for now).
+ DESC
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -65,10 +71,47 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
type: :object,
properties: {
email: { type: :string, example: '[email protected]' },
- user_id: { type: :string, description: 'Prefixed user ID to assign' },
+ customer_id: { type: :string, description: 'Customer prefixed 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, example: 'USD' },
- channel: { type: :string, example: 'admin' },
- internal_note: { type: :string }
+ market_id: { type: :string, description: 'Market prefixed ID' },
+ locale: { type: :string, example: 'en-US' },
+ 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 prefixed 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 prefixed ID' },
+ items: {
+ type: :array,
+ items: {
+ type: :object,
+ required: %w[variant_id quantity],
+ properties: {
+ variant_id: { type: :string, description: 'Variant prefixed ID' },
+ quantity: { type: :integer, example: 1 },
+ metadata: { type: :object }
+ }
+ }
+ },
+ coupon_code: { type: :string, description: 'Optional. Applied non-fatally; invalid codes do not block creation.' }
}
}
@@ -138,7 +181,6 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
email: { type: :string },
special_instructions: { type: :string },
internal_note: { type: :string },
- channel: { type: :string },
ship_address: {
type: :object,
properties: {
@@ -165,13 +207,15 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
phone: { type: :string }
}
},
- line_items: {
+ items: {
type: :array,
items: {
type: :object,
+ required: %w[variant_id],
properties: {
- variant_id: { type: :string },
- quantity: { type: :integer }
+ variant_id: { type: :string, description: 'Variant prefixed ID' },
+ quantity: { type: :integer, example: 1 },
+ metadata: { type: :object }
}
}
}
diff --git a/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb
index 21678551c2..4145663fba 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb
@@ -2,7 +2,9 @@
require 'swagger_helper'
-RSpec.describe 'Admin Product Media API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+# NOTE: This spec exercises the API but is excluded from the OpenAPI doc until 6.0
+# product media rework is finalized. See docs/plans/5.4-6.0-product-media-system.md.
+RSpec.describe 'Admin Product Media API', type: :request do
include_context 'API v3 Admin'
let!(:product) { create(:product, stores: [store]) }
@@ -10,11 +12,11 @@ RSpec.describe 'Admin Product Media API', type: :request, swagger_doc: 'api-refe
let(:Authorization) { "Bearer #{admin_jwt_token}" }
path '/api/v3/admin/products/{product_id}/media' do
- get 'List product assets' do
- tags 'Product Assets'
+ get 'List product media' do
+ tags 'Product Media'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns a paginated list of assets (images) for a product.'
+ description 'Returns a paginated list of media (images, video) for a product.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -34,12 +36,12 @@ RSpec.describe 'Admin Product Media API', type: :request, swagger_doc: 'api-refe
end
end
- post 'Create a product asset' do
- tags 'Product Assets'
+ post 'Create a product media item' do
+ tags 'Product Media'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Creates a new asset (image) for a product.'
+ description 'Creates a new media item (image, video) for a product.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -50,12 +52,12 @@ RSpec.describe 'Admin Product Media API', type: :request, swagger_doc: 'api-refe
properties: {
alt: { type: :string, example: 'Product front view' },
position: { type: :integer, example: 1 },
- type: { type: :string, example: 'Spree::Image', description: 'Asset type (defaults to Spree::Image)' },
+ type: { type: :string, example: 'Spree::Image', description: 'Media type (defaults to Spree::Image)' },
url: { type: :string, example: 'https://example.com/image.jpg', description: 'External URL to import image from (async). Returns 202 Accepted.' }
}
}
- response '202', 'asset import from URL enqueued' do
+ response '202', 'media import from URL enqueued' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
let(:product_id) { product.prefixed_id }
let(:body) { { url: 'https://example.com/image.jpg', position: 1 } }
@@ -76,18 +78,18 @@ RSpec.describe 'Admin Product Media API', type: :request, swagger_doc: 'api-refe
end
path '/api/v3/admin/products/{product_id}/media/{id}' do
- patch 'Update a product asset' do
- tags 'Product Assets'
+ patch 'Update a product media item' do
+ tags 'Product Media'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Updates a product asset. Only provided fields are updated.'
+ description 'Updates a product media item. Only provided fields are updated.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
description: 'Bearer token for admin authentication'
parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'
- parameter name: :id, in: :path, type: :string, required: true, description: 'Asset prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -109,16 +111,16 @@ RSpec.describe 'Admin Product Media API', type: :request, swagger_doc: 'api-refe
end
end
- delete 'Delete a product asset' do
- tags 'Product Assets'
+ delete 'Delete a product media item' do
+ tags 'Product Media'
security [api_key: [], bearer_auth: []]
- description 'Deletes an asset from a product.'
+ description 'Deletes a media item from a product.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
description: 'Bearer token for admin authentication'
parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'
- parameter name: :id, in: :path, type: :string, required: true, description: 'Asset prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'
response '204', 'media deleted' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
diff --git a/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rb
index be290d5972..5a4f4ba1dd 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rb
@@ -2,7 +2,9 @@
require 'swagger_helper'
-RSpec.describe 'Admin Variant Media API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+# NOTE: This spec exercises the API but is excluded from the OpenAPI doc until 6.0
+# variant media rework is finalized. See docs/plans/5.4-6.0-product-media-system.md.
+RSpec.describe 'Admin Variant Media API', type: :request do
include_context 'API v3 Admin'
let!(:product) { create(:product, stores: [store]) }
@@ -11,11 +13,11 @@ RSpec.describe 'Admin Variant Media API', type: :request, swagger_doc: 'api-refe
let(:Authorization) { "Bearer #{admin_jwt_token}" }
path '/api/v3/admin/products/{product_id}/variants/{variant_id}/media' do
- get 'List variant assets' do
- tags 'Variant Assets'
+ get 'List variant media' do
+ tags 'Variant Media'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns a paginated list of assets (images) for a variant.'
+ description 'Returns a paginated list of media (images, video) for a variant.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -39,12 +41,12 @@ RSpec.describe 'Admin Variant Media API', type: :request, swagger_doc: 'api-refe
end
end
- post 'Create a variant asset' do
- tags 'Variant Assets'
+ post 'Create a variant media item' do
+ tags 'Variant Media'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Creates a new asset (image) for a variant.'
+ description 'Creates a new media item (image, video) for a variant.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -56,12 +58,12 @@ RSpec.describe 'Admin Variant Media API', type: :request, swagger_doc: 'api-refe
properties: {
alt: { type: :string, example: 'Variant image' },
position: { type: :integer, example: 1 },
- type: { type: :string, example: 'Spree::Image', description: 'Asset type (defaults to Spree::Image)' },
+ type: { type: :string, example: 'Spree::Image', description: 'Media type (defaults to Spree::Image)' },
url: { type: :string, example: 'https://example.com/image.jpg', description: 'External URL to import image from (async). Returns 202 Accepted.' }
}
}
- response '202', 'variant asset import from URL enqueued' do
+ response '202', 'variant media import from URL enqueued' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
let(:product_id) { product.prefixed_id }
let(:variant_id) { variant.prefixed_id }
@@ -84,19 +86,19 @@ RSpec.describe 'Admin Variant Media API', type: :request, swagger_doc: 'api-refe
end
path '/api/v3/admin/products/{product_id}/variants/{variant_id}/media/{id}' do
- patch 'Update a variant asset' do
- tags 'Variant Assets'
+ patch 'Update a variant media item' do
+ tags 'Variant Media'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Updates a variant asset. Only provided fields are updated.'
+ description 'Updates a variant media item. Only provided fields are updated.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
description: 'Bearer token for admin authentication'
parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'
parameter name: :variant_id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'
- parameter name: :id, in: :path, type: :string, required: true, description: 'Asset prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -119,17 +121,17 @@ RSpec.describe 'Admin Variant Media API', type: :request, swagger_doc: 'api-refe
end
end
- delete 'Delete a variant asset' do
- tags 'Variant Assets'
+ delete 'Delete a variant media item' do
+ tags 'Variant Media'
security [api_key: [], bearer_auth: []]
- description 'Deletes an asset from a variant.'
+ description 'Deletes a media item from a variant.'
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
description: 'Bearer token for admin authentication'
parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'
parameter name: :variant_id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'
- parameter name: :id, in: :path, type: :string, required: true, description: 'Asset prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'
response '204', 'variant media deleted' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
diff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rb
index 7da39d0713..46e2dfc0af 100644
--- a/spree/api/spec/swagger_helper.rb
+++ b/spree/api/spec/swagger_helper.rb
@@ -167,16 +167,19 @@ RSpec.configure do |config|
{ name: 'Products', description: 'Product management' },
{ name: 'Variants', description: 'Product variant management' },
{ name: 'Option Types', description: 'Option type and value management' },
- { name: 'Taxonomies', description: 'Taxonomy management' },
- { name: 'Taxons', description: 'Taxon (category) management' },
- { name: 'Assets', description: 'Product image and asset management' },
- { name: 'Prices', description: 'Variant price management' }
+ { name: 'Prices', description: 'Variant price management' },
+ { name: 'Orders', description: 'Order management — list, create, update, items, complete, cancel, approve' },
+ { name: 'Payments', description: 'Order payment management — capture, void, off-session charges' },
+ { name: 'Refunds', description: 'Order refund management' },
+ { name: 'Fulfillments', description: 'Order fulfillment management — ship, cancel, split' },
+ { name: 'Order Gift Cards', description: 'Apply / remove gift cards on an order' },
+ { name: 'Order Store Credits', description: 'Apply / remove customer store credit on an order' }
],
'x-tagGroups': [
{ name: 'Authentication', tags: ['Authentication'] },
- { name: 'Catalog', tags: %w[Products Variants Assets Prices] },
- { name: 'Categories', tags: %w[Taxonomies Taxons] },
- { name: 'Options', tags: ['Option Types'] }
+ { name: 'Catalog', tags: %w[Products Variants Prices] },
+ { name: 'Options', tags: ['Option Types'] },
+ { name: 'Orders', tags: ['Orders', 'Payments', 'Refunds', 'Fulfillments', 'Order Gift Cards', 'Order Store Credits'] }
],
components: {
securitySchemes: {
diff --git a/spree/core/app/models/concerns/spree/prefixed_id.rb b/spree/core/app/models/concerns/spree/prefixed_id.rb
index 94bb754d02..680a2dabe9 100644
--- a/spree/core/app/models/concerns/spree/prefixed_id.rb
+++ b/spree/core/app/models/concerns/spree/prefixed_id.rb
@@ -101,8 +101,10 @@ module Spree
# Uses the association's target class to validate the record exists.
# Only resolves when a matching belongs_to association exists — columns
# like external_id that happen to end with _id are left untouched.
+ # Resolves aliased FKs (via alias_attribute) to their canonical name.
def resolve_prefixed_id_for_attribute(attribute_name, prefixed_id_value)
- reflection = belongs_to_reflections_by_fk[attribute_name]
+ canonical_name = attribute_aliases[attribute_name] || attribute_name
+ reflection = belongs_to_reflections_by_fk[canonical_name]
if reflection
reflection.klass.find_by_param!(prefixed_id_value).id
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 5a104cbca7..bc23c33f52 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -106,7 +106,7 @@ module Spree
self.whitelisted_ransackable_associations = %w[shipments user created_by approver canceler promotions bill_address ship_address line_items store]
self.whitelisted_ransackable_attributes = %w[
- completed_at email number state payment_state shipment_state
+ completed_at email number state status payment_state shipment_state
total item_total item_count considered_risky channel
]
self.whitelisted_ransackable_scopes = %w[complete incomplete refunded partially_refunded multi_search]
@@ -114,13 +114,28 @@ module Spree
attr_reader :coupon_code
attr_accessor :temporary_address
+ # Set to false on admin-initiated flows to suppress customer-facing emails.
+ attr_accessor :notify_customer
+
attribute :state_machine_resumed, :boolean
+ STATUSES = %w[draft placed canceled].freeze
+
+ attribute :status, :string, default: 'draft'
+ validates :status, inclusion: { in: STATUSES }
+
+ scope :drafts, -> { where(status: 'draft') }
+ scope :placed_orders, -> { where(status: 'placed') }
+ scope :canceled_orders, -> { where(status: 'canceled') }
+
acts_as_taggable_on :tags
acts_as_taggable_tenant :store_id
ASSOCIATED_USER_ATTRIBUTES = [:user_id, :email, :bill_address_id, :ship_address_id]
+ # 6.0 forward-compat: User→Customer rename. Column stays user_id in 5.x.
+ alias_attribute :customer_id, :user_id
+
belongs_to :user, class_name: "::#{Spree.user_class}", optional: true, autosave: true
belongs_to :created_by, class_name: "::#{Spree.admin_user_class}", optional: true
belongs_to :approver, class_name: "::#{Spree.admin_user_class}", optional: true
@@ -148,6 +163,8 @@ module Spree
has_many :payment_sessions, inverse_of: :order, class_name: 'Spree::PaymentSession'
has_many :return_authorizations, inverse_of: :order, class_name: 'Spree::ReturnAuthorization'
has_many :adjustments, -> { order(:created_at) }, as: :adjustable, class_name: 'Spree::Adjustment'
+ has_many :cancellations, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::OrderCancellation'
+ has_many :approvals, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::OrderApproval'
end
has_many :reimbursements, inverse_of: :order, class_name: 'Spree::Reimbursement'
has_many :customer_returns, class_name: 'Spree::CustomerReturn', through: :return_authorizations
@@ -348,6 +365,14 @@ module Spree
completed_at.present?
end
+ def draft?
+ status == 'draft'
+ end
+
+ def placed?
+ status == 'placed'
+ end
+
# Checks if the order is fully refunded
# @return [Boolean]
def order_refunded?
@@ -591,6 +616,7 @@ module Spree
end
updater.update_shipment_state
+ self.status = 'placed'
save!
updater.run_hooks
@@ -1089,7 +1115,7 @@ module Spree
end
def publish_order_completed_event
- publish_event('order.completed')
+ publish_event('order.completed', event_payload.merge(notify_customer: notify_customer))
end
def publish_order_resumed_event
diff --git a/spree/core/app/models/spree/order_approval.rb b/spree/core/app/models/spree/order_approval.rb
new file mode 100644
index 0000000000..fc052e2228
--- /dev/null
+++ b/spree/core/app/models/spree/order_approval.rb
@@ -0,0 +1,19 @@
+module Spree
+ class OrderApproval < Spree.base_class
+ has_prefix_id :appr
+
+ STATUSES = %w[pending approved rejected].freeze
+
+ attribute :metadata, default: -> { {} }
+
+ belongs_to :order, class_name: 'Spree::Order', inverse_of: :approvals
+ belongs_to :approver, polymorphic: true, optional: true
+
+ validates :order, presence: true
+ validates :status, presence: true, inclusion: { in: STATUSES }
+
+ scope :approved, -> { where(status: 'approved') }
+ scope :pending, -> { where(status: 'pending') }
+ scope :rejected, -> { where(status: 'rejected') }
+ end
+end
diff --git a/spree/core/app/models/spree/order_cancellation.rb b/spree/core/app/models/spree/order_cancellation.rb
new file mode 100644
index 0000000000..45167540a8
--- /dev/null
+++ b/spree/core/app/models/spree/order_cancellation.rb
@@ -0,0 +1,19 @@
+module Spree
+ class OrderCancellation < Spree.base_class
+ has_prefix_id :cncl
+
+ REASONS = %w[customer declined fraud inventory staff other expired].freeze
+
+ attribute :restock_items, :boolean, default: false
+ attribute :refund_payments, :boolean, default: false
+ attribute :notify_customer, :boolean, default: false
+ attribute :metadata, default: -> { {} }
+
+ belongs_to :order, class_name: 'Spree::Order', inverse_of: :cancellations
+ belongs_to :canceled_by, polymorphic: true, optional: true
+
+ validates :order, presence: true
+ validates :reason, presence: true, inclusion: { in: REASONS }
+ validates :refund_amount, numericality: { greater_than_or_equal_to: 0, allow_nil: true }
+ end
+end
diff --git a/spree/core/app/services/spree/orders/approve.rb b/spree/core/app/services/spree/orders/approve.rb
index aa59e2469f..78c46a7bfb 100644
--- a/spree/core/app/services/spree/orders/approve.rb
+++ b/spree/core/app/services/spree/orders/approve.rb
@@ -3,16 +3,37 @@ module Spree
class Approve
prepend Spree::ServiceModule::Base
- def call(order:, approver: nil)
- changes = { considered_risky: false, approved_at: Time.current }
- if approver.present?
- changes[:approver_id] = approver.id
+ # Approves an order and records a Spree::OrderApproval history record.
+ #
+ # The legacy keyword `approver:` remains valid; new keywords (`level:`, `note:`)
+ # are additive and stored on the approval record.
+ #
+ # @param order [Spree::Order]
+ # @param approver [Object, nil] the user/admin who approved
+ # @param level [String, nil] approval level (used by 6.0 multi-level B2B flow)
+ # @param note [String, nil] staff-facing note
+ # @return [Spree::ServiceModule::Result]
+ def call(order:, approver: nil, level: nil, note: nil)
+ decided_at = Time.current
+
+ order.transaction do
+ order.approvals.create!(
+ status: 'approved',
+ level: level,
+ note: note,
+ approver: approver,
+ decided_at: decided_at,
+ created_at: decided_at
+ )
+
+ changes = { considered_risky: false, approved_at: decided_at }
+ changes[:approver_id] = approver.id if approver.present?
+ order.update_columns(changes)
end
- order.update_columns(changes)
order.publish_event('order.approved')
success(order.reload)
- rescue ActiveRecord::Rollback, ActiveRecord::RecordInvalid, StateMachines::InvalidTransition
+ rescue ActiveRecord::RecordInvalid, StateMachines::InvalidTransition
failure(order)
end
end
diff --git a/spree/core/app/services/spree/orders/cancel.rb b/spree/core/app/services/spree/orders/cancel.rb
index f84bb5a51b..61afdd77be 100644
--- a/spree/core/app/services/spree/orders/cancel.rb
+++ b/spree/core/app/services/spree/orders/cancel.rb
@@ -3,19 +3,50 @@ module Spree
class Cancel
prepend Spree::ServiceModule::Base
- def call(order:, canceler: nil, canceled_at: nil)
+ DEFAULT_REASON = 'other'.freeze
+
+ # Cancels an order and records a Spree::OrderCancellation history record.
+ # Legacy `canceler:` and `canceled_at:` remain valid; new keywords are additive.
+ #
+ # @param order [Spree::Order]
+ # @param canceler [Object, nil] the user/admin who initiated the cancellation
+ # @param canceled_at [Time, nil] timestamp (defaults to Time.current)
+ # @param reason [String] one of Spree::OrderCancellation::REASONS
+ # @param note [String, nil] staff-facing note
+ # @param restock_items [Boolean] whether to return inventory
+ # @param refund_payments [Boolean] whether to refund captured payments
+ # @param refund_amount [BigDecimal, Numeric, nil] amount to refund;
+ # when refund_payments is true and this is nil, defaults to order.payment_total
+ # @param notify_customer [Boolean] hint for subscribers
+ # @return [Spree::ServiceModule::Result]
+ def call(order:, canceler: nil, canceled_at: nil,
+ reason: DEFAULT_REASON, note: nil,
+ restock_items: false, refund_payments: false, refund_amount: nil,
+ notify_customer: false)
canceled_at ||= Time.current
+ refund_amount ||= order.payment_total if refund_payments
order.transaction do
- changes = { canceled_at: canceled_at }
+ order.cancellations.create!(
+ reason: reason,
+ note: note,
+ restock_items: restock_items,
+ refund_payments: refund_payments,
+ refund_amount: refund_amount,
+ notify_customer: notify_customer,
+ canceled_by: canceler,
+ created_at: canceled_at
+ )
+
+ changes = { canceled_at: canceled_at, status: 'canceled' }
changes[:canceler_id] = canceler.id if canceler.present?
order.update_columns(changes)
order.cancel!
end
- order.publish_event('order.canceled')
+ order.publish_event('order.canceled', order.event_payload.merge(notify_customer: notify_customer))
success(order.reload)
- rescue ActiveRecord::Rollback, ActiveRecord::RecordInvalid, StateMachines::InvalidTransition
+ rescue ActiveRecord::RecordInvalid, StateMachines::InvalidTransition
failure(order)
end
end
diff --git a/spree/core/app/services/spree/orders/complete.rb b/spree/core/app/services/spree/orders/complete.rb
new file mode 100644
index 0000000000..69c2fc8dac
--- /dev/null
+++ b/spree/core/app/services/spree/orders/complete.rb
@@ -0,0 +1,53 @@
+module Spree
+ module Orders
+ # Admin-side order completion.
+ #
+ # Distinct from Spree::Carts::Complete (storefront checkout). Callers must
+ # wrap invocation in Spree::Api::V3::OrderLock#with_order_lock — this
+ # service does not lock the row itself.
+ #
+ # @param order [Spree::Order]
+ # @param payment_pending [Boolean] if true, completes the order without
+ # processing payments. Order is placed but `payment_status` may be
+ # 'balance_due'. Useful for B2B / invoice-later flows.
+ # @param notify_customer [Boolean] if true, the customer receives the
+ # standard order confirmation email. Defaults to false — admin orders
+ # complete silently unless explicitly opted in.
+ # @return [Spree::ServiceModule::Result]
+ class Complete
+ prepend Spree::ServiceModule::Base
+
+ def call(order:, payment_pending: false, notify_customer: false)
+ order.notify_customer = notify_customer
+
+ return success(order) if order.completed?
+ return failure(order, 'Order is canceled') if order.canceled?
+
+ process_payments!(order) if order.payment_required? && !payment_pending
+
+ return failure(order, order.errors.full_messages.to_sentence) if order.errors.any?
+
+ advance_to_complete!(order)
+
+ if order.reload.complete?
+ success(order)
+ else
+ failure(order, order.errors.full_messages.to_sentence.presence || 'Could not complete order')
+ end
+ end
+
+ private
+
+ def process_payments!(order)
+ return if order.payment_total >= order.total
+ return if order.payments.valid.any?(&:completed?) && order.unprocessed_payments.empty?
+
+ order.process_payments!
+ end
+
+ def advance_to_complete!(order)
+ order.next until order.complete? || order.errors.present?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/orders/create.rb b/spree/core/app/services/spree/orders/create.rb
new file mode 100644
index 0000000000..cb4ad58da9
--- /dev/null
+++ b/spree/core/app/services/spree/orders/create.rb
@@ -0,0 +1,118 @@
+module Spree
+ module Orders
+ # Admin-side order creation. One-shot: customer, items, addresses, currency,
+ # market, locale, notes, metadata, and a coupon code in a single call.
+ # Invalid coupons are non-fatal — the order is created and `result.value`
+ # carries `discount_application_errors`.
+ #
+ # Standalone from Spree::Carts::Create (storefront). Admin-created orders
+ # are first-class Spree::Order records (status: 'draft') in 5.x and remain
+ # so in 6.0 — Spree::Cart in 6.0 is storefront-only.
+ class Create
+ prepend Spree::ServiceModule::Base
+
+ attr_reader :discount_application_errors
+
+ # @param store [Spree::Store]
+ # @param user [Object, nil] resolved customer (Spree.user_class instance)
+ # @param params [Hash] order params (see admin API docs)
+ # @return [Spree::ServiceModule::Result]
+ def call(store:, user: nil, params: {})
+ @store = store
+ @user = user
+ @params = params.to_h.deep_symbolize_keys
+ @discount_application_errors = []
+
+ return failure(:store_is_required) if store.nil?
+
+ order = nil
+ ApplicationRecord.transaction do
+ order = build_order
+ assign_addresses(order)
+ order.save!
+
+ add_items(order) if @params[:items].present?
+ apply_coupon(order) if @params[:coupon_code].present?
+ end
+
+ success(order.reload)
+ rescue ActiveRecord::RecordInvalid => e
+ failure(e.record, e.record.errors.full_messages.to_sentence)
+ end
+
+ private
+
+ def build_order
+ attrs = {
+ user: @user,
+ email: @params[:email] || @user&.email,
+ currency: @params[:currency].presence&.upcase || @store.default_currency,
+ locale: @params[:locale] || Spree::Current.locale,
+ customer_note: @params[:customer_note],
+ internal_note: @params[:internal_note],
+ metadata: @params[:metadata].to_h,
+ token: Spree::GenerateToken.new.call(Spree::Order),
+ status: 'draft'
+ }
+
+ attrs[:market] = resolve_market if @params[:market_id].present?
+ attrs.compact_blank!
+
+ @store.orders.new(attrs)
+ end
+
+ def resolve_market
+ @store.markets.find_by_prefix_id!(@params[:market_id])
+ end
+
+ def assign_addresses(order)
+ if @params[:use_customer_default_address] && @user
+ @user.association(:bill_address).load_target
+ @user.association(:ship_address).load_target
+ order.bill_address = @user.bill_address&.dup
+ order.ship_address = @user.ship_address&.dup
+ end
+
+ assign_address(order, :ship_address, @params[:shipping_address_id], @params[:shipping_address])
+ assign_address(order, :bill_address, @params[:billing_address_id], @params[:billing_address])
+ end
+
+ def assign_address(order, association, address_id, address_attrs)
+ if address_id.present?
+ address = resolve_user_address(address_id)
+ order.public_send(:"#{association}_id=", address.id) if address
+ elsif address_attrs.present?
+ order.public_send(:"#{association}_attributes=", address_attrs)
+ end
+ end
+
+ def resolve_user_address(prefixed_id)
+ return unless @user
+
+ decoded = Spree::Address.decode_prefixed_id(prefixed_id)
+ decoded ? @user.addresses.find_by(id: decoded) : nil
+ end
+
+ def add_items(order)
+ result = Spree::Orders::UpsertItems.call(order: order, items: @params[:items])
+ raise ActiveRecord::RecordInvalid, order if result.failure?
+ end
+
+ def apply_coupon(order)
+ order.coupon_code = @params[:coupon_code]
+ handler = Spree::PromotionHandler::Coupon.new(order).apply
+
+ if handler.successful?
+ order.save!
+ else
+ @discount_application_errors << {
+ code: handler.status_code,
+ message: handler.error,
+ coupon_code: @params[:coupon_code]
+ }
+ order.coupon_code = nil
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/orders/update.rb b/spree/core/app/services/spree/orders/update.rb
new file mode 100644
index 0000000000..c91c4a01d0
--- /dev/null
+++ b/spree/core/app/services/spree/orders/update.rb
@@ -0,0 +1,38 @@
+module Spree
+ module Orders
+ # Admin-side order update.
+ #
+ # Updates Order attributes plus optional line items via a flat `items: [...]`
+ # array (matches POST shape and Store API convention). Standalone from
+ # Spree::Carts::Update (storefront).
+ class Update
+ prepend Spree::ServiceModule::Base
+
+ def call(order:, params: {})
+ @order = order
+ @params = params.to_h.deep_symbolize_keys
+
+ items_param = @params.delete(:items)
+
+ ApplicationRecord.transaction do
+ if @order.update(@params)
+ process_items(items_param) if items_param
+ else
+ return failure(@order, @order.errors.full_messages.to_sentence)
+ end
+ end
+
+ success(@order.reload)
+ rescue ActiveRecord::RecordInvalid => e
+ failure(e.record, e.record.errors.full_messages.to_sentence)
+ end
+
+ private
+
+ def process_items(items)
+ result = Spree::Orders::UpsertItems.call(order: @order, items: items)
+ raise ActiveRecord::RecordInvalid, @order if result.failure?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/orders/upsert_items.rb b/spree/core/app/services/spree/orders/upsert_items.rb
new file mode 100644
index 0000000000..f5630d223b
--- /dev/null
+++ b/spree/core/app/services/spree/orders/upsert_items.rb
@@ -0,0 +1,69 @@
+module Spree
+ module Orders
+ # Bulk upsert line items on an order. Mirrors Spree::Carts::UpsertItems
+ # but is admin/order-side (separate from the cart pipeline per the 6.0
+ # cart/order split — see docs/plans/6.0-cart-order-split.md).
+ #
+ # For each entry in +items+:
+ # - If a line item for the variant already exists -> sets its quantity
+ # - If no line item exists -> creates one with the given quantity
+ #
+ # After all items are processed the order is recalculated once.
+ class UpsertItems
+ prepend Spree::ServiceModule::Base
+
+ def call(order:, items:)
+ items = Array(items)
+ return success(order) if items.empty?
+
+ store = order.store || Spree::Current.store
+
+ ApplicationRecord.transaction do
+ items.each do |item_params|
+ item_params = item_params.to_h.deep_symbolize_keys
+ variant = resolve_variant(store, item_params[:variant_id])
+ next unless variant
+
+ quantity = (item_params[:quantity] || 1).to_i
+ next if quantity <= 0
+
+ return failure(variant, "#{variant.name} is not available in #{order.currency}") if variant.amount_in(order.currency).nil?
+
+ line_item = Spree.line_item_by_variant_finder.new.execute(order: order, variant: variant)
+
+ if line_item
+ line_item.quantity = quantity
+ line_item.metadata = line_item.metadata.merge(item_params[:metadata].to_h) if item_params[:metadata].present?
+ else
+ line_item = order.line_items.new(quantity: quantity, variant: variant, options: { currency: order.currency })
+ line_item.metadata = item_params[:metadata].to_h if item_params[:metadata].present?
+ end
+
+ return failure(line_item) unless line_item.save
+ end
+
+ order.update_with_updater!
+ end
+
+ success(order)
+ end
+
+ private
+
+ def resolve_variant(store, variant_id)
+ return nil if variant_id.blank?
+
+ variant = store.variants.find_by_param(variant_id)
+
+ raise ActiveRecord::RecordNotFound.new(
+ "Variant '#{variant_id}' not found in this store",
+ 'Spree::Variant',
+ 'id',
+ variant_id
+ ) unless variant
+
+ variant
+ end
+ end
+ end
+end
diff --git a/spree/core/db/migrate/20260429000001_create_spree_order_cancellations.rb b/spree/core/db/migrate/20260429000001_create_spree_order_cancellations.rb
new file mode 100644
index 0000000000..c777a09b2b
--- /dev/null
+++ b/spree/core/db/migrate/20260429000001_create_spree_order_cancellations.rb
@@ -0,0 +1,25 @@
+class CreateSpreeOrderCancellations < ActiveRecord::Migration[7.2]
+ def change
+ create_table :spree_order_cancellations do |t|
+ t.references :order, null: false, index: false
+ t.string :reason, null: false
+ t.text :note
+ t.boolean :restock_items, null: false
+ t.boolean :refund_payments, null: false
+ t.decimal :refund_amount, precision: 10, scale: 2
+ t.boolean :notify_customer, null: false
+ t.references :canceled_by, polymorphic: true, index: false
+ if t.respond_to? :jsonb
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+ t.timestamps
+ end
+
+ add_index :spree_order_cancellations, :order_id
+ add_index :spree_order_cancellations, [:canceled_by_id, :canceled_by_type],
+ name: 'idx_order_cancellations_canceled_by'
+ add_index :spree_order_cancellations, :created_at
+ end
+end
diff --git a/spree/core/db/migrate/20260429000002_create_spree_order_approvals.rb b/spree/core/db/migrate/20260429000002_create_spree_order_approvals.rb
new file mode 100644
index 0000000000..32747b95e5
--- /dev/null
+++ b/spree/core/db/migrate/20260429000002_create_spree_order_approvals.rb
@@ -0,0 +1,22 @@
+class CreateSpreeOrderApprovals < ActiveRecord::Migration[7.2]
+ def change
+ create_table :spree_order_approvals do |t|
+ t.references :order, null: false, index: false
+ t.string :status, null: false
+ t.string :level
+ t.text :note
+ t.references :approver, polymorphic: true, index: false
+ t.datetime :decided_at
+ if t.respond_to? :jsonb
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+ t.timestamps
+ end
+
+ add_index :spree_order_approvals, [:order_id, :status]
+ add_index :spree_order_approvals, [:approver_id, :approver_type],
+ name: 'idx_order_approvals_approver'
+ end
+end
diff --git a/spree/core/db/migrate/20260429000003_add_status_to_spree_orders.rb b/spree/core/db/migrate/20260429000003_add_status_to_spree_orders.rb
new file mode 100644
index 0000000000..5df9a570be
--- /dev/null
+++ b/spree/core/db/migrate/20260429000003_add_status_to_spree_orders.rb
@@ -0,0 +1,6 @@
+class AddStatusToSpreeOrders < ActiveRecord::Migration[7.2]
+ def change
+ add_column :spree_orders, :status, :string
+ add_index :spree_orders, :status
+ end
+end
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 3eeec639ee..e7eb7fd7c0 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -48,6 +48,9 @@ module Spree
# order
order_approve_service: 'Spree::Orders::Approve',
order_cancel_service: 'Spree::Orders::Cancel',
+ order_complete_service: 'Spree::Orders::Complete',
+ order_create_service: 'Spree::Orders::Create',
+ order_update_service: 'Spree::Orders::Update',
order_updater: 'Spree::OrderUpdater',
# shipment
diff --git a/spree/core/spec/models/spree/order_approval_spec.rb b/spree/core/spec/models/spree/order_approval_spec.rb
new file mode 100644
index 0000000000..335cbeed92
--- /dev/null
+++ b/spree/core/spec/models/spree/order_approval_spec.rb
@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe Spree::OrderApproval, type: :model do
+ let(:order) { create(:order) }
+
+ describe 'validations' do
+ it 'requires status' do
+ approval = described_class.new(order: order, status: nil)
+ expect(approval).not_to be_valid
+ expect(approval.errors[:status]).to include("can't be blank")
+ end
+
+ it 'rejects invalid status values' do
+ approval = described_class.new(order: order, status: 'maybe')
+ expect(approval).not_to be_valid
+ expect(approval.errors[:status]).to include('is not included in the list')
+ end
+
+ it 'accepts each STATUSES value' do
+ Spree::OrderApproval::STATUSES.each do |status|
+ approval = described_class.new(order: order, status: status)
+ approval.valid?
+ expect(approval.errors[:status]).to be_empty
+ end
+ end
+ end
+
+ describe 'scopes' do
+ let!(:pending) { described_class.create!(order: order, status: 'pending') }
+ let!(:approved) { described_class.create!(order: order, status: 'approved') }
+ let!(:rejected) { described_class.create!(order: order, status: 'rejected') }
+
+ it { expect(described_class.approved).to contain_exactly(approved) }
+ it { expect(described_class.pending).to contain_exactly(pending) }
+ it { expect(described_class.rejected).to contain_exactly(rejected) }
+ end
+
+ describe 'prefixed id' do
+ it 'has appr_ prefix' do
+ approval = described_class.create!(order: order, status: 'approved')
+ expect(approval.prefixed_id).to start_with('appr_')
+ end
+ end
+
+ describe 'polymorphic approver' do
+ let(:admin) { create(:admin_user) }
+
+ it 'records the approver' do
+ approval = described_class.create!(order: order, status: 'approved', approver: admin, decided_at: Time.current)
+ expect(approval.approver).to eq(admin)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/order_cancellation_spec.rb b/spree/core/spec/models/spree/order_cancellation_spec.rb
new file mode 100644
index 0000000000..c32845b352
--- /dev/null
+++ b/spree/core/spec/models/spree/order_cancellation_spec.rb
@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe Spree::OrderCancellation, type: :model do
+ let(:order) { create(:order) }
+
+ describe 'validations' do
+ it 'requires reason' do
+ cancellation = described_class.new(order: order, reason: nil)
+ expect(cancellation).not_to be_valid
+ expect(cancellation.errors[:reason]).to include("can't be blank")
+ end
+
+ it 'rejects invalid reason values' do
+ cancellation = described_class.new(order: order, reason: 'not_a_real_reason')
+ expect(cancellation).not_to be_valid
+ expect(cancellation.errors[:reason]).to include('is not included in the list')
+ end
+
+ it 'accepts each REASONS value' do
+ Spree::OrderCancellation::REASONS.each do |reason|
+ cancellation = described_class.new(order: order, reason: reason)
+ cancellation.valid?
+ expect(cancellation.errors[:reason]).to be_empty
+ end
+ end
+
+ it 'rejects negative refund_amount' do
+ cancellation = described_class.new(order: order, reason: 'other', refund_amount: -1)
+ expect(cancellation).not_to be_valid
+ expect(cancellation.errors[:refund_amount]).to include('must be greater than or equal to 0')
+ end
+ end
+
+ describe 'prefixed id' do
+ it 'has cncl_ prefix' do
+ cancellation = described_class.create!(order: order, reason: 'other')
+ expect(cancellation.prefixed_id).to start_with('cncl_')
+ end
+ end
+
+ describe 'polymorphic canceled_by' do
+ let(:admin) { create(:admin_user) }
+
+ it 'records the canceler' do
+ cancellation = described_class.create!(order: order, reason: 'staff', canceled_by: admin)
+ expect(cancellation.canceled_by).to eq(admin)
+ end
+
+ it 'allows nil canceled_by' do
+ cancellation = described_class.new(order: order, reason: 'other')
+ expect(cancellation).to be_valid
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/order_spec.rb b/spree/core/spec/models/spree/order_spec.rb
index 524113b2f8..a2b927675c 100644
--- a/spree/core/spec/models/spree/order_spec.rb
+++ b/spree/core/spec/models/spree/order_spec.rb
@@ -353,7 +353,7 @@ describe Spree::Order, type: :model do
let(:order) { create(:completed_order_with_totals) }
it 'publishes order.canceled event' do
- expect(order).to receive(:publish_event).with('order.canceled')
+ expect(order).to receive(:publish_event).with('order.canceled', hash_including(:notify_customer))
order.canceled_by(admin_user)
end
end
@@ -466,8 +466,9 @@ describe Spree::Order, type: :model do
before { order.update_column(:state, 'complete') }
it 'publishes order.completed event' do
- expect(order).to receive(:publish_event).with('order.completed').at_least(:once)
+ expect(order).to receive(:publish_event).with('order.completed', hash_including(:notify_customer)).at_least(:once)
allow(order).to receive(:publish_event).with(anything)
+ allow(order).to receive(:publish_event).with(anything, anything)
order.finalize!
end
diff --git a/spree/core/spec/services/spree/orders/approve_spec.rb b/spree/core/spec/services/spree/orders/approve_spec.rb
index 8a6846152b..54f4e52119 100644
--- a/spree/core/spec/services/spree/orders/approve_spec.rb
+++ b/spree/core/spec/services/spree/orders/approve_spec.rb
@@ -27,5 +27,28 @@ module Spree
it_behaves_like 'approves order'
end
+
+ describe 'OrderApproval record creation' do
+ it 'creates an approval record with status approved' do
+ expect { result }.to change(order.approvals, :count).by(1)
+ approval = order.approvals.last
+ expect(approval.status).to eq('approved')
+ expect(approval.approver).to eq(user)
+ expect(approval.decided_at).to be_present
+ end
+
+ context 'with level and note' do
+ let(:result) do
+ subject.call(order: order, approver: user, level: 'manager', note: 'Approved per phone call')
+ end
+
+ it 'records level and note on the approval' do
+ result
+ approval = order.approvals.last
+ expect(approval.level).to eq('manager')
+ expect(approval.note).to eq('Approved per phone call')
+ end
+ end
+ end
end
end
diff --git a/spree/core/spec/services/spree/orders/cancel_spec.rb b/spree/core/spec/services/spree/orders/cancel_spec.rb
index 3e8dd82f2f..aaff558dbe 100644
--- a/spree/core/spec/services/spree/orders/cancel_spec.rb
+++ b/spree/core/spec/services/spree/orders/cancel_spec.rb
@@ -16,7 +16,7 @@ module Spree
it { expect(result.value).to eq(order) }
it 'publishes order.canceled event' do
- expect(order).to receive(:publish_event).with('order.canceled')
+ expect(order).to receive(:publish_event).with('order.canceled', hash_including(:notify_customer))
result
end
end
@@ -45,5 +45,53 @@ module Spree
it_behaves_like 'tries to cancel'
end
+
+ describe 'OrderCancellation record creation' do
+ it 'creates a cancellation record with default reason' do
+ expect { result }.to change(order.cancellations, :count).by(1)
+ cancellation = order.cancellations.last
+ expect(cancellation.reason).to eq('other')
+ expect(cancellation.canceled_by).to eq(user)
+ end
+
+ context 'with all new keyword arguments' do
+ let(:result) do
+ subject.call(
+ order: order,
+ canceler: user,
+ reason: 'inventory',
+ note: 'Out of stock',
+ restock_items: true,
+ refund_payments: true,
+ refund_amount: 25.00,
+ notify_customer: true
+ )
+ end
+
+ it 'records all fields on the cancellation' do
+ result
+ cancellation = order.cancellations.last
+ expect(cancellation.reason).to eq('inventory')
+ expect(cancellation.note).to eq('Out of stock')
+ expect(cancellation.restock_items).to be true
+ expect(cancellation.refund_payments).to be true
+ expect(cancellation.refund_amount).to eq(25.00)
+ expect(cancellation.notify_customer).to be true
+ expect(cancellation.canceled_by).to eq(user)
+ end
+ end
+
+ context 'when the cancellation is invalid' do
+ let(:result) do
+ subject.call(order: order, canceler: user, reason: 'not_a_real_reason')
+ end
+
+ it 'returns a failure result and rolls back' do
+ expect(result).to be_failure
+ expect(order.reload.canceled_at).to be_nil
+ expect(order.cancellations).to be_empty
+ end
+ end
+ end
end
end
diff --git a/spree/core/spec/services/spree/orders/update_spec.rb b/spree/core/spec/services/spree/orders/update_spec.rb
new file mode 100644
index 0000000000..cf1b45c337
--- /dev/null
+++ b/spree/core/spec/services/spree/orders/update_spec.rb
@@ -0,0 +1,130 @@
+require 'spec_helper'
+
+module Spree
+ RSpec.describe Orders::Update do
+ let(:store) { create(:store) }
+ let(:user) { create(:user) }
+ let(:order) { create(:order, user: user, store: store) }
+ let(:variant) { create(:variant) }
+
+ before do
+ variant.stock_items.first.update!(count_on_hand: 10)
+ store.products << variant.product unless store.products.include?(variant.product)
+ end
+
+ describe '#call' do
+ subject { described_class.call(order: order, params: params) }
+
+ context 'with empty params' do
+ let(:params) { {} }
+
+ it 'returns success' do
+ expect(subject).to be_success
+ end
+ end
+
+ context 'updating scalar attributes' do
+ let(:params) { { email: '[email protected]', customer_note: 'Leave at door' } }
+
+ it 'updates the order' do
+ expect(subject).to be_success
+ order.reload
+ expect(order.email).to eq('[email protected]')
+ expect(order.customer_note).to eq('Leave at door')
+ end
+ end
+
+ context 'with items array' do
+ let(:params) do
+ { items: [{ variant_id: variant.prefixed_id, quantity: 2 }] }
+ end
+
+ it 'creates the line item' do
+ expect(subject).to be_success
+ order.reload
+ expect(order.line_items.find_by(variant: variant).quantity).to eq(2)
+ end
+ end
+
+ context 'with both attributes and items' do
+ let(:params) do
+ {
+ email: '[email protected]',
+ items: [{ variant_id: variant.prefixed_id, quantity: 1 }]
+ }
+ end
+
+ it 'updates both' do
+ expect(subject).to be_success
+ order.reload
+ expect(order.email).to eq('[email protected]')
+ expect(order.line_items.find_by(variant: variant)).to be_present
+ end
+ end
+
+ context 'with item that fails (currency mismatch)' do
+ let(:order) { create(:order, user: user, store: store, currency: 'GBP') }
+ let(:params) do
+ {
+ email: '[email protected]',
+ items: [{ variant_id: variant.prefixed_id, quantity: 1 }]
+ }
+ end
+
+ it 'rolls back the entire update' do
+ expect(subject).to be_failure
+ expect(order.reload.email).not_to eq('[email protected]')
+ expect(order.line_items.count).to eq(0)
+ end
+ end
+
+ context 'with invalid variant in items' do
+ let(:params) do
+ {
+ email: '[email protected]',
+ items: [{ variant_id: 'variant_doesnotexist', quantity: 1 }]
+ }
+ end
+
+ it 'raises RecordNotFound and does not commit attribute changes' do
+ expect { subject }.to raise_error(ActiveRecord::RecordNotFound)
+ expect(order.reload.email).not_to eq('[email protected]')
+ end
+ end
+
+ context 'with empty items array' do
+ let(:params) { { items: [] } }
+
+ it 'is a no-op for items, returns success' do
+ expect(subject).to be_success
+ expect(order.line_items.count).to eq(0)
+ end
+ end
+
+ context 'replaces an existing line item quantity' do
+ let!(:existing) { create(:line_item, order: order, variant: variant, quantity: 5) }
+ let(:params) do
+ { items: [{ variant_id: variant.prefixed_id, quantity: 2 }] }
+ end
+
+ it 'sets quantity to 2 (not 7)' do
+ expect(subject).to be_success
+ expect(existing.reload.quantity).to eq(2)
+ end
+ end
+
+ context 'with string keys' do
+ let(:params) do
+ { 'email' => '[email protected]', 'items' => [{ 'variant_id' => variant.prefixed_id, 'quantity' => 1 }] }
+ end
+
+ it 'handles string keys' do
+ expect(subject).to be_success
+ order.reload
+ expect(order.email).to eq('[email protected]')
+ expect(order.line_items.find_by(variant: variant)).to be_present
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/spec/services/spree/orders/upsert_items_spec.rb b/spree/core/spec/services/spree/orders/upsert_items_spec.rb
new file mode 100644
index 0000000000..8abb82b129
--- /dev/null
+++ b/spree/core/spec/services/spree/orders/upsert_items_spec.rb
@@ -0,0 +1,263 @@
+require 'spec_helper'
+
+module Spree
+ RSpec.describe Orders::UpsertItems do
+ let(:store) { create(:store) }
+ let(:user) { create(:user) }
+ let(:order) { create(:order, user: user, store: store) }
+ let(:variant) { create(:variant) }
+ let(:variant2) { create(:variant) }
+
+ before do
+ [variant, variant2].each do |v|
+ v.stock_items.first.update!(count_on_hand: 10)
+ store.products << v.product unless store.products.include?(v.product)
+ end
+ end
+
+ describe '#call' do
+ subject { described_class.call(order: order, items: items) }
+
+ context 'with empty items' do
+ let(:items) { [] }
+
+ it 'returns success without changes' do
+ expect(subject).to be_success
+ end
+ end
+
+ context 'with nil items' do
+ let(:items) { nil }
+
+ it 'returns success without changes' do
+ expect(subject).to be_success
+ end
+ end
+
+ context 'creating new line items' do
+ let(:items) do
+ [
+ { variant_id: variant.prefixed_id, quantity: 2 },
+ { variant_id: variant2.prefixed_id, quantity: 3 }
+ ]
+ end
+
+ it 'creates line items with correct quantities' do
+ expect(subject).to be_success
+ order.reload
+ expect(order.line_items.find_by(variant: variant).quantity).to eq(2)
+ expect(order.line_items.find_by(variant: variant2).quantity).to eq(3)
+ end
+ end
+
+ context 'upserting existing line items' do
+ let!(:existing_line_item) { create(:line_item, order: order, variant: variant, quantity: 5) }
+
+ let(:items) do
+ [{ variant_id: variant.prefixed_id, quantity: 2 }]
+ end
+
+ it 'sets quantity instead of incrementing' do
+ expect(subject).to be_success
+ expect(existing_line_item.reload.quantity).to eq(2)
+ end
+ end
+
+ context 'mix of new and existing line items' do
+ let!(:existing_line_item) { create(:line_item, order: order, variant: variant, quantity: 5) }
+
+ let(:items) do
+ [
+ { variant_id: variant.prefixed_id, quantity: 1 },
+ { variant_id: variant2.prefixed_id, quantity: 4 }
+ ]
+ end
+
+ it 'updates existing and creates new' do
+ expect(subject).to be_success
+ order.reload
+ expect(existing_line_item.reload.quantity).to eq(1)
+ expect(order.line_items.find_by(variant: variant2).quantity).to eq(4)
+ end
+ end
+
+ context 'with default quantity' do
+ let(:items) { [{ variant_id: variant.prefixed_id }] }
+
+ it 'defaults quantity to 1' do
+ expect(subject).to be_success
+ expect(order.line_items.find_by(variant: variant).quantity).to eq(1)
+ end
+ end
+
+ context 'with quantity zero' do
+ let(:items) { [{ variant_id: variant.prefixed_id, quantity: 0 }] }
+
+ it 'skips the entry' do
+ expect(subject).to be_success
+ expect(order.line_items.count).to eq(0)
+ end
+ end
+
+ context 'with negative quantity' do
+ let(:items) { [{ variant_id: variant.prefixed_id, quantity: -3 }] }
+
+ it 'skips the entry' do
+ expect(subject).to be_success
+ expect(order.line_items.count).to eq(0)
+ end
+ end
+
+ context 'with metadata on a new line item' do
+ let(:items) do
+ [{ variant_id: variant.prefixed_id, quantity: 1, metadata: { 'gift' => true } }]
+ end
+
+ it 'sets metadata on new line item' do
+ expect(subject).to be_success
+ expect(order.line_items.find_by(variant: variant).metadata).to include('gift' => true)
+ end
+ end
+
+ context 'merging metadata on existing line item' do
+ let!(:existing_line_item) { create(:line_item, order: order, variant: variant, quantity: 1, private_metadata: { 'existing' => 'val' }) }
+
+ let(:items) do
+ [{ variant_id: variant.prefixed_id, quantity: 2, metadata: { 'new_key' => 'new_val' } }]
+ end
+
+ it 'merges new metadata into existing' do
+ expect(subject).to be_success
+ expect(existing_line_item.reload.metadata).to include('existing' => 'val', 'new_key' => 'new_val')
+ end
+ end
+
+ context 'with invalid variant_id' do
+ let(:items) { [{ variant_id: 'variant_invalid999', quantity: 1 }] }
+
+ it 'raises RecordNotFound with variant details' do
+ expect { subject }.to raise_error(ActiveRecord::RecordNotFound) do |error|
+ expect(error.model).to eq('Spree::Variant')
+ expect(error.message).to include('variant_invalid999')
+ end
+ end
+ end
+
+ context 'with blank variant_id in entry' do
+ let(:items) { [{ variant_id: '', quantity: 1 }] }
+
+ it 'skips the entry and returns success' do
+ expect(subject).to be_success
+ expect(order.line_items.count).to eq(0)
+ end
+ end
+
+ context 'with nil variant_id in entry' do
+ let(:items) { [{ variant_id: nil, quantity: 1 }] }
+
+ it 'skips the entry and returns success' do
+ expect(subject).to be_success
+ expect(order.line_items.count).to eq(0)
+ end
+ end
+
+ context 'with variant not available in order currency' do
+ let(:order) { create(:order, user: user, store: store, currency: 'GBP') }
+ let(:items) { [{ variant_id: variant.prefixed_id, quantity: 1 }] }
+
+ it 'returns failure with descriptive message' do
+ expect(subject).to be_failure
+ expect(subject.error.to_s).to include('is not available in GBP')
+ end
+ end
+
+ context 'with variant from another store' do
+ let(:other_store) { create(:store) }
+ let(:other_variant) { create(:variant) }
+
+ before do
+ other_variant.stock_items.first.update!(count_on_hand: 10)
+ other_store.products << other_variant.product
+ end
+
+ let(:items) { [{ variant_id: other_variant.prefixed_id, quantity: 1 }] }
+
+ it 'raises RecordNotFound (cross-store leakage prevented)' do
+ expect { subject }.to raise_error(ActiveRecord::RecordNotFound) do |error|
+ expect(error.model).to eq('Spree::Variant')
+ expect(error.message).to include(other_variant.prefixed_id)
+ end
+ end
+ end
+
+ context 'with string keys in params' do
+ let(:items) do
+ [{ 'variant_id' => variant.prefixed_id, 'quantity' => 3 }]
+ end
+
+ it 'handles string keys' do
+ expect(subject).to be_success
+ expect(order.line_items.find_by(variant: variant).quantity).to eq(3)
+ end
+ end
+
+ context 'with duplicate variant in items array' do
+ let(:items) do
+ [
+ { variant_id: variant.prefixed_id, quantity: 2 },
+ { variant_id: variant.prefixed_id, quantity: 5 }
+ ]
+ end
+
+ it 'last entry wins' do
+ expect(subject).to be_success
+ expect(order.line_items.where(variant: variant).count).to eq(1)
+ expect(order.line_items.find_by(variant: variant).quantity).to eq(5)
+ end
+ end
+
+ context 'recalculates order totals' do
+ let(:items) do
+ [
+ { variant_id: variant.prefixed_id, quantity: 2 },
+ { variant_id: variant2.prefixed_id, quantity: 1 }
+ ]
+ end
+
+ it 'updates order item_total' do
+ expect(subject).to be_success
+ order.reload
+ expected_total = (variant.price * 2) + variant2.price
+ expect(order.item_total).to eq(expected_total)
+ end
+ end
+
+ context 'rolls back on failure mid-batch' do
+ let(:items) do
+ [
+ { variant_id: variant.prefixed_id, quantity: 1 },
+ { variant_id: 'variant_doesnotexist', quantity: 1 }
+ ]
+ end
+
+ it 'does not persist partial changes' do
+ expect { subject }.to raise_error(ActiveRecord::RecordNotFound)
+ expect(order.reload.line_items.find_by(variant: variant)).to be_nil
+ end
+ end
+
+ context 'does not touch unrelated existing line items' do
+ let!(:unrelated_line_item) { create(:line_item, order: order, variant: variant, quantity: 3) }
+
+ let(:items) do
+ [{ variant_id: variant2.prefixed_id, quantity: 1 }]
+ end
+
+ it 'leaves unrelated line items unchanged' do
+ expect(subject).to be_success
+ expect(unrelated_line_item.reload.quantity).to eq(3)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/emails/app/subscribers/spree/order_email_subscriber.rb b/spree/emails/app/subscribers/spree/order_email_subscriber.rb
index e8c8dbd16a..1828761914 100644
--- a/spree/emails/app/subscribers/spree/order_email_subscriber.rb
+++ b/spree/emails/app/subscribers/spree/order_email_subscriber.rb
@@ -14,6 +14,7 @@ module Spree
order = find_order(event)
return unless order
return if order.confirmation_delivered?
+ return if event.payload['notify_customer'] == false
store = order.store
return unless store.prefers_send_consumer_transactional_emails?
@@ -38,6 +39,7 @@ module Spree
def send_cancel_email(event)
order = find_order(event)
return unless order
+ return if event.payload['notify_customer'] == false
OrderMailer.cancel_email(order.id).deliver_later
end
diff --git a/spree/emails/spec/models/spree/order_spec.rb b/spree/emails/spec/models/spree/order_spec.rb
index 03577d3c6f..97fe363e6a 100644
--- a/spree/emails/spec/models/spree/order_spec.rb
+++ b/spree/emails/spec/models/spree/order_spec.rb
@@ -13,8 +13,9 @@ describe Spree::Order, type: :model do
end
it 'publishes order.completed event when finalizing', events: true do
- expect(order).to receive(:publish_event).with('order.completed')
+ expect(order).to receive(:publish_event).with('order.completed', hash_including(:notify_customer))
allow(order).to receive(:publish_event).with(anything)
+ allow(order).to receive(:publish_event).with(anything, anything)
order.finalize!
end
diff --git a/spree/emails/spec/subscribers/spree/order_email_subscriber_spec.rb b/spree/emails/spec/subscribers/spree/order_email_subscriber_spec.rb
index 4c7be78228..af4f9ad026 100644
--- a/spree/emails/spec/subscribers/spree/order_email_subscriber_spec.rb
+++ b/spree/emails/spec/subscribers/spree/order_email_subscriber_spec.rb
@@ -7,8 +7,8 @@ RSpec.describe Spree::OrderEmailSubscriber do
let(:order) { create(:completed_order_with_totals, store: store) }
let(:subscriber) { described_class.new }
- def mock_event(order)
- double('Event', payload: { 'id' => order.prefixed_id })
+ def mock_event(order, payload_extras = {})
+ double('Event', payload: { 'id' => order.prefixed_id }.merge(payload_extras.transform_keys(&:to_s)))
end
before do
@@ -85,6 +85,38 @@ RSpec.describe Spree::OrderEmailSubscriber do
expect { subscriber.send(:send_confirmation_email, mock_event(order)) }.not_to raise_error
end
end
+
+ context 'when notify_customer is false in payload' do
+ it 'does not send confirmation email' do
+ expect(Spree::OrderMailer).not_to receive(:confirm_email)
+
+ subscriber.send(:send_confirmation_email, mock_event(order, notify_customer: false))
+ end
+
+ it 'does not mark confirmation as delivered' do
+ expect {
+ subscriber.send(:send_confirmation_email, mock_event(order, notify_customer: false))
+ }.not_to change { order.reload.confirmation_delivered }
+ end
+ end
+
+ context 'when notify_customer is true in payload' do
+ it 'sends confirmation email' do
+ expect(Spree::OrderMailer).to receive(:confirm_email).with(order.id).and_return(double(deliver_later: true))
+ allow(Spree::OrderMailer).to receive(:store_owner_notification_email).and_return(double(deliver_later: true))
+
+ subscriber.send(:send_confirmation_email, mock_event(order, notify_customer: true))
+ end
+ end
+
+ context 'when notify_customer is absent from payload' do
+ it 'sends confirmation email (default behavior)' do
+ expect(Spree::OrderMailer).to receive(:confirm_email).with(order.id).and_return(double(deliver_later: true))
+ allow(Spree::OrderMailer).to receive(:store_owner_notification_email).and_return(double(deliver_later: true))
+
+ subscriber.send(:send_confirmation_email, mock_event(order))
+ end
+ end
end
describe 'order.canceled event' do
@@ -101,5 +133,21 @@ RSpec.describe Spree::OrderEmailSubscriber do
expect { subscriber.send(:send_cancel_email, mock_event(order)) }.not_to raise_error
end
end
+
+ context 'when notify_customer is false in payload' do
+ it 'does not send cancel email' do
+ expect(Spree::OrderMailer).not_to receive(:cancel_email)
+
+ subscriber.send(:send_cancel_email, mock_event(order, notify_customer: false))
+ end
+ end
+
+ context 'when notify_customer is true in payload' do
+ it 'sends cancel email' do
+ expect(Spree::OrderMailer).to receive(:cancel_email).with(order.id).and_return(double(deliver_later: true))
+
+ subscriber.send(:send_cancel_email, mock_event(order, notify_customer: true))
+ end
+ end
end
end