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.

Promote shipping labels and deliveries to first-class records

Damian Legawiec7e2fe2a1b702
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 7a190dcf1a..763e92e3ee 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -7523,8 +7523,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -7542,15 +7540,26 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -7558,6 +7567,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
meta:
page: 1
@@ -7629,8 +7639,6 @@ paths:
number: R1001-F1
tracking: INPOST-12345
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_EfhxLZ9ck8
cost: '100.0'
@@ -7648,15 +7656,26 @@ paths:
status: fulfilled
fulfillment_type: shipping
fulfilled_at: '2026-01-15T12:00:00.000Z'
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_gbHJdmfrXB
+ tracking_number: INPOST-12345
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -7664,6 +7683,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
'422':
description: order not completed
@@ -7805,8 +7825,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -7824,15 +7842,26 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -7840,6 +7869,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
patch:
summary: Update a shipment
@@ -7903,8 +7933,6 @@ paths:
number: R1001-F1
tracking: 1Z999AA10123456784
tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
- tracking_carrier: ups
- tracking_carrier_name: UPS
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -7922,15 +7950,26 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: 1Z999AA10123456784
+ tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
+ carrier: ups
+ carrier_name: UPS
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -7938,6 +7977,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
requestBody:
content:
@@ -8015,8 +8055,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -8034,15 +8072,26 @@ paths:
status: fulfilled
fulfillment_type: shipping
fulfilled_at: '2026-01-15T12:00:00.000Z'
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -8050,19 +8099,21 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":
patch:
- summary: Buy the shipping label
+ summary: Buy the shipping label (deprecated)
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.
+ Deprecated alias of POST /labels, answering with the fulfillment instead of the label. Removed in Spree 6.1.
**Required scope:** `write_fulfillments` (for API-key authentication).
+ deprecated: true
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -8074,13 +8125,15 @@ paths:
secretKey: 'sk_xxx',
})
+ // Deprecated: use client.orders.fulfillments.labels.create() instead, which
+ // answers with the label itself. Removed in Spree 6.1.
const fulfillment = await client.orders.fulfillments.purchaseLabel(
'or_UkLWZg9DAJ',
'ful_UkLWZg9DAJ',
)
// The label is ready to print; the parcel is still unfulfilled.
- const label = fulfillment.documents.find((document) => document.kind === 'label')
+ const label = fulfillment.labels[0]
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fulfillments/{id}/purchase_label
@@ -8117,10 +8170,8 @@ paths:
example:
id: ful_UkLWZg9DAJ
number: R1001-F1
- tracking: LBL-123
- tracking_url:
- tracking_carrier:
- tracking_carrier_name:
+ tracking: 1Z879E930346834440
+ tracking_url: https://tracker.example/1Z879E930346834440
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -8138,24 +8189,57 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_gbHJdmfrXB
+ tracking_number: 1Z879E930346834440
+ tracking_url: https://tracker.example/1Z879E930346834440
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id: lbl_UkLWZg9DAJ
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
- documents:
- - kind: label
- url: https://carrier.example/label.pdf
+ documents: []
+ labels:
+ - id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ service: Ground
+ tracking_number: 1Z879E930346834440
+ currency: USD
+ format: pdf
+ external_id: shp_1
+ metadata:
+ tracker_id: trk_1
+ file_url: https://carrier.example/label.pdf
+ refunded_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ful_UkLWZg9DAJ
+ owner_type: fulfillment
+ carrier_name: UPS
+ cost: '7.25'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: true
+ download_url: "/api/v3/admin/orders/or_UkLWZg9DAJ/fulfillments/ful_UkLWZg9DAJ/labels/lbl_UkLWZg9DAJ/download"
provider_generates_labels: true
'422':
description: provider does not produce labels
@@ -8231,8 +8315,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -8250,15 +8332,26 @@ paths:
status: delivered
fulfillment_type: shipping
fulfilled_at: '2026-01-15T12:00:00.000Z'
- tracking_status:
- estimated_delivery_at:
delivered_at: '2026-01-15T12:00:00.000Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: delivered
+ estimated_delivery_at:
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -8266,6 +8359,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
'422':
description: fulfillment has not shipped
@@ -8351,8 +8445,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -8370,15 +8462,26 @@ paths:
status: canceled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -8386,6 +8489,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
+ labels: []
provider_generates_labels: false
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
patch:
@@ -8460,8 +8564,6 @@ paths:
number: R1001-F1
tracking:
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_EfhxLZ9ck8
cost: '10.0'
@@ -8479,15 +8581,13 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries: []
metadata: {}
- tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
created_at: '2026-01-15T12:00:00.000Z'
@@ -8495,6 +8595,7 @@ paths:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
documents: []
+ labels: []
provider_generates_labels: false
requestBody:
content:
@@ -12362,8 +12463,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 499180
- slug: product-499180
+ name: Product 559180
+ slug: product-559180
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -12475,8 +12576,8 @@ paths:
preorder_ships_at:
quantity: 3
currency: USD
- name: Product 5199
- slug: product-5199
+ name: Product 5799
+ slug: product-5799
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -12610,8 +12711,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 522714
- slug: product-522714
+ name: Product 582714
+ slug: product-582714
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -12718,8 +12819,8 @@ paths:
preorder_ships_at:
quantity: 5
currency: USD
- name: Product 539758
- slug: product-539758
+ name: Product 599758
+ slug: product-599758
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -17174,8 +17275,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 906550
- slug: product-906550
+ name: Product 1036550
+ slug: product-1036550
meta_title:
meta_description:
meta_keywords:
@@ -17568,8 +17669,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 942061
- slug: product-942061
+ name: Product 1072061
+ slug: product-1072061
meta_title:
meta_description:
meta_keywords:
@@ -17682,7 +17783,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-965339
+ slug: product-1095339
meta_title:
meta_description:
meta_keywords:
@@ -21860,15 +21961,15 @@ paths:
label: Country
description:
preference_schema:
- - key: country_id
- type: integer
- default:
- - key: country_code
- type: string
- default:
- key: country_codes
type: array
default: []
+ - key: country_code
+ type: string
+ default:
+ - key: country_id
+ type: integer
+ default:
- type: currency
label: Currency
description:
@@ -21895,9 +21996,6 @@ paths:
label: Item total
description:
preference_schema:
- - key: operator_max
- type: string
- default: "<"
- key: amount_min
type: decimal
default: 100.0
@@ -21907,6 +22005,9 @@ paths:
- key: amount_max
type: decimal
default:
+ - key: operator_max
+ type: string
+ default: "<"
- type: market
label: Market(s)
description:
@@ -25429,7 +25530,7 @@ paths:
data:
- id: variant_UkLWZg9DAJ
product_id: prod_UkLWZg9DAJ
- sku: SKU-153
+ sku: SKU-166
options_text: ''
track_inventory: true
media_count: 0
@@ -25480,11 +25581,11 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1216804
+ product_name: Product 1346804
delivery_profile_id: fp_UkLWZg9DAJ
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-154
+ sku: SKU-167
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -25547,7 +25648,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1216804
+ product_name: Product 1346804
delivery_profile_id: fp_UkLWZg9DAJ
meta:
page: 1
@@ -25689,7 +25790,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1221771
+ product_name: Product 1351771
delivery_profile_id: fp_UkLWZg9DAJ
'422':
description: validation error
@@ -25868,7 +25969,7 @@ paths:
example:
id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-160
+ sku: SKU-173
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -25931,7 +26032,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1244025
+ product_name: Product 1374025
delivery_profile_id: fp_UkLWZg9DAJ
'404':
description: variant not found
@@ -26067,7 +26168,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1265672
+ product_name: Product 1395672
delivery_profile_id: fp_UkLWZg9DAJ
requestBody:
content:
@@ -31494,9 +31595,9 @@ paths:
stock_location_ids: []
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '10.0'
- currency: USD
meta:
page: 1
limit: 25
@@ -31586,9 +31687,9 @@ paths:
stock_location_ids: []
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '12.5'
- currency: USD
requestBody:
content:
application/json:
@@ -31693,18 +31794,21 @@ paths:
- type: Spree::Calculator::Shipping::FlatRate
name: Flat rate
preference_schema:
+ - key: currency
+ type: string
+ default: USD
- key: amounts
type: hash
default: {}
- key: amount
type: decimal
default: 0
- - key: currency
- type: string
- default: USD
- type: Spree::Calculator::Shipping::FlexiRate
name: Flexible Rate per package item
preference_schema:
+ - key: currency
+ type: string
+ default: USD
- key: first_item
type: decimal
default: 0.0
@@ -31714,27 +31818,21 @@ paths:
- key: max_items
type: integer
default: 0
- - key: currency
- type: string
- default: USD
- type: Spree::Calculator::Shipping::PerItem
name: Flat rate per package item
preference_schema:
- - key: amount
- type: decimal
- default: 0
- key: currency
type: string
default: USD
- key: amounts
type: hash
default: {}
+ - key: amount
+ type: decimal
+ default: 0
- type: Spree::Calculator::Shipping::PriceSack
name: Price sack
preference_schema:
- - key: minimal_amount
- type: decimal
- default: 0
- key: normal_amount
type: decimal
default: 0
@@ -31744,18 +31842,21 @@ paths:
- key: currency
type: string
default: USD
+ - key: minimal_amount
+ type: decimal
+ default: 0
- type: Spree::Calculator::Shipping::DigitalDelivery
name: Digital Delivery
preference_schema:
- - key: amount
- type: decimal
- default: 0
- key: currency
type: string
default: USD
- key: amounts
type: hash
default: {}
+ - key: amount
+ type: decimal
+ default: 0
"/api/v3/admin/delivery_zones":
post:
summary: Create delivery zone
@@ -32209,13 +32310,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/thinking-cat.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e088d68778630357bc9c111025c520318f9e53f6/thinking-cat.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7862bdb0b4a1129a04e4b5aab6b2d42a96b1a6e8/thinking-cat.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c847f73f620dc717959362354a84b70def902c6/thinking-cat.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--058c36bdee88fe169e9ecd9e751878b90274e800/thinking-cat.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--89c8edba3b32de2b9ab556aeb83f02aa665527b0/thinking-cat.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--f20565de0e51f71a93c101afb0dfb31f86befc9b/thinking-cat.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d7596f383abfdff308e034c9ea5ad505acd7f2b4/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e135576662c594d9c8cfd5a3e58d866defe22992/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--aaf899c506d117d283f0ccd3e8cb48a41bdcee1d/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0bb7cacbaf66ddaa1c179a61a1e5a9e0a849f8/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--717aa91ed068163f5b61bb03ed156b6f56fa991f/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--4c20916daf771f49aa482b19600aa72bbfd820a6/thinking-cat.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -32223,10 +32324,10 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8eb21fd248651262b4d6dbe284889dd96fb1a811/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7e5aedb16bc1f8f3bb9766a4e2782205777e8468/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c
viewable_id: prod_UkLWZg9DAJ
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/thinking-cat.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/thinking-cat.jpg?disposition=attachment
metadata: {}
viewable_type: product
meta:
@@ -32297,13 +32398,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/library-upload.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e088d68778630357bc9c111025c520318f9e53f6/library-upload.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7862bdb0b4a1129a04e4b5aab6b2d42a96b1a6e8/library-upload.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c847f73f620dc717959362354a84b70def902c6/library-upload.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--058c36bdee88fe169e9ecd9e751878b90274e800/library-upload.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--89c8edba3b32de2b9ab556aeb83f02aa665527b0/library-upload.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--f20565de0e51f71a93c101afb0dfb31f86befc9b/library-upload.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/library-upload.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d7596f383abfdff308e034c9ea5ad505acd7f2b4/library-upload.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e135576662c594d9c8cfd5a3e58d866defe22992/library-upload.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--aaf899c506d117d283f0ccd3e8cb48a41bdcee1d/library-upload.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0bb7cacbaf66ddaa1c179a61a1e5a9e0a849f8/library-upload.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--717aa91ed068163f5b61bb03ed156b6f56fa991f/library-upload.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--4c20916daf771f49aa482b19600aa72bbfd820a6/library-upload.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -32311,10 +32412,10 @@ paths:
filename: library-upload.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8eb21fd248651262b4d6dbe284889dd96fb1a811/library-upload.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7e5aedb16bc1f8f3bb9766a4e2782205777e8468/library-upload.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13
viewable_id:
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--6fca0d8bf0f2d456709d08d503fe460d092ee623/library-upload.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/library-upload.jpg?disposition=attachment
metadata: {}
viewable_type:
schema:
@@ -32471,13 +32572,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/thinking-cat.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e088d68778630357bc9c111025c520318f9e53f6/thinking-cat.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7862bdb0b4a1129a04e4b5aab6b2d42a96b1a6e8/thinking-cat.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c847f73f620dc717959362354a84b70def902c6/thinking-cat.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--058c36bdee88fe169e9ecd9e751878b90274e800/thinking-cat.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--89c8edba3b32de2b9ab556aeb83f02aa665527b0/thinking-cat.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--f20565de0e51f71a93c101afb0dfb31f86befc9b/thinking-cat.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d7596f383abfdff308e034c9ea5ad505acd7f2b4/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e135576662c594d9c8cfd5a3e58d866defe22992/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--aaf899c506d117d283f0ccd3e8cb48a41bdcee1d/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0bb7cacbaf66ddaa1c179a61a1e5a9e0a849f8/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--717aa91ed068163f5b61bb03ed156b6f56fa991f/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--4c20916daf771f49aa482b19600aa72bbfd820a6/thinking-cat.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -32485,10 +32586,10 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8eb21fd248651262b4d6dbe284889dd96fb1a811/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7e5aedb16bc1f8f3bb9766a4e2782205777e8468/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c
viewable_id: prod_gbHJdmfrXB
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2/thinking-cat.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c/thinking-cat.jpg?disposition=attachment
metadata: {}
viewable_type: product
schema:
@@ -32510,6 +32611,855 @@ paths:
example: 1
required:
- source_media_id
+ "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":
+ get:
+ summary: List deliveries
+ tags:
+ - Deliveries
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ The consignments of a parcel — one per tracking number, each with the carrier status last reported.
+
+ **Required scope:** `read_fulfillments` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: deliveries } = await client.orders.fulfillments.deliveries.list(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ )
+
+ // Each carries its own carrier status: pending, in_transit, delivered, ...
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: deliveries found
+ content:
+ application/json:
+ example:
+ data:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Record a delivery
+ tags:
+ - Deliveries
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // A second box, or a freight consignment: the carrier is free text, so a
+ // forwarder's PRO number is as valid as a parcel number.
+ const delivery = await client.orders.fulfillments.deliveries.create(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ { tracking_number: 'PRO-4471923', carrier: 'Estes Freight' },
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries
+ -d '{"tracking_number":"PRO-4471923","carrier":"Estes Freight"}'
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ responses:
+ '201':
+ description: delivery recorded
+ content:
+ application/json:
+ example:
+ id: dlv_gbHJdmfrXB
+ tracking_number: 1Z879E930346834440
+ tracking_url: https://www.ups.com/track?tracknum=1Z879E930346834440
+ carrier: ups
+ carrier_name: UPS
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ '422':
+ description: tracking number already recorded on this parcel
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Tracking number has already been taken
+ details:
+ tracking_number:
+ - has already been taken
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - tracking_number
+ properties:
+ tracking_number:
+ type: string
+ description: Carrier tracking number, freight PRO number, or a full
+ tracking link
+ carrier:
+ type: string
+ description: Free-text carrier; detected from the number when omitted
+ service:
+ type: string
+ description: Carrier service
+ tracking_url:
+ type: string
+ description: Tracking page for this consignment
+ required: true
+ "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":
+ patch:
+ summary: Correct a delivery
+ tags:
+ - Deliveries
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Delivery ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: delivery updated
+ content:
+ application/json:
+ example:
+ id: dlv_UkLWZg9DAJ
+ tracking_number: CORRECTED-1
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ tracking_number:
+ type: string
+ carrier:
+ type: string
+ service:
+ type: string
+ tracking_url:
+ type: string
+ required: true
+ delete:
+ summary: Delete a delivery
+ tags:
+ - Deliveries
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Removes a hand-entered consignment. One a label minted is refused — refund the label instead.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Delivery ID
+ schema:
+ type: string
+ responses:
+ '204':
+ description: delivery deleted
+ "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":
+ patch:
+ summary: Mark a delivery delivered
+ tags:
+ - Deliveries
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Staff confirming one consignment arrived. The fulfillment follows once
+ // every one of its consignments has.
+ const delivery = await client.orders.fulfillments.deliveries.markDelivered(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'dlv_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Delivery ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: delivery marked delivered
+ content:
+ application/json:
+ example:
+ id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: delivered
+ estimated_delivery_at:
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ delivered_at:
+ type: string
+ format: date-time
+ description: When it arrived. Defaults to now.
+ notify_customer:
+ type: boolean
+ description: Whether the customer gets a delivery notification when
+ the parcel completes.
+ "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":
+ get:
+ summary: List shipping labels
+ tags:
+ - Shipping Labels
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Every label bought or uploaded for a parcel, refunded ones included.
+
+ **Required scope:** `read_fulfillments` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: labels } = await client.orders.fulfillments.labels.list(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /orders/{order_id}/fulfillments/{fulfillment_id}/labels
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: labels found
+ content:
+ application/json:
+ example:
+ data:
+ - id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ service: Ground
+ tracking_number: 1Z879E930346830001
+ currency: USD
+ format: pdf
+ external_id: shp_1
+ metadata: {}
+ refunded_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ful_UkLWZg9DAJ
+ owner_type: fulfillment
+ carrier_name: UPS
+ cost: '7.25'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: false
+ download_url:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Buy or record a shipping label
+ tags:
+ - Shipping Labels
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // With no body, the parcel's carrier account buys the label.
+ const label = await client.orders.fulfillments.labels.create(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ )
+
+ // The tracking number is now on the parcel's first delivery, and the label is
+ // ready to print. What the merchant paid the carrier is label.display_cost.
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /orders/{order_id}/fulfillments/{fulfillment_id}/labels
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ responses:
+ '201':
+ description: label purchased
+ content:
+ application/json:
+ example:
+ id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ service: Ground
+ tracking_number: 1Z879E930346834440
+ currency: USD
+ format: pdf
+ external_id: shp_1
+ metadata:
+ tracker_id: trk_1
+ file_url: https://carrier.example/label.pdf
+ refunded_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ful_UkLWZg9DAJ
+ owner_type: fulfillment
+ carrier_name: UPS
+ cost: '7.25'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: true
+ download_url: "/api/v3/admin/orders/or_UkLWZg9DAJ/fulfillments/ful_UkLWZg9DAJ/labels/lbl_UkLWZg9DAJ/download"
+ '422':
+ description: provider does not produce labels
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: This delivery method's provider does not produce labels
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ file:
+ type: string
+ description: Signed blob id of an uploaded label file; its presence
+ records rather than buys
+ tracking_number:
+ type: string
+ description: Number printed on an uploaded label
+ carrier:
+ type: string
+ description: Free-text carrier; detected from the number when omitted
+ service:
+ type: string
+ description: Carrier service the label was bought at
+ cost:
+ type: string
+ description: What the merchant paid the carrier
+ currency:
+ type: string
+ description: Currency of the cost
+ file_format:
+ type: string
+ enum:
+ - pdf
+ - png
+ - zpl
+ description: Label file format; taken from the file when omitted
+ tracking_url:
+ type: string
+ description: Tracking page for the consignment
+ "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":
+ get:
+ summary: Get a shipping label
+ tags:
+ - Shipping Labels
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ One label, with what it cost and where to print it from.
+
+ **Required scope:** `read_fulfillments` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Shipping label ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: label found
+ content:
+ application/json:
+ example:
+ id: lbl_UkLWZg9DAJ
+ source: uploaded
+ status: purchased
+ carrier: ups
+ service: Ground
+ tracking_number: 1Z879E930346830002
+ currency: USD
+ format: pdf
+ external_id:
+ metadata: {}
+ refunded_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ful_UkLWZg9DAJ
+ owner_type: fulfillment
+ carrier_name: UPS
+ cost: '7.25'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: false
+ download_url:
+ delete:
+ summary: Delete an uploaded label
+ tags:
+ - Shipping Labels
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Shipping label ID
+ schema:
+ type: string
+ responses:
+ '204':
+ description: label deleted
+ "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":
+ patch:
+ summary: Refund a shipping label
+ tags:
+ - Shipping Labels
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.
+
+ **Required scope:** `write_fulfillments` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const label = await client.orders.fulfillments.labels.refund(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'lbl_UkLWZg9DAJ',
+ )
+
+ // 'refunded' when the carrier settled at once, 'refund_requested' when it
+ // will answer later.
+ const outcome = label.status
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Shipping label ID
+ schema:
+ type: string
+ responses:
+ '200':
+ description: refund filed
+ content:
+ application/json:
+ example:
+ id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: refunded
+ carrier: ups
+ service: Ground
+ tracking_number: 1Z879E930346830004
+ currency: USD
+ format: pdf
+ external_id: shp_2
+ metadata: {}
+ refunded_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ful_UkLWZg9DAJ
+ owner_type: fulfillment
+ carrier_name: UPS
+ cost: '7.25'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: false
+ download_url:
+ '422':
+ description: uploaded labels cannot be refunded
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: An uploaded label was not bought through Spree and cannot
+ be refunded — delete it instead
"/api/v3/admin/price_lists/{price_list_id}/products":
get:
summary: List price list products
@@ -33374,6 +34324,9 @@ paths:
accepted_content_types: []
association_fields: []
preference_schema:
+ - key: require_contact_email
+ type: boolean
+ default: true
- key: require_about
type: boolean
default: true
@@ -33383,9 +34336,6 @@ paths:
- key: require_cover_photo
type: boolean
default: false
- - key: require_contact_email
- type: boolean
- default: true
- type: billing_address
name: Billing address
description: The address your payouts are billed from
@@ -37766,6 +38716,58 @@ components:
- created_at
- updated_at
x-typelizer: true
+ Delivery:
+ type: object
+ properties:
+ id:
+ type: string
+ tracking_number:
+ type: string
+ tracking_url:
+ type: string
+ nullable: true
+ carrier:
+ type: string
+ nullable: true
+ carrier_name:
+ type: string
+ nullable: true
+ service:
+ type: string
+ nullable: true
+ status:
+ type: string
+ estimated_delivery_at:
+ type: string
+ nullable: true
+ delivered_at:
+ type: string
+ nullable: true
+ details:
+ type: object
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ shipping_label_id:
+ type: string
+ nullable: true
+ required:
+ - id
+ - tracking_number
+ - tracking_url
+ - carrier
+ - carrier_name
+ - service
+ - status
+ - estimated_delivery_at
+ - delivered_at
+ - details
+ - created_at
+ - updated_at
+ - shipping_label_id
+ x-typelizer: true
DeliveryZoneMember:
type: object
properties:
@@ -38267,12 +39269,6 @@ components:
tracking_url:
type: string
nullable: true
- tracking_carrier:
- type: string
- nullable: true
- tracking_carrier_name:
- type: string
- nullable: true
pickup_point_data:
type: object
nullable: true
@@ -38310,12 +39306,6 @@ components:
fulfilled_at:
type: string
nullable: true
- tracking_status:
- type: string
- nullable: true
- estimated_delivery_at:
- type: string
- nullable: true
delivered_at:
type: string
nullable: true
@@ -38323,6 +39313,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/FulfillmentManifestItem"
+ deliveries:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Delivery"
delivery_method:
"$ref": "#/components/schemas/DeliveryMethod"
stock_location:
@@ -38337,9 +39331,6 @@ components:
"$ref": "#/components/schemas/TaxLine"
metadata:
type: object
- tracking_details:
- type: object
- nullable: true
adjustment_total:
type: string
pre_tax_amount:
@@ -38356,6 +39347,10 @@ components:
nullable: true
documents:
type: object
+ labels:
+ type: array
+ items:
+ "$ref": "#/components/schemas/ShippingLabel"
provider_generates_labels:
type: boolean
fulfillment_items:
@@ -38369,8 +39364,6 @@ components:
- number
- tracking
- tracking_url
- - tracking_carrier
- - tracking_carrier_name
- pickup_point_data
- selected_delivery_rate_id
- cost
@@ -38388,12 +39381,10 @@ components:
- status
- fulfillment_type
- fulfilled_at
- - tracking_status
- - estimated_delivery_at
- delivered_at
- items
+ - deliveries
- metadata
- - tracking_details
- adjustment_total
- pre_tax_amount
- created_at
@@ -38401,6 +39392,7 @@ components:
- order_id
- stock_location_id
- documents
+ - labels
- provider_generates_labels
x-typelizer: true
GiftCardBatch:
@@ -41281,6 +42273,84 @@ components:
- name
- done
x-typelizer: true
+ ShippingLabel:
+ type: object
+ properties:
+ id:
+ type: string
+ source:
+ type: string
+ status:
+ type: string
+ carrier:
+ type: string
+ nullable: true
+ service:
+ type: string
+ nullable: true
+ tracking_number:
+ type: string
+ nullable: true
+ currency:
+ type: string
+ nullable: true
+ format:
+ type: string
+ nullable: true
+ external_id:
+ type: string
+ nullable: true
+ metadata:
+ type: object
+ refunded_at:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ owner_id:
+ type: string
+ owner_type:
+ type: string
+ carrier_name:
+ type: string
+ nullable: true
+ cost:
+ type: string
+ display_cost:
+ type: string
+ integration_id:
+ type: string
+ nullable: true
+ file_pending:
+ type: boolean
+ download_url:
+ type: string
+ nullable: true
+ required:
+ - id
+ - source
+ - status
+ - carrier
+ - service
+ - tracking_number
+ - currency
+ - format
+ - external_id
+ - metadata
+ - refunded_at
+ - created_at
+ - updated_at
+ - owner_id
+ - owner_type
+ - carrier_name
+ - cost
+ - display_cost
+ - integration_id
+ - file_pending
+ - download_url
+ x-typelizer: true
State:
type: object
properties:
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yaml
index 8c1eec50ab..4b94d79d5e 100644
--- a/docs/api-reference/seller.yaml
+++ b/docs/api-reference/seller.yaml
@@ -12351,9 +12351,9 @@ paths:
delivery_zone_id:
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '10.0'
- currency: USD
- id: dm_gbHJdmfrXB
name: Marketplace post
code: UPS_GROUND
@@ -12373,9 +12373,9 @@ paths:
delivery_zone_id:
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '10.0'
- currency: USD
meta:
page: 1
limit: 25
@@ -12442,9 +12442,9 @@ paths:
delivery_zone_id:
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '9.99'
- currency: USD
schema:
"$ref": "#/components/schemas/DeliveryMethod"
'422':
@@ -12552,9 +12552,9 @@ paths:
delivery_zone_id:
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '10.0'
- currency: USD
schema:
"$ref": "#/components/schemas/DeliveryMethod"
patch:
@@ -12591,9 +12591,9 @@ paths:
delivery_zone_id:
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ currency: USD
amounts: {}
amount: '10.0'
- currency: USD
schema:
"$ref": "#/components/schemas/DeliveryMethod"
requestBody:
@@ -12692,10 +12692,10 @@ paths:
description: Limits the delivery method to packages within a weight
range
preference_schema:
- - key: maximum_weight
+ - key: minimum_weight
type: decimal
default:
- - key: minimum_weight
+ - key: maximum_weight
type: decimal
default:
schema:
@@ -12747,18 +12747,21 @@ paths:
- type: Spree::Calculator::Shipping::FlatRate
name: Flat rate
preference_schema:
+ - key: currency
+ type: string
+ default: USD
- key: amounts
type: hash
default: {}
- key: amount
type: decimal
default: 0
- - key: currency
- type: string
- default: USD
- type: Spree::Calculator::Shipping::FlexiRate
name: Flexible Rate per package item
preference_schema:
+ - key: currency
+ type: string
+ default: USD
- key: first_item
type: decimal
default: 0.0
@@ -12768,27 +12771,21 @@ paths:
- key: max_items
type: integer
default: 0
- - key: currency
- type: string
- default: USD
- type: Spree::Calculator::Shipping::PerItem
name: Flat rate per package item
preference_schema:
- - key: amount
- type: decimal
- default: 0
- key: currency
type: string
default: USD
- key: amounts
type: hash
default: {}
+ - key: amount
+ type: decimal
+ default: 0
- type: Spree::Calculator::Shipping::PriceSack
name: Price sack
preference_schema:
- - key: minimal_amount
- type: decimal
- default: 0
- key: normal_amount
type: decimal
default: 0
@@ -12798,18 +12795,21 @@ paths:
- key: currency
type: string
default: USD
+ - key: minimal_amount
+ type: decimal
+ default: 0
- type: Spree::Calculator::Shipping::DigitalDelivery
name: Digital Delivery
preference_schema:
- - key: amount
- type: decimal
- default: 0
- key: currency
type: string
default: USD
- key: amounts
type: hash
default: {}
+ - key: amount
+ type: decimal
+ default: 0
schema:
type: object
properties:
@@ -13540,8 +13540,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1423250
- slug: product-1423250
+ name: Product 1543250
+ slug: product-1543250
meta_title:
meta_description:
meta_keywords:
@@ -13784,8 +13784,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1456710
- slug: product-1456710
+ name: Product 1576710
+ slug: product-1576710
meta_title:
meta_description:
meta_keywords:
@@ -13864,7 +13864,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Hand-thrown mug, large
- slug: product-1488212
+ slug: product-1608212
meta_title:
meta_description:
meta_keywords:
@@ -14793,10 +14793,10 @@ paths:
application/json:
example:
direct_upload:
- url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--fefa29846e57b406fd870c24f857d52f6cd20dcc
+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--de94a8a7ad335bb09c67c34e0d1636eb260bf5ee
headers:
Content-Type: application/pdf
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--097870ba8f99e7e5fea39d9882796b01b2f16bd2
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a48538b48c503641a28ef3feb456a870f0c28b6c
schema:
"$ref": "#/components/schemas/DirectUploadResponse"
requestBody:
@@ -15048,9 +15048,8 @@ paths:
status: unfulfilled
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_status:
fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
@@ -15060,9 +15059,23 @@ paths:
- id: fi_UkLWZg9DAJ
quantity: 1
line_item_id: li_UkLWZg9DAJ
- name: Product 1359315
- sku: SKU-174
+ name: Product 1479315
+ sku: SKU-186
options_text: ''
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
schema:
type: object
properties:
@@ -15118,9 +15131,8 @@ paths:
status: fulfilled
tracking: TRACK-1
tracking_url:
- tracking_carrier:
- tracking_status:
fulfilled_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
@@ -15130,9 +15142,23 @@ paths:
- id: fi_UkLWZg9DAJ
quantity: 1
line_item_id: li_UkLWZg9DAJ
- name: Product 136961
- sku: SKU-175
+ name: Product 148961
+ sku: SKU-187
options_text: ''
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: TRACK-1
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
schema:
"$ref": "#/components/schemas/Fulfillment"
requestBody:
@@ -15231,7 +15257,7 @@ paths:
display_total: "$110.00"
items:
- id: li_UkLWZg9DAJ
- name: Product 13795
+ name: Product 14995
options_text: ''
quantity: 1
currency: USD
@@ -15240,7 +15266,7 @@ paths:
total: '10.0'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
- sku: SKU-176
+ sku: SKU-188
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -15248,9 +15274,8 @@ paths:
status: unfulfilled
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_status:
fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
@@ -15260,16 +15285,30 @@ paths:
- id: fi_UkLWZg9DAJ
quantity: 1
line_item_id: li_UkLWZg9DAJ
- name: Product 13795
- sku: SKU-176
+ name: Product 14995
+ sku: SKU-188
options_text: ''
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
shipping_address:
id: addr_gbHJdmfrXB
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 115 Lovely Street
+ address1: 139 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -15291,7 +15330,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 114 Lovely Street
+ address1: 138 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -15380,7 +15419,7 @@ paths:
display_total: "$110.00"
items:
- id: li_UkLWZg9DAJ
- name: Product 1389755
+ name: Product 1509755
options_text: ''
quantity: 1
currency: USD
@@ -15389,7 +15428,7 @@ paths:
total: '10.0'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
- sku: SKU-177
+ sku: SKU-189
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -15397,9 +15436,8 @@ paths:
status: unfulfilled
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_status:
fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
@@ -15409,16 +15447,30 @@ paths:
- id: fi_UkLWZg9DAJ
quantity: 1
line_item_id: li_UkLWZg9DAJ
- name: Product 1389755
- sku: SKU-177
+ name: Product 1509755
+ sku: SKU-189
options_text: ''
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
shipping_address:
id: addr_gbHJdmfrXB
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 117 Lovely Street
+ address1: 141 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -15440,7 +15492,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 116 Lovely Street
+ address1: 140 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -15518,7 +15570,7 @@ paths:
display_total: "$110.00"
items:
- id: li_UkLWZg9DAJ
- name: Product 1416554
+ name: Product 1536554
options_text: ''
quantity: 1
currency: USD
@@ -15527,7 +15579,7 @@ paths:
total: '10.0'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
- sku: SKU-180
+ sku: SKU-192
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -15535,9 +15587,8 @@ paths:
status: canceled
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_status:
fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
@@ -15547,16 +15598,30 @@ paths:
- id: fi_UkLWZg9DAJ
quantity: 1
line_item_id: li_UkLWZg9DAJ
- name: Product 1416554
- sku: SKU-180
+ name: Product 1536554
+ sku: SKU-192
options_text: ''
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
shipping_address:
id: addr_gbHJdmfrXB
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 123 Lovely Street
+ address1: 147 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -15578,7 +15643,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 122 Lovely Street
+ address1: 146 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16764,6 +16829,54 @@ components:
- default
- digital
x-typelizer: true
+ Delivery:
+ type: object
+ properties:
+ id:
+ type: string
+ tracking_number:
+ type: string
+ tracking_url:
+ type: string
+ nullable: true
+ carrier:
+ type: string
+ nullable: true
+ carrier_name:
+ type: string
+ nullable: true
+ service:
+ type: string
+ nullable: true
+ status:
+ type: string
+ estimated_delivery_at:
+ type: string
+ nullable: true
+ delivered_at:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ shipping_label_id:
+ type: string
+ nullable: true
+ required:
+ - id
+ - tracking_number
+ - tracking_url
+ - carrier
+ - carrier_name
+ - service
+ - status
+ - estimated_delivery_at
+ - delivered_at
+ - created_at
+ - updated_at
+ - shipping_label_id
+ x-typelizer: true
DeliveryZone:
type: object
properties:
@@ -16868,13 +16981,10 @@ components:
tracking_url:
type: string
nullable: true
- tracking_carrier:
- type: string
- nullable: true
- tracking_status:
+ fulfilled_at:
type: string
nullable: true
- fulfilled_at:
+ delivered_at:
type: string
nullable: true
created_at:
@@ -16894,21 +17004,30 @@ components:
type: array
items:
"$ref": "#/components/schemas/FulfillmentItem"
+ deliveries:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Delivery"
+ labels:
+ type: array
+ items:
+ "$ref": "#/components/schemas/ShippingLabel"
required:
- id
- number
- status
- tracking
- tracking_url
- - tracking_carrier
- - tracking_status
- fulfilled_at
+ - delivered_at
- created_at
- updated_at
- fulfillment_type
- delivery_method_name
- stock_location_name
- fulfillment_items
+ - deliveries
+ - labels
x-typelizer: true
ImportMapping:
type: object
@@ -17744,6 +17863,84 @@ components:
- file_url
- file_name
x-typelizer: true
+ ShippingLabel:
+ type: object
+ properties:
+ id:
+ type: string
+ source:
+ type: string
+ status:
+ type: string
+ carrier:
+ type: string
+ nullable: true
+ service:
+ type: string
+ nullable: true
+ tracking_number:
+ type: string
+ nullable: true
+ currency:
+ type: string
+ nullable: true
+ format:
+ type: string
+ nullable: true
+ external_id:
+ type: string
+ nullable: true
+ metadata:
+ type: object
+ refunded_at:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ owner_id:
+ type: string
+ owner_type:
+ type: string
+ carrier_name:
+ type: string
+ nullable: true
+ cost:
+ type: string
+ display_cost:
+ type: string
+ integration_id:
+ type: string
+ nullable: true
+ file_pending:
+ type: boolean
+ download_url:
+ type: string
+ nullable: true
+ required:
+ - id
+ - source
+ - status
+ - carrier
+ - service
+ - tracking_number
+ - currency
+ - format
+ - external_id
+ - metadata
+ - refunded_at
+ - created_at
+ - updated_at
+ - owner_id
+ - owner_type
+ - carrier_name
+ - cost
+ - display_cost
+ - integration_id
+ - file_pending
+ - download_url
+ x-typelizer: true
StockLevel:
type: object
properties:
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 4300934993..923ade273f 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -876,8 +876,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1766979
- slug: product-1766979
+ name: Product 1886979
+ slug: product-1886979
meta_title:
meta_description:
meta_keywords:
@@ -1051,8 +1051,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 2229085
- slug: product-2229085
+ name: Product 2349085
+ slug: product-2349085
meta_title:
meta_description:
meta_keywords:
@@ -1083,8 +1083,8 @@ paths:
original_price:
seller_id:
- id: prod_gbHJdmfrXB
- name: Product 2238209
- slug: product-2238209
+ name: Product 2358209
+ slug: product-2358209
meta_title:
meta_description:
meta_keywords:
@@ -1213,8 +1213,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 2506885
- slug: product-2506885
+ name: Product 2626885
+ slug: product-2626885
meta_title:
meta_description:
meta_keywords:
@@ -1572,8 +1572,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 150715
- slug: product-150715
+ name: Product 162715
+ slug: product-162715
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1690,8 +1690,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1512171
- slug: product-1512171
+ name: Product 1632171
+ slug: product-1632171
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1998,7 +1998,7 @@ paths:
total_quantity: 0
warnings:
- code: line_item_removed
- message: Product 155307 was removed because it was sold out
+ message: Product 167307 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
coupon_code:
@@ -2218,8 +2218,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1563263
- slug: product-1563263
+ name: Product 1683263
+ slug: product-1683263
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2503,8 +2503,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1588992
- slug: product-1588992
+ name: Product 1708992
+ slug: product-1708992
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2535,7 +2535,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 160 Lovely Street
+ address1: 184 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2557,7 +2557,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 159 Lovely Street
+ address1: 183 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2714,8 +2714,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1614794
- slug: product-1614794
+ name: Product 1734794
+ slug: product-1734794
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2743,8 +2743,6 @@ paths:
number: R1001-F1
tracking:
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '10.0'
@@ -2762,13 +2760,12 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_gbHJdmfrXB
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries: []
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
@@ -2849,7 +2846,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 166 Lovely Street
+ address1: 190 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2871,7 +2868,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 165 Lovely Street
+ address1: 189 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3054,8 +3051,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1884241
- slug: product-1884241
+ name: Product 2004241
+ slug: product-2004241
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3252,8 +3249,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1903461
- slug: product-1903461
+ name: Product 2023461
+ slug: product-2023461
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3438,8 +3435,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1928182
- slug: product-1928182
+ name: Product 2048182
+ slug: product-2048182
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3467,8 +3464,6 @@ paths:
number: cart_UkLWZg9DAJ-F1
tracking:
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '10.0'
@@ -3486,13 +3481,12 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries: []
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
@@ -3549,7 +3543,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 250 Lovely Street
+ address1: 274 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3734,8 +3728,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1945702
- slug: product-1945702
+ name: Product 2065702
+ slug: product-2065702
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3987,8 +3981,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1989569
- slug: product-1989569
+ name: Product 2109569
+ slug: product-2109569
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4141,10 +4135,10 @@ paths:
total_quantity: 2
warnings:
- code: delivery_unavailable
- message: Product 20163 cannot be delivered to the selected address
+ message: Product 21363 cannot be delivered to the selected address
line_item_id: li_UkLWZg9DAJ
- code: delivery_unavailable
- message: Product 202298 cannot be delivered to the selected address
+ message: Product 214298 cannot be delivered to the selected address
line_item_id: li_gbHJdmfrXB
coupon_code:
item_total: '29.99'
@@ -4201,8 +4195,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 20163
- slug: product-20163
+ name: Product 21363
+ slug: product-21363
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4232,8 +4226,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 202298
- slug: product-202298
+ name: Product 214298
+ slug: product-214298
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4461,8 +4455,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2089165
- slug: product-2089165
+ name: Product 2209165
+ slug: product-2209165
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5289,8 +5283,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2709789
- slug: product-2709789
+ name: Product 2829789
+ slug: product-2829789
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5506,8 +5500,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 272179
- slug: product-272179
+ name: Product 284179
+ slug: product-284179
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5676,8 +5670,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 212496
- slug: product-212496
+ name: Product 224496
+ slug: product-224496
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5705,8 +5699,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -5724,13 +5716,21 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
@@ -5786,7 +5786,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 306 Lovely Street
+ address1: 330 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5808,7 +5808,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 307 Lovely Street
+ address1: 331 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5914,7 +5914,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 124 Lovely Street
+ address1: 148 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5935,7 +5935,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 125 Lovely Street
+ address1: 149 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5956,7 +5956,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 126 Lovely Street
+ address1: 150 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6214,7 +6214,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 138 Lovely Street
+ address1: 162 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6296,7 +6296,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 144 Lovely Street
+ address1: 168 Lovely Street
address2: Northwest
postal_code: '10118'
city: Los Angeles
@@ -6789,8 +6789,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1785270
- slug: product-1785270
+ name: Product 1905270
+ slug: product-1905270
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6818,8 +6818,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -6837,13 +6835,21 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
@@ -6899,7 +6905,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 210 Lovely Street
+ address1: 234 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6921,7 +6927,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 211 Lovely Street
+ address1: 235 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7100,8 +7106,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1805633
- slug: product-1805633
+ name: Product 1925633
+ slug: product-1925633
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7129,8 +7135,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -7148,13 +7152,21 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
@@ -7210,7 +7222,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 216 Lovely Street
+ address1: 240 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7232,7 +7244,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 217 Lovely Street
+ address1: 241 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7451,7 +7463,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 222 Lovely Street
+ address1: 246 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7472,7 +7484,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 223 Lovely Street
+ address1: 247 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7494,7 +7506,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 223 Lovely Street
+ address1: 247 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7516,7 +7528,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 222 Lovely Street
+ address1: 246 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7607,7 +7619,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 224 Lovely Street
+ address1: 248 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7628,7 +7640,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 225 Lovely Street
+ address1: 249 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7650,7 +7662,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 225 Lovely Street
+ address1: 249 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7672,7 +7684,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 224 Lovely Street
+ address1: 248 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9468,7 +9480,7 @@ paths:
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-333
+ sku: SKU-345
options_text: ''
track_inventory: true
media_count: 0
@@ -10397,7 +10409,7 @@ paths:
first_name:
last_name:
full_name: ''
- address1: 183 Lovely Street
+ address1: 207 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -10468,7 +10480,7 @@ paths:
first_name:
last_name:
full_name: ''
- address1: 186 Lovely Street
+ address1: 210 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -10645,8 +10657,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1775649
- slug: product-1775649
+ name: Product 1895649
+ slug: product-1895649
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -10674,8 +10686,6 @@ paths:
number: R1001-F1
tracking: U10000
tracking_url:
- tracking_carrier:
- tracking_carrier_name:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
cost: '100.0'
@@ -10693,13 +10703,21 @@ paths:
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
- tracking_status:
- estimated_delivery_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ tracking_url:
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ estimated_delivery_at:
+ delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
@@ -10755,7 +10773,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 194 Lovely Street
+ address1: 218 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -10777,7 +10795,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 195 Lovely Street
+ address1: 219 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -12569,6 +12587,44 @@ components:
- display_tax_total
- delivery_method
x-typelizer: true
+ Delivery:
+ type: object
+ properties:
+ id:
+ type: string
+ tracking_number:
+ type: string
+ tracking_url:
+ type: string
+ nullable: true
+ carrier:
+ type: string
+ nullable: true
+ carrier_name:
+ type: string
+ nullable: true
+ service:
+ type: string
+ nullable: true
+ status:
+ type: string
+ estimated_delivery_at:
+ type: string
+ nullable: true
+ delivered_at:
+ type: string
+ nullable: true
+ required:
+ - id
+ - tracking_number
+ - tracking_url
+ - carrier
+ - carrier_name
+ - service
+ - status
+ - estimated_delivery_at
+ - delivered_at
+ x-typelizer: true
DeliveryZoneMember:
type: object
properties:
@@ -12769,12 +12825,6 @@ components:
tracking_url:
type: string
nullable: true
- tracking_carrier:
- type: string
- nullable: true
- tracking_carrier_name:
- type: string
- nullable: true
pickup_point_data:
type: object
nullable: true
@@ -12824,12 +12874,6 @@ components:
fulfilled_at:
type: string
nullable: true
- tracking_status:
- type: string
- nullable: true
- estimated_delivery_at:
- type: string
- nullable: true
delivered_at:
type: string
nullable: true
@@ -12837,6 +12881,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/FulfillmentManifestItem"
+ deliveries:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Delivery"
delivery_method:
"$ref": "#/components/schemas/DeliveryMethod"
stock_location:
@@ -12854,8 +12902,6 @@ components:
- number
- tracking
- tracking_url
- - tracking_carrier
- - tracking_carrier_name
- pickup_point_data
- selected_delivery_rate_id
- cost
@@ -12873,10 +12919,9 @@ components:
- status
- fulfillment_type
- fulfilled_at
- - tracking_status
- - estimated_delivery_at
- delivered_at
- items
+ - deliveries
- delivery_method
- stock_location
- delivery_rates
@@ -14477,6 +14522,84 @@ components:
- square_logo_url
- cover_photo_url
x-typelizer: true
+ ShippingLabelEvent:
+ type: object
+ properties:
+ id:
+ type: string
+ source:
+ type: string
+ status:
+ type: string
+ carrier:
+ type: string
+ nullable: true
+ service:
+ type: string
+ nullable: true
+ tracking_number:
+ type: string
+ nullable: true
+ currency:
+ type: string
+ nullable: true
+ format:
+ type: string
+ nullable: true
+ external_id:
+ type: string
+ nullable: true
+ metadata:
+ type: object
+ refunded_at:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ owner_id:
+ type: string
+ owner_type:
+ type: string
+ carrier_name:
+ type: string
+ nullable: true
+ cost:
+ type: string
+ display_cost:
+ type: string
+ integration_id:
+ type: string
+ nullable: true
+ file_pending:
+ type: boolean
+ download_url:
+ type: string
+ nullable: true
+ required:
+ - id
+ - source
+ - status
+ - carrier
+ - service
+ - tracking_number
+ - currency
+ - format
+ - external_id
+ - metadata
+ - refunded_at
+ - created_at
+ - updated_at
+ - owner_id
+ - owner_type
+ - carrier_name
+ - cost
+ - display_cost
+ - integration_id
+ - file_pending
+ - download_url
+ x-typelizer: true
State:
type: object
properties:
diff --git a/docs/plans/6.0-shipping-labels-and-deliveries.md b/docs/plans/6.0-shipping-labels-and-deliveries.md
index 289b11cdc0..96c27121fd 100644
--- a/docs/plans/6.0-shipping-labels-and-deliveries.md
+++ b/docs/plans/6.0-shipping-labels-and-deliveries.md
@@ -1,6 +1,6 @@
# Shipping Labels and Deliveries
-**Status:** Draft — design finalized 2026-09-03, nothing built
+**Status:** Implemented 2026-09-03 (phases 1–6; phase 7 is 6.1 cleanup)
**Target:** Spree 6.0
**Depends on:** `6.0-fulfillment-and-delivery.md` (status model, `PurchaseLabel`, `UpdateTracking`), `6.0-delivery-rate-provider.md` (EasyPost reference provider), `6.0-returns-exchanges-claims.md` (the `Return` owner). Coordinates with: `6.0-b2b-wholesale-shipping.md` (freight consignments are deliveries too; freight paperwork is not a label), `6.1-b2b-order-documents.md` (where a bill of lading goes).
**Author:** Damian Legawiec
@@ -158,6 +158,16 @@ Admin API; `purchase_label` and `mark_delivered` stop being the only doors.
report **never** auto-receives — `Returns::Receive` stays a staff act
because arrival is not inspection. The returns plan's interim "URL in
`metadata`" advice is withdrawn.
+- **A return label buys the cheapest rate the account offers (2026-09-03).**
+ Unlike an outbound parcel there is no rate the customer selected: return
+ postage is the merchant's own money and nobody chose a service for it, so
+ `EasyPost::Util.get_lowest_object_rate` picks across every connected
+ carrier. Reusing the outbound carrier was considered and rejected — an
+ outbound parcel whose tracking was hand-entered has no carrier to reuse,
+ and mirroring the outbound *service* inbound is usually the most expensive
+ answer to a question the merchant never asked. A merchant who wants a
+ specific return service configures it on the integration later; that is
+ additive.
- **No transition graph, no state machine.** `ShippingLabel` uses
`has_status`; every status change is a workflow (`ShippingLabels::Purchase`,
`::Refund`, `::Record` for uploads). `Delivery#status` is the carrier's
@@ -440,6 +450,15 @@ Phases 1–6 are one PR train on one branch; the data task ships with phase 3.
`Returns::Receive` itself, staff-style.
- **Label files are private-storage attachments streamed by the API** —
never a public blob URL on any serializer, never `attachment.url`.
+- **`Fulfillment#tracking` is a read-through summary, and `tracking=` is a
+ deprecated shell.** New code creates a delivery (`Deliveries::Create`, or
+ the `tracking:` keyword on `Fulfillments::Fulfill`/`Update`); assigning
+ `tracking` still works one release, writing the primary delivery on save
+ with a warning, and is removed in 6.1 with the column.
+- **The label's file format is written as `file_format` on the API.**
+ `format` is Rails' own request-format parameter, so a controller permitting
+ it receives `"json"` and the label refuses to save; the model attribute
+ keeps the name `format`.
## Open Questions
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index bb38afed39..4c44a00f0a 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -6,6 +6,34 @@
**Consequences:** No behaviour change; the fix is that the code and the dashboard now say so. The class comment is corrected (it was the only place claiming the two audiences combine), the `for_context` and pricing-resolver comments read "or failing that" rather than "then", and the fallback carries an inline note. The dashboard states the precedence where a merchant can act on it: help text under the audience picker when a customer group is chosen, and a standing note on the audience card and wizard step whenever a group assignment is present, pointing at the company route for tier pricing. The developer docs stop framing the three ways of reaching a buyer as combining and carry the tier recipe as a warning. Three examples in `catalog_spec.rb` lock the ruling — the group dropping out once a company catalog exists, the group still applying when none does, and the subtree union when the tier is a company assignment. What is *not* solved: nothing detects a catalog assigned only to groups whose members are all company buyers, so such a catalog is still silently unreachable; a reachability warning needs the buyer population and is a separate piece of work.
+## 2026-09-03: A return label buys the cheapest rate; the fulfillment's tracking becomes a read-through summary
+
+**Context:** Implementing `6.0-shipping-labels-and-deliveries.md` raised two
+questions the design left open — which rate a return label buys, and what
+happens to code that assigns `fulfillment.tracking`.
+
+**Decision:** A return label buys the **cheapest rate the connected account
+offers** across every carrier. Unlike an outbound parcel there is no rate the
+customer selected: return postage is the merchant's own money and nobody chose
+a service for it. Reusing the outbound carrier was rejected because a parcel
+whose tracking was hand-entered has no carrier to reuse, and mirroring the
+outbound service inbound is usually the most expensive answer to a question the
+merchant never asked; a merchant wanting a fixed return service configures it on
+the integration later, which is additive. Separately, `Spree::Fulfillment#tracking`
+becomes a **read-through summary of the primary delivery** and `#tracking=` a
+deprecated shell that writes that delivery on save — the 5.6 field keeps
+working for host code and the storefront one more release, and both go in 6.1
+with the column. One naming consequence: the label's file format is written as
+**`file_format`** on the API, because `format` is Rails' own request-format
+parameter and a controller permitting it receives `"json"`.
+
+**Consequences:** Return labels need no configuration to work, which is what
+makes the customer-facing return-label download usable the day the plan ships.
+The deprecated `tracking=` writer is the reason the upgrade is quiet: an
+extension or host app that sets a tracking number the old way still lands it
+where every reader looks, with a warning naming the replacement. Plan:
+`6.0-shipping-labels-and-deliveries.md`.
+
## 2026-09-03: Labels and parcels are records; the carrier axis moves onto `Spree::Delivery` in 6.0 (supersedes 2026-08-11 "multiple trackings deferred to 6.1")
**Context:** A shipping label was three EasyPost-private keys in `fulfillment.metadata`, surfaced by a per-read `provider.documents` call and bought through `PATCH .../purchase_label`. Spree never knew the postage cost, could not reprint once the carrier's hosted URL expired, could not buy a second label after a refund (idempotency keyed off the metadata), and had nowhere to put a return label — the returns plan had already sent that to "the URL in `metadata`". Tracking lived in seven columns on `spree_fulfillments`, one number per parcel, with a `spree_fulfillment_trackings` model deferred to 6.1 and required to absorb the whole axis when it came. Both were candidates for "promote to a model with RESTful routes"; only one of them is a thing.
diff --git a/packages/admin-sdk/examples/order-deliveries/create.ts b/packages/admin-sdk/examples/order-deliveries/create.ts
new file mode 100644
index 0000000000..7d78e43736
--- /dev/null
+++ b/packages/admin-sdk/examples/order-deliveries/create.ts
@@ -0,0 +1,19 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// A second box, or a freight consignment: the carrier is free text, so a
+// forwarder's PRO number is as valid as a parcel number.
+const delivery = await client.orders.fulfillments.deliveries.create(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ { tracking_number: 'PRO-4471923', carrier: 'Estes Freight' },
+)
+
+// endregion:example
+
+export { delivery }
diff --git a/packages/admin-sdk/examples/order-deliveries/list.ts b/packages/admin-sdk/examples/order-deliveries/list.ts
new file mode 100644
index 0000000000..4d50248df9
--- /dev/null
+++ b/packages/admin-sdk/examples/order-deliveries/list.ts
@@ -0,0 +1,17 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: deliveries } = await client.orders.fulfillments.deliveries.list(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+)
+
+// Each carries its own carrier status: pending, in_transit, delivered, ...
+// endregion:example
+
+export { deliveries }
diff --git a/packages/admin-sdk/examples/order-deliveries/mark-delivered.ts b/packages/admin-sdk/examples/order-deliveries/mark-delivered.ts
new file mode 100644
index 0000000000..34146b4f20
--- /dev/null
+++ b/packages/admin-sdk/examples/order-deliveries/mark-delivered.ts
@@ -0,0 +1,19 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Staff confirming one consignment arrived. The fulfillment follows once
+// every one of its consignments has.
+const delivery = await client.orders.fulfillments.deliveries.markDelivered(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'dlv_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { delivery }
diff --git a/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts b/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts
index 8b7a9178dd..c7df8b85a2 100644
--- a/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts
+++ b/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts
@@ -6,13 +6,15 @@ const client = createAdminClient({
})
// region:example
+// Deprecated: use client.orders.fulfillments.labels.create() instead, which
+// answers with the label itself. Removed in Spree 6.1.
const fulfillment = await client.orders.fulfillments.purchaseLabel(
'or_UkLWZg9DAJ',
'ful_UkLWZg9DAJ',
)
// The label is ready to print; the parcel is still unfulfilled.
-const label = fulfillment.documents.find((document) => document.kind === 'label')
+const label = fulfillment.labels[0]
// endregion:example
diff --git a/packages/admin-sdk/examples/order-labels/create.ts b/packages/admin-sdk/examples/order-labels/create.ts
new file mode 100644
index 0000000000..9df9dc9025
--- /dev/null
+++ b/packages/admin-sdk/examples/order-labels/create.ts
@@ -0,0 +1,16 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// With no body, the parcel's carrier account buys the label.
+const label = await client.orders.fulfillments.labels.create('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+
+// The tracking number is now on the parcel's first delivery, and the label is
+// ready to print. What the merchant paid the carrier is label.display_cost.
+// endregion:example
+
+export { label }
diff --git a/packages/admin-sdk/examples/order-labels/list.ts b/packages/admin-sdk/examples/order-labels/list.ts
new file mode 100644
index 0000000000..d3846f1942
--- /dev/null
+++ b/packages/admin-sdk/examples/order-labels/list.ts
@@ -0,0 +1,16 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: labels } = await client.orders.fulfillments.labels.list(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { labels }
diff --git a/packages/admin-sdk/examples/order-labels/refund.ts b/packages/admin-sdk/examples/order-labels/refund.ts
new file mode 100644
index 0000000000..6c933847a9
--- /dev/null
+++ b/packages/admin-sdk/examples/order-labels/refund.ts
@@ -0,0 +1,21 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const label = await client.orders.fulfillments.labels.refund(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'lbl_UkLWZg9DAJ',
+)
+
+// 'refunded' when the carrier settled at once, 'refund_requested' when it
+// will answer later.
+const outcome = label.status
+
+// endregion:example
+
+export { outcome }
diff --git a/packages/admin-sdk/examples/order-labels/upload.ts b/packages/admin-sdk/examples/order-labels/upload.ts
new file mode 100644
index 0000000000..1cce90e266
--- /dev/null
+++ b/packages/admin-sdk/examples/order-labels/upload.ts
@@ -0,0 +1,20 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Postage bought elsewhere: upload the file first, then record it with the
+// tracking number printed on it.
+const label = await client.orders.fulfillments.labels.create('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {
+ file: 'signed_blob_id',
+ tracking_number: '1Z879E930346834440',
+ cost: '6.50',
+ currency: 'USD',
+})
+
+// endregion:example
+
+export { label }
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index 40802edf44..de95cc46e1 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -135,9 +135,12 @@ import type {
CustomFieldOwnerType,
CustomFieldResourceType,
CustomFieldUpdateParams,
+ DeliveryCreateParams,
+ DeliveryMarkDeliveredParams,
DeliveryMethodParams,
DeliveryOriginGroupParams,
DeliveryProfileParams,
+ DeliveryUpdateParams,
DeliveryZoneParams,
DigitalAssetCreateParams,
DigitalAssetProvider,
@@ -233,6 +236,7 @@ import type {
SetupCountries,
SetupParams,
SetupStatus,
+ ShippingLabelCreateParams,
StockLevelBulkUpsertRow,
StockLevelUpdateParams,
StockLocationCreateParams,
@@ -282,6 +286,7 @@ import type {
CustomerGroup,
CustomField,
CustomFieldDefinition,
+ Delivery,
DeliveryMethod,
DeliveryMethodRule,
DeliveryOriginGroup,
@@ -334,6 +339,7 @@ import type {
SellerRequirementSubmission,
SellerTeamMember,
SellerTransfer,
+ ShippingLabel,
StockLevel,
StockLocation,
StockMovement,
@@ -1418,6 +1424,168 @@ export class AdminClient {
cancel: (orderId: string, id: string, options?: RequestOptions): Promise<Fulfillment> =>
this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/cancel`, options),
+ /**
+ * The carrier documents bought or uploaded for a parcel. Creating one
+ * with no body buys it through the parcel's carrier account; creating it
+ * with a `file` (a signed blob id from `directUploads.create()`) records
+ * postage the merchant bought elsewhere. To print one, fetch
+ * `download_url` with the `Authorization` header and drive the browser
+ * download from a Blob — the bytes are streamed through the API rather
+ * than served from storage.
+ */
+ labels: {
+ list: (
+ orderId: string,
+ fulfillmentId: string,
+ options?: RequestOptions,
+ ): Promise<{ data: ShippingLabel[] }> =>
+ this.request<{ data: ShippingLabel[] }>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
+ options,
+ ),
+
+ get: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<ShippingLabel> =>
+ this.request<ShippingLabel>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
+ options,
+ ),
+
+ create: (
+ orderId: string,
+ fulfillmentId: string,
+ params?: ShippingLabelCreateParams,
+ options?: RequestOptions,
+ ): Promise<ShippingLabel> =>
+ this.request<ShippingLabel>(
+ 'POST',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
+ { ...options, body: params },
+ ),
+
+ /**
+ * Asks the carrier to refund a purchased label. The answer is
+ * `refunded` when the carrier settled at once, `refund_requested` when
+ * it will decide later. Uploaded labels cannot be refunded.
+ */
+ refund: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<ShippingLabel> =>
+ this.request<ShippingLabel>(
+ 'PATCH',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}/refund`,
+ options,
+ ),
+
+ /** Uploaded labels only — a purchased label is refunded instead. */
+ delete: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<void> =>
+ this.request<void>(
+ 'DELETE',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
+ options,
+ ),
+ },
+
+ /**
+ * The tracked consignments of a parcel — one per tracking number, each
+ * carrying the carrier status last reported. A fulfillment's own
+ * `tracking` field summarizes the first of them.
+ */
+ deliveries: {
+ list: (
+ orderId: string,
+ fulfillmentId: string,
+ options?: RequestOptions,
+ ): Promise<{ data: Delivery[] }> =>
+ this.request<{ data: Delivery[] }>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
+ options,
+ ),
+
+ get: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
+ options,
+ ),
+
+ create: (
+ orderId: string,
+ fulfillmentId: string,
+ params: DeliveryCreateParams,
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'POST',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
+ { ...options, body: params },
+ ),
+
+ /** A corrected tracking number starts the carrier journey over. */
+ update: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ params: DeliveryUpdateParams,
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'PATCH',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
+ { ...options, body: params },
+ ),
+
+ /** Refused for a consignment a label minted — refund the label. */
+ delete: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<void> =>
+ this.request<void>(
+ 'DELETE',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
+ options,
+ ),
+
+ /**
+ * Staff confirming one consignment arrived. The parcel becomes
+ * delivered once every one of its consignments has.
+ */
+ markDelivered: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ params?: DeliveryMarkDeliveredParams,
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'PATCH',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}/mark_delivered`,
+ { ...options, body: params },
+ ),
+ },
+
// Returns every fulfillment on the order, since a split re-shapes the
// source as well as creating the new one (and destroys the source when
// it is fully drained).
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index e07145fe38..0072919288 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -285,6 +285,50 @@ export interface FulfillmentFulfillParams {
* lifecycle. Reached by a carrier reporting delivery, by staff who know the
* parcel arrived, or by a customer collecting a pickup order.
*/
+/** Buying a label takes no body; recording an uploaded one takes at least a file and a number. */
+export interface ShippingLabelCreateParams {
+ /** Signed blob id from `directUploads.create()`. Its presence records an uploaded label instead of buying one. */
+ file?: string
+ /** The number printed on an uploaded label. */
+ tracking_number?: string
+ /** Free text — a forwarder's name is as valid as a carrier slug. Detected from the number when omitted. */
+ carrier?: string
+ /** Carrier service the label was bought at. */
+ service?: string
+ /** What the merchant paid the carrier. Admin-only accounting data; it never touches the order's shipping charge. */
+ cost?: string | number
+ /** Currency of the cost. */
+ currency?: string
+ /** `pdf`, `png` or `zpl`; taken from the file when omitted. */
+ file_format?: string
+ /** Tracking page for the consignment the label mints. */
+ tracking_url?: string
+}
+
+export interface DeliveryCreateParams {
+ /** A carrier tracking number, a freight PRO or container number, or a full tracking link. */
+ tracking_number: string
+ /** Free text; detected from the number's format when omitted. */
+ carrier?: string
+ service?: string
+ tracking_url?: string
+}
+
+/** A corrected tracking number resets the consignment's carrier status to `pending`. */
+export interface DeliveryUpdateParams {
+ tracking_number?: string
+ carrier?: string
+ service?: string
+ tracking_url?: string
+}
+
+export interface DeliveryMarkDeliveredParams {
+ /** When it arrived. Defaults to now. */
+ delivered_at?: string
+ /** Whether the customer gets a delivery notification once the parcel completes. Defaults to true. */
+ notify_customer?: boolean
+}
+
export interface FulfillmentMarkDeliveredParams {
/**
* When it arrived, as an ISO 8601 string. Defaults to now. Carriers report a
diff --git a/packages/admin-sdk/src/types/generated/Delivery.ts b/packages/admin-sdk/src/types/generated/Delivery.ts
new file mode 100644
index 0000000000..faff103ae6
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/Delivery.ts
@@ -0,0 +1,21 @@
+// Typelizer digest 86737df652b65774976c59b7997822c9
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface Delivery {
+ id: string;
+ tracking_number: string;
+ tracking_url: string | null;
+ carrier: string | null;
+ carrier_name: string | null;
+ service: string | null;
+ status: string;
+ estimated_delivery_at: string | null;
+ delivered_at: string | null;
+ details: Record<string, unknown> | null;
+ created_at: string;
+ updated_at: string;
+ shipping_label_id: string | null;
+}
+
+export default Delivery;
diff --git a/packages/admin-sdk/src/types/generated/Fulfillment.ts b/packages/admin-sdk/src/types/generated/Fulfillment.ts
index e38b88d50a..c61427b286 100644
--- a/packages/admin-sdk/src/types/generated/Fulfillment.ts
+++ b/packages/admin-sdk/src/types/generated/Fulfillment.ts
@@ -1,15 +1,13 @@
-// Typelizer digest a6ce9755793869194d5eed84c3e4c026
+// Typelizer digest 162de390cc568b9e4ea761e6bd35cbdc
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {DeliveryMethod, StockLocation, DeliveryRate, TaxLine, FulfillmentItem, Order} from '@/types'
+import type {Delivery, DeliveryMethod, StockLocation, DeliveryRate, TaxLine, ShippingLabel, FulfillmentItem, Order} from '@/types'
interface Fulfillment {
id: string;
number: string;
tracking: string | null;
tracking_url: string | null;
- tracking_carrier: string | null;
- tracking_carrier_name: string | null;
pickup_point_data: Record<string, unknown> | null;
selected_delivery_rate_id: string | null;
cost: string;
@@ -27,16 +25,14 @@ interface Fulfillment {
status: string;
fulfillment_type: string;
fulfilled_at: string | null;
- tracking_status: string | null;
- estimated_delivery_at: string | null;
delivered_at: string | null;
items: Array<{ item_id: string; variant_id: string; quantity: number }>;
+ deliveries: Array<Delivery>;
delivery_method?: DeliveryMethod;
stock_location?: StockLocation;
delivery_rates?: Array<DeliveryRate>;
tax_lines?: Array<TaxLine>;
metadata: Record<string, unknown>;
- tracking_details: Record<string, unknown> | null;
adjustment_total: string;
pre_tax_amount: string;
created_at: string;
@@ -44,6 +40,7 @@ interface Fulfillment {
order_id: string | null;
stock_location_id: string | null;
documents: Array<{ kind: string; url: string }>;
+ labels: Array<ShippingLabel>;
provider_generates_labels: boolean;
fulfillment_items?: Array<FulfillmentItem>;
order?: Order;
diff --git a/packages/admin-sdk/src/types/generated/ShippingLabel.ts b/packages/admin-sdk/src/types/generated/ShippingLabel.ts
new file mode 100644
index 0000000000..c05ad8d1dc
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/ShippingLabel.ts
@@ -0,0 +1,29 @@
+// Typelizer digest 40290dc0266f99196b6506a1da1e5b1a
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface ShippingLabel {
+ id: string;
+ source: string;
+ status: string;
+ carrier: string | null;
+ service: string | null;
+ tracking_number: string | null;
+ currency: string | null;
+ format: string | null;
+ external_id: string | null;
+ metadata: Record<string, unknown>;
+ refunded_at: string | null;
+ created_at: string;
+ updated_at: string;
+ owner_id: string;
+ owner_type: string;
+ carrier_name: string | null;
+ cost: string;
+ display_cost: string;
+ integration_id: string | null;
+ file_pending: boolean;
+ download_url: string | null;
+}
+
+export default ShippingLabel;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index e7d188c757..427b405a06 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest b935827ec76d586ad2435901b917fda9
+// Typelizer digest 859f5a332d20b2f26833b28c52fac108
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -40,6 +40,7 @@ export type { default as DeliveryMethodService } from './DeliveryMethodService'
export type { default as DeliveryOriginGroup } from './DeliveryOriginGroup'
export type { default as DeliveryProfile } from './DeliveryProfile'
export type { default as DeliveryRate } from './DeliveryRate'
+export type { default as Delivery } from './Delivery'
export type { default as DeliveryZoneMember } from './DeliveryZoneMember'
export type { default as DeliveryZone } from './DeliveryZone'
export type { default as DigitalAsset } from './DigitalAsset'
@@ -99,6 +100,7 @@ export type { default as Seller } from './Seller'
export type { default as SellerTeamMember } from './SellerTeamMember'
export type { default as SellerTransfer } from './SellerTransfer'
export type { default as SetupTask } from './SetupTask'
+export type { default as ShippingLabel } from './ShippingLabel'
export type { default as State } from './State'
export type { default as StockLevel } from './StockLevel'
export type { default as StockLocation } from './StockLocation'
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 4c3142f514..7ade934385 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -47,6 +47,7 @@ export type { default as Customer } from './generated/Customer'
export type { default as CustomerGroup } from './generated/CustomerGroup'
export type { default as CustomField } from './generated/CustomField'
export type { default as CustomFieldDefinition } from './generated/CustomFieldDefinition'
+export type { default as Delivery } from './generated/Delivery'
export type { default as DeliveryMethod } from './generated/DeliveryMethod'
export type { default as DeliveryMethodRule } from './generated/DeliveryMethodRule'
export type { default as DeliveryOriginGroup } from './generated/DeliveryOriginGroup'
@@ -107,6 +108,7 @@ export type { default as SellerRequirementSubmission } from './generated/SellerR
export type { default as SellerTeamMember } from './generated/SellerTeamMember'
export type { default as SellerTransfer } from './generated/SellerTransfer'
export type { default as SetupTask } from './generated/SetupTask'
+export type { default as ShippingLabel } from './generated/ShippingLabel'
export type { default as State } from './generated/State'
export type { default as StockLevel } from './generated/StockLevel'
export type { default as StockLocation } from './generated/StockLocation'
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 22f2e496e1..2d74eb26d1 100644
--- a/packages/cli/src/generated/admin-spec.json
+++ b/packages/cli/src/generated/admin-spec.json
@@ -1 +1 @@
-{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"get":{"summary":"List catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's per-variant quantity terms. The catalog-wide default is a pair of fields on the catalog itself, so these are strictly the overrides.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"quantity rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"States how much of one variant a buyer on this agreement must order. Both fields are optional individually, but a rule must state at least one — a field left out falls through to the catalog default, and then to the variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"quantity rule created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"variant_id":{"type":"string"},"minimum_order_quantity":{"type":"integer","nullable":true,"description":"The least a buyer may order."},"order_multiple":{"type":"integer","nullable":true,"description":"Orders must land on a multiple of this, counted from the minimum."}},"required":["variant_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules/{id}":{"patch":{"summary":"Update a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one variant term. A field sent as null hands that field back to the catalog default; a rule must still state at least one of the two.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"quantity rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}}}},"delete":{"summary":"Delete a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drops one variant's exception, so it falls back to the catalog's own default.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rule deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/product_terms":{"get":{"summary":"List catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's quantity terms at the grain a merchant states them: one entry per product, over rows the database keeps per variant. `mixed` marks a product whose variants carry different terms.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"product terms found","content":{"application/json":{}}}}},"put":{"summary":"Set catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' terms in one request, keyed by prefixed product id. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — this is the one catalog-term surface that is not a whole-set replacement, because an agreement may name terms for thousands of SKUs.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"product terms set","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"currency":{"type":"string"},"source":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["currency","source","amount","display_amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"},"catalog_price":{"allOf":[{"$ref":"#/components/schemas/CatalogPrice"}],"nullable":true}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","external_references","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"default_catalog_id":{"type":"string","nullable":true}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids","default_catalog_id"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string"},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","label","description"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string"},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_type","provider_settings","created_at","updated_at","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"expires_at":{"type":"string","nullable":true},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"tracking_carrier":{"type":"string","nullable":true},"tracking_carrier_name":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"tracking_status":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"tracking_details":{"type":"object","nullable":true},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","tracking_carrier","tracking_carrier_name","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","tracking_status","estimated_delivery_at","delivered_at","items","metadata","tracking_details","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/AdminUser"},"canceler":{"$ref":"#/components/schemas/AdminUser"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","canceler_id","cancel_reason_id","cancel_reason_name","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string"},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"type":"string"},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label (deprecated)","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deprecated alias of POST /labels, answering with the fulfillment instead of the label. Removed in Spree 6.1.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","deprecated":true,"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"get":{"summary":"List catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's per-variant quantity terms. The catalog-wide default is a pair of fields on the catalog itself, so these are strictly the overrides.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"quantity rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"States how much of one variant a buyer on this agreement must order. Both fields are optional individually, but a rule must state at least one — a field left out falls through to the catalog default, and then to the variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"quantity rule created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"variant_id":{"type":"string"},"minimum_order_quantity":{"type":"integer","nullable":true,"description":"The least a buyer may order."},"order_multiple":{"type":"integer","nullable":true,"description":"Orders must land on a multiple of this, counted from the minimum."}},"required":["variant_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules/{id}":{"patch":{"summary":"Update a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one variant term. A field sent as null hands that field back to the catalog default; a rule must still state at least one of the two.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"quantity rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}}}},"delete":{"summary":"Delete a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drops one variant's exception, so it falls back to the catalog's own default.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rule deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/product_terms":{"get":{"summary":"List catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's quantity terms at the grain a merchant states them: one entry per product, over rows the database keeps per variant. `mixed` marks a product whose variants carry different terms.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"product terms found","content":{"application/json":{}}}}},"put":{"summary":"Set catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' terms in one request, keyed by prefixed product id. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — this is the one catalog-term surface that is not a whole-set replacement, because an agreement may name terms for thousands of SKUs.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"product terms set","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"currency":{"type":"string"},"source":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["currency","source","amount","display_amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"},"catalog_price":{"allOf":[{"$ref":"#/components/schemas/CatalogPrice"}],"nullable":true}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","external_references","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"default_catalog_id":{"type":"string","nullable":true}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids","default_catalog_id"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string"},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","label","description"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string","nullable":true},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string"},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","tracking_url","carrier","carrier_name","service","status","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string"},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_type","provider_settings","created_at","updated_at","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"expires_at":{"type":"string","nullable":true},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","labels","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/AdminUser"},"canceler":{"$ref":"#/components/schemas/AdminUser"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","canceler_id","cancel_reason_id","cancel_reason_name","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string"},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"type":"string"},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"carrier":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string"},"carrier_name":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","carrier_name","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx
new file mode 100644
index 0000000000..45c82f897b
--- /dev/null
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx
@@ -0,0 +1,116 @@
+import type { Delivery } from '@spree/admin-sdk'
+import { Badge, Button, CardContent, useConfirm } from '@spree/dashboard-ui'
+import { PackageCheckIcon, PencilIcon, TrashIcon } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
+
+/** How far along the carrier says each consignment is. */
+const STATUS_VARIANT: Record<string, 'secondary' | 'default' | 'destructive'> = {
+ delivered: 'default',
+ failure: 'destructive',
+ return_to_sender: 'destructive',
+}
+
+/**
+ * The tracked consignments of one parcel. A parcel usually has one, but three
+ * boxes or a freight PRO number covering a pallet are the same shape, and each
+ * travels on its own carrier status.
+ */
+export function FulfillmentDeliveries({
+ orderId,
+ fulfillmentId,
+ deliveries,
+ onEdit,
+ canMarkDelivered,
+}: {
+ orderId: string
+ fulfillmentId: string
+ deliveries: Delivery[]
+ onEdit: (delivery: Delivery) => void
+ canMarkDelivered: boolean
+}) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { deleteDelivery, markDeliveryDelivered } = useFulfillmentActions(orderId)
+
+ if (deliveries.length === 0) return null
+
+ return (
+ <CardContent className="space-y-2 border-b border-border-subtle py-3 text-sm">
+ {deliveries.map((delivery) => (
+ <div key={delivery.id} className="flex flex-wrap items-center justify-between gap-2">
+ <div className="flex min-w-0 flex-wrap items-center gap-2">
+ <span className="text-muted-foreground">
+ {delivery.carrier_name ?? t('admin.orders.detail.tracking.prefix')}:
+ </span>
+ {delivery.tracking_url ? (
+ <a
+ href={delivery.tracking_url}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="truncate text-blue-600 hover:underline"
+ >
+ {delivery.tracking_number}
+ </a>
+ ) : (
+ <span className="truncate">{delivery.tracking_number}</span>
+ )}
+ <Badge variant={STATUS_VARIANT[delivery.status] ?? 'secondary'}>
+ {t(`admin.orders.detail.fulfillments.carrier_status_${delivery.status}`)}
+ </Badge>
+ </div>
+
+ <div className="flex items-center gap-1">
+ {canMarkDelivered && delivery.status !== 'delivered' && (
+ <Button
+ type="button"
+ size="icon-xs"
+ variant="ghost"
+ disabled={markDeliveryDelivered.isPending}
+ onClick={() =>
+ markDeliveryDelivered.mutate({ fulfillmentId, deliveryId: delivery.id })
+ }
+ >
+ <PackageCheckIcon className="size-4" />
+ <span className="sr-only">
+ {t('admin.orders.detail.fulfillments.mark_delivery_delivered')}
+ </span>
+ </Button>
+ )}
+
+ <Button type="button" size="icon-xs" variant="ghost" onClick={() => onEdit(delivery)}>
+ <PencilIcon className="size-4" />
+ <span className="sr-only">{t('admin.actions.edit')}</span>
+ </Button>
+
+ {/* A consignment a label minted is not removable on its own — the
+ label is the record of what was bought, so the way out is
+ refunding it. The server refuses too; this keeps the button
+ honest. */}
+ {!delivery.shipping_label_id && (
+ <Button
+ type="button"
+ size="icon-xs"
+ variant="ghost"
+ onClick={async () => {
+ if (
+ await confirm({
+ message: t('admin.orders.detail.fulfillments.confirm_delete_delivery'),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.delete'),
+ })
+ ) {
+ deleteDelivery.mutate({ fulfillmentId, deliveryId: delivery.id })
+ }
+ }}
+ >
+ <TrashIcon className="size-4" />
+ <span className="sr-only">{t('admin.actions.delete')}</span>
+ </Button>
+ )}
+ </div>
+ </div>
+ ))}
+ </CardContent>
+ )
+}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx
new file mode 100644
index 0000000000..85660a6a67
--- /dev/null
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx
@@ -0,0 +1,174 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type { Delivery } from '@spree/admin-sdk'
+import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
+import {
+ Button,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ Field,
+ FieldError,
+ FieldLabel,
+ Input,
+} from '@spree/dashboard-ui'
+import { useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { z } from 'zod'
+import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
+import { useTrackingCarriers } from '../../../hooks/use-tracking-carriers'
+
+const deliverySchema = z.object({
+ tracking_number: z.string().min(1),
+ // Free text: a forwarder's own name is as valid as a registered carrier,
+ // and an empty value asks the server to detect one from the number.
+ carrier: z.string(),
+ tracking_url: z.string(),
+})
+
+type DeliveryFormValues = z.infer<typeof deliverySchema>
+
+/**
+ * Records a tracked consignment on a parcel, or corrects one. A parcel can
+ * carry several — three boxes, or a freight PRO number covering a pallet —
+ * and each travels on its own carrier status.
+ */
+export function FulfillmentDeliveryDialog({
+ orderId,
+ fulfillmentId,
+ delivery,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ fulfillmentId: string
+ delivery?: Delivery
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { createDelivery, updateDelivery } = useFulfillmentActions(orderId)
+ const { data: carriersData } = useTrackingCarriers(open)
+
+ const carrierOptions = (carriersData?.data ?? []).map((carrier) => ({
+ value: carrier.name,
+ label: carrier.name,
+ }))
+
+ const form = useForm<DeliveryFormValues>({
+ resolver: zodResolver(deliverySchema),
+ defaultValues: {
+ tracking_number: delivery?.tracking_number ?? '',
+ carrier: delivery?.carrier_name ?? '',
+ tracking_url: delivery?.tracking_url ?? '',
+ },
+ })
+
+ const pending = createDelivery.isPending || updateDelivery.isPending
+
+ async function onSubmit(values: DeliveryFormValues) {
+ try {
+ const params = {
+ tracking_number: values.tracking_number.trim(),
+ carrier: values.carrier.trim() || undefined,
+ tracking_url: values.tracking_url.trim() || undefined,
+ }
+
+ if (delivery) {
+ await updateDelivery.mutateAsync({ fulfillmentId, deliveryId: delivery.id, ...params })
+ } else {
+ await createDelivery.mutateAsync({ fulfillmentId, ...params })
+ }
+ onOpenChange(false)
+ } catch (err) {
+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ }
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ <DialogHeader>
+ <DialogTitle>
+ {delivery
+ ? t('admin.orders.detail.fulfillments.edit_tracking_title')
+ : t('admin.orders.detail.fulfillments.add_tracking_title')}
+ </DialogTitle>
+ <DialogDescription>
+ {t('admin.orders.detail.fulfillments.tracking_description')}
+ </DialogDescription>
+ </DialogHeader>
+
+ <DialogBody>
+ {form.formState.errors.root?.message && (
+ <p className="text-sm text-destructive" role="alert">
+ {form.formState.errors.root.message}
+ </p>
+ )}
+
+ <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+ <Field>
+ <FieldLabel htmlFor="delivery-tracking-number">
+ {t('admin.orders.fulfill.tracking_label')}
+ </FieldLabel>
+ <Input
+ id="delivery-tracking-number"
+ placeholder={t('admin.orders.fulfill.tracking_placeholder')}
+ aria-invalid={!!form.formState.errors.tracking_number}
+ {...form.register('tracking_number')}
+ />
+ <FieldError errors={[form.formState.errors.tracking_number]} />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="delivery-carrier">
+ {t('admin.orders.detail.fulfillments.carrier_label')}
+ </FieldLabel>
+ {/* Free text with the registered carriers as suggestions: a
+ forwarder's own name has to be enterable, and an empty
+ value asks the server to detect one from the number. */}
+ <Input
+ id="delivery-carrier"
+ list="delivery-carrier-options"
+ placeholder={t('admin.orders.detail.fulfillments.carrier_auto')}
+ {...form.register('carrier')}
+ />
+ <datalist id="delivery-carrier-options">
+ {carrierOptions.map((option) => (
+ <option key={option.value} value={option.value} />
+ ))}
+ </datalist>
+ </Field>
+ </div>
+
+ <Field>
+ <FieldLabel htmlFor="delivery-tracking-url">
+ {t('admin.orders.detail.fulfillments.tracking_url_label')}
+ </FieldLabel>
+ <Input
+ id="delivery-tracking-url"
+ placeholder={t('admin.orders.detail.fulfillments.tracking_url_placeholder')}
+ aria-invalid={!!form.formState.errors.tracking_url}
+ {...form.register('tracking_url')}
+ />
+ <FieldError errors={[form.formState.errors.tracking_url]} />
+ </Field>
+ </DialogBody>
+
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button type="submit" disabled={pending}>
+ {pending ? t('admin.actions.saving') : t('admin.actions.save')}
+ </Button>
+ </DialogFooter>
+ </form>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-fulfill-form.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-fulfill-form.tsx
index aa6f5fa1e6..6912364fe4 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillment-fulfill-form.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-fulfill-form.tsx
@@ -159,7 +159,9 @@ export function FulfillmentFulfillForm({
defaultValues: {
items: rows.map((row) => ({ item_id: row.itemId, selected: true, quantity: row.quantity })),
tracking: fulfillment.tracking ?? '',
- tracking_carrier: fulfillment.tracking_carrier ?? '',
+ // The carrier is detected from the number, or picked in the tracking
+ // dialog once the parcel has one.
+ tracking_carrier: '',
notify_customer: true,
},
})
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx
new file mode 100644
index 0000000000..180ab5ee9b
--- /dev/null
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx
@@ -0,0 +1,184 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import {
+ EMPTY_FILE_UPLOAD_VALUE,
+ FileUploadField,
+ type FileUploadValue,
+ mapSpreeErrorsToForm,
+} from '@spree/dashboard-core'
+import {
+ Button,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ Field,
+ FieldError,
+ FieldLabel,
+ Input,
+ InputGroup,
+ InputGroupAddon,
+ InputGroupInput,
+ InputGroupText,
+} from '@spree/dashboard-ui'
+import { useState } from 'react'
+import { useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { z } from 'zod'
+import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
+
+/** What a carrier label plausibly arrives as — mirrors the server allowlist. */
+const LABEL_ACCEPT = 'application/pdf,image/png,text/plain'
+
+const uploadSchema = z.object({
+ tracking_number: z.string().min(1),
+ carrier: z.string(),
+ cost: z.string(),
+})
+
+type UploadFormValues = z.infer<typeof uploadSchema>
+
+/**
+ * Records a label the merchant bought elsewhere — postage from a carrier site,
+ * a 3PL's PDF — so the parcel still has its file, its tracking number and what
+ * it cost, with no carrier account connected.
+ */
+export function FulfillmentLabelUploadDialog({
+ orderId,
+ fulfillmentId,
+ currency,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ fulfillmentId: string
+ currency?: string
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { buyLabel } = useFulfillmentActions(orderId)
+
+ const [file, setFile] = useState<FileUploadValue>(EMPTY_FILE_UPLOAD_VALUE)
+ // The signed id does not exist until the upload resolves, so saving during
+ // one would silently drop the file.
+ const [uploading, setUploading] = useState(false)
+
+ const form = useForm<UploadFormValues>({
+ resolver: zodResolver(uploadSchema),
+ defaultValues: { tracking_number: '', carrier: '', cost: '' },
+ })
+
+ async function onSubmit(values: UploadFormValues) {
+ if (!file.signedId) {
+ form.setError('root', { message: t('admin.orders.detail.fulfillments.upload_label_file') })
+ return
+ }
+
+ try {
+ await buyLabel.mutateAsync({
+ fulfillmentId,
+ file: file.signedId,
+ tracking_number: values.tracking_number.trim(),
+ carrier: values.carrier.trim() || undefined,
+ cost: values.cost.trim() || undefined,
+ currency: values.cost.trim() ? currency : undefined,
+ })
+ onOpenChange(false)
+ } catch (err) {
+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ }
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ <DialogHeader>
+ <DialogTitle>{t('admin.orders.detail.fulfillments.upload_label_title')}</DialogTitle>
+ <DialogDescription>
+ {t('admin.orders.detail.fulfillments.upload_label_description')}
+ </DialogDescription>
+ </DialogHeader>
+
+ <DialogBody>
+ {form.formState.errors.root?.message && (
+ <p className="text-sm text-destructive" role="alert">
+ {form.formState.errors.root.message}
+ </p>
+ )}
+
+ <Field>
+ <FieldLabel>{t('admin.orders.detail.fulfillments.upload_label_file')}</FieldLabel>
+ <FileUploadField
+ accept={LABEL_ACCEPT}
+ value={file}
+ onChange={setFile}
+ onUploadingChange={setUploading}
+ private
+ />
+ </Field>
+
+ <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+ <Field>
+ <FieldLabel htmlFor="label-tracking-number">
+ {t('admin.orders.fulfill.tracking_label')}
+ </FieldLabel>
+ <Input
+ id="label-tracking-number"
+ placeholder={t('admin.orders.fulfill.tracking_placeholder')}
+ aria-invalid={!!form.formState.errors.tracking_number}
+ {...form.register('tracking_number')}
+ />
+ <FieldError errors={[form.formState.errors.tracking_number]} />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="label-cost">
+ {t('admin.orders.detail.fulfillments.upload_label_cost')}
+ </FieldLabel>
+ <InputGroup>
+ {currency && (
+ <InputGroupAddon>
+ <InputGroupText>{currency}</InputGroupText>
+ </InputGroupAddon>
+ )}
+ <InputGroupInput
+ id="label-cost"
+ type="number"
+ step="0.01"
+ min="0"
+ {...form.register('cost')}
+ />
+ </InputGroup>
+ <FieldError errors={[form.formState.errors.cost]} />
+ </Field>
+ </div>
+
+ <Field>
+ <FieldLabel htmlFor="label-carrier">
+ {t('admin.orders.detail.fulfillments.carrier_label')}
+ </FieldLabel>
+ <Input
+ id="label-carrier"
+ placeholder={t('admin.orders.detail.fulfillments.carrier_auto')}
+ {...form.register('carrier')}
+ />
+ </Field>
+ </DialogBody>
+
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button type="submit" disabled={buyLabel.isPending || uploading}>
+ {buyLabel.isPending ? t('admin.actions.saving') : t('admin.actions.save')}
+ </Button>
+ </DialogFooter>
+ </form>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx
new file mode 100644
index 0000000000..e4ba935b30
--- /dev/null
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx
@@ -0,0 +1,120 @@
+import type { ShippingLabel } from '@spree/admin-sdk'
+import { downloadFromApi, getApiClient, useAuth } from '@spree/dashboard-core'
+import { Badge, Button, CardContent, useConfirm } from '@spree/dashboard-ui'
+import { PrinterIcon, ReceiptIcon, TrashIcon } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
+
+/**
+ * The label bound to a parcel: what it cost, how to print it, and how to give
+ * it back. A purchased label is refunded through the carrier; an uploaded one
+ * has nothing to refund, so it is deleted instead.
+ */
+export function FulfillmentLabel({
+ orderId,
+ fulfillmentId,
+ label,
+}: {
+ orderId: string
+ fulfillmentId: string
+ label: ShippingLabel
+}) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { token } = useAuth()
+ const { refundLabel, deleteLabel } = useFulfillmentActions(orderId)
+
+ const refundable = label.source === 'purchased' && label.status === 'purchased'
+ const deletable = label.source === 'uploaded'
+
+ async function print() {
+ if (!label.download_url) return
+
+ await downloadFromApi(
+ token,
+ label.download_url,
+ `${label.tracking_number ?? 'label'}.${label.format ?? 'pdf'}`,
+ getApiClient().downloadHeaders?.() ?? {},
+ )
+ }
+
+ return (
+ <CardContent className="flex flex-wrap items-center justify-between gap-2 border-b border-border-subtle py-3 text-sm">
+ <div className="flex flex-wrap items-center gap-2">
+ <ReceiptIcon className="size-4 text-muted-foreground" />
+ <span className="text-muted-foreground">
+ {t('admin.orders.detail.fulfillments.label_title')}
+ </span>
+ {label.source === 'uploaded' && (
+ <Badge variant="secondary">{t('admin.orders.detail.fulfillments.label_uploaded')}</Badge>
+ )}
+ {label.status === 'refund_requested' && (
+ <Badge variant="secondary">
+ {t('admin.orders.detail.fulfillments.label_refund_requested')}
+ </Badge>
+ )}
+ {label.status === 'refunded' && (
+ <Badge variant="secondary">{t('admin.orders.detail.fulfillments.label_refunded')}</Badge>
+ )}
+ {/* What the merchant paid the carrier — accounting data, never the
+ shopper's shipping charge. */}
+ <span className="text-muted-foreground">
+ {t('admin.orders.detail.fulfillments.label_cost')}: {label.display_cost}
+ </span>
+ </div>
+
+ <div className="flex items-center gap-2">
+ {label.download_url && (
+ <Button type="button" size="sm" variant="outline" onClick={print}>
+ <PrinterIcon data-icon="inline-start" />
+ {t('admin.orders.detail.fulfillments.print_label')}
+ </Button>
+ )}
+
+ {refundable && (
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ disabled={refundLabel.isPending}
+ onClick={async () => {
+ if (
+ await confirm({
+ message: t('admin.orders.detail.fulfillments.confirm_refund_label'),
+ variant: 'destructive',
+ confirmLabel: t('admin.orders.detail.fulfillments.refund_label'),
+ })
+ ) {
+ refundLabel.mutate({ fulfillmentId, labelId: label.id })
+ }
+ }}
+ >
+ {t('admin.orders.detail.fulfillments.refund_label')}
+ </Button>
+ )}
+
+ {deletable && (
+ <Button
+ type="button"
+ size="icon-xs"
+ variant="ghost"
+ onClick={async () => {
+ if (
+ await confirm({
+ message: t('admin.orders.detail.fulfillments.confirm_delete_label'),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.delete'),
+ })
+ ) {
+ deleteLabel.mutate({ fulfillmentId, labelId: label.id })
+ }
+ }}
+ >
+ <TrashIcon className="size-4" />
+ <span className="sr-only">{t('admin.orders.detail.fulfillments.delete_label')}</span>
+ </Button>
+ )}
+ </div>
+ </CardContent>
+ )
+}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-tracking-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-tracking-dialog.tsx
deleted file mode 100644
index 22faeefa04..0000000000
--- a/packages/dashboard/src/components/spree/orders/fulfillment-tracking-dialog.tsx
+++ /dev/null
@@ -1,162 +0,0 @@
-import { zodResolver } from '@hookform/resolvers/zod'
-import type { Fulfillment } from '@spree/admin-sdk'
-import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
-import {
- Button,
- Dialog,
- DialogBody,
- DialogContent,
- DialogDescription,
- DialogFooter,
- DialogHeader,
- DialogTitle,
- Field,
- FieldError,
- FieldLabel,
- Input,
- Select,
- SelectContent,
- SelectItem,
- SelectTrigger,
- SelectValue,
-} from '@spree/dashboard-ui'
-import { Controller, useForm } from 'react-hook-form'
-import { useTranslation } from 'react-i18next'
-import { z } from 'zod'
-import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
-import { useTrackingCarriers } from '../../../hooks/use-tracking-carriers'
-
-const trackingSchema = z.object({
- tracking: z.string(),
- // '' means "detect from the number" — the backend pins the carrier itself
- // when the format is recognisable.
- tracking_carrier: z.string(),
-})
-
-type TrackingFormValues = z.infer<typeof trackingSchema>
-
-/**
- * Adds or edits a fulfillment's tracking number. Separate from the edit
- * dialog, which is about where a parcel ships from and by which service —
- * this is the one thing a merchant reaches for after a parcel has gone out.
- */
-export function FulfillmentTrackingDialog({
- orderId,
- fulfillment,
- open,
- onOpenChange,
-}: {
- orderId: string
- fulfillment: Fulfillment
- open: boolean
- onOpenChange: (open: boolean) => void
-}) {
- const { t } = useTranslation()
- const { update } = useFulfillmentActions(orderId)
- const { data: carriersData } = useTrackingCarriers(open)
-
- const carrierOptions = [
- { value: '', label: t('admin.orders.detail.fulfillments.carrier_auto') },
- ...(carriersData?.data ?? []).map((carrier) => ({ value: carrier.id, label: carrier.name })),
- ]
-
- const form = useForm<TrackingFormValues>({
- resolver: zodResolver(trackingSchema),
- defaultValues: {
- tracking: fulfillment.tracking ?? '',
- tracking_carrier: fulfillment.tracking_carrier ?? '',
- },
- })
-
- async function onSubmit(values: TrackingFormValues) {
- try {
- await update.mutateAsync({
- fulfillmentId: fulfillment.id,
- tracking: values.tracking.trim(),
- tracking_carrier: values.tracking_carrier,
- })
- onOpenChange(false)
- } catch (err) {
- if (!mapSpreeErrorsToForm(err, form.setError)) throw err
- }
- }
-
- return (
- <Dialog open={open} onOpenChange={onOpenChange}>
- <DialogContent>
- <form onSubmit={form.handleSubmit(onSubmit)}>
- <DialogHeader>
- <DialogTitle>
- {fulfillment.tracking
- ? t('admin.orders.detail.fulfillments.edit_tracking_title')
- : t('admin.orders.detail.fulfillments.add_tracking_title')}
- </DialogTitle>
- <DialogDescription>
- {t('admin.orders.detail.fulfillments.tracking_description')}
- </DialogDescription>
- </DialogHeader>
-
- <DialogBody>
- {form.formState.errors.root?.message && (
- <p className="text-sm text-destructive" role="alert">
- {form.formState.errors.root.message}
- </p>
- )}
-
- <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
- <Field>
- <FieldLabel htmlFor="fulfillment-tracking">
- {t('admin.orders.fulfill.tracking_label')}
- </FieldLabel>
- <Input
- id="fulfillment-tracking"
- placeholder={t('admin.orders.fulfill.tracking_placeholder')}
- aria-invalid={!!form.formState.errors.tracking}
- {...form.register('tracking')}
- />
- <FieldError errors={[form.formState.errors.tracking]} />
- </Field>
-
- <Field>
- <FieldLabel htmlFor="fulfillment-tracking-carrier">
- {t('admin.orders.detail.fulfillments.carrier_label')}
- </FieldLabel>
- <Controller
- control={form.control}
- name="tracking_carrier"
- render={({ field }) => (
- <Select
- items={carrierOptions}
- value={field.value}
- onValueChange={(value) => field.onChange(value ?? '')}
- >
- <SelectTrigger id="fulfillment-tracking-carrier">
- <SelectValue />
- </SelectTrigger>
- <SelectContent>
- {carrierOptions.map((option) => (
- <SelectItem key={option.value} value={option.value}>
- {option.label}
- </SelectItem>
- ))}
- </SelectContent>
- </Select>
- )}
- />
- </Field>
- </div>
- </DialogBody>
-
- <DialogFooter>
- <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
- {t('admin.actions.cancel')}
- </Button>
- <Button type="submit" disabled={update.isPending}>
- {update.isPending ? t('admin.actions.saving') : t('admin.actions.save')}
- </Button>
- </DialogFooter>
- </form>
- </DialogContent>
- </Dialog>
- )
-}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
index 30dd485370..8dc7d3f065 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
@@ -1,4 +1,4 @@
-import type { Fulfillment, Order } from '@spree/admin-sdk'
+import type { Delivery, Fulfillment, Order } from '@spree/admin-sdk'
import { useStockLocations } from '@spree/dashboard-core'
import {
Badge,
@@ -56,10 +56,13 @@ import {
unfulfilledItemRows,
} from '../../../lib/fulfillment-items'
import { printPackingSlip } from '../../../lib/packing-slip'
+import { FulfillmentDeliveries } from './fulfillment-deliveries'
+import { FulfillmentDeliveryDialog } from './fulfillment-delivery-dialog'
import { FulfillmentEditDialog } from './fulfillment-edit-dialog'
import { FulfillmentFulfillForm } from './fulfillment-fulfill-form'
import { FulfillmentItemList } from './fulfillment-item-list'
-import { FulfillmentTrackingDialog } from './fulfillment-tracking-dialog'
+import { FulfillmentLabel } from './fulfillment-label'
+import { FulfillmentLabelUploadDialog } from './fulfillment-label-upload-dialog'
/**
* A unit sitting in one fulfillment. Splitting moves units per variant rather
@@ -398,11 +401,13 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
const { t } = useTranslation()
const confirm = useConfirm()
const orderId = order.id
- const { cancel, markDelivered, purchaseLabel } = useFulfillmentActions(orderId)
+ const { cancel, markDelivered, buyLabel } = useFulfillmentActions(orderId)
const [editOpen, setEditOpen] = useState(false)
const [splitOpen, setSplitOpen] = useState(false)
- const [trackingOpen, setTrackingOpen] = useState(false)
+ const [deliveryOpen, setDeliveryOpen] = useState(false)
+ const [editingDelivery, setEditingDelivery] = useState<Delivery | undefined>()
+ const [uploadOpen, setUploadOpen] = useState(false)
const [fulfilling, setFulfilling] = useState(false)
const editable = CAN_EDIT.includes(fulfillment.status)
@@ -417,11 +422,17 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
(rate) => rate.id === fulfillment.selected_delivery_rate_id,
)
const deliverable = CAN_MARK_DELIVERED.includes(fulfillment.status)
+ const deliveries = fulfillment.deliveries ?? []
+ // At most one label binds a parcel: the workflows refuse a second while one
+ // is active, and a refunded one stays as history.
+ const activeLabel = (fulfillment.labels ?? []).find((label) => label.status !== 'refunded')
// The label leads, fulfilled follows: print the label, pack the box, hand
// it over — so buying the label is offered before the parcel ships.
- const labelDocument = (fulfillment.documents ?? []).find((doc) => doc.kind === 'label')
- const canBuyLabel = shippable && fulfillment.provider_generates_labels && !labelDocument
- const trackable = deliverable && !fulfillment.tracking
+ const canBuyLabel = shippable && fulfillment.provider_generates_labels && !activeLabel
+ // Merchants without a carrier account buy postage elsewhere and still need
+ // the file and the cost on the parcel.
+ const canUploadLabel =
+ !activeLabel && !CAN_MARK_DELIVERED.includes(fulfillment.status) ? shippable : false
return (
<FulfillmentPanel
@@ -466,10 +477,20 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
{t('admin.orders.detail.fulfillments.print_packing_slip')}
</DropdownMenuItem>
- {deliverable && fulfillment.tracking && (
- <DropdownMenuItem onClick={() => setTrackingOpen(true)}>
- <TruckIcon className="size-4" />
- {t('admin.orders.detail.fulfillments.edit_tracking_title')}
+ <DropdownMenuItem
+ onClick={() => {
+ setEditingDelivery(undefined)
+ setDeliveryOpen(true)
+ }}
+ >
+ <TruckIcon className="size-4" />
+ {t('admin.orders.detail.fulfillments.add_delivery')}
+ </DropdownMenuItem>
+
+ {canUploadLabel && (
+ <DropdownMenuItem onClick={() => setUploadOpen(true)}>
+ <TagIcon className="size-4" />
+ {t('admin.orders.detail.fulfillments.upload_label')}
</DropdownMenuItem>
)}
@@ -514,24 +535,21 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
</CardContent>
)}
- {fulfillment.tracking && !fulfilling && (
- <CardContent className="border-b border-border-subtle py-3 text-sm">
- <span className="text-muted-foreground">
- {fulfillment.tracking_carrier_name ?? t('admin.orders.detail.tracking.prefix')}:{' '}
- </span>
- {fulfillment.tracking_url ? (
- <a
- href={fulfillment.tracking_url}
- target="_blank"
- rel="noopener noreferrer"
- className="text-blue-600 hover:underline"
- >
- {fulfillment.tracking}
- </a>
- ) : (
- <span>{fulfillment.tracking}</span>
- )}
- </CardContent>
+ {activeLabel && !fulfilling && (
+ <FulfillmentLabel orderId={orderId} fulfillmentId={fulfillment.id} label={activeLabel} />
+ )}
+
+ {!fulfilling && (
+ <FulfillmentDeliveries
+ orderId={orderId}
+ fulfillmentId={fulfillment.id}
+ deliveries={deliveries}
+ canMarkDelivered={deliverable}
+ onEdit={(delivery) => {
+ setEditingDelivery(delivery)
+ setDeliveryOpen(true)
+ }}
+ />
)}
{fulfilling ? (
@@ -551,7 +569,7 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
type="button"
size="sm"
variant="outline"
- disabled={purchaseLabel.isPending}
+ disabled={buyLabel.isPending}
onClick={async () => {
// Buying a label charges the carrier account, so it gets
// an explicit yes even though nothing is destroyed.
@@ -566,26 +584,17 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
confirmLabel: t('admin.orders.detail.fulfillments.buy_label'),
})
) {
- purchaseLabel.mutate(fulfillment.id)
+ buyLabel.mutate({ fulfillmentId: fulfillment.id })
}
}}
>
<TagIcon data-icon="inline-start" />
- {purchaseLabel.isPending
+ {buyLabel.isPending
? t('admin.actions.saving')
: t('admin.orders.detail.fulfillments.buy_label')}
</Button>
)}
- {labelDocument && (
- <Button type="button" size="sm" variant="outline" asChild>
- <a href={labelDocument.url} target="_blank" rel="noopener noreferrer">
- <PrinterIcon data-icon="inline-start" />
- {t('admin.orders.detail.fulfillments.print_label')}
- </a>
- </Button>
- )}
-
<Button type="button" size="sm" onClick={() => setFulfilling(true)}>
<TruckIcon data-icon="inline-start" />
{t('admin.orders.fulfill.action')}
@@ -593,23 +602,12 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
</CardFooter>
)}
- {!shippable && labelDocument && (
- <CardFooter className="justify-end py-3">
- <Button type="button" size="sm" variant="outline" asChild>
- <a href={labelDocument.url} target="_blank" rel="noopener noreferrer">
- <PrinterIcon data-icon="inline-start" />
- {t('admin.orders.detail.fulfillments.print_label')}
- </a>
- </Button>
- </CardFooter>
- )}
-
{deliverable && (
<CardFooter className="justify-end gap-2 py-3">
<Button
type="button"
size="sm"
- variant={trackable ? 'outline' : 'default'}
+ variant={deliveries.length === 0 ? 'outline' : 'default'}
disabled={markDelivered.isPending}
onClick={() => markDelivered.mutate(fulfillment.id)}
>
@@ -617,12 +615,18 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
{t('admin.orders.detail.fulfillments.mark_delivered')}
</Button>
- {trackable && (
- <Button type="button" size="sm" onClick={() => setTrackingOpen(true)}>
- <PlusIcon data-icon="inline-start" />
- {t('admin.orders.detail.fulfillments.add_tracking')}
- </Button>
- )}
+ <Button
+ type="button"
+ size="sm"
+ variant={deliveries.length === 0 ? 'default' : 'outline'}
+ onClick={() => {
+ setEditingDelivery(undefined)
+ setDeliveryOpen(true)
+ }}
+ >
+ <PlusIcon data-icon="inline-start" />
+ {t('admin.orders.detail.fulfillments.add_tracking')}
+ </Button>
</CardFooter>
)}
</>
@@ -646,12 +650,26 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
/>
)}
- {trackingOpen && (
- <FulfillmentTrackingDialog
+ {deliveryOpen && (
+ <FulfillmentDeliveryDialog
orderId={orderId}
- fulfillment={fulfillment}
- open={trackingOpen}
- onOpenChange={setTrackingOpen}
+ fulfillmentId={fulfillment.id}
+ delivery={editingDelivery}
+ open={deliveryOpen}
+ onOpenChange={(open) => {
+ setDeliveryOpen(open)
+ if (!open) setEditingDelivery(undefined)
+ }}
+ />
+ )}
+
+ {uploadOpen && (
+ <FulfillmentLabelUploadDialog
+ orderId={orderId}
+ fulfillmentId={fulfillment.id}
+ currency={order.currency}
+ open={uploadOpen}
+ onOpenChange={setUploadOpen}
/>
)}
</FulfillmentPanel>
diff --git a/packages/dashboard/src/hooks/use-fulfillments.ts b/packages/dashboard/src/hooks/use-fulfillments.ts
index cd50cd2c8d..e2a517090f 100644
--- a/packages/dashboard/src/hooks/use-fulfillments.ts
+++ b/packages/dashboard/src/hooks/use-fulfillments.ts
@@ -1,7 +1,10 @@
import {
+ type DeliveryCreateParams,
+ type DeliveryUpdateParams,
type FulfillmentCreateParams,
type FulfillmentFulfillParams,
type FulfillmentSplitParams,
+ type ShippingLabelCreateParams,
SpreeError,
} from '@spree/admin-sdk'
import { adminClient, useResourceKeyBuilder } from '@spree/dashboard-core'
@@ -91,9 +94,66 @@ export function useFulfillmentActions(orderId: string) {
adminClient.orders.fulfillments.markDelivered(orderId, fulfillmentId),
)
- const purchaseLabel = useFulfillmentMutation(orderId, (fulfillmentId: string) =>
- adminClient.orders.fulfillments.purchaseLabel(orderId, fulfillmentId),
+ // Buying with no body; a `file` records postage bought elsewhere instead.
+ const buyLabel = useFulfillmentMutation(
+ orderId,
+ ({ fulfillmentId, ...params }: { fulfillmentId: string } & ShippingLabelCreateParams) =>
+ adminClient.orders.fulfillments.labels.create(orderId, fulfillmentId, params),
+ )
+
+ const refundLabel = useFulfillmentMutation(
+ orderId,
+ ({ fulfillmentId, labelId }: { fulfillmentId: string; labelId: string }) =>
+ adminClient.orders.fulfillments.labels.refund(orderId, fulfillmentId, labelId),
+ )
+
+ const deleteLabel = useFulfillmentMutation(
+ orderId,
+ ({ fulfillmentId, labelId }: { fulfillmentId: string; labelId: string }) =>
+ adminClient.orders.fulfillments.labels.delete(orderId, fulfillmentId, labelId),
+ )
+
+ const createDelivery = useFulfillmentMutation(
+ orderId,
+ ({ fulfillmentId, ...params }: { fulfillmentId: string } & DeliveryCreateParams) =>
+ adminClient.orders.fulfillments.deliveries.create(orderId, fulfillmentId, params),
+ )
+
+ const updateDelivery = useFulfillmentMutation(
+ orderId,
+ ({
+ fulfillmentId,
+ deliveryId,
+ ...params
+ }: { fulfillmentId: string; deliveryId: string } & DeliveryUpdateParams) =>
+ adminClient.orders.fulfillments.deliveries.update(orderId, fulfillmentId, deliveryId, params),
+ )
+
+ const deleteDelivery = useFulfillmentMutation(
+ orderId,
+ ({ fulfillmentId, deliveryId }: { fulfillmentId: string; deliveryId: string }) =>
+ adminClient.orders.fulfillments.deliveries.delete(orderId, fulfillmentId, deliveryId),
+ )
+
+ const markDeliveryDelivered = useFulfillmentMutation(
+ orderId,
+ ({ fulfillmentId, deliveryId }: { fulfillmentId: string; deliveryId: string }) =>
+ adminClient.orders.fulfillments.deliveries.markDelivered(orderId, fulfillmentId, deliveryId),
)
- return { create, update, split, fulfill, cancel, markDelivered, purchaseLabel }
+ return {
+ create,
+ update,
+ split,
+ fulfill,
+ cancel,
+ markDelivered,
+ buyLabel,
+ refundLabel,
+ deleteLabel,
+ createDelivery,
+ updateDelivery,
+ deleteDelivery,
+ markDeliveryDelivered,
+ }
}
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index a75fa38c82..c6b53a9ca5 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -2718,24 +2718,46 @@
"confirmation_send_failed": "فشل في إرسال التأكيد"
},
"fulfillments": {
+ "add_delivery": "إضافة رقم تتبع",
"add_tracking": "إضافة تتبع",
"add_tracking_title": "إضافة تتبع",
"buy_label": "شراء الملصق",
"buy_label_confirm": "شراء ملصق شحن لهذه الشحنة؟ سيتم الخصم من حساب شركة الشحن الخاص بك فور إصدار الملصق.",
"buy_label_confirm_rate": "شراء ملصق {{rate}} مقابل {{cost}}؟ سيتم الخصم من حساب شركة الشحن الخاص بك فور إصدار الملصق.",
+ "buy_label_pending_file": "لا تزال نسخة شركة الشحن قيد التنزيل؛ ستفتح الطباعة رابط شركة الشحن نفسه.",
"carrier_auto": "اكتشاف تلقائي",
"carrier_label": "شركة الشحن",
+ "carrier_status_available_for_pickup": "جاهز للاستلام",
+ "carrier_status_delivered": "تم التسليم",
+ "carrier_status_failure": "فشل التسليم",
+ "carrier_status_in_transit": "في الطريق",
+ "carrier_status_out_for_delivery": "قيد التسليم",
+ "carrier_status_pending": "بانتظار شركة الشحن",
+ "carrier_status_pre_transit": "تم إنشاء الملصق",
+ "carrier_status_return_to_sender": "إعادة إلى المرسل",
+ "carrier_status_unknown": "الحالة غير معروفة",
+ "confirm_delete_delivery": "إزالة رقم التتبع هذا؟ يسري المفعول فورًا.",
+ "confirm_delete_label": "حذف هذا الملصق؟ سيُزال الملف من الطلب. يسري المفعول فورًا.",
+ "confirm_refund_label": "طلب استرداد قيمة هذا الملصق من شركة الشحن؟ ستُعاد أجرة الشحن إلى حسابك.",
"confirm_split": "نقل هذه الوحدات إلى شحنة جديدة؟ يسري هذا فوراً.",
"create_description": "تنشئ شحنة وتنقل إليها الكميات المختارة.",
"create_items": "العناصر",
"create_title": "إضافة شحنة",
+ "delete_label": "حذف الملصق",
+ "deliveries_title": "التتبع",
"delivery_method": "طريقة التوصيل",
"edit_description": "غيّر مكان شحن هذه الشحنة وطريقة التوصيل التي تنقلها.",
"edit_title": "تعديل الشحنة",
"edit_tracking_title": "تعديل التتبع",
"empty": "لا توجد شحنات لهذا الطلب بعد.",
"free": "مجاني",
+ "label_cost": "أجرة الشحن",
+ "label_refund_requested": "تم طلب الاسترداد",
+ "label_refunded": "تم الاسترداد",
+ "label_title": "ملصق الشحن",
+ "label_uploaded": "مرفوع",
"mark_delivered": "وضع علامة كمُسلَّم",
+ "mark_delivery_delivered": "وضع علامة وصل",
"move_and_requote": "نقل وإعادة التسعير",
"no_rates": "لا توجد طرق توصيل متاحة لهذه الشحنة.",
"out_of_stock": "غير متوفر في المخزون",
@@ -2743,6 +2765,7 @@
"print_label": "طباعة الملصق",
"print_packing_slip": "طباعة قائمة التعبئة",
"rates_pending_origin": "احفظ مصدر الشحن الجديد لعرض طرق التوصيل المتاحة منه.",
+ "refund_label": "استرداد الملصق",
"ship_to": "الشحن إلى",
"ships_from": "الشحن من",
"split": "تقسيم",
@@ -2752,7 +2775,14 @@
"split_title": "تقسيم الشحنة",
"split_would_empty": "اترك وحدة واحدة على الأقل، أو غيّر مصدر الشحنة بالكامل بدلاً من ذلك.",
"tracking_description": "رقم تتبع شركة الشحن، أو رابط تتبع كامل.",
- "unfulfilled_other": "غير مُنفَّذ ({{count}})"
+ "tracking_url_label": "رابط التتبع",
+ "tracking_url_placeholder": "https://carrier.example/track/...",
+ "unfulfilled_other": "غير مُنفَّذ ({{count}})",
+ "upload_label": "رفع ملصق",
+ "upload_label_cost": "تكلفة أجرة الشحن",
+ "upload_label_description": "سجّل ملصقًا اشتريته من مكان آخر، ليكون للطرد ملفه ورقم تتبعه وتكلفته.",
+ "upload_label_file": "ملف الملصق",
+ "upload_label_title": "رفع ملصق"
},
"gift_card_section": {
"applied_suffix": "مُطبَّق",
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 3e75a4dbff..4d78d9e45f 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -2700,24 +2700,46 @@
"confirmation_send_failed": "Bestätigung konnte nicht gesendet werden"
},
"fulfillments": {
+ "add_delivery": "Sendungsnummer hinzufügen",
"add_tracking": "Sendungsverfolgung hinzufügen",
"add_tracking_title": "Sendungsverfolgung hinzufügen",
"buy_label": "Label kaufen",
"buy_label_confirm": "Versandlabel für diese Sendung kaufen? Ihr Versanddienstleister-Konto wird belastet, sobald das Label ausgestellt ist.",
"buy_label_confirm_rate": "Label {{rate}} für {{cost}} kaufen? Ihr Versanddienstleister-Konto wird belastet, sobald das Label ausgestellt ist.",
+ "buy_label_pending_file": "Die Kopie des Transportunternehmens wird noch geladen; beim Drucken öffnet sich dessen eigener Link.",
"carrier_auto": "Automatisch erkennen",
"carrier_label": "Versanddienstleister",
+ "carrier_status_available_for_pickup": "Zur Abholung bereit",
+ "carrier_status_delivered": "Zugestellt",
+ "carrier_status_failure": "Zustellung fehlgeschlagen",
+ "carrier_status_in_transit": "Unterwegs",
+ "carrier_status_out_for_delivery": "In Zustellung",
+ "carrier_status_pending": "Wartet auf Transportunternehmen",
+ "carrier_status_pre_transit": "Etikett erstellt",
+ "carrier_status_return_to_sender": "Rücksendung an Absender",
+ "carrier_status_unknown": "Status unbekannt",
+ "confirm_delete_delivery": "Diese Sendungsnummer entfernen? Die Änderung wird sofort wirksam.",
+ "confirm_delete_label": "Dieses Etikett löschen? Die Datei wird von der Bestellung entfernt. Die Änderung wird sofort wirksam.",
+ "confirm_refund_label": "Erstattung dieses Etiketts beim Transportunternehmen beantragen? Das Porto wird Ihrem Konto gutgeschrieben.",
"confirm_split": "Diese Einheiten in eine neue Sendung verschieben? Die Änderung wird sofort wirksam.",
"create_description": "Erstellt eine Sendung und verschiebt die gewählten Mengen hinein.",
"create_items": "Artikel",
"create_title": "Sendung hinzufügen",
+ "delete_label": "Etikett löschen",
+ "deliveries_title": "Sendungsverfolgung",
"delivery_method": "Versandart",
"edit_description": "Ändern Sie, von wo diese Sendung versandt wird und welche Versandart sie befördert.",
"edit_title": "Sendung bearbeiten",
"edit_tracking_title": "Sendungsverfolgung bearbeiten",
"empty": "Noch keine Sendungen für diese Bestellung.",
"free": "Kostenlos",
+ "label_cost": "Porto",
+ "label_refund_requested": "Erstattung beantragt",
+ "label_refunded": "Erstattet",
+ "label_title": "Versandetikett",
+ "label_uploaded": "Hochgeladen",
"mark_delivered": "Als zugestellt markieren",
+ "mark_delivery_delivered": "Als angekommen markieren",
"move_and_requote": "Verschieben und neu berechnen",
"no_rates": "Für diese Sendung liegen keine Versandarten vor.",
"out_of_stock": "Nicht auf Lager",
@@ -2725,6 +2747,7 @@
"print_label": "Label drucken",
"print_packing_slip": "Lieferschein drucken",
"rates_pending_origin": "Speichern Sie den neuen Ursprung, um die dort verfügbaren Versandarten zu sehen.",
+ "refund_label": "Etikett erstatten",
"ship_to": "Lieferadresse",
"ships_from": "Versand ab",
"split": "Aufteilen",
@@ -2734,8 +2757,15 @@
"split_title": "Sendung aufteilen",
"split_would_empty": "Lassen Sie mindestens eine Einheit zurück oder ändern Sie stattdessen den Ursprung der gesamten Sendung.",
"tracking_description": "Die Sendungsnummer des Zustellers oder ein vollständiger Tracking-Link.",
+ "tracking_url_label": "Sendungsverfolgungs-Link",
+ "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_one": "Nicht versandt ({{count}})",
- "unfulfilled_other": "Nicht versandt ({{count}})"
+ "unfulfilled_other": "Nicht versandt ({{count}})",
+ "upload_label": "Etikett hochladen",
+ "upload_label_cost": "Portokosten",
+ "upload_label_description": "Erfassen Sie ein anderswo gekauftes Etikett, damit die Sendung ihre Datei, ihre Sendungsnummer und ihre Kosten hat.",
+ "upload_label_file": "Etikettendatei",
+ "upload_label_title": "Etikett hochladen"
},
"gift_card_section": {
"applied_suffix": "angewendet",
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index 861a8ae96f..474ac8dadf 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -2700,24 +2700,46 @@
"confirmation_send_failed": "Failed to send confirmation"
},
"fulfillments": {
+ "add_delivery": "Add tracking",
"add_tracking": "Add tracking",
"add_tracking_title": "Add tracking",
"buy_label": "Buy label",
"buy_label_confirm": "Buy a shipping label for this fulfillment? Your carrier account is charged as soon as the label is issued.",
"buy_label_confirm_rate": "Buy a {{rate}} label for {{cost}}? Your carrier account is charged as soon as the label is issued.",
+ "buy_label_pending_file": "The carrier's copy is still downloading; printing opens the carrier's own link.",
"carrier_auto": "Detect automatically",
"carrier_label": "Shipping carrier",
+ "carrier_status_available_for_pickup": "Available for pickup",
+ "carrier_status_delivered": "Delivered",
+ "carrier_status_failure": "Delivery failed",
+ "carrier_status_in_transit": "In transit",
+ "carrier_status_out_for_delivery": "Out for delivery",
+ "carrier_status_pending": "Awaiting carrier",
+ "carrier_status_pre_transit": "Label created",
+ "carrier_status_return_to_sender": "Returning to sender",
+ "carrier_status_unknown": "Status unknown",
+ "confirm_delete_delivery": "Remove this tracking number? This takes effect immediately.",
+ "confirm_delete_label": "Delete this label? The file is removed from the order. This takes effect immediately.",
+ "confirm_refund_label": "Ask the carrier to refund this label? Postage is credited back to your carrier account.",
"confirm_split": "Move these units into a new fulfillment? This takes effect immediately.",
"create_description": "Creates a fulfillment and moves the chosen quantities into it.",
"create_items": "Items",
"create_title": "Add fulfillment",
+ "delete_label": "Delete label",
+ "deliveries_title": "Tracking",
"delivery_method": "Delivery method",
"edit_description": "Change where this fulfillment ships from and which delivery method carries it.",
"edit_title": "Edit fulfillment",
"edit_tracking_title": "Edit tracking",
"empty": "No fulfillments on this order yet.",
"free": "Free",
+ "label_cost": "Postage",
+ "label_refund_requested": "Refund requested",
+ "label_refunded": "Refunded",
+ "label_title": "Shipping label",
+ "label_uploaded": "Uploaded",
"mark_delivered": "Mark as delivered",
+ "mark_delivery_delivered": "Mark arrived",
"move_and_requote": "Move and re-quote",
"no_rates": "No delivery methods are quoted for this fulfillment.",
"out_of_stock": "Out of stock",
@@ -2725,6 +2747,7 @@
"print_label": "Print label",
"print_packing_slip": "Print packing slip",
"rates_pending_origin": "Save the new origin to see the delivery methods it offers.",
+ "refund_label": "Refund label",
"ship_to": "Ship to",
"ships_from": "Ships from",
"split": "Split",
@@ -2734,8 +2757,15 @@
"split_title": "Split fulfillment",
"split_would_empty": "Leave at least one unit behind, or change the origin of the whole fulfillment instead.",
"tracking_description": "The carrier tracking number, or a full tracking link.",
+ "tracking_url_label": "Tracking link",
+ "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_one": "Unfulfilled ({{count}})",
- "unfulfilled_other": "Unfulfilled ({{count}})"
+ "unfulfilled_other": "Unfulfilled ({{count}})",
+ "upload_label": "Upload label",
+ "upload_label_cost": "Postage cost",
+ "upload_label_description": "Record a label you bought elsewhere, so the parcel has its file, its tracking number and what it cost.",
+ "upload_label_file": "Label file",
+ "upload_label_title": "Upload label"
},
"gift_card_section": {
"applied_suffix": "applied",
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index 24842371ef..227471a167 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -2700,24 +2700,46 @@
"confirmation_send_failed": "Échec de l'envoi de la confirmation"
},
"fulfillments": {
+ "add_delivery": "Ajouter un suivi",
"add_tracking": "Ajouter un suivi",
"add_tracking_title": "Ajouter un suivi",
"buy_label": "Acheter l'étiquette",
"buy_label_confirm": "Acheter une étiquette d'expédition pour ce colis ? Votre compte transporteur est débité dès l'émission de l'étiquette.",
"buy_label_confirm_rate": "Acheter une étiquette {{rate}} pour {{cost}} ? Votre compte transporteur est débité dès l'émission de l'étiquette.",
+ "buy_label_pending_file": "La copie du transporteur est en cours de téléchargement ; l'impression ouvre son propre lien.",
"carrier_auto": "Détecter automatiquement",
"carrier_label": "Transporteur",
+ "carrier_status_available_for_pickup": "Disponible au retrait",
+ "carrier_status_delivered": "Livré",
+ "carrier_status_failure": "Échec de la livraison",
+ "carrier_status_in_transit": "En transit",
+ "carrier_status_out_for_delivery": "En cours de livraison",
+ "carrier_status_pending": "En attente du transporteur",
+ "carrier_status_pre_transit": "Étiquette créée",
+ "carrier_status_return_to_sender": "Retour à l'expéditeur",
+ "carrier_status_unknown": "Statut inconnu",
+ "confirm_delete_delivery": "Supprimer ce numéro de suivi ? L'effet est immédiat.",
+ "confirm_delete_label": "Supprimer cette étiquette ? Le fichier est retiré de la commande. L'effet est immédiat.",
+ "confirm_refund_label": "Demander au transporteur le remboursement de cette étiquette ? L'affranchissement est recrédité sur votre compte.",
"confirm_split": "Déplacer ces unités vers une nouvelle expédition ? L'effet est immédiat.",
"create_description": "Crée une expédition et y déplace les quantités choisies.",
"create_items": "Articles",
"create_title": "Ajouter une expédition",
+ "delete_label": "Supprimer l'étiquette",
+ "deliveries_title": "Suivi",
"delivery_method": "Mode de livraison",
"edit_description": "Modifiez le lieu d'expédition et le mode de livraison de cette expédition.",
"edit_title": "Modifier l'expédition",
"edit_tracking_title": "Modifier le suivi",
"empty": "Aucune expédition pour cette commande.",
"free": "Gratuit",
+ "label_cost": "Affranchissement",
+ "label_refund_requested": "Remboursement demandé",
+ "label_refunded": "Remboursé",
+ "label_title": "Étiquette d'expédition",
+ "label_uploaded": "Téléversée",
"mark_delivered": "Marquer comme livré",
+ "mark_delivery_delivered": "Marquer comme arrivé",
"move_and_requote": "Déplacer et recalculer",
"no_rates": "Aucun mode de livraison n'est proposé pour cette expédition.",
"out_of_stock": "En rupture de stock",
@@ -2725,6 +2747,7 @@
"print_label": "Imprimer l'étiquette",
"print_packing_slip": "Imprimer le bordereau de colisage",
"rates_pending_origin": "Enregistrez la nouvelle origine pour voir les modes de livraison proposés.",
+ "refund_label": "Rembourser l'étiquette",
"ship_to": "Livrer à",
"ships_from": "Expédié depuis",
"split": "Diviser",
@@ -2734,8 +2757,15 @@
"split_title": "Diviser l'expédition",
"split_would_empty": "Laissez au moins une unité, ou modifiez plutôt l'origine de toute l'expédition.",
"tracking_description": "Le numéro de suivi du transporteur, ou un lien de suivi complet.",
+ "tracking_url_label": "Lien de suivi",
+ "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_one": "Non expédié ({{count}})",
- "unfulfilled_other": "Non expédiés ({{count}})"
+ "unfulfilled_other": "Non expédiés ({{count}})",
+ "upload_label": "Téléverser une étiquette",
+ "upload_label_cost": "Coût d'affranchissement",
+ "upload_label_description": "Enregistrez une étiquette achetée ailleurs, pour que le colis ait son fichier, son numéro de suivi et son coût.",
+ "upload_label_file": "Fichier de l'étiquette",
+ "upload_label_title": "Téléverser une étiquette"
},
"gift_card_section": {
"applied_suffix": "appliqué",
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index a39c24cf6e..8bf22c9659 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -2720,24 +2720,46 @@
"confirmation_send_failed": "Nie udało się wysłać potwierdzenia"
},
"fulfillments": {
+ "add_delivery": "Dodaj numer przesyłki",
"add_tracking": "Dodaj śledzenie",
"add_tracking_title": "Dodaj śledzenie",
"buy_label": "Kup etykietę",
"buy_label_confirm": "Kupić etykietę wysyłkową dla tej przesyłki? Twoje konto przewoźnika zostanie obciążone w momencie wystawienia etykiety.",
"buy_label_confirm_rate": "Kupić etykietę {{rate}} za {{cost}}? Twoje konto przewoźnika zostanie obciążone w momencie wystawienia etykiety.",
+ "buy_label_pending_file": "Kopia przewoźnika jest jeszcze pobierana; drukowanie otworzy jego własny link.",
"carrier_auto": "Wykryj automatycznie",
"carrier_label": "Przewoźnik",
+ "carrier_status_available_for_pickup": "Gotowa do odbioru",
+ "carrier_status_delivered": "Dostarczona",
+ "carrier_status_failure": "Doręczenie nieudane",
+ "carrier_status_in_transit": "W drodze",
+ "carrier_status_out_for_delivery": "W doręczeniu",
+ "carrier_status_pending": "Oczekuje na przewoźnika",
+ "carrier_status_pre_transit": "Etykieta utworzona",
+ "carrier_status_return_to_sender": "Powrót do nadawcy",
+ "carrier_status_unknown": "Status nieznany",
+ "confirm_delete_delivery": "Usunąć ten numer przesyłki? Zmiana obowiązuje natychmiast.",
+ "confirm_delete_label": "Usunąć tę etykietę? Plik zostanie usunięty z zamówienia. Zmiana obowiązuje natychmiast.",
+ "confirm_refund_label": "Poprosić przewoźnika o zwrot za tę etykietę? Opłata wróci na Twoje konto.",
"confirm_split": "Przenieść te sztuki do nowej przesyłki? Zmiana zadziała natychmiast.",
"create_description": "Tworzy przesyłkę i przenosi do niej wybrane ilości.",
"create_items": "Pozycje",
"create_title": "Dodaj przesyłkę",
+ "delete_label": "Usuń etykietę",
+ "deliveries_title": "Śledzenie",
"delivery_method": "Sposób dostawy",
"edit_description": "Zmień miejsce wysyłki tej przesyłki oraz sposób dostawy, którym jest realizowana.",
"edit_title": "Edytuj przesyłkę",
"edit_tracking_title": "Edytuj śledzenie",
"empty": "Brak przesyłek dla tego zamówienia.",
"free": "Za darmo",
+ "label_cost": "Opłata pocztowa",
+ "label_refund_requested": "Zgłoszono zwrot",
+ "label_refunded": "Zwrócono",
+ "label_title": "Etykieta wysyłkowa",
+ "label_uploaded": "Wgrana",
"mark_delivered": "Oznacz jako dostarczone",
+ "mark_delivery_delivered": "Oznacz jako dostarczoną",
"move_and_requote": "Przenieś i przelicz",
"no_rates": "Dla tej przesyłki nie ma dostępnych sposobów dostawy.",
"out_of_stock": "Brak w magazynie",
@@ -2745,6 +2767,7 @@
"print_label": "Drukuj etykietę",
"print_packing_slip": "Drukuj list przewozowy",
"rates_pending_origin": "Zapisz nowe miejsce wysyłki, aby zobaczyć dostępne dla niego sposoby dostawy.",
+ "refund_label": "Zwrot za etykietę",
"ship_to": "Adres dostawy",
"ships_from": "Wysyłka z",
"split": "Podziel",
@@ -2754,10 +2777,17 @@
"split_title": "Podziel przesyłkę",
"split_would_empty": "Pozostaw co najmniej jedną sztukę albo zmień miejsce wysyłki całej przesyłki.",
"tracking_description": "Numer przesyłki od przewoźnika lub pełny link do śledzenia.",
+ "tracking_url_label": "Link do śledzenia",
+ "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_few": "Niezrealizowane ({{count}})",
"unfulfilled_many": "Niezrealizowane ({{count}})",
"unfulfilled_one": "Niezrealizowane ({{count}})",
- "unfulfilled_other": "Niezrealizowane ({{count}})"
+ "unfulfilled_other": "Niezrealizowane ({{count}})",
+ "upload_label": "Wgraj etykietę",
+ "upload_label_cost": "Koszt opłaty pocztowej",
+ "upload_label_description": "Zapisz etykietę kupioną gdzie indziej, aby przesyłka miała swój plik, numer i koszt.",
+ "upload_label_file": "Plik etykiety",
+ "upload_label_title": "Wgraj etykietę"
},
"gift_card_section": {
"applied_suffix": "zastosowano",
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index e5d41363bb..4e93a8a433 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -2693,24 +2693,46 @@
"confirmation_send_failed": "发送确认失败"
},
"fulfillments": {
+ "add_delivery": "添加运单号",
"add_tracking": "添加物流跟踪",
"add_tracking_title": "添加物流跟踪",
"buy_label": "购买面单",
"buy_label_confirm": "为此包裹购买运输面单?面单签发后将立即从您的承运商账户扣费。",
"buy_label_confirm_rate": "以 {{cost}} 购买 {{rate}} 面单?面单签发后将立即从您的承运商账户扣费。",
+ "buy_label_pending_file": "承运商的副本仍在下载中;打印将打开承运商自己的链接。",
"carrier_auto": "自动识别",
"carrier_label": "承运商",
+ "carrier_status_available_for_pickup": "可自提",
+ "carrier_status_delivered": "已送达",
+ "carrier_status_failure": "投递失败",
+ "carrier_status_in_transit": "运输中",
+ "carrier_status_out_for_delivery": "派送中",
+ "carrier_status_pending": "等待承运商",
+ "carrier_status_pre_transit": "已创建面单",
+ "carrier_status_return_to_sender": "退回发件人",
+ "carrier_status_unknown": "状态未知",
+ "confirm_delete_delivery": "删除此运单号?此操作立即生效。",
+ "confirm_delete_label": "删除此面单?文件将从订单中移除。此操作立即生效。",
+ "confirm_refund_label": "请求承运商退还此面单?邮资将退回您的承运商账户。",
"confirm_split": "将这些数量移入新的发货单?此操作立即生效。",
"create_description": "创建发货单并将所选数量移入其中。",
"create_items": "商品项",
"create_title": "添加发货单",
+ "delete_label": "删除面单",
+ "deliveries_title": "物流跟踪",
"delivery_method": "配送方式",
"edit_description": "修改此发货单的发货地以及承运的配送方式。",
"edit_title": "编辑发货单",
"edit_tracking_title": "编辑物流跟踪",
"empty": "此订单暂无发货单。",
"free": "免费",
+ "label_cost": "邮资",
+ "label_refund_requested": "已申请退款",
+ "label_refunded": "已退款",
+ "label_title": "运输面单",
+ "label_uploaded": "已上传",
"mark_delivered": "标记为已送达",
+ "mark_delivery_delivered": "标记为已送达",
"move_and_requote": "移动并重新报价",
"no_rates": "此发货单暂无可用的配送方式。",
"out_of_stock": "无库存",
@@ -2718,6 +2740,7 @@
"print_label": "打印面单",
"print_packing_slip": "打印装箱单",
"rates_pending_origin": "保存新的发货地后即可查看该地可用的配送方式。",
+ "refund_label": "退还面单",
"ship_to": "收货地址",
"ships_from": "发货地",
"split": "拆分",
@@ -2727,7 +2750,14 @@
"split_title": "拆分发货单",
"split_would_empty": "请至少保留一件,或改为修改整个发货单的发货地。",
"tracking_description": "承运商的物流单号,或完整的跟踪链接。",
- "unfulfilled_other": "未发货({{count}})"
+ "tracking_url_label": "跟踪链接",
+ "tracking_url_placeholder": "https://carrier.example/track/...",
+ "unfulfilled_other": "未发货({{count}})",
+ "upload_label": "上传面单",
+ "upload_label_cost": "邮资费用",
+ "upload_label_description": "记录在别处购买的面单,让包裹拥有自己的文件、运单号和费用。",
+ "upload_label_file": "面单文件",
+ "upload_label_title": "上传面单"
},
"gift_card_section": {
"applied_suffix": "已应用",
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index b272325b48..f266f42d8d 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -794,6 +794,16 @@ export class StoreClient {
...options,
body: params,
}),
+
+ /**
+ * The prepaid return label the merchant bought, if there is one — the
+ * path to fetch it from. The bytes are streamed through the API rather
+ * than served from storage, so fetch this with the customer's
+ * credentials and drive the browser download from a Blob; a 404 means no
+ * label was bought.
+ */
+ labelPath: (orderId: string, id: string): string =>
+ `/api/v3/store/orders/${orderId}/returns/${id}/label`,
},
/**
diff --git a/packages/sdk/src/types/generated/Delivery.ts b/packages/sdk/src/types/generated/Delivery.ts
new file mode 100644
index 0000000000..4d2a2b78b1
--- /dev/null
+++ b/packages/sdk/src/types/generated/Delivery.ts
@@ -0,0 +1,17 @@
+// Typelizer digest ac2d4e4b90d458a0e3f185015a1146a6
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface Delivery {
+ id: string;
+ tracking_number: string;
+ tracking_url: string | null;
+ carrier: string | null;
+ carrier_name: string | null;
+ service: string | null;
+ status: string;
+ estimated_delivery_at: string | null;
+ delivered_at: string | null;
+}
+
+export default Delivery;
diff --git a/packages/sdk/src/types/generated/Fulfillment.ts b/packages/sdk/src/types/generated/Fulfillment.ts
index c9a8dcceed..d43582c419 100644
--- a/packages/sdk/src/types/generated/Fulfillment.ts
+++ b/packages/sdk/src/types/generated/Fulfillment.ts
@@ -1,15 +1,13 @@
-// Typelizer digest e3654a95ab4a56e25b6e7de8b765adb8
+// Typelizer digest 6b9106eebecf1200d2d90855d9dd162e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {DeliveryMethod, StockLocation, DeliveryRate, TaxLine} from '@/types'
+import type {Delivery, DeliveryMethod, StockLocation, DeliveryRate, TaxLine} from '@/types'
interface Fulfillment {
id: string;
number: string;
tracking: string | null;
tracking_url: string | null;
- tracking_carrier: string | null;
- tracking_carrier_name: string | null;
pickup_point_data: Record<string, unknown> | null;
selected_delivery_rate_id: string | null;
cost: string | null;
@@ -27,10 +25,9 @@ interface Fulfillment {
status: string;
fulfillment_type: string;
fulfilled_at: string | null;
- tracking_status: string | null;
- estimated_delivery_at: string | null;
delivered_at: string | null;
items: Array<{ item_id: string; variant_id: string; quantity: number }>;
+ deliveries: Array<Delivery>;
delivery_method: DeliveryMethod;
stock_location: StockLocation;
delivery_rates: Array<DeliveryRate>;
diff --git a/packages/sdk/src/types/generated/ShippingLabelEvent.ts b/packages/sdk/src/types/generated/ShippingLabelEvent.ts
new file mode 100644
index 0000000000..5b97d5f0e1
--- /dev/null
+++ b/packages/sdk/src/types/generated/ShippingLabelEvent.ts
@@ -0,0 +1,29 @@
+// Typelizer digest 28ef8030836c61f77a9912e2c3146c0f
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface ShippingLabelEvent {
+ id: string;
+ source: string;
+ status: string;
+ carrier: string | null;
+ service: string | null;
+ tracking_number: string | null;
+ currency: string | null;
+ format: string | null;
+ external_id: string | null;
+ metadata: Record<string, unknown>;
+ refunded_at: string | null;
+ created_at: string;
+ updated_at: string;
+ owner_id: string;
+ owner_type: string;
+ carrier_name: string | null;
+ cost: string;
+ display_cost: string;
+ integration_id: string | null;
+ file_pending: boolean;
+ download_url: string | null;
+}
+
+export default ShippingLabelEvent;
diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.ts
index 1990bd3e92..8b29e3017a 100644
--- a/packages/sdk/src/types/generated/index.ts
+++ b/packages/sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 71ba6d932aa5bd91922d19e68b242a92
+// Typelizer digest b6704d2de79466a9fa0b56f72e0c04dd
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -22,6 +22,7 @@ export type { default as CustomerGroup } from './CustomerGroup'
export type { default as Customer } from './Customer'
export type { default as DeliveryMethod } from './DeliveryMethod'
export type { default as DeliveryRate } from './DeliveryRate'
+export type { default as Delivery } from './Delivery'
export type { default as DeliveryZoneMember } from './DeliveryZoneMember'
export type { default as DeliveryZone } from './DeliveryZone'
export type { default as DigitalAsset } from './DigitalAsset'
@@ -68,6 +69,7 @@ export type { default as ReturnLineItem } from './ReturnLineItem'
export type { default as ReturnReason } from './ReturnReason'
export type { default as Return } from './Return'
export type { default as Seller } from './Seller'
+export type { default as ShippingLabelEvent } from './ShippingLabelEvent'
export type { default as State } from './State'
export type { default as StockLocation } from './StockLocation'
export type { default as StockReservation } from './StockReservation'
diff --git a/packages/sdk/src/zod/generated/Delivery.ts b/packages/sdk/src/zod/generated/Delivery.ts
new file mode 100644
index 0000000000..a5b18bb9f1
--- /dev/null
+++ b/packages/sdk/src/zod/generated/Delivery.ts
@@ -0,0 +1,16 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+
+export const DeliverySchema = z.object({
+ id: z.string(),
+ tracking_number: z.string(),
+ tracking_url: z.string().nullable(),
+ carrier: z.string().nullable(),
+ carrier_name: z.string().nullable(),
+ service: z.string().nullable(),
+ status: z.string(),
+ estimated_delivery_at: z.string().nullable(),
+ delivered_at: z.string().nullable(),
+});
+
+export type Delivery = z.infer<typeof DeliverySchema>;
diff --git a/packages/sdk/src/zod/generated/Fulfillment.ts b/packages/sdk/src/zod/generated/Fulfillment.ts
index 121cb2cc26..ac95c49585 100644
--- a/packages/sdk/src/zod/generated/Fulfillment.ts
+++ b/packages/sdk/src/zod/generated/Fulfillment.ts
@@ -1,5 +1,6 @@
// This file is auto-generated. Do not edit directly.
import { z } from 'zod';
+import { DeliverySchema } from './Delivery';
import { DeliveryMethodSchema } from './DeliveryMethod';
import { DeliveryRateSchema } from './DeliveryRate';
import { StockLocationSchema } from './StockLocation';
@@ -10,8 +11,6 @@ export const FulfillmentSchema = z.object({
number: z.string(),
tracking: z.string().nullable(),
tracking_url: z.string().nullable(),
- tracking_carrier: z.string().nullable(),
- tracking_carrier_name: z.string().nullable(),
pickup_point_data: z.record(z.string(), z.unknown()).nullable(),
selected_delivery_rate_id: z.string().nullable(),
cost: z.string().nullable(),
@@ -29,10 +28,9 @@ export const FulfillmentSchema = z.object({
status: z.string(),
fulfillment_type: z.string(),
fulfilled_at: z.string().nullable(),
- tracking_status: z.string().nullable(),
- estimated_delivery_at: z.string().nullable(),
delivered_at: z.string().nullable(),
items: z.array(z.object({ item_id: z.any() })),
+ deliveries: z.array(DeliverySchema),
delivery_method: DeliveryMethodSchema,
stock_location: StockLocationSchema,
delivery_rates: z.array(DeliveryRateSchema),
diff --git a/packages/sdk/src/zod/generated/ShippingLabelEvent.ts b/packages/sdk/src/zod/generated/ShippingLabelEvent.ts
new file mode 100644
index 0000000000..361be91b81
--- /dev/null
+++ b/packages/sdk/src/zod/generated/ShippingLabelEvent.ts
@@ -0,0 +1,28 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+
+export const ShippingLabelEventSchema = z.object({
+ id: z.string(),
+ source: z.string(),
+ status: z.string(),
+ carrier: z.string().nullable(),
+ service: z.string().nullable(),
+ tracking_number: z.string().nullable(),
+ currency: z.string().nullable(),
+ format: z.string().nullable(),
+ external_id: z.string().nullable(),
+ metadata: z.record(z.string(), z.unknown()),
+ refunded_at: z.string().nullable(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ owner_id: z.string(),
+ owner_type: z.string(),
+ carrier_name: z.string().nullable(),
+ cost: z.string(),
+ display_cost: z.string(),
+ integration_id: z.string().nullable(),
+ file_pending: z.boolean(),
+ download_url: z.string().nullable(),
+});
+
+export type ShippingLabelEvent = z.infer<typeof ShippingLabelEventSchema>;
diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.ts
index 9e59b5ea15..a3ee71a744 100644
--- a/packages/sdk/src/zod/generated/index.ts
+++ b/packages/sdk/src/zod/generated/index.ts
@@ -18,6 +18,7 @@ export { CurrencySchema, type Currency } from './Currency';
export { CustomFieldSchema, type CustomField } from './CustomField';
export { CustomerSchema, type Customer } from './Customer';
export { CustomerGroupSchema, type CustomerGroup } from './CustomerGroup';
+export { DeliverySchema, type Delivery } from './Delivery';
export { DeliveryMethodSchema, type DeliveryMethod } from './DeliveryMethod';
export { DeliveryRateSchema, type DeliveryRate } from './DeliveryRate';
export { DeliveryZoneSchema, type DeliveryZone } from './DeliveryZone';
@@ -66,6 +67,7 @@ export { ReturnSchema, type Return } from './Return';
export { ReturnLineItemSchema, type ReturnLineItem } from './ReturnLineItem';
export { ReturnReasonSchema, type ReturnReason } from './ReturnReason';
export { SellerSchema, type Seller } from './Seller';
+export { ShippingLabelEventSchema, type ShippingLabelEvent } from './ShippingLabelEvent';
export { StateSchema, type State } from './State';
export { StockLocationSchema, type StockLocation } from './StockLocation';
export { StockReservationSchema, type StockReservation } from './StockReservation';
diff --git a/packages/seller-sdk/src/seller-client.ts b/packages/seller-sdk/src/seller-client.ts
index 287eeabdf9..53849b693c 100644
--- a/packages/seller-sdk/src/seller-client.ts
+++ b/packages/seller-sdk/src/seller-client.ts
@@ -2,6 +2,7 @@ import type { ListParams, PaginatedResponse, RequestFn, RequestOptions } from '@
import { transformListParams } from '@spree/sdk-core'
import type {
AuthTokens,
+ Delivery,
DeliveryMethod,
DeliveryProfile,
DeliveryZone,
@@ -18,6 +19,7 @@ import type {
RequirementStatus,
RequirementSubmission,
SellerSummary,
+ ShippingLabel,
StockLocation,
TaxIdentifier,
TeamMember,
@@ -417,6 +419,148 @@ export class SellerClient {
...options,
body: params,
}),
+
+ /**
+ * The tracked consignments of one of the seller's parcels. A seller
+ * ships on manual methods, so tracking numbers are entered here by hand.
+ */
+ deliveries: {
+ list: (
+ orderId: string,
+ fulfillmentId: string,
+ options?: RequestOptions,
+ ): Promise<{ data: Delivery[] }> =>
+ this.request<{ data: Delivery[] }>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
+ options,
+ ),
+
+ get: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
+ options,
+ ),
+
+ create: (
+ orderId: string,
+ fulfillmentId: string,
+ params: {
+ tracking_number: string
+ carrier?: string
+ service?: string
+ tracking_url?: string
+ },
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'POST',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
+ { ...options, body: params },
+ ),
+
+ update: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ params: {
+ tracking_number?: string
+ carrier?: string
+ service?: string
+ tracking_url?: string
+ },
+ options?: RequestOptions,
+ ): Promise<Delivery> =>
+ this.request<Delivery>(
+ 'PATCH',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
+ { ...options, body: params },
+ ),
+
+ delete: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<void> =>
+ this.request<void>(
+ 'DELETE',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
+ options,
+ ),
+ },
+
+ /**
+ * Labels on the seller's own parcels. Sellers upload postage they bought
+ * elsewhere and print it back; buying and refunding need the operator's
+ * carrier account, so neither is offered here.
+ *
+ * Upload the file with `directUploads.create()` and pass the returned
+ * `signed_id` as `file`.
+ */
+ labels: {
+ list: (
+ orderId: string,
+ fulfillmentId: string,
+ options?: RequestOptions,
+ ): Promise<{ data: ShippingLabel[] }> =>
+ this.request<{ data: ShippingLabel[] }>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
+ options,
+ ),
+
+ get: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<ShippingLabel> =>
+ this.request<ShippingLabel>(
+ 'GET',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
+ options,
+ ),
+
+ create: (
+ orderId: string,
+ fulfillmentId: string,
+ params: {
+ file: string
+ tracking_number: string
+ carrier?: string
+ service?: string
+ cost?: string | number
+ currency?: string
+ file_format?: string
+ tracking_url?: string
+ },
+ options?: RequestOptions,
+ ): Promise<ShippingLabel> =>
+ this.request<ShippingLabel>(
+ 'POST',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
+ { ...options, body: params },
+ ),
+
+ delete: (
+ orderId: string,
+ fulfillmentId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<void> =>
+ this.request<void>(
+ 'DELETE',
+ `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
+ options,
+ ),
+ },
},
}
diff --git a/packages/seller-sdk/src/types/generated/Delivery.ts b/packages/seller-sdk/src/types/generated/Delivery.ts
new file mode 100644
index 0000000000..c5224b378a
--- /dev/null
+++ b/packages/seller-sdk/src/types/generated/Delivery.ts
@@ -0,0 +1,20 @@
+// Typelizer digest 419b9251277a1f6b303a310472c8629c
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type Delivery = {
+ id: string;
+ tracking_number: string;
+ tracking_url: string | null;
+ carrier: string | null;
+ carrier_name: string | null;
+ service: string | null;
+ status: string;
+ estimated_delivery_at: string | null;
+ delivered_at: string | null;
+ created_at: string;
+ updated_at: string;
+ shipping_label_id: string | null;
+}
+
+export default Delivery;
diff --git a/packages/seller-sdk/src/types/generated/Fulfillment.ts b/packages/seller-sdk/src/types/generated/Fulfillment.ts
index d2851e8e1f..ae8d658a2a 100644
--- a/packages/seller-sdk/src/types/generated/Fulfillment.ts
+++ b/packages/seller-sdk/src/types/generated/Fulfillment.ts
@@ -1,7 +1,7 @@
-// Typelizer digest 0f435cdfec74916fc1add4ec0f65dc9d
+// Typelizer digest 9cc1d3085ba0b3fb127c5ab079fc34ee
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {FulfillmentItem} from '@/types'
+import type {FulfillmentItem, Delivery, ShippingLabel} from '@/types'
type Fulfillment = {
id: string;
@@ -9,15 +9,16 @@ type Fulfillment = {
status: string;
tracking: string | null;
tracking_url: string | null;
- tracking_carrier: string | null;
- tracking_status: string | null;
fulfilled_at: string | null;
+ delivered_at: string | null;
created_at: string;
updated_at: string;
fulfillment_type: string | null;
delivery_method_name: string | null;
stock_location_name: string | null;
fulfillment_items: Array<FulfillmentItem>;
+ deliveries: Array<Delivery>;
+ labels: Array<ShippingLabel>;
}
export default Fulfillment;
diff --git a/packages/seller-sdk/src/types/generated/ShippingLabel.ts b/packages/seller-sdk/src/types/generated/ShippingLabel.ts
new file mode 100644
index 0000000000..381000b8ff
--- /dev/null
+++ b/packages/seller-sdk/src/types/generated/ShippingLabel.ts
@@ -0,0 +1,29 @@
+// Typelizer digest 40290dc0266f99196b6506a1da1e5b1a
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type ShippingLabel = {
+ id: string;
+ source: string;
+ status: string;
+ carrier: string | null;
+ service: string | null;
+ tracking_number: string | null;
+ currency: string | null;
+ format: string | null;
+ external_id: string | null;
+ metadata: Record<string, unknown>;
+ refunded_at: string | null;
+ created_at: string;
+ updated_at: string;
+ owner_id: string;
+ owner_type: string;
+ carrier_name: string | null;
+ cost: string;
+ display_cost: string;
+ integration_id: string | null;
+ file_pending: boolean;
+ download_url: string | null;
+}
+
+export default ShippingLabel;
diff --git a/packages/seller-sdk/src/types/generated/index.ts b/packages/seller-sdk/src/types/generated/index.ts
index 3e255389af..f6a8b8136e 100644
--- a/packages/seller-sdk/src/types/generated/index.ts
+++ b/packages/seller-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest cb722dd5503bea09c6f0b563802def41
+// Typelizer digest ac6e4a9037835131918bca4d055ee34e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -11,6 +11,7 @@ export type { default as Price } from './Price'
export type { default as DeliveryMethodRule } from './DeliveryMethodRule'
export type { default as DeliveryMethod } from './DeliveryMethod'
export type { default as DeliveryProfile } from './DeliveryProfile'
+export type { default as Delivery } from './Delivery'
export type { default as DeliveryZone } from './DeliveryZone'
export type { default as Export } from './Export'
export type { default as FulfillmentItem } from './FulfillmentItem'
@@ -30,6 +31,7 @@ export type { default as Profile } from './Profile'
export type { default as RequirementCustomField } from './RequirementCustomField'
export type { default as RequirementStatus } from './RequirementStatus'
export type { default as RequirementSubmission } from './RequirementSubmission'
+export type { default as ShippingLabel } from './ShippingLabel'
export type { default as StockLevel } from './StockLevel'
export type { default as StockLocation } from './StockLocation'
export type { default as TaxIdentifier } from './TaxIdentifier'
diff --git a/packages/seller-sdk/src/types/index.ts b/packages/seller-sdk/src/types/index.ts
index a04c091407..1e3ad0c4f7 100644
--- a/packages/seller-sdk/src/types/index.ts
+++ b/packages/seller-sdk/src/types/index.ts
@@ -32,3 +32,6 @@ export interface AuthTokens {
user: TeamMember
sellers: SellerSummary[]
}
+
+export type { default as Delivery } from './generated/Delivery'
+export type { default as ShippingLabel } from './generated/ShippingLabel'
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/deliveries_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/deliveries_controller.rb
new file mode 100644
index 0000000000..f1c5e68279
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/deliveries_controller.rb
@@ -0,0 +1,138 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ # The consignments of one fulfillment — a parcel each, or a freight
+ # PRO number covering several pallets — under
+ # /orders/:order_id/fulfillments/:fulfillment_id/deliveries.
+ #
+ # A delivery is born when a tracking number is attached, days before
+ # anything arrives, so POST means "this fulfillment went out as
+ # another consignment"; arrival is the mark_delivered transition on
+ # an existing row. The fulfillment-level mark_delivered stays beside
+ # it for parcels that have no delivery row at all.
+ class DeliveriesController < BaseController
+ before_action :set_resource, only: [:show, :update, :destroy, :mark_delivered]
+
+ # POST .../deliveries
+ def create
+ authorize!(:create, Spree::Delivery)
+
+ with_order_lock do
+ result = Spree.delivery_create_service.call(owner: @parent, **create_arguments)
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # PATCH .../deliveries/:id — correcting the number, carrier or link.
+ # A corrected number is a different parcel to the carrier, so its
+ # journey starts over.
+ def update
+ with_order_lock do
+ attributes = update_params.to_h
+ if attributes[:tracking_number].present? && attributes[:tracking_number].squish != @resource.tracking_number
+ attributes[:status] = 'pending'
+ end
+
+ if @resource.update(attributes)
+ render json: serialize_resource(@resource.reload)
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+ end
+
+ # DELETE .../deliveries/:id — 422 when a label minted it.
+ def destroy
+ with_order_lock do
+ result = Spree.delivery_destroy_service.call(delivery: @resource)
+
+ if result.success?
+ head :no_content
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # PATCH .../deliveries/:id/mark_delivered — staff saying this one
+ # consignment arrived; the fulfillment follows once every
+ # consignment has.
+ def mark_delivered
+ with_order_lock do
+ result = Spree.delivery_update_tracking_workflow.call(
+ delivery: @resource,
+ tracking_status: 'delivered',
+ delivered_at: mark_delivered_params[:delivered_at],
+ notify_customer: notify_customer?(mark_delivered_params[:notify_customer])
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Delivery
+ end
+
+ def serializer_class
+ Spree.api.admin_delivery_serializer
+ end
+
+ def parent_association
+ :deliveries
+ end
+
+ def collection_includes
+ [:shipping_label]
+ end
+
+ def set_parent
+ @order = current_store.orders.find_by_prefix_id!(params[:order_id])
+ @parent = @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+ end
+
+ def resource_permitted_attributes
+ [:tracking_number, :carrier, :service, :tracking_url]
+ end
+
+ def update_params
+ params.permit(*resource_permitted_attributes)
+ end
+
+ def create_arguments
+ permitted = params.permit(*resource_permitted_attributes)
+ {
+ tracking_number: permitted[:tracking_number],
+ carrier: permitted[:carrier],
+ service: permitted[:service],
+ tracking_url: permitted[:tracking_url]
+ }
+ end
+
+ def mark_delivered_params
+ @mark_delivered_params ||= params.permit(:delivered_at, :notify_customer)
+ end
+
+ # Only an explicit false suppresses the email.
+ def notify_customer?(value)
+ !ActiveModel::Type::Boolean.new.cast(value).equal?(false)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb
index 4a5fbe3350..df864baa8f 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb
@@ -81,12 +81,12 @@ module Spree
# PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/purchase_label
#
- # Buys the shipping label for a parcel that has not shipped yet, so
- # the merchant can print it, pack the box and hand it over before
- # anything tells the customer it shipped. Only providers that
- # produce labels accept this; failures are loud (422), unlike the
- # one-click fulfill path which degrades to "no label yet".
+ # @deprecated Labels are a nested resource since 6.0 —
+ # POST .../fulfillments/:id/labels buys one and answers with the
+ # label. This alias answers with the fulfillment for one release
+ # and is removed in 6.1.
def purchase_label
+ response.headers['Deprecation'] = 'true'
with_order_lock do
result = Spree.fulfillment_purchase_label_workflow.call(fulfillment: @resource)
@@ -171,8 +171,9 @@ module Spree
:shipments
end
- # State changes go through the dedicated `fulfill`/`cancel`/`resume`
- # member actions, not mass assignment.
+ # State changes go through the dedicated `fulfill`/`cancel` member
+ # actions, not mass assignment. `tracking` and `tracking_carrier`
+ # are the one-parcel shortcut onto the primary delivery.
def permitted_params
params.permit(:tracking, :tracking_carrier, :selected_delivery_rate_id, :stock_location_id)
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rb
new file mode 100644
index 0000000000..bb9dadf7a7
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rb
@@ -0,0 +1,159 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ # Shipping labels on one parcel — a fulfillment's outbound label
+ # under /orders/:order_id/fulfillments/:fulfillment_id/labels, a
+ # return's inbound label under /orders/:order_id/returns/:return_id/labels
+ # (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ #
+ # Creating one either buys it through the parcel's provider, or —
+ # when a +file+ is given — records a label the merchant bought
+ # elsewhere. A refund is a transition, so it is a PATCH member
+ # action; the only destroy is for an uploaded label, which has
+ # nothing to refund.
+ class LabelsController < BaseController
+ include ActiveStorage::SetCurrent
+
+ before_action :set_resource, only: [:show, :download, :refund, :destroy]
+
+ # A tampered signed id would otherwise surface as a 500.
+ rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_signature
+
+ # POST .../labels
+ def create
+ authorize!(:create, Spree::ShippingLabel)
+
+ with_order_lock do
+ result = if label_params[:file].present?
+ Spree.shipping_label_record_workflow.call(owner: @parent, **record_arguments)
+ else
+ Spree.shipping_label_purchase_workflow.call(owner: @parent)
+ end
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # GET .../labels/:id/download — streamed rather than redirected, so
+ # the label is never reachable without admin credentials. The
+ # carrier's copy is proxied only while the fetch is still pending.
+ def download
+ if @resource.file.attached?
+ send_data(
+ @resource.file.download,
+ filename: @resource.download_filename,
+ type: @resource.file.content_type || 'application/octet-stream',
+ disposition: 'attachment'
+ )
+ elsif @resource.file_pending?
+ redirect_to @resource.file_url, allow_other_host: true
+ else
+ render_error(
+ code: ERROR_CODES[:validation_error],
+ message: Spree.t('shipping_labels.errors.no_file_url'),
+ status: :unprocessable_content
+ )
+ end
+ end
+
+ # PATCH .../labels/:id/refund
+ def refund
+ with_order_lock do
+ result = Spree.shipping_label_refund_workflow.call(shipping_label: @resource)
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # DELETE .../labels/:id — uploaded labels only; a purchased label
+ # is refunded, never deleted, so the postage history stays honest.
+ def destroy
+ unless @resource.uploaded?
+ return render_error(
+ code: ERROR_CODES[:validation_error],
+ message: Spree.t('shipping_labels.errors.purchased_not_deletable'),
+ status: :unprocessable_content
+ )
+ end
+
+ with_order_lock do
+ ApplicationRecord.transaction do
+ @resource.delivery&.destroy!
+ @resource.destroy!
+ end
+ head :no_content
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::ShippingLabel
+ end
+
+ def serializer_class
+ Spree.api.admin_shipping_label_serializer
+ end
+
+ def parent_association
+ :shipping_labels
+ end
+
+ def collection_includes
+ [:integration, :delivery, { file_attachment: :blob }]
+ end
+
+ # The owner — fulfillment or return — is the parent the labels hang
+ # off; the order is fetched first so an owner id from another
+ # order can never resolve.
+ def set_parent
+ @order = current_store.orders.find_by_prefix_id!(params[:order_id])
+ @parent = if params[:return_id].present?
+ @order.returns.find_by_prefix_id!(params[:return_id])
+ else
+ @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+ end
+ end
+
+ READ_ACTIONS = %w[index show download].freeze
+
+ def read_actions
+ READ_ACTIONS
+ end
+
+ def label_params
+ @label_params ||= params.permit(:file, :tracking_number, :carrier, :service, :cost, :currency, :file_format, :tracking_url)
+ end
+
+ def record_arguments
+ {
+ file: label_params[:file],
+ tracking_number: label_params[:tracking_number],
+ carrier: label_params[:carrier],
+ service: label_params[:service],
+ cost: label_params[:cost],
+ currency: label_params[:currency],
+ file_format: label_params[:file_format],
+ tracking_url: label_params[:tracking_url]
+ }
+ end
+
+ def render_invalid_signature
+ render_error(code: ERROR_CODES[:parameter_invalid], message: Spree.t('shipping_labels.errors.file_required'), status: :unprocessable_content)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/deliveries_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/deliveries_controller.rb
new file mode 100644
index 0000000000..f79cc21a72
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/deliveries_controller.rb
@@ -0,0 +1,109 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ module Orders
+ # The consignments on a parcel the seller ships themselves. Rooted
+ # at the order fetched through `current_seller_orders`, so a
+ # fulfillment on somebody else's order reads as missing.
+ class DeliveriesController < Seller::BaseController
+ include Spree::Api::V3::OrderLock
+
+ scoped_resource :fulfillments
+
+ before_action :set_fulfillment
+ before_action :set_delivery, only: [:show, :update, :destroy]
+
+ def index
+ render json: { data: @fulfillment.deliveries.map { |delivery| serialize(delivery) } }
+ end
+
+ def show
+ render json: serialize(@delivery)
+ end
+
+ # POST /api/v3/seller/orders/:order_id/fulfillments/:fulfillment_id/deliveries
+ def create
+ authorize! :update, @fulfillment
+
+ with_order_lock do
+ result = Spree.delivery_create_service.call(
+ owner: @fulfillment,
+ tracking_number: delivery_params[:tracking_number],
+ carrier: delivery_params[:carrier],
+ service: delivery_params[:service],
+ tracking_url: delivery_params[:tracking_url]
+ )
+
+ if result.success?
+ render json: serialize(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # PATCH .../deliveries/:id
+ def update
+ authorize! :update, @fulfillment
+
+ with_order_lock do
+ attributes = delivery_params.to_h
+ if attributes[:tracking_number].present? && attributes[:tracking_number].squish != @delivery.tracking_number
+ attributes[:status] = 'pending'
+ end
+
+ if @delivery.update(attributes)
+ render json: serialize(@delivery.reload)
+ else
+ render_validation_error(@delivery.errors)
+ end
+ end
+ end
+
+ # DELETE .../deliveries/:id — 422 when a label minted it.
+ def destroy
+ authorize! :update, @fulfillment
+
+ with_order_lock do
+ result = Spree.delivery_destroy_service.call(delivery: @delivery)
+
+ if result.success?
+ head :no_content
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ protected
+
+ def read_actions
+ %w[index show]
+ end
+
+ private
+
+ def set_fulfillment
+ @order = current_seller_orders.find_by_prefix_id!(params[:order_id])
+ authorize! :show, @order
+ @fulfillment = @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+ end
+
+ def set_delivery
+ @delivery = @fulfillment.deliveries.find_by_prefix_id!(params[:id])
+ end
+
+ def delivery_params
+ @delivery_params ||= params.permit(:tracking_number, :carrier, :service, :tracking_url)
+ end
+
+ def serialize(delivery)
+ Spree.api.seller_delivery_serializer.new(delivery, params: { store: current_store }).to_h
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rb
new file mode 100644
index 0000000000..eb648ff453
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rb
@@ -0,0 +1,140 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ module Orders
+ # Labels on a parcel the seller ships themselves. Sellers fulfill on
+ # manual methods only, so they upload a label bought elsewhere and
+ # print it back — never purchase or refund, which need the
+ # operator's carrier account.
+ class LabelsController < Seller::BaseController
+ include Spree::Api::V3::OrderLock
+ include ActiveStorage::SetCurrent
+
+ scoped_resource :fulfillments
+
+ before_action :set_fulfillment
+ before_action :set_label, only: [:show, :download, :destroy]
+
+ rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_signature
+
+ def index
+ render json: { data: @fulfillment.shipping_labels.map { |label| serialize(label) } }
+ end
+
+ def show
+ render json: serialize(@label)
+ end
+
+ # POST /api/v3/seller/orders/:order_id/fulfillments/:fulfillment_id/labels
+ #
+ # Records an uploaded label; a request without a file is refused,
+ # since purchase is the operator's.
+ def create
+ authorize! :update, @fulfillment
+
+ if label_params[:file].blank?
+ return render_error(
+ code: ERROR_CODES[:validation_error],
+ message: Spree.t('shipping_labels.errors.file_required'),
+ status: :unprocessable_content
+ )
+ end
+
+ with_order_lock do
+ result = Spree.shipping_label_record_workflow.call(
+ owner: @fulfillment,
+ file: label_params[:file],
+ tracking_number: label_params[:tracking_number],
+ carrier: label_params[:carrier],
+ service: label_params[:service],
+ cost: label_params[:cost],
+ currency: label_params[:currency],
+ file_format: label_params[:file_format],
+ tracking_url: label_params[:tracking_url]
+ )
+
+ if result.success?
+ render json: serialize(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # GET .../labels/:id/download
+ def download
+ if @label.file.attached?
+ send_data(
+ @label.file.download,
+ filename: @label.download_filename,
+ type: @label.file.content_type || 'application/octet-stream',
+ disposition: 'attachment'
+ )
+ elsif @label.file_pending?
+ redirect_to @label.file_url, allow_other_host: true
+ else
+ render_error(
+ code: ERROR_CODES[:validation_error],
+ message: Spree.t('shipping_labels.errors.no_file_url'),
+ status: :unprocessable_content
+ )
+ end
+ end
+
+ # DELETE .../labels/:id — uploaded labels only.
+ def destroy
+ authorize! :update, @fulfillment
+
+ unless @label.uploaded?
+ return render_error(
+ code: ERROR_CODES[:validation_error],
+ message: Spree.t('shipping_labels.errors.purchased_not_deletable'),
+ status: :unprocessable_content
+ )
+ end
+
+ with_order_lock do
+ ApplicationRecord.transaction do
+ @label.delivery&.destroy!
+ @label.destroy!
+ end
+ head :no_content
+ end
+ end
+
+ protected
+
+ def read_actions
+ %w[index show download]
+ end
+
+ private
+
+ def set_fulfillment
+ @order = current_seller_orders.find_by_prefix_id!(params[:order_id])
+ authorize! :show, @order
+ @fulfillment = @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+ end
+
+ def set_label
+ @label = @fulfillment.shipping_labels.find_by_prefix_id!(params[:id])
+ end
+
+ def label_params
+ @label_params ||= params.permit(:file, :tracking_number, :carrier, :service, :cost, :currency, :file_format, :tracking_url)
+ end
+
+ def serialize(label)
+ Spree.api.seller_shipping_label_serializer.new(label, params: { store: current_store }).to_h
+ end
+
+ def render_invalid_signature
+ render_error(code: ERROR_CODES[:parameter_invalid], message: Spree.t('shipping_labels.errors.file_required'), status: :unprocessable_content)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/returns_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders/returns_controller.rb
index 905cc2c0cf..eb8226bd4a 100644
--- a/spree/api/app/controllers/spree/api/v3/store/orders/returns_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/orders/returns_controller.rb
@@ -11,6 +11,33 @@ module Spree
# Whether a customer may open a return at all is store policy, and
# belongs in a `returns.create.validate` hook rather than here.
class ReturnsController < Store::ResourceController
+ # Re-declaring the filter replaces the inherited options, so the
+ # standard actions are listed alongside the label download.
+ before_action :set_resource, only: [:show, :update, :destroy, :label]
+
+ # GET /api/v3/store/orders/:order_id/returns/:id/label
+ #
+ # The customer's return label, streamed to whoever owns the order.
+ # The label row itself is never serialized to the storefront —
+ # its cost and provider ids are merchant data — only the file.
+ def label
+ shipping_label = @resource.active_shipping_label
+ return head :not_found if shipping_label.nil?
+
+ if shipping_label.file.attached?
+ send_data(
+ shipping_label.file.download,
+ filename: shipping_label.download_filename,
+ type: shipping_label.file.content_type || 'application/octet-stream',
+ disposition: 'attachment'
+ )
+ elsif shipping_label.file_pending?
+ redirect_to shipping_label.file_url, allow_other_host: true
+ else
+ head :not_found
+ end
+ end
+
def create
result = Spree.return_create_workflow.call(
order: @parent,
@@ -51,6 +78,10 @@ module Spree
@resource = find_resource
end
+ def read_actions
+ %w[index show label]
+ end
+
# The order is the customer's own — by JWT or by guest token,
# mirroring Store::OrdersController.
def set_parent
diff --git a/spree/api/app/controllers/spree/api/v3/webhooks/fulfillments_controller.rb b/spree/api/app/controllers/spree/api/v3/webhooks/fulfillments_controller.rb
index 17fccafd8b..a7c25197d5 100644
--- a/spree/api/app/controllers/spree/api/v3/webhooks/fulfillments_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/webhooks/fulfillments_controller.rb
@@ -36,11 +36,11 @@ module Spree
event = integration.parse_webhook_event(request.raw_post, request.headers)
return head :ok if event.nil?
- fulfillment = find_fulfillment(event[:tracking_code])
- return head :ok if fulfillment.nil?
+ delivery = find_delivery(event[:tracking_code])
+ return head :ok if delivery.nil?
- Spree.fulfillment_update_tracking_workflow.call(
- fulfillment: fulfillment,
+ Spree.delivery_update_tracking_workflow.call(
+ delivery: delivery,
**event.except(:tracking_code)
)
@@ -58,16 +58,16 @@ module Spree
# Scoped to the store the verified integration belongs to — a
# tracking code can never address another tenant's parcel — and to
- # parcels that shipped, so a recycled code cannot reopen an old one.
- def find_fulfillment(tracking_code)
+ # consignments whose parcel was not canceled, so a recycled code
+ # cannot reopen an old one. The newest wins when a code was reused.
+ def find_delivery(tracking_code)
return if tracking_code.blank?
- Spree::Fulfillment.
- joins(:order).merge(current_store.orders).
- where(tracking: tracking_code).
- not_canceled.
- reverse_chronological.
- first
+ current_store.deliveries.
+ where(tracking_number: tracking_code).
+ order(created_at: :desc, id: :desc).
+ includes(:owner).
+ detect { |delivery| !delivery.owner.try(:canceled?) }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/delivery_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/delivery_serializer.rb
new file mode 100644
index 0000000000..53f4539d0e
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/delivery_serializer.rb
@@ -0,0 +1,20 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ class DeliverySerializer < V3::DeliverySerializer
+ typelize shipping_label_id: [:string, nullable: true],
+ details: ['Record<string, unknown>', nullable: true]
+
+ # The raw carrier payload — scan history, signature, failure reason.
+ # Operational detail, so admin-only.
+ attributes :details, created_at: :iso8601, updated_at: :iso8601
+
+ attribute :shipping_label_id do |delivery|
+ delivery.shipping_label&.prefixed_id
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb
index a07058f9d4..4a37d7c9f3 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb
@@ -13,7 +13,6 @@ module Spree
tax_total: [:string, nullable: false], display_tax_total: [:string, nullable: false]
typelize metadata: 'Record<string, unknown>',
- tracking_details: ['Record<string, unknown>', nullable: true],
documents: "Array<{ kind: string; url: string }>",
provider_generates_labels: :boolean,
order_id: [:string, nullable: true],
@@ -21,9 +20,7 @@ module Spree
adjustment_total: :string,
pre_tax_amount: :string
- # The raw carrier payload — scan history, signature, failure reason.
- # Operational detail, so admin-only.
- attributes :metadata, :tracking_details, :adjustment_total, :pre_tax_amount,
+ attributes :metadata, :adjustment_total, :pre_tax_amount,
created_at: :iso8601, updated_at: :iso8601
attribute :order_id do |fulfillment|
@@ -34,17 +31,23 @@ module Spree
fulfillment.stock_location&.prefixed_id
end
- # Label PDFs and customs forms the provider produced for this parcel.
+ # Customs forms and other paperwork the provider produced beside the
+ # label; the labels themselves are listed under +labels+.
attribute :documents do |fulfillment|
fulfillment.provider.documents(fulfillment)
end
+ # Every label bought or uploaded for this parcel, refunded ones
+ # included — the postage history of the box.
+ many :shipping_labels, key: :labels, resource: proc { Spree.api.admin_shipping_label_serializer }
+
# Whether the buy-label step applies to this parcel's provider.
attribute :provider_generates_labels do |fulfillment|
fulfillment.provider.class.generates_labels?
end
# Override inherited associations to use admin serializers
+ many :deliveries, resource: proc { Spree.api.admin_delivery_serializer }
one :delivery_method, resource: proc { Spree.api.admin_delivery_method_serializer }, if: proc { expand?('delivery_method') }
one :stock_location, resource: proc { Spree.api.admin_stock_location_serializer }, if: proc { expand?('stock_location') }
many :delivery_rates, resource: proc { Spree.api.admin_delivery_rate_serializer }, if: proc { expand?('delivery_rates') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/shipping_label_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/shipping_label_serializer.rb
new file mode 100644
index 0000000000..f336913539
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/shipping_label_serializer.rb
@@ -0,0 +1,84 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # A bought or uploaded carrier label. Admin-only by design: the cost is
+ # what the merchant paid the carrier, and the ids are the provider's.
+ # The file is streamed through +download_url+, never linked to storage.
+ class ShippingLabelSerializer < V3::BaseSerializer
+ typelize owner_id: :string,
+ owner_type: :string,
+ source: :string,
+ status: :string,
+ carrier: [:string, nullable: true],
+ carrier_name: [:string, nullable: true],
+ service: [:string, nullable: true],
+ tracking_number: [:string, nullable: true],
+ cost: :string,
+ currency: [:string, nullable: true],
+ display_cost: :string,
+ format: [:string, nullable: true],
+ external_id: [:string, nullable: true],
+ integration_id: [:string, nullable: true],
+ download_url: [:string, nullable: true],
+ file_pending: :boolean,
+ refunded_at: [:string, nullable: true],
+ metadata: 'Record<string, unknown>'
+
+ attributes :source, :status, :carrier, :service, :tracking_number, :currency, :format,
+ :external_id, :metadata, refunded_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+ attribute :owner_id do |shipping_label|
+ shipping_label.owner&.prefixed_id
+ end
+
+ attribute :owner_type do |shipping_label|
+ shipping_label.owner_type == 'Spree::Return' ? 'return' : 'fulfillment'
+ end
+
+ attribute :carrier_name do |shipping_label|
+ next if shipping_label.carrier.blank?
+
+ Spree.tracking_carriers.dig(shipping_label.carrier, :name) || shipping_label.carrier
+ end
+
+ attribute :cost do |shipping_label|
+ shipping_label.cost.to_s
+ end
+
+ attribute :display_cost do |shipping_label|
+ shipping_label.display_cost.to_s
+ end
+
+ attribute :integration_id do |shipping_label|
+ shipping_label.integration&.prefixed_id
+ end
+
+ # Whether the file is still being fetched from the carrier; the
+ # download proxies the provider's copy meanwhile.
+ attribute :file_pending do |shipping_label|
+ shipping_label.file_pending?
+ end
+
+ # Our own endpoint rather than a storage URL: the controller streams
+ # the bytes, so admin auth runs on every print.
+ attribute :download_url do |shipping_label|
+ next nil unless shipping_label.file.attached? || shipping_label.file_pending?
+
+ helpers = Spree::Core::Engine.routes.url_helpers
+ owner = shipping_label.owner
+ if owner.is_a?(Spree::Return)
+ helpers.download_api_v3_admin_order_return_label_path(
+ order_id: owner.order.prefixed_id, return_id: owner.prefixed_id, id: shipping_label.prefixed_id
+ )
+ else
+ helpers.download_api_v3_admin_order_fulfillment_label_path(
+ order_id: owner.order&.prefixed_id, fulfillment_id: owner.prefixed_id, id: shipping_label.prefixed_id
+ )
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/delivery_serializer.rb b/spree/api/app/serializers/spree/api/v3/delivery_serializer.rb
new file mode 100644
index 0000000000..021f3b2750
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/delivery_serializer.rb
@@ -0,0 +1,23 @@
+module Spree
+ module Api
+ module V3
+ # One consignment's carrier journey — the customer's "where is my
+ # parcel" answer, so it sits on the public serializer beside the
+ # fulfillment's tracking summary.
+ class DeliverySerializer < BaseSerializer
+ typelize tracking_number: :string,
+ tracking_url: [:string, nullable: true],
+ carrier: [:string, nullable: true],
+ carrier_name: [:string, nullable: true],
+ service: [:string, nullable: true],
+ status: :string,
+ estimated_delivery_at: [:string, nullable: true],
+ delivered_at: [:string, nullable: true]
+
+ attributes :tracking_number, :tracking_url, :carrier, :carrier_name, :service, :status
+
+ attributes estimated_delivery_at: :iso8601, delivered_at: :iso8601
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/fulfillment_serializer.rb b/spree/api/app/serializers/spree/api/v3/fulfillment_serializer.rb
index b0c211e1ba..79fcd73d34 100644
--- a/spree/api/app/serializers/spree/api/v3/fulfillment_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/fulfillment_serializer.rb
@@ -5,10 +5,6 @@ module Spree
typelize number: :string, status: :string, fulfillment_type: :string,
tracking: [:string, nullable: true],
tracking_url: [:string, nullable: true], fulfilled_at: [:string, nullable: true],
- tracking_status: [:string, nullable: true],
- tracking_carrier: [:string, nullable: true],
- tracking_carrier_name: [:string, nullable: true],
- estimated_delivery_at: [:string, nullable: true],
delivered_at: [:string, nullable: true],
cost: [:string, nullable: true], display_cost: [:string, nullable: true],
total: [:string, nullable: true], display_total: [:string, nullable: true],
@@ -20,8 +16,9 @@ module Spree
pickup_point_data: ['Record<string, unknown>', nullable: true],
selected_delivery_rate_id: [:string, nullable: true]
- attributes :number, :tracking, :tracking_url, :tracking_carrier, :tracking_carrier_name,
- :pickup_point_data, :selected_delivery_rate_id
+ # +tracking+ and +tracking_url+ summarize the primary delivery; every
+ # consignment is listed under +deliveries+.
+ attributes :number, :tracking, :tracking_url, :pickup_point_data, :selected_delivery_rate_id
# Nulled for gated (prices_hidden) guests so a fulfillment can't leak the
# shipping/tax amounts the cart/order totals already withhold.
@@ -40,12 +37,7 @@ module Spree
fulfillment.fulfillment_type.presence || (fulfillment.digital? ? 'digital' : 'shipping')
end
- attributes fulfilled_at: :iso8601
-
- # Where the parcel is, as the carrier last reported it — the customer's
- # question, so it belongs on the public serializer alongside tracking.
- attributes :tracking_status
- attributes estimated_delivery_at: :iso8601, delivered_at: :iso8601
+ attributes fulfilled_at: :iso8601, delivered_at: :iso8601
# Which items (and how many) are in this fulfillment.
# A line item can be split across fulfillments with different quantities.
@@ -61,6 +53,9 @@ module Spree
end
end
+ # Where each parcel is, as the carrier last reported it — the
+ # customer's question, so always embedded.
+ many :deliveries, resource: proc { Spree.api.delivery_serializer }
one :delivery_method, resource: proc { Spree.api.delivery_method_serializer }
one :stock_location, resource: proc { Spree.api.stock_location_serializer }
many :delivery_rates, resource: proc { Spree.api.delivery_rate_serializer }
diff --git a/spree/api/app/serializers/spree/api/v3/seller/delivery_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/delivery_serializer.rb
new file mode 100644
index 0000000000..1891852ebf
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/delivery_serializer.rb
@@ -0,0 +1,17 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ class DeliverySerializer < V3::DeliverySerializer
+ typelize shipping_label_id: [:string, nullable: true]
+
+ attributes created_at: :iso8601, updated_at: :iso8601
+
+ attribute :shipping_label_id do |delivery|
+ delivery.shipping_label&.prefixed_id
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb
index 17c6dca8d8..705b2d300a 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb
@@ -13,15 +13,14 @@ module Spree
status: :string,
tracking: [:string, nullable: true],
tracking_url: [:string, nullable: true],
- tracking_carrier: [:string, nullable: true],
- tracking_status: [:string, nullable: true],
fulfillment_type: [:string, nullable: true],
delivery_method_name: [:string, nullable: true],
stock_location_name: [:string, nullable: true]
- attributes :number, :status, :tracking, :tracking_url, :tracking_carrier,
- :tracking_status,
- fulfilled_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+ attributes :number, :status, :tracking, :tracking_url,
+ fulfilled_at: :iso8601, delivered_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+ typelize delivered_at: [:string, nullable: true]
# Null until the parcel actually ships, which is most of its life.
typelize fulfilled_at: [:string, nullable: true]
@@ -46,6 +45,11 @@ module Spree
# else's. These are the persisted fulfillment items, so they say so.
many :fulfillment_items,
resource: proc { Spree.api.seller_fulfillment_item_serializer }
+
+ # The consignments and labels on this parcel — what a seller adds
+ # when they ship it themselves.
+ many :deliveries, resource: proc { Spree.api.seller_delivery_serializer }
+ many :shipping_labels, key: :labels, resource: proc { Spree.api.seller_shipping_label_serializer }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/shipping_label_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/shipping_label_serializer.rb
new file mode 100644
index 0000000000..dac159dffe
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/shipping_label_serializer.rb
@@ -0,0 +1,21 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # The seller's view of a label on one of their parcels — the same
+ # facts the operator sees, downloaded through the seller branch.
+ class ShippingLabelSerializer < Admin::ShippingLabelSerializer
+ attribute :download_url do |shipping_label|
+ next nil unless shipping_label.file.attached? || shipping_label.file_pending?
+
+ Spree::Core::Engine.routes.url_helpers.download_api_v3_seller_order_fulfillment_label_path(
+ order_id: shipping_label.owner.order&.prefixed_id,
+ fulfillment_id: shipping_label.owner.prefixed_id,
+ id: shipping_label.prefixed_id
+ )
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/shipping_label_event_serializer.rb b/spree/api/app/serializers/spree/api/v3/shipping_label_event_serializer.rb
new file mode 100644
index 0000000000..827548c0b2
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/shipping_label_event_serializer.rb
@@ -0,0 +1,11 @@
+module Spree
+ module Api
+ module V3
+ # Payload of the shipping_label.* events. Labels have no storefront
+ # serializer — a customer never sees one — so the event shape is
+ # declared here rather than found by convention.
+ class ShippingLabelEventSerializer < Admin::ShippingLabelSerializer
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 4662799d61..9295f68fe9 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -71,7 +71,11 @@ Spree::Core::Engine.add_routes do
resources :orders, only: [:show] do
# Customer self-service returns — opening and viewing only; the
# merchant approves, receives and refunds through the Admin API.
- resources :returns, only: [:index, :show, :create], controller: 'orders/returns'
+ resources :returns, only: [:index, :show, :create], controller: 'orders/returns' do
+ member do
+ get :label
+ end
+ end
resources :claims, only: [:index, :show, :create], controller: 'orders/claims'
# Read-only — the registration frozen onto the order at completion.
resource :tax_identifier, only: [:show], controller: 'orders/tax_identifiers'
@@ -718,11 +722,24 @@ Spree::Core::Engine.add_routes do
resources :fulfillments, controller: 'orders/fulfillments', only: [:index, :show, :create, :update] do
member do
patch :fulfill
+ # Deprecated alias of POST .../labels — removed in 6.1.
patch :purchase_label
patch :mark_delivered
patch :cancel
patch :split
end
+
+ resources :labels, controller: 'orders/labels', only: [:index, :show, :create, :destroy] do
+ member do
+ get :download
+ patch :refund
+ end
+ end
+ resources :deliveries, controller: 'orders/deliveries', only: [:index, :show, :create, :update, :destroy] do
+ member do
+ patch :mark_delivered
+ end
+ end
end
resources :returns, controller: 'orders/returns', only: [:index, :show, :create, :update] do
member do
@@ -731,6 +748,13 @@ Spree::Core::Engine.add_routes do
patch :refund
patch :cancel
end
+
+ resources :labels, controller: 'orders/labels', only: [:index, :show, :create, :destroy] do
+ member do
+ get :download
+ patch :refund
+ end
+ end
end
resources :exchanges, controller: 'orders/exchanges', only: [:index, :show, :create, :update] do
member do
@@ -845,6 +869,13 @@ Spree::Core::Engine.add_routes do
member do
patch :fulfill
end
+
+ resources :deliveries, controller: 'orders/deliveries', only: [:index, :show, :create, :update, :destroy]
+ resources :labels, controller: 'orders/labels', only: [:index, :show, :create, :destroy] do
+ member do
+ get :download
+ end
+ end
end
end
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index efa282ea7f..e608137638 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -25,6 +25,7 @@ module Spree
store_credit_serializer: 'Spree::Api::V3::StoreCreditSerializer',
shipment_serializer: 'Spree::Api::V3::FulfillmentSerializer',
fulfillment_serializer: 'Spree::Api::V3::FulfillmentSerializer',
+ delivery_serializer: 'Spree::Api::V3::DeliverySerializer',
address_serializer: 'Spree::Api::V3::AddressSerializer',
customer_serializer: 'Spree::Api::V3::CustomerSerializer',
customer_group_serializer: 'Spree::Api::V3::CustomerGroupSerializer',
@@ -132,6 +133,8 @@ module Spree
admin_shipment_serializer: 'Spree::Api::V3::Admin::FulfillmentSerializer',
admin_fulfillment_serializer: 'Spree::Api::V3::Admin::FulfillmentSerializer',
admin_fulfillment_item_serializer: 'Spree::Api::V3::Admin::FulfillmentItemSerializer',
+ admin_delivery_serializer: 'Spree::Api::V3::Admin::DeliverySerializer',
+ admin_shipping_label_serializer: 'Spree::Api::V3::Admin::ShippingLabelSerializer',
admin_gift_card_serializer: 'Spree::Api::V3::Admin::GiftCardSerializer',
admin_gift_card_batch_serializer: 'Spree::Api::V3::Admin::GiftCardBatchSerializer',
admin_payment_serializer: 'Spree::Api::V3::Admin::PaymentSerializer',
@@ -185,6 +188,8 @@ module Spree
seller_order_line_item_serializer: 'Spree::Api::V3::Seller::OrderLineItemSerializer',
seller_fulfillment_serializer: 'Spree::Api::V3::Seller::FulfillmentSerializer',
seller_fulfillment_item_serializer: 'Spree::Api::V3::Seller::FulfillmentItemSerializer',
+ seller_delivery_serializer: 'Spree::Api::V3::Seller::DeliverySerializer',
+ seller_shipping_label_serializer: 'Spree::Api::V3::Seller::ShippingLabelSerializer',
seller_stock_location_serializer: 'Spree::Api::V3::Seller::StockLocationSerializer',
seller_requirement_custom_field_serializer: 'Spree::Api::V3::Seller::RequirementCustomFieldSerializer',
seller_tax_identifier_serializer: 'Spree::Api::V3::Seller::TaxIdentifierSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb
new file mode 100644
index 0000000000..e279179b55
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb
@@ -0,0 +1,135 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::DeliveriesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:fulfillment) { order.fulfillments.first }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'lists the consignments of the fulfillment' do
+ get :index, params: { order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].first['tracking_number']).to eq(fulfillment.tracking)
+ expect(json_response['data'].first['status']).to eq('pending')
+ end
+ end
+
+ describe 'POST #create' do
+ it 'records another consignment on the fulfillment' do
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ tracking_number: '1Z879E930346834440'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['id']).to start_with('dlv_')
+ expect(json_response['carrier']).to eq('ups')
+ expect(json_response['carrier_name']).to eq('UPS')
+ expect(fulfillment.reload.deliveries.count).to eq(2)
+ end
+
+ # A forwarder's PRO number belongs to a carrier the registry never heard
+ # of and must still be enterable.
+ it 'takes a free-text carrier and a pasted tracking link' do
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ tracking_number: 'PRO-4471923', carrier: 'Estes Freight',
+ tracking_url: 'https://forwarder.example/PRO-4471923'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['carrier']).to eq('Estes Freight')
+ expect(json_response['tracking_url']).to eq('https://forwarder.example/PRO-4471923')
+ end
+
+ it 'refuses a duplicate number on the same fulfillment' do
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ tracking_number: fulfillment.tracking
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'PATCH #update' do
+ it 'corrects the number and starts the carrier journey over' do
+ delivery = fulfillment.deliveries.first
+ delivery.update_columns(status: 'in_transit')
+
+ patch :update, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ id: delivery.prefixed_id, tracking_number: 'CORRECTED-1'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['tracking_number']).to eq('CORRECTED-1')
+ expect(json_response['status']).to eq('pending')
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ it 'removes a hand-entered consignment' do
+ delivery = fulfillment.deliveries.first
+
+ delete :destroy, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: delivery.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(Spree::Delivery.exists?(delivery.id)).to be(false)
+ end
+
+ it 'refuses one a label minted' do
+ label = create(:shipping_label, :with_delivery, owner: fulfillment)
+
+ delete :destroy, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.delivery.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'PATCH #mark_delivered' do
+ before { Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment) }
+
+ it 'closes the consignment and rolls the fulfillment up' do
+ patch :mark_delivered, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ id: fulfillment.deliveries.first.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['status']).to eq('delivered')
+ expect(fulfillment.reload).to be_delivered
+ end
+
+ it 'leaves the fulfillment fulfilled while a sibling is still travelling' do
+ Spree::Deliveries::Create.new.call(owner: fulfillment, tracking_number: 'BOX-2')
+
+ patch :mark_delivered, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ id: fulfillment.deliveries.first.prefixed_id
+ }, as: :json
+
+ expect(fulfillment.reload).to be_fulfilled
+ end
+ end
+
+ # Every lookup runs through the store's own order, so an id from elsewhere
+ # is missing rather than denied.
+ it 'answers 404 for a fulfillment on another store order' do
+ other = create(:order_ready_to_ship, store: create(:store))
+
+ get :index, params: { order_id: other.prefixed_id, fulfillment_id: other.fulfillments.first.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb
index b597dcff88..1b393333fa 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb
@@ -1,4 +1,5 @@
require 'spec_helper'
+require 'spree/testing_support/label_provider'
RSpec.describe Spree::Api::V3::Admin::Orders::FulfillmentsController, type: :controller do
render_views
@@ -301,43 +302,30 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FulfillmentsController, type: :con
end
end
- describe 'PATCH #purchase_label' do
- let(:label_provider_class) do
- Class.new(Spree::FulfillmentProvider::Base) do
- def self.generates_labels?
- true
- end
-
- def create_fulfillment(_fulfillment)
- { tracking_number: 'LBL-123', tracking_url: 'https://carrier.example/t/1' }
- end
-
- def documents(_fulfillment)
- [{ kind: 'label', url: 'https://carrier.example/label.pdf' }]
- end
- end
- end
-
+ describe 'PATCH #purchase_label (deprecated alias of POST labels)' do
before do
- shipment.update_column(:tracking, nil)
- allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(label_provider_class.new)
+ Spree::TestingSupport::LabelProvider.reset!
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
+ shipment.deliveries.destroy_all
end
- it 'buys the label without fulfilling' do
+ it 'buys the label without fulfilling and answers with the fulfillment' do
patch :purchase_label, params: { order_id: order.prefixed_id, id: shipment.prefixed_id }, as: :json
expect(response).to have_http_status(:ok)
+ expect(response.headers['Deprecation']).to eq('true')
expect(json_response['status']).to eq('unfulfilled')
- expect(json_response['tracking']).to eq('LBL-123')
- expect(json_response['documents']).to eq([{ 'kind' => 'label', 'url' => 'https://carrier.example/label.pdf' }])
+ expect(json_response['tracking']).to eq('1Z879E930346834440')
+ expect(json_response['labels'].first['source']).to eq('purchased')
end
it 'fails loudly when the provider cannot produce a label' do
- allow_any_instance_of(label_provider_class).to receive(:create_fulfillment).and_return({})
+ allow_any_instance_of(Spree::TestingSupport::LabelProvider).to receive(:purchase_label).and_return(nil)
patch :purchase_label, params: { order_id: order.prefixed_id, id: shipment.prefixed_id }, as: :json
- expect(response).to have_http_status(:unprocessable_entity)
+ expect(response).to have_http_status(:unprocessable_content)
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rb
new file mode 100644
index 0000000000..18b921e9ed
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rb
@@ -0,0 +1,175 @@
+require 'spec_helper'
+require 'spree/testing_support/label_provider'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::LabelsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:fulfillment) { order.fulfillments.first }
+ let(:signed_file) do
+ ActiveStorage::Blob.create_and_upload!(
+ io: StringIO.new("%PDF-1.4\n%label\n"), filename: 'label.pdf', content_type: 'application/pdf',
+ service_name: Spree.private_storage_service_name
+ ).signed_id
+ end
+
+ before do
+ request.headers.merge!(headers)
+ Spree::TestingSupport::LabelProvider.reset!
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
+ end
+
+ describe 'POST #create' do
+ context 'buying through the provider' do
+ before do
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
+ fulfillment.deliveries.destroy_all
+ end
+
+ it 'buys the label and answers with it' do
+ post :create, params: { order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['id']).to start_with('lbl_')
+ expect(json_response['source']).to eq('purchased')
+ expect(json_response['status']).to eq('purchased')
+ expect(json_response['cost']).to eq('7.25')
+ expect(json_response['owner_type']).to eq('fulfillment')
+ expect(json_response['download_url']).to include('/labels/')
+ expect(fulfillment.reload.tracking).to eq('1Z879E930346834440')
+ end
+
+ it 'refuses a second label while one is active' do
+ post :create, params: { order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id }, as: :json
+ post :create, params: { order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'recording an uploaded label' do
+ before { fulfillment.deliveries.destroy_all }
+
+ it 'records the file, the cost and the consignment' do
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ file: signed_file, tracking_number: '1Z879E930346834440', cost: '6.50', currency: 'USD'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['source']).to eq('uploaded')
+ expect(json_response['display_cost']).to eq('$6.50')
+ expect(fulfillment.reload.tracking).to eq('1Z879E930346834440')
+ end
+
+ it 'refuses an upload with no tracking number' do
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, file: signed_file
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+ end
+
+ describe 'GET #download' do
+ it 'streams the stored file rather than redirecting to storage' do
+ label = create(:shipping_label, :with_file, owner: fulfillment)
+
+ get :download, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }
+
+ expect(response).to have_http_status(:ok)
+ expect(response.headers['Content-Disposition']).to include('attachment')
+ expect(response.body).to include('%PDF')
+ end
+
+ it 'proxies the carrier copy while the fetch is pending' do
+ label = create(:shipping_label, owner: fulfillment, metadata: { 'file_url' => 'https://carrier.example/l.pdf' })
+
+ get :download, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }
+
+ expect(response).to redirect_to('https://carrier.example/l.pdf')
+ end
+ end
+
+ describe 'PATCH #refund' do
+ before do
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
+ end
+
+ it 'refunds a purchased label and drops its unshipped consignment' do
+ label = create(:shipping_label, :with_delivery, owner: fulfillment)
+
+ patch :refund, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['status']).to eq('refunded')
+ expect(label.reload.delivery).to be_nil
+ end
+
+ it 'refuses an uploaded label' do
+ label = create(:shipping_label, :uploaded, owner: fulfillment)
+
+ patch :refund, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ it 'deletes an uploaded label and its consignment' do
+ label = create(:shipping_label, :uploaded, :with_delivery, owner: fulfillment)
+
+ delete :destroy, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(Spree::ShippingLabel.exists?(label.id)).to be(false)
+ end
+
+ it 'refuses to delete a purchased label' do
+ label = create(:shipping_label, owner: fulfillment)
+
+ delete :destroy, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'return labels' do
+ let(:return_record) { create(:return, order: create(:shipped_order, store: store)) }
+
+ it 'records an uploaded label on the return' do
+ post :create, params: {
+ order_id: return_record.order.prefixed_id, return_id: return_record.prefixed_id,
+ file: signed_file, tracking_number: 'RET-1'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['owner_type']).to eq('return')
+ expect(json_response['download_url']).to include('/returns/')
+ expect(return_record.reload.active_shipping_label).to be_present
+ end
+ end
+
+ it 'answers 404 for a fulfillment on another store order' do
+ other = create(:order_ready_to_ship, store: create(:store))
+
+ get :index, params: { order_id: other.prefixed_id, fulfillment_id: other.fulfillments.first.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/deliveries_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/deliveries_controller_spec.rb
new file mode 100644
index 0000000000..5eb8881916
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/deliveries_controller_spec.rb
@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::Orders::DeliveriesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ let!(:order) { create(:order_ready_to_ship, store: store, seller: seller) }
+ let(:fulfillment) { order.fulfillments.first }
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ end
+
+ it 'lists and records consignments on the seller own parcel' do
+ get :index, params: { order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id }, as: :json
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].first['tracking_number']).to eq(fulfillment.tracking)
+
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, tracking_number: 'SELLER-1'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(fulfillment.reload.deliveries.count).to eq(2)
+ end
+
+ it 'corrects and removes a consignment' do
+ delivery = fulfillment.deliveries.first
+
+ patch :update, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ id: delivery.prefixed_id, tracking_number: 'FIXED-1'
+ }, as: :json
+ expect(json_response['tracking_number']).to eq('FIXED-1')
+
+ delete :destroy, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: delivery.prefixed_id
+ }, as: :json
+ expect(response).to have_http_status(:no_content)
+ end
+
+ # A fulfillment on somebody else's order reads as missing rather than
+ # denied, whatever id the seller sends.
+ it 'answers 404 for another seller order' do
+ other = create(:order_ready_to_ship, store: store)
+
+ get :index, params: { order_id: other.prefixed_id, fulfillment_id: other.fulfillments.first.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rb
new file mode 100644
index 0000000000..5bb67d3050
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rb
@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::Orders::LabelsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ let!(:order) { create(:order_ready_to_ship, store: store, seller: seller) }
+ let(:fulfillment) { order.fulfillments.first }
+ let(:signed_file) do
+ ActiveStorage::Blob.create_and_upload!(
+ io: StringIO.new("%PDF-1.4\n%label\n"), filename: 'label.pdf', content_type: 'application/pdf',
+ service_name: Spree.private_storage_service_name
+ ).signed_id
+ end
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ fulfillment.deliveries.destroy_all
+ end
+
+ it 'records a label the seller bought elsewhere' do
+ post :create, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,
+ file: signed_file, tracking_number: 'SELLER-LBL-1', cost: '4.20', currency: 'USD'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['source']).to eq('uploaded')
+ expect(json_response['download_url']).to include('/seller/')
+ expect(fulfillment.reload.tracking).to eq('SELLER-LBL-1')
+ end
+
+ # Buying and refunding need the operator's carrier account, so the seller
+ # branch offers neither: a request with no file has nothing to record.
+ it 'refuses a purchase request' do
+ post :create, params: { order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(fulfillment.reload.shipping_labels).to be_empty
+ end
+
+ it 'exposes no refund action at all' do
+ expect(described_class.action_methods).not_to include('refund')
+ expect(Spree::Core::Engine.routes.routes.map { |route| route.path.spec.to_s }).
+ not_to include(a_string_matching(%r{/seller/.*labels/.*refund}))
+ end
+
+ it 'streams the label back' do
+ label = create(:shipping_label, :uploaded, :with_file, owner: fulfillment)
+
+ get :download, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: label.prefixed_id
+ }
+
+ expect(response).to have_http_status(:ok)
+ expect(response.body).to include('%PDF')
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/returns_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/orders/returns_controller_spec.rb
index 7b53fe2785..eac27bcbb0 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/returns_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/orders/returns_controller_spec.rb
@@ -93,4 +93,34 @@ RSpec.describe Spree::Api::V3::Store::Orders::ReturnsController, type: :controll
expect(response).to have_http_status(:not_found)
end
end
+ describe 'GET #label' do
+ let(:return_record) { create(:return, order: order) }
+
+ it 'streams the return label to the order customer' do
+ create(:shipping_label, :with_file, owner: return_record, store: store)
+
+ get :label, params: { order_id: order.to_param, id: return_record.prefixed_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(response.headers['Content-Disposition']).to include('attachment')
+ expect(response.body).to include('%PDF')
+ end
+
+ it 'is missing when no label was bought' do
+ get :label, params: { order_id: order.to_param, id: return_record.prefixed_id }
+
+ expect(response).to have_http_status(:not_found)
+ end
+
+ # The label row is merchant data — cost, provider ids — so only the file
+ # is ever reachable from the storefront.
+ it 'never serializes the label onto the return' do
+ create(:shipping_label, :with_file, owner: return_record, store: store)
+
+ get :show, params: { order_id: order.to_param, id: return_record.prefixed_id }, as: :json
+
+ expect(json_response).not_to have_key('labels')
+ expect(json_response).not_to have_key('shipping_labels')
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/deliveries_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/deliveries_spec.rb
new file mode 100644
index 0000000000..56508c9f3f
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/deliveries_spec.rb
@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Deliveries API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:shipment) { order.fulfillments.first }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries' do
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+
+ get 'List deliveries' do
+ tags 'Deliveries'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'The consignments of a parcel — one per tracking number, each with the carrier status last reported.'
+ admin_scope :read, :fulfillments
+
+ admin_sdk_example 'order-deliveries/list'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+
+ response '200', 'deliveries found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].first['status']).to eq('pending')
+ end
+ end
+ end
+
+ post 'Record a delivery' do
+ tags 'Deliveries'
+ consumes 'application/json'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.'
+ admin_scope :write, :fulfillments
+
+ admin_sdk_example 'order-deliveries/create'
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :body, in: :body, required: true, schema: {
+ type: :object,
+ required: %w[tracking_number],
+ properties: {
+ tracking_number: { type: :string, description: 'Carrier tracking number, freight PRO number, or a full tracking link' },
+ carrier: { type: :string, description: 'Free-text carrier; detected from the number when omitted' },
+ service: { type: :string, description: 'Carrier service' },
+ tracking_url: { type: :string, description: 'Tracking page for this consignment' }
+ }
+ }
+
+ response '201', 'delivery recorded' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { tracking_number: '1Z879E930346834440' } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['carrier']).to eq('ups')
+ expect(data['status']).to eq('pending')
+ end
+ end
+
+ response '422', 'tracking number already recorded on this parcel' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { tracking_number: shipment.tracking } }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}' do
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+ let(:id) { shipment.deliveries.first.prefixed_id }
+
+ patch 'Correct a delivery' do
+ tags 'Deliveries'
+ consumes 'application/json'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.'
+ admin_scope :write, :fulfillments
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Delivery ID'
+ parameter name: :body, in: :body, required: true, schema: {
+ type: :object,
+ properties: {
+ tracking_number: { type: :string },
+ carrier: { type: :string },
+ service: { type: :string },
+ tracking_url: { type: :string }
+ }
+ }
+
+ response '200', 'delivery updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { tracking_number: 'CORRECTED-1' } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['tracking_number']).to eq('CORRECTED-1')
+ end
+ end
+ end
+
+ delete 'Delete a delivery' do
+ tags 'Deliveries'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Removes a hand-entered consignment. One a label minted is refused — refund the label instead.'
+ admin_scope :write, :fulfillments
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Delivery ID'
+
+ response '204', 'delivery deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered' do
+ patch 'Mark a delivery delivered' do
+ tags 'Deliveries'
+ consumes 'application/json'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.'
+ admin_scope :write, :fulfillments
+
+ admin_sdk_example 'order-deliveries/mark-delivered'
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Delivery ID'
+ parameter name: :body, in: :body, required: false, schema: {
+ type: :object,
+ properties: {
+ delivered_at: { type: :string, format: 'date-time', description: 'When it arrived. Defaults to now.' },
+ notify_customer: { type: :boolean, description: 'Whether the customer gets a delivery notification when the parcel completes.' }
+ }
+ }
+
+ response '200', 'delivery marked delivered' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+ let(:id) { shipment.deliveries.first.prefixed_id }
+ let(:body) { {} }
+
+ before { Spree.fulfillment_fulfill_workflow.call(fulfillment: shipment) }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('delivered')
+ expect(data['delivered_at']).to be_present
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb
index 2e09409a68..666f68b3a3 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
require 'swagger_helper'
+require 'spree/testing_support/label_provider'
RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
include_context 'API v3 Admin'
@@ -234,11 +235,12 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
end
path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label' do
- patch 'Buy the shipping label' do
+ patch 'Buy the shipping label (deprecated)' do
tags 'Fulfillments'
produces 'application/json'
security [{ api_key: [], bearer_auth: [] }]
- description 'Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.'
+ description 'Deprecated alias of POST /labels, answering with the fulfillment instead of the label. Removed in Spree 6.1.'
+ deprecated true
admin_scope :write, :fulfillments
admin_sdk_example 'order-fulfillments/purchase-label'
@@ -257,27 +259,16 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
let(:id) { shipment.prefixed_id }
before do
- shipment.update_column(:tracking, nil)
- label_provider = Class.new(Spree::FulfillmentProvider::Base) do
- def self.generates_labels?
- true
- end
-
- def create_fulfillment(_fulfillment)
- { tracking_number: 'LBL-123' }
- end
-
- def documents(_fulfillment)
- [{ kind: 'label', url: 'https://carrier.example/label.pdf' }]
- end
- end
- allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(label_provider.new)
+ shipment.deliveries.destroy_all
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).
+ and_return(Spree::TestingSupport::LabelProvider.new)
end
run_test! do |response|
data = JSON.parse(response.body)
expect(data['status']).to eq('unfulfilled')
- expect(data['documents'].first['kind']).to eq('label')
+ expect(data['labels'].first['source']).to eq('purchased')
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/labels_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/labels_spec.rb
new file mode 100644
index 0000000000..b8f5defbe5
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/labels_spec.rb
@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+require 'spree/testing_support/label_provider'
+
+RSpec.describe 'Admin Shipping Labels API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:shipment) { order.fulfillments.first }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:signed_file) do
+ ActiveStorage::Blob.create_and_upload!(
+ io: StringIO.new("%PDF-1.4\n%label\n"), filename: 'label.pdf', content_type: 'application/pdf',
+ service_name: Spree.private_storage_service_name
+ ).signed_id
+ end
+
+ path '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels' do
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+
+ get 'List shipping labels' do
+ tags 'Shipping Labels'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Every label bought or uploaded for a parcel, refunded ones included.'
+ admin_scope :read, :fulfillments
+
+ admin_sdk_example 'order-labels/list'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+
+ response '200', 'labels found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ before { create(:shipping_label, owner: shipment, store: store) }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].first['source']).to eq('purchased')
+ end
+ end
+ end
+
+ post 'Buy or record a shipping label' do
+ tags 'Shipping Labels'
+ consumes 'application/json'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'With no body, buys the label through the parcel\'s carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.'
+ admin_scope :write, :fulfillments
+
+ admin_sdk_example 'order-labels/create'
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :body, in: :body, required: false, schema: {
+ type: :object,
+ properties: {
+ file: { type: :string, description: 'Signed blob id of an uploaded label file; its presence records rather than buys' },
+ tracking_number: { type: :string, description: 'Number printed on an uploaded label' },
+ carrier: { type: :string, description: 'Free-text carrier; detected from the number when omitted' },
+ service: { type: :string, description: 'Carrier service the label was bought at' },
+ cost: { type: :string, description: 'What the merchant paid the carrier' },
+ currency: { type: :string, description: 'Currency of the cost' },
+ file_format: { type: :string, enum: %w[pdf png zpl], description: 'Label file format; taken from the file when omitted' },
+ tracking_url: { type: :string, description: 'Tracking page for the consignment' }
+ }
+ }
+
+ response '201', 'label purchased' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { {} }
+
+ before do
+ shipment.deliveries.destroy_all
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).
+ and_return(Spree::TestingSupport::LabelProvider.new)
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['source']).to eq('purchased')
+ expect(data['status']).to eq('purchased')
+ expect(data['tracking_number']).to be_present
+ end
+ end
+
+ response '422', 'provider does not produce labels' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { {} }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}' do
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+ let!(:shipping_label) { create(:shipping_label, :uploaded, owner: shipment, store: store) }
+ let(:id) { shipping_label.prefixed_id }
+
+ get 'Get a shipping label' do
+ tags 'Shipping Labels'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'One label, with what it cost and where to print it from.'
+ admin_scope :read, :fulfillments
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Shipping label ID'
+
+ response '200', 'label found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(shipping_label.prefixed_id)
+ expect(data['source']).to eq('uploaded')
+ end
+ end
+ end
+
+ delete 'Delete an uploaded label' do
+ tags 'Shipping Labels'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.'
+ admin_scope :write, :fulfillments
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Shipping label ID'
+
+ response '204', 'label deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund' do
+ patch 'Refund a shipping label' do
+ tags 'Shipping Labels'
+ produces 'application/json'
+ security [{ api_key: [], bearer_auth: [] }]
+ description 'Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.'
+ admin_scope :write, :fulfillments
+
+ admin_sdk_example 'order-labels/refund'
+
+ 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 ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, required: true, description: 'Fulfillment ID'
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Shipping label ID'
+
+ response '200', 'refund filed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+ let(:shipping_label) { create(:shipping_label, :with_delivery, owner: shipment, store: store) }
+ let(:id) { shipping_label.prefixed_id }
+
+ before do
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).
+ and_return(Spree::TestingSupport::LabelProvider.new)
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('refunded')
+ end
+ end
+
+ response '422', 'uploaded labels cannot be refunded' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { shipment.prefixed_id }
+ let(:shipping_label) { create(:shipping_label, :uploaded, owner: shipment, store: store) }
+ let(:id) { shipping_label.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/core/app/jobs/spree/shipping_labels/store_file_job.rb b/spree/core/app/jobs/spree/shipping_labels/store_file_job.rb
new file mode 100644
index 0000000000..cb3ace1eea
--- /dev/null
+++ b/spree/core/app/jobs/spree/shipping_labels/store_file_job.rb
@@ -0,0 +1,17 @@
+module Spree
+ module ShippingLabels
+ # Retries fetching a purchased label's file when the fetch right after
+ # purchase failed — the carrier's hosted copy is usually there a moment
+ # later. Idempotent: an already-attached file is left alone.
+ class StoreFileJob < Spree::BaseJob
+ retry_on StandardError, wait: :polynomially_longer, attempts: 5
+
+ # @param shipping_label_id [Integer]
+ def perform(shipping_label_id)
+ shipping_label = Spree::ShippingLabel.find(shipping_label_id)
+ result = Spree.shipping_label_store_file_service.call(shipping_label: shipping_label)
+ raise result.error.to_s if result.failure?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/delivery.rb b/spree/core/app/models/spree/delivery.rb
new file mode 100644
index 0000000000..e357f21c06
--- /dev/null
+++ b/spree/core/app/models/spree/delivery.rb
@@ -0,0 +1,118 @@
+module Spree
+ # One consignment's carrier journey — a parcel, or three pallets under one
+ # PRO number — with the tracking number, carrier and the carrier's own
+ # status axis (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ #
+ # Owned polymorphically by a +Spree::Fulfillment+ (outbound) or a
+ # +Spree::Return+ (inbound), and optionally minted by a shipping label. The
+ # owner's own lifecycle never lives here: a fulfillment is +delivered+ when
+ # every one of its deliveries is, and that rollup belongs to
+ # +Spree::Deliveries::UpdateTracking+.
+ #
+ # +status+ is data the carrier reports, written by that workflow. It has no
+ # transition graph: carriers resend the whole picture on every update.
+ class Delivery < Spree.base_class
+ has_prefix_id :dlv
+
+ include Spree::SingleStoreResource
+
+ publishes_lifecycle_events
+
+ STATUSES = %w[
+ pending pre_transit in_transit out_for_delivery available_for_pickup
+ delivered return_to_sender failure unknown
+ ].freeze
+ OWNER_TYPES = %w[Spree::Fulfillment Spree::Return].freeze
+
+ belongs_to :owner, polymorphic: true
+ belongs_to :shipping_label, class_name: 'Spree::ShippingLabel', optional: true, inverse_of: :delivery
+
+ attribute :status, :string, default: 'pending'
+
+ validates :tracking_number, presence: true, uniqueness: { scope: [:owner_type, :owner_id] }
+ validates :status, inclusion: { in: STATUSES }
+ validates :owner_type, inclusion: { in: OWNER_TYPES }
+
+ normalizes :tracking_number, with: ->(value) { value&.to_s&.squish&.presence }
+
+ # Numbers from the big carriers encode who they belong to; pinning the
+ # detected carrier means the badge and the URL survive when the merchant
+ # only pasted a number. Fills a blank only — a merchant's or a provider's
+ # explicit carrier is never second-guessed, and a forwarder's name is a
+ # legal value: nothing validates +carrier+ against the registry.
+ before_validation :detect_carrier, if: -> { carrier.blank? && tracking_number.present? }
+
+ scope :chronological, -> { order(:created_at, :id) }
+ scope :delivered, -> { where(status: 'delivered') }
+ scope :undelivered, -> { where.not(status: 'delivered') }
+
+ self.whitelisted_ransackable_attributes = %w[tracking_number carrier status]
+
+ STATUSES.each do |value|
+ define_method(:"#{value}?") { status == value }
+ end
+
+ # The public page where this consignment can be followed, best answer
+ # first: a link the merchant pasted or the provider's tracker page (the
+ # column), the pinned carrier's registered tracking page, the delivery
+ # method's configured format, then detection from the number's format.
+ #
+ # @return [String, nil]
+ def tracking_url
+ return if tracking_number.blank?
+
+ super.presence ||
+ (tracking_number if pasted_link?) ||
+ provider_tracking_url.presence ||
+ carrier_tracking_url.presence ||
+ delivery_method_tracking_url.presence ||
+ detected_tracking_url
+ end
+
+ # The carrier's display name — from the registry when the key is known,
+ # otherwise the free text as entered.
+ #
+ # @return [String, nil]
+ def carrier_name
+ return if carrier.blank?
+
+ Spree.tracking_carriers.dig(carrier, :name) || carrier
+ end
+
+ # @return [Boolean] whether the tracking value is a full link rather than a number
+ def pasted_link?
+ tracking_number.to_s.start_with?('https://', 'http://')
+ end
+
+ private
+
+ def provider_tracking_url
+ return unless owner.respond_to?(:provider)
+
+ owner.provider.tracking_url(self)
+ end
+
+ def carrier_tracking_url
+ template = Spree.tracking_carriers.dig(carrier.to_s, :url)
+ template&.gsub(':tracking', ERB::Util.url_encode(tracking_number))
+ end
+
+ def delivery_method_tracking_url
+ return unless owner.respond_to?(:delivery_method)
+
+ owner.delivery_method&.build_tracking_url(tracking_number)
+ end
+
+ def detected_tracking_url
+ service = Spree.tracking_number_service.new(tracking_number.upcase)
+ service.tracking_url if service.valid?
+ end
+
+ def detect_carrier
+ return if pasted_link?
+
+ service = Spree.tracking_number_service.new(tracking_number.upcase)
+ self.carrier = service.tracking.courier_code.to_s if service.valid?
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rb
index e96849fecb..9796beefc3 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -40,11 +40,16 @@ module Spree
# stock by the time it is destroyed.
has_many :stock_movements, class_name: 'Spree::StockMovement', inverse_of: :fulfillment
has_one :selected_delivery_rate, -> { where(selected: true).order(:cost) }, class_name: 'Spree::DeliveryRate'
+ # The carrier documents bought or uploaded for this parcel, and its
+ # consignments in flight (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ # The first delivery is the primary one that #tracking summarizes.
+ has_many :shipping_labels, -> { order(:created_at, :id) }, class_name: 'Spree::ShippingLabel', as: :owner, dependent: :destroy
+ has_many :deliveries, -> { order(:created_at, :id) }, class_name: 'Spree::Delivery', as: :owner, dependent: :destroy
after_save :update_adjustments
+ after_save :apply_pending_tracking, if: -> { defined?(@pending_tracking) }
before_validation :set_cost_zero_when_nil
- before_save :detect_tracking_carrier, if: -> { will_save_change_to_tracking? && tracking_carrier.blank? }
validate :exactly_one_owner
@@ -65,7 +70,7 @@ module Spree
# has confirmed receipt — the natural set for reporting and for skipping
# work that only applies to packages still on the shelf.
scope :fulfilled_or_delivered, -> { where(status: %w(fulfilled delivered)) }
- scope :trackable, -> { where("tracking IS NOT NULL AND tracking != ''") }
+ scope :trackable, -> { where(id: Spree::Delivery.where(owner_type: name).select(:owner_id)) }
scope :with_state, ->(*s) { where(status: s) }
# sort by most recent fulfilled_at, falling back to created_at. add "id desc" to make specs that involve this scope more deterministic.
scope :reverse_chronological, -> { order(Arel.sql("coalesce(#{table_name}.fulfilled_at, #{table_name}.created_at) desc"), id: :desc) }
@@ -120,14 +125,8 @@ module Spree
include Spree::HasStatus
has_status :unfulfilled, :fulfilled, :delivered, :canceled, default: :unfulfilled
- # What the carrier reports, kept apart from the merchant lifecycle: a bounced
- # or damaged package changes this, never #status.
- TRACKING_STATUSES = %w(
- pre_transit in_transit out_for_delivery available_for_pickup
- delivered return_to_sender failure unknown
- ).freeze
-
- validates :tracking_status, inclusion: { in: TRACKING_STATUSES }, allow_blank: true
+ # @deprecated The carrier vocabulary lives on {Spree::Delivery::STATUSES}; removed in 6.1.
+ TRACKING_STATUSES = Spree::Delivery::STATUSES
# @deprecated Use {Spree::Fulfillments::Fulfill}; removed in 6.1.
def ship(*args)
@@ -187,7 +186,6 @@ module Spree
# @deprecated the column is +status+ since 6.0
alias_attribute :state, :status
alias_attribute :shipped_at, :fulfilled_at
- after_save { @tracking_url = nil }
# Legacy association names — removed in 6.1.
has_many :inventory_units, class_name: 'Spree::FulfillmentItem', foreign_key: :fulfillment_id, inverse_of: :fulfillment, deprecated: true
has_many :shipping_rates, -> { order(:cost) }, class_name: 'Spree::DeliveryRate', foreign_key: :fulfillment_id, deprecated: true
@@ -204,8 +202,6 @@ module Spree
alias_attribute :promo_total, :discount_total
alias display_promo_total display_discount_total
- normalizes :tracking, with: ->(value) { value&.to_s&.squish&.presence }
-
# Returns the shipment number and shipping method name
#
# @return [String]
@@ -661,43 +657,49 @@ module Spree
package
end
- # External systems (3PLs, courier APIs) often hand over a complete
- # tracking link rather than a bare tracking code — returned as-is
- # instead of being templated into the delivery method's tracking URL.
+ # The consignment the 5.6 +tracking+/+tracking_url+ summary describes —
+ # the earliest delivery. Every other delivery is read through
+ # #deliveries; the fulfillment only ever summarizes this one.
#
- # @return [String, nil]
- # The public page where this parcel can be followed, best answer first:
- #
- # 1. The tracking value is already a link — pasted in whole.
- # 2. The provider that bought the label knows its own tracker page.
- # 3. The carrier pinned on this fulfillment (picked or detected) has a
- # registered tracking page.
- # 4. The delivery method's configured format string, or detection from the
- # number's format — the legacy path, still right for single-carrier
- # methods.
+ # @return [Spree::Delivery, nil]
+ def primary_delivery
+ deliveries.first
+ end
+
+ # The primary delivery's tracking number. Read-only since 6.0: tracking is
+ # a {Spree::Delivery} created through Spree::Deliveries::Create or the
+ # +tracking:+ shortcut on Spree::Fulfillments::Fulfill / Update.
#
# @return [String, nil]
- def tracking_url
- return if tracking.blank?
-
- @tracking_url ||= if tracking.start_with?('https://', 'http://')
- tracking
- else
- provider.tracking_url(self).presence ||
- carrier_tracking_url.presence ||
- delivery_method&.build_tracking_url(tracking).presence ||
- detected_tracking_url
- end
+ def tracking
+ primary_delivery&.tracking_number
+ end
+
+ # @deprecated Assigning tracking writes a delivery on save; removed in
+ # 6.1. Use Spree::Deliveries::Create or the +tracking:+ keyword on
+ # Spree::Fulfillments::Fulfill / Update instead.
+ def tracking=(value)
+ Spree::Deprecation.warn(
+ 'Spree::Fulfillment#tracking= is deprecated and will be removed in Spree 6.1. ' \
+ 'Tracking is a Spree::Delivery — use Spree::Deliveries::Create or the tracking: keyword ' \
+ 'on Spree::Fulfillments::Fulfill / Update.'
+ )
+ @pending_tracking = value
end
- # The pinned carrier's display name, for storefronts and admin UIs
- # showing "InPost: 421432" rather than a bare number.
+ # The public page where the primary consignment can be followed.
#
# @return [String, nil]
- def tracking_carrier_name
- return if tracking_carrier.blank?
+ def tracking_url
+ primary_delivery&.tracking_url
+ end
- Spree.tracking_carriers.dig(tracking_carrier, :name) || tracking_carrier.titleize
+ # The label that currently binds this parcel — bought or uploaded, and not
+ # refunded. At most one exists: the label workflows refuse a second one.
+ #
+ # @return [Spree::ShippingLabel, nil]
+ def active_shipping_label
+ shipping_labels.active.last
end
def update_amounts
@@ -844,13 +846,17 @@ module Spree
end
# Lets the provider perform its dispatch mechanics; tracking data it
- # returns is persisted unless an admin already entered one.
+ # returns becomes the primary delivery unless an admin already entered one.
def run_provider_create_fulfillment
result = provider.create_fulfillment(self)
return unless result.is_a?(Hash)
new_tracking = result[:tracking_number].presence
- update_column(:tracking, new_tracking) if new_tracking && tracking.blank?
+ return if new_tracking.blank? || tracking.present?
+
+ Spree.delivery_create_service.call(
+ owner: self, tracking_number: new_tracking, tracking_url: result[:tracking_url]
+ )
end
def update_order_fulfillment_status
@@ -883,25 +889,17 @@ module Spree
self.cost = 0 unless cost
end
- def carrier_tracking_url
- template = Spree.tracking_carriers.dig(tracking_carrier.to_s, :url)
- template&.gsub(':tracking', ERB::Util.url_encode(tracking))
- end
-
- def detected_tracking_url
- service = Spree.tracking_number_service.new(tracking.upcase)
- service.tracking_url if service.valid?
- end
-
- # Numbers from the big carriers encode who they belong to; pinning the
- # detected carrier means the badge and the URL survive even when the
- # merchant only pasted a number. Only fills a blank — a merchant's
- # explicit pick, or a provider's, is never second-guessed.
- def detect_tracking_carrier
- return if tracking.blank? || tracking.start_with?('https://', 'http://')
+ # The deprecated writer's other half: a tracking number assigned the old
+ # way still lands where every reader looks, on the primary delivery.
+ def apply_pending_tracking
+ value = remove_instance_variable(:@pending_tracking)
+ return if value.blank?
- service = Spree.tracking_number_service.new(tracking.upcase)
- self.tracking_carrier = service.tracking.courier_code.to_s if service.valid?
+ if primary_delivery
+ primary_delivery.update!(tracking_number: value, status: 'pending')
+ else
+ Spree.delivery_create_service.call(owner: self, tracking_number: value)
+ end
end
def exactly_one_owner
diff --git a/spree/core/app/models/spree/fulfillment_provider/base.rb b/spree/core/app/models/spree/fulfillment_provider/base.rb
index 759065dd5a..f442e4f9e3 100644
--- a/spree/core/app/models/spree/fulfillment_provider/base.rb
+++ b/spree/core/app/models/spree/fulfillment_provider/base.rb
@@ -61,7 +61,31 @@ module Spree
group.covers_location?(stock_location)
end
- # Performs the provider-side dispatch when a fulfillment fulfills.
+ # Buys a carrier label for the owner — a +Spree::Fulfillment+ for an
+ # outbound parcel, a +Spree::Return+ for the inbound one. Core turns the
+ # answer into a +Spree::ShippingLabel+ and its +Spree::Delivery+, and
+ # never asks twice for an owner that already holds an active label, so
+ # a provider needs no idempotency bookkeeping of its own. Only
+ # providers answering +generates_labels?+ are asked.
+ #
+ # @param _owner [Spree::Fulfillment, Spree::Return]
+ # @return [Spree::LabelPurchase, nil] nil when no label could be bought
+ def purchase_label(_owner)
+ nil
+ end
+
+ # Asks the carrier to refund a purchased label.
+ #
+ # @param _shipping_label [Spree::ShippingLabel]
+ # @return [String, false] +'refunded'+ when the carrier settled it,
+ # +'refund_requested'+ when it will answer later, false when refused
+ def refund_label(_shipping_label)
+ false
+ end
+
+ # Performs the provider-side dispatch when a fulfillment fulfills — a
+ # 3PL pick, a pickup counter, digital links. Label-generating providers
+ # implement +purchase_label+ instead.
#
# @return [Hash] optionally { tracking_number:, tracking_url: }
def create_fulfillment(_fulfillment)
@@ -73,28 +97,33 @@ module Spree
raise NotImplementedError, "Please implement 'cancel_fulfillment' in your fulfillment provider: #{self.class.name}"
end
- # @return [String, nil] provider-computed tracking URL
- def tracking_url(_fulfillment)
+ # The provider's own tracker page for a consignment.
+ #
+ # @param _delivery [Spree::Delivery]
+ # @return [String, nil]
+ def tracking_url(_delivery)
nil
end
- # @return [Array] provider documents (labels, customs forms, ...)
- def documents(_fulfillment)
+ # Documents the provider produced beside the label — customs forms,
+ # commercial invoices. The label itself is a +Spree::ShippingLabel+ and
+ # is never reported here.
+ #
+ # @param _owner [Spree::Fulfillment, Spree::Return]
+ # @return [Array<Hash>] `{ kind:, url: }` entries
+ def documents(_owner)
[]
end
- private
-
# The connected, active integration carrying this provider's
- # credentials, resolved from the fulfillment's store.
+ # credentials, resolved from the owner's store.
#
- # @param fulfillment [Spree::Fulfillment]
+ # @param owner [Spree::Fulfillment, Spree::Return]
# @return [Spree::Integration, nil]
- def integration_for(fulfillment)
+ def integration_for(owner)
return if self.class.integration_class.blank?
- store = fulfillment.order&.store || fulfillment.cart&.store
- store&.integrations&.active&.find_by(type: self.class.integration_class)
+ owner.store&.integrations&.active&.find_by(type: self.class.integration_class)
end
end
end
diff --git a/spree/core/app/models/spree/label_purchase.rb b/spree/core/app/models/spree/label_purchase.rb
new file mode 100644
index 0000000000..1cee3780ce
--- /dev/null
+++ b/spree/core/app/models/spree/label_purchase.rb
@@ -0,0 +1,29 @@
+module Spree
+ # What a label-generating fulfillment provider hands back from
+ # +purchase_label+: the carrier's answer, typed, before core turns it into
+ # a +Spree::ShippingLabel+ and its +Spree::Delivery+. Ephemeral, never
+ # persisted.
+ #
+ # +cost+ and +currency+ are what the merchant paid the carrier; +file_url+
+ # is the provider's hosted copy of the label, fetched into private storage
+ # right after purchase. +metadata+ carries whatever ids the provider needs
+ # to find the purchase again (a tracker id, a shipment id).
+ class LabelPurchase
+ include ActiveModel::Model
+ include ActiveModel::Attributes
+
+ attribute :external_id, :string
+ attribute :carrier, :string
+ attribute :service, :string
+ attribute :tracking_number, :string
+ attribute :tracking_url, :string
+ attribute :cost, :decimal, default: 0
+ attribute :currency, :string
+ attribute :format, :string
+ attribute :file_url, :string
+ attribute :metadata, default: -> { {} }
+
+ validates :tracking_number, presence: true
+ validates :cost, numericality: { greater_than_or_equal_to: 0 }
+ end
+end
diff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rb
index 94aee77858..666b7eefb7 100644
--- a/spree/core/app/models/spree/return.rb
+++ b/spree/core/app/models/spree/return.rb
@@ -37,6 +37,11 @@ module Spree
dependent: :destroy, inverse_of: :return
has_many :refunds, class_name: 'Spree::Refund', as: :originator, dependent: :nullify
has_many :store_credits, class_name: 'Spree::StoreCredit', as: :originator, dependent: :nullify
+ # The return label and the inbound parcel's journey
+ # (docs/plans/6.0-shipping-labels-and-deliveries.md). A delivery reporting
+ # arrival never receives the return: arrival is not inspection.
+ has_many :shipping_labels, -> { order(:created_at, :id) }, class_name: 'Spree::ShippingLabel', as: :owner, dependent: :destroy
+ has_many :deliveries, -> { order(:created_at, :id) }, class_name: 'Spree::Delivery', as: :owner, dependent: :destroy
validates :return_line_items, presence: true, on: :create
@@ -47,6 +52,45 @@ module Spree
self.whitelisted_ransackable_attributes = %w[number status created_at]
self.whitelisted_ransackable_associations = %w[order reason]
+ # The label that currently binds the inbound parcel — bought or uploaded,
+ # not refunded. The label workflows refuse a second active one.
+ #
+ # @return [Spree::ShippingLabel, nil]
+ def active_shipping_label
+ shipping_labels.active.last
+ end
+
+ # The provider that ships this return's label — the one that handled the
+ # outbound parcel the returned items travelled in, since that is the
+ # carrier account the merchant connected. Manual when nothing shipped
+ # through a provider.
+ #
+ # @return [Spree::FulfillmentProvider::Base]
+ def provider
+ return_line_items.first&.fulfillment_item&.fulfillment&.provider || Spree::FulfillmentProvider::Manual.new
+ end
+
+ # The address the inbound parcel leaves from: where the order shipped to.
+ #
+ # @return [Spree::Address, nil]
+ def ship_from_address
+ order.ship_address
+ end
+
+ # The returned goods as a package, for providers that need a weight and
+ # dimensions to rate a return label. Built at the return's stock
+ # location, which is where the parcel is going.
+ #
+ # @return [Spree::Stock::Package]
+ def to_package
+ package = Spree::Stock::Package.new(stock_location)
+ package.owner = order
+ return_line_items.includes(:fulfillment_item).each do |line|
+ package.add(line.fulfillment_item) if line.fulfillment_item
+ end
+ package
+ end
+
# What the customer is owed for the items being returned.
def refund_total
return_line_items.sum(&:pre_tax_amount)
diff --git a/spree/core/app/models/spree/shipping_label.rb b/spree/core/app/models/spree/shipping_label.rb
new file mode 100644
index 0000000000..52f72863d5
--- /dev/null
+++ b/spree/core/app/models/spree/shipping_label.rb
@@ -0,0 +1,106 @@
+module Spree
+ # A carrier document the merchant bought through a connected carrier account
+ # or uploaded after buying postage elsewhere
+ # (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ #
+ # Owned polymorphically: a +Spree::Fulfillment+ for an outbound parcel, a
+ # +Spree::Return+ for the inbound one. What the merchant paid the carrier is
+ # recorded here as accounting data — it never feeds the order's shipping
+ # charge and never reaches a store serializer.
+ #
+ # Every status change is a workflow (+Spree::ShippingLabels::Purchase+,
+ # +::Refund+, +::Record+); the model holds associations, validations and
+ # reads only.
+ class ShippingLabel < Spree.base_class
+ has_prefix_id :lbl
+
+ include Spree::SingleStoreResource
+ include Spree::HasStatus
+ include Spree::Metadata
+
+ publishes_lifecycle_events
+
+ has_status :purchased, :refund_requested, :refunded, default: :purchased
+
+ SOURCES = %w[purchased uploaded].freeze
+ FORMATS = %w[pdf png zpl].freeze
+ OWNER_TYPES = %w[Spree::Fulfillment Spree::Return].freeze
+ MAX_FILE_SIZE = 10.megabytes
+ # ZPL is plain text as far as any byte-sniffer can tell.
+ FILE_CONTENT_TYPES = %w[application/pdf image/png text/plain].freeze
+
+ belongs_to :owner, polymorphic: true
+ belongs_to :integration, class_name: 'Spree::Integration', optional: true
+ has_one :delivery, class_name: 'Spree::Delivery', inverse_of: :shipping_label, dependent: :nullify
+
+ # Private storage: a label carries the customer's address and the
+ # merchant's account details, and is served only through an
+ # authenticated, streamed download.
+ has_one_attached :file, service: Spree.private_storage_service_name
+
+ validates :source, inclusion: { in: SOURCES }
+ validates :owner_type, inclusion: { in: OWNER_TYPES }
+ validates :format, inclusion: { in: FORMATS }, allow_blank: true
+ validates :cost, numericality: { greater_than_or_equal_to: 0 }
+ validates :file, size: { less_than_or_equal_to: MAX_FILE_SIZE }, if: -> { file.attached? }
+ # Uploaded by sellers and staff, opened by warehouse staff — the bytes
+ # decide what the file is, not the header the uploader sent.
+ validates_with Spree::AttachmentContentTypeValidator,
+ attributes: [:file],
+ in: FILE_CONTENT_TYPES,
+ if: -> { file.attached? }
+
+ normalizes :tracking_number, with: ->(value) { value&.to_s&.squish&.presence }
+
+ # Labels that still bind a parcel: a refunded one is history.
+ scope :active, -> { where.not(status: 'refunded') }
+ scope :chronological, -> { order(:created_at, :id) }
+
+ self.whitelisted_ransackable_attributes = %w[status source carrier tracking_number]
+
+ # @return [Boolean] whether the merchant uploaded this label rather than
+ # buying it through a provider
+ def uploaded?
+ source == 'uploaded'
+ end
+
+ # @return [Boolean] whether a refund can still be requested from the
+ # carrier — only a purchased label that has not been refunded
+ def refundable?
+ purchased? && !uploaded?
+ end
+
+ # @return [Boolean] whether the file is still to be fetched from the
+ # provider's URL
+ def file_pending?
+ !file.attached? && file_url.present?
+ end
+
+ # The provider's hosted copy of the label, kept only until the file has
+ # been fetched into Spree's own storage.
+ #
+ # @return [String, nil]
+ def file_url
+ metadata['file_url']
+ end
+
+ # @return [Spree::Money]
+ def display_cost
+ Spree::Money.new(cost, currency: currency.presence || store.default_currency)
+ end
+
+ # @return [String] the filename a download is served under
+ def download_filename
+ return file.filename.to_s if file.attached?
+
+ "#{tracking_number.presence || prefixed_id}.#{format.presence || 'pdf'}"
+ end
+
+ # Custom events carry the label rather than the minimal payload; the
+ # store never sees a label, so there is no storefront serializer to find
+ # by convention.
+ def event_serializer_class
+ 'Spree::Api::V3::ShippingLabelEventSerializer'.safe_constantize
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index 806e56a239..dfaf0a98e6 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -168,6 +168,8 @@ module Spree
has_many :shipments, through: :orders, class_name: 'Spree::Fulfillment', source: :fulfillments, deprecated: true
has_many :payments, through: :orders, class_name: 'Spree::Payment'
has_many :returns, class_name: 'Spree::Return', inverse_of: :store
+ has_many :shipping_labels, class_name: 'Spree::ShippingLabel', inverse_of: :store
+ has_many :deliveries, class_name: 'Spree::Delivery', inverse_of: :store
has_many :exchanges, class_name: 'Spree::Exchange', inverse_of: :store
has_many :claims, class_name: 'Spree::Claim', inverse_of: :store
has_many :return_reasons, class_name: 'Spree::ReturnReason', inverse_of: :store, dependent: :destroy
diff --git a/spree/core/app/services/spree/deliveries/create.rb b/spree/core/app/services/spree/deliveries/create.rb
new file mode 100644
index 0000000000..aebffbfd33
--- /dev/null
+++ b/spree/core/app/services/spree/deliveries/create.rb
@@ -0,0 +1,38 @@
+module Spree
+ module Deliveries
+ # Records a consignment on its owner: a parcel's tracking number, a
+ # forwarder's PRO or container number, or the number printed on a label
+ # that was just bought (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ #
+ # The one write path for a delivery row — the +tracking:+ shortcut on
+ # Spree::Fulfillments::Fulfill / Update and the label workflows all come
+ # through here. A plain service: no hook has been earned yet.
+ class Create
+ prepend Spree::ServiceModule::Base
+
+ # @param owner [Spree::Fulfillment, Spree::Return]
+ # @param tracking_number [String] a carrier number, or a full tracking
+ # link pasted whole — which then also becomes +tracking_url+
+ # @param carrier [String, nil] free text; detected from the number when omitted
+ # @param tracking_url [String, nil]
+ # @param service [String, nil]
+ # @param shipping_label [Spree::ShippingLabel, nil] the label that minted this delivery
+ # @param status [String] the carrier status to start at
+ # @return [Spree::ServiceModule::Result] the delivery on success
+ def call(owner:, tracking_number:, carrier: nil, tracking_url: nil, service: nil, shipping_label: nil, status: 'pending')
+ delivery = owner.deliveries.new(
+ store: owner.store,
+ tracking_number: tracking_number,
+ carrier: carrier.presence,
+ tracking_url: tracking_url.presence,
+ service: service.presence,
+ shipping_label: shipping_label,
+ status: status
+ )
+ delivery[:tracking_url] ||= delivery.tracking_number if delivery.pasted_link?
+
+ delivery.save ? success(delivery) : failure(delivery)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/deliveries/destroy.rb b/spree/core/app/services/spree/deliveries/destroy.rb
new file mode 100644
index 0000000000..aab731498f
--- /dev/null
+++ b/spree/core/app/services/spree/deliveries/destroy.rb
@@ -0,0 +1,22 @@
+module Spree
+ module Deliveries
+ # Removes a hand-entered consignment. A delivery minted by a label is not
+ # removable on its own — the label is the record of what was bought, so
+ # the way out is refunding it, which removes the delivery when the parcel
+ # never moved.
+ class Destroy
+ prepend Spree::ServiceModule::Base
+
+ # @param delivery [Spree::Delivery]
+ # @return [Spree::ServiceModule::Result]
+ def call(delivery:)
+ if delivery.shipping_label_id.present?
+ delivery.errors.add(:base, Spree.t('deliveries.errors.has_label'))
+ return failure(delivery)
+ end
+
+ delivery.destroy ? success(delivery) : failure(delivery)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/fulfillments/stand_down_provider.rb b/spree/core/app/services/spree/fulfillments/stand_down_provider.rb
new file mode 100644
index 0000000000..e8e5057fe3
--- /dev/null
+++ b/spree/core/app/services/spree/fulfillments/stand_down_provider.rb
@@ -0,0 +1,28 @@
+module Spree
+ module Fulfillments
+ # The carrier half of cancelling a parcel: every active label is refunded
+ # and the provider is told to drop any non-label dispatch (a 3PL pick).
+ # Network I/O, so callers run it from an external step after their own
+ # transaction has committed — Spree::Fulfillments::Cancel directly,
+ # Spree::Orders::Cancel batched over every fulfillment on the order.
+ #
+ # Nothing here blocks the cancellation: the goods are not going out
+ # either way, and a refund the carrier refuses surfaces on the label.
+ class StandDownProvider
+ prepend Spree::ServiceModule::Base
+
+ # @param fulfillment [Spree::Fulfillment]
+ # @return [Spree::ServiceModule::Result]
+ def call(fulfillment:)
+ fulfillment.shipping_labels.active.each do |shipping_label|
+ next unless shipping_label.refundable?
+
+ Spree.shipping_label_refund_workflow.call(shipping_label: shipping_label)
+ end
+
+ fulfillment.provider.cancel_fulfillment(fulfillment)
+ success(fulfillment)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/shipping_labels/confirm_refund.rb b/spree/core/app/services/spree/shipping_labels/confirm_refund.rb
new file mode 100644
index 0000000000..3a25b41b45
--- /dev/null
+++ b/spree/core/app/services/spree/shipping_labels/confirm_refund.rb
@@ -0,0 +1,27 @@
+module Spree
+ module ShippingLabels
+ # Settles a refund the carrier answered later. Providers whose refunds
+ # resolve asynchronously call this from their webhook handler once the
+ # carrier confirms; the label moves from +refund_requested+ to
+ # +refunded+ and the same event fires as for a synchronous refund.
+ class ConfirmRefund
+ prepend Spree::ServiceModule::Base
+
+ # @param shipping_label [Spree::ShippingLabel]
+ # @param refunded_at [Time, nil] when the carrier settled it; defaults to now
+ # @return [Spree::ServiceModule::Result]
+ def call(shipping_label:, refunded_at: nil)
+ return success(shipping_label) if shipping_label.refunded?
+
+ unless shipping_label.refund_requested?
+ shipping_label.errors.add(:base, Spree.t('shipping_labels.errors.not_refund_requested'))
+ return failure(shipping_label)
+ end
+
+ shipping_label.update!(status: 'refunded', refunded_at: refunded_at || Time.current)
+ shipping_label.publish_event('shipping_label.refunded')
+ success(shipping_label)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/shipping_labels/store_file.rb b/spree/core/app/services/spree/shipping_labels/store_file.rb
new file mode 100644
index 0000000000..7fcc3c84d8
--- /dev/null
+++ b/spree/core/app/services/spree/shipping_labels/store_file.rb
@@ -0,0 +1,65 @@
+require 'ssrf_filter'
+
+module Spree
+ module ShippingLabels
+ # Fetches a purchased label from the provider's hosted URL into Spree's
+ # own private storage, so the merchant can reprint after the carrier's
+ # link has expired and a disconnected integration never breaks a
+ # warehouse. Called right after purchase and retried by
+ # Spree::ShippingLabels::StoreFileJob when that first fetch fails.
+ class StoreFile
+ prepend Spree::ServiceModule::Base
+
+ READ_TIMEOUT = 30
+ OPEN_TIMEOUT = 10
+
+ # @param shipping_label [Spree::ShippingLabel]
+ # @return [Spree::ServiceModule::Result] the label with its file attached
+ def call(shipping_label:)
+ return success(shipping_label) if shipping_label.file.attached?
+
+ url = shipping_label.file_url
+ if url.blank?
+ shipping_label.errors.add(:file, Spree.t('shipping_labels.errors.no_file_url'))
+ return failure(shipping_label)
+ end
+
+ response = fetch(url)
+ unless response.is_a?(Net::HTTPSuccess)
+ shipping_label.errors.add(:file, Spree.t('shipping_labels.errors.file_fetch_failed', status: response.code))
+ return failure(shipping_label)
+ end
+
+ attach(shipping_label, response.body, url)
+ shipping_label.save ? success(shipping_label) : failure(shipping_label)
+ end
+
+ # A carrier CDN that is down, slow or refuses the address is an
+ # ordinary outcome here, reported as a failed fetch rather than raised —
+ # the purchase behind it is already a fact.
+ class FetchFailed < StandardError
+ def code
+ 'unreachable'
+ end
+ end
+
+ private
+
+ def fetch(url)
+ SsrfFilter.get(url, http_options: { read_timeout: READ_TIMEOUT, open_timeout: OPEN_TIMEOUT })
+ rescue SsrfFilter::Error, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, SystemCallError, Net::HTTPError => e
+ FetchFailed.new(e.message)
+ end
+
+ def attach(shipping_label, body, url)
+ extension = shipping_label.format.presence || File.extname(URI.parse(url).path).delete('.').presence || 'pdf'
+ filename = shipping_label.download_filename
+ filename = "#{filename}.#{extension}" if File.extname(filename).blank?
+ # Assigned rather than attached: attaching to a persisted record
+ # writes the blob before validation, and the bytes decide whether
+ # this is a label at all.
+ shipping_label.file = { io: StringIO.new(body), filename: filename }
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/deliveries/update_tracking.rb b/spree/core/app/workflows/spree/deliveries/update_tracking.rb
new file mode 100644
index 0000000000..d64af8f8f9
--- /dev/null
+++ b/spree/core/app/workflows/spree/deliveries/update_tracking.rb
@@ -0,0 +1,102 @@
+module Spree
+ module Deliveries
+ # Records what the carrier says about one consignment in flight.
+ #
+ # This is the carrier axis: it never moves the owner backwards and never
+ # contradicts the merchant. A parcel that bounces or is damaged shows up
+ # here as `return_to_sender` or `failure` while the fulfillment still
+ # says `fulfilled` — the merchant did hand it over. The one status that
+ # crosses over is `delivered`: when every delivery of a fulfillment has
+ # arrived, the fulfillment is marked delivered through
+ # Spree::Fulfillments::MarkDelivered. A Return owner never transitions —
+ # goods arriving is not goods inspected, and Spree::Returns::Receive stays
+ # a staff act; anything that wants to react hangs on
+ # +after_update_tracking+.
+ #
+ # Providers call this from their webhook handlers, so it accepts the
+ # already-normalized vocabulary rather than any carrier's raw payload:
+ # translating a provider's status names is the provider gem's job.
+ class UpdateTracking < Spree::Workflow
+ hooks :validate, :after_update_tracking
+
+ # @param delivery [Spree::Delivery] the consignment being tracked
+ # @param tracking_status [String, nil] one of {Spree::Delivery::STATUSES}
+ # @param estimated_delivery_at [Time, nil] carrier's current estimate
+ # @param delivered_at [Time, nil] when the carrier says it arrived; used
+ # only when +tracking_status+ is `delivered`, defaulting to now
+ # @param details [Hash, nil] provider payload worth keeping — scan events,
+ # the signature, the failure reason
+ # @param notify_customer [Boolean] passed through to MarkDelivered when
+ # this update completes the fulfillment's delivery
+ # @return [Spree::ServiceModule::Result] the updated delivery on success
+ def perform(delivery:, tracking_status: nil, estimated_delivery_at: nil, delivered_at: nil,
+ details: nil, notify_customer: true)
+ super
+
+ run_hooks :validate
+
+ step :ensure_known_status
+ step :apply_carrier_report
+ step :roll_up_owner_delivery
+
+ run_hooks :after_update_tracking
+ success(delivery.reload)
+ end
+
+ private
+
+ def ensure_known_status
+ return if tracking_status.blank?
+ return if Spree::Delivery::STATUSES.include?(tracking_status.to_s)
+
+ failure(delivery, Spree.t('fulfillments.errors.unknown_tracking_status', status: tracking_status))
+ end
+
+ # Overwrite rather than accumulate: this axis answers "where is it now",
+ # and carriers resend the whole picture on every update. Only attributes
+ # the caller actually supplied are touched, so a webhook carrying just a
+ # scan does not wipe an estimate from an earlier one.
+ def apply_carrier_report
+ attributes = {}
+ attributes[:status] = tracking_status.to_s if tracking_status.present?
+ attributes[:estimated_delivery_at] = estimated_delivery_at unless estimated_delivery_at.nil?
+ attributes[:details] = details unless details.nil?
+ attributes[:delivered_at] = delivered_at || delivery.delivered_at || Time.current if reported_delivered?
+
+ return if attributes.empty?
+
+ # update_columns, deliberately: carrier scans arrive many times per
+ # parcel, and a lifecycle event per scan would run the full order
+ # status rollup for writes that cannot change any status. The
+ # after_update_tracking hook and the fulfillment.delivered event are
+ # the notification surface for this axis.
+ delivery.update_columns(attributes.merge(updated_at: Time.current))
+ end
+
+ # Delivery is the one carrier report that is also a merchant fact, so it
+ # crosses over to the fulfillment's status — once every consignment has
+ # arrived, and only from `fulfilled`, which MarkDelivered enforces. A
+ # carrier reporting delivery on a canceled parcel is noise on this axis.
+ def roll_up_owner_delivery
+ return unless reported_delivered?
+
+ owner = delivery.owner
+ return unless owner.is_a?(Spree::Fulfillment)
+ return unless owner.can_mark_delivered?
+ return if owner.deliveries.undelivered.exists?
+
+ result = Spree.fulfillment_mark_delivered_workflow.call(
+ fulfillment: owner,
+ delivered_at: owner.deliveries.maximum(:delivered_at),
+ notify_customer: notify_customer
+ )
+
+ failure(delivery, result.error.to_s) if result.failure?
+ end
+
+ def reported_delivered?
+ tracking_status.to_s == 'delivered'
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/fulfillments/cancel.rb b/spree/core/app/workflows/spree/fulfillments/cancel.rb
index 4cfb8249bf..038237fa41 100644
--- a/spree/core/app/workflows/spree/fulfillments/cancel.rb
+++ b/spree/core/app/workflows/spree/fulfillments/cancel.rb
@@ -78,8 +78,9 @@ module Spree
fulfillment.publish_fulfillment_canceled_event
end
+ # Refunds every active label, then drops any non-label dispatch.
def tell_provider_to_stand_down
- fulfillment.provider.cancel_fulfillment(fulfillment)
+ Spree::Fulfillments::StandDownProvider.new.call(fulfillment: fulfillment)
end
end
end
diff --git a/spree/core/app/workflows/spree/fulfillments/create.rb b/spree/core/app/workflows/spree/fulfillments/create.rb
index 01daa32630..d84cbedeab 100644
--- a/spree/core/app/workflows/spree/fulfillments/create.rb
+++ b/spree/core/app/workflows/spree/fulfillments/create.rb
@@ -103,11 +103,15 @@ module Spree
@fulfillment = order.fulfillments.new(
stock_location: stock_location,
- address_id: order.ship_address_id,
- tracking: tracking
+ address_id: order.ship_address_id
)
@fulfillment.metadata = metadata if metadata.present?
@fulfillment.save!
+
+ return if tracking.blank?
+
+ result = Spree.delivery_create_service.call(owner: @fulfillment, tracking_number: tracking)
+ failure(@fulfillment, result.error.to_s) if result.failure?
end
def move_requested_units
diff --git a/spree/core/app/workflows/spree/fulfillments/fulfill.rb b/spree/core/app/workflows/spree/fulfillments/fulfill.rb
index 9c96c978f2..e6613ca7a7 100644
--- a/spree/core/app/workflows/spree/fulfillments/fulfill.rb
+++ b/spree/core/app/workflows/spree/fulfillments/fulfill.rb
@@ -29,10 +29,12 @@ module Spree
# @param fulfillment [Spree::Fulfillment] the fulfillment to ship from
# @param items [Array<Hash>, nil] `[{ line_item: Spree::LineItem, quantity: Integer }]`
# to ship; nil or empty fulfills every unit the fulfillment holds
- # @param tracking [String, nil] carrier tracking number or full tracking URL,
- # stored on the fulfillment that ships
+ # @param tracking [String, nil] carrier tracking number or full tracking URL —
+ # the one-parcel shortcut: recorded as the primary Spree::Delivery of
+ # the fulfillment that ships
# @param tracking_carrier [String, nil] which carrier the number belongs
- # to (a Spree.tracking_carriers slug); detected from the number when omitted
+ # to (free text; a Spree.tracking_carriers key gets a badge and URL);
+ # detected from the number when omitted
# @param notify_customer [Boolean] whether the shipment email goes out;
# false suppresses it for this dispatch only
# @param force [Boolean] dispatch even when the order is unpaid or holds
@@ -70,6 +72,7 @@ module Spree
# failure here still degrades to "no label yet" — a carrier outage
# must never stop a merchant recording a parcel that physically left.
# Network I/O, so never in a transaction.
+ external_step :purchase_label
external_step :tell_provider_it_shipped
ApplicationRecord.transaction do
@@ -270,19 +273,26 @@ module Spree
end
end
- # Written before the transition so the provider's own tracking lookup
- # (run_provider_create_fulfillment) sees an admin-entered number and
- # leaves it alone, and so the shipment email carries it.
- #
- # update! rather than update_columns so the carrier-detection callback
- # runs — a number typed without a carrier still gets its badge and URL.
+ # Recorded before the provider is asked, so a label purchase sees the
+ # admin-entered number and binds to it rather than minting a second
+ # consignment, and so the shipment email carries it. The primary
+ # delivery is created, or its number corrected.
def apply_tracking
- attributes = {}
- attributes[:tracking] = tracking.to_s.squish if tracking.present?
- attributes[:tracking_carrier] = tracking_carrier if tracking_carrier.present?
- return if attributes.empty?
+ return if tracking.blank?
+
+ primary = @fulfillment.primary_delivery
+ if primary
+ attributes = { tracking_number: tracking.to_s.squish }
+ attributes[:carrier] = tracking_carrier if tracking_carrier.present?
+ attributes[:status] = 'pending' if attributes[:tracking_number] != primary.tracking_number
+ primary.update!(attributes)
+ return
+ end
- @fulfillment.update!(attributes)
+ result = Spree.delivery_create_service.call(
+ owner: @fulfillment, tracking_number: tracking, carrier: tracking_carrier
+ )
+ failure(@source, result.error.to_s) if result.failure?
end
# The suppression flag rides on the record because the event publisher
@@ -306,7 +316,24 @@ module Spree
@fulfillment.process_order_payments
end
- # Tracking the provider discovers is kept unless an admin already typed
+ # A label-generating provider is asked for the label unless one is
+ # already active; the outcome is the label's own affair — a failure
+ # here is reported and the parcel still ships.
+ def purchase_label
+ return unless @fulfillment.provider.class.generates_labels?
+ return if @fulfillment.shipping_labels.active.exists?
+
+ result = Spree.shipping_label_purchase_workflow.call(owner: @fulfillment)
+ return if result.success?
+
+ Rails.error.report(
+ Spree::Core::LabelPurchaseFailed.new(result.error.to_s),
+ context: { fulfillment_id: @fulfillment.id }, source: 'spree.fulfillments.fulfill'
+ )
+ end
+
+ # Non-label dispatch — a 3PL pick, digital links. Tracking the provider
+ # discovers becomes the primary delivery unless an admin already typed
# one in — a human who entered a number meant it.
def tell_provider_it_shipped
result = @fulfillment.provider.create_fulfillment(@fulfillment)
@@ -315,7 +342,9 @@ module Spree
new_tracking = result[:tracking_number].presence
return if new_tracking.blank? || @fulfillment.tracking.present?
- @fulfillment.update_column(:tracking, new_tracking)
+ Spree.delivery_create_service.call(
+ owner: @fulfillment, tracking_number: new_tracking, tracking_url: result[:tracking_url]
+ )
end
def roll_up_order_status
diff --git a/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb b/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb
index a812fd9709..aefba9b57c 100644
--- a/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb
+++ b/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb
@@ -30,7 +30,11 @@ module Spree
run_hooks :validate
step :ensure_deliverable
- step :mark_delivered
+
+ ApplicationRecord.transaction do
+ step :close_open_deliveries
+ step :mark_delivered
+ end
run_hooks :after_mark_delivered
success(fulfillment.reload)
@@ -44,6 +48,14 @@ module Spree
failure(fulfillment, Spree.t('fulfillments.errors.cannot_mark_delivered'))
end
+ # A human saying "it arrived" outranks a carrier that never sent the
+ # last scan: every consignment still open is closed at the same time.
+ def close_open_deliveries
+ fulfillment.deliveries.undelivered.update_all(
+ status: 'delivered', delivered_at: delivered_at || Time.current, updated_at: Time.current
+ )
+ end
+
def mark_delivered
fulfillment.notify_customer = notify_customer
fulfillment.update!(status: 'delivered', delivered_at: delivered_at || Time.current)
diff --git a/spree/core/app/workflows/spree/fulfillments/purchase_label.rb b/spree/core/app/workflows/spree/fulfillments/purchase_label.rb
index 5c20367dde..d45e1cbfb9 100644
--- a/spree/core/app/workflows/spree/fulfillments/purchase_label.rb
+++ b/spree/core/app/workflows/spree/fulfillments/purchase_label.rb
@@ -9,21 +9,21 @@ module Spree
# never stop a merchant recording a parcel that physically left; here
# nothing has left, so a failed purchase simply fails and the merchant
# retries.
+ #
+ # Thin over Spree::ShippingLabels::Purchase, kept as its own workflow for
+ # the hooks that have been public since the label-leads amendment.
class PurchaseLabel < Spree::Workflow
hooks :validate, :after_purchase_label
# @param fulfillment [Spree::Fulfillment] the parcel to buy a label for
- # @return [Spree::ServiceModule::Result] the fulfillment with tracking
- # and label attached on success
+ # @return [Spree::ServiceModule::Result] the fulfillment with its label
+ # and delivery attached on success
def perform(fulfillment:)
super
run_hooks :validate
- step :ensure_purchasable
-
- # Carrier I/O — never inside a transaction.
- external_step :purchase
+ step :purchase
run_hooks :after_purchase_label
success(fulfillment.reload)
@@ -31,31 +31,9 @@ module Spree
private
- def ensure_purchasable
- unless fulfillment.provider.class.generates_labels?
- failure(fulfillment, Spree.t('fulfillments.errors.provider_has_no_labels'))
- end
-
- unless fulfillment.unfulfilled?
- failure(fulfillment, Spree.t('fulfillments.errors.cannot_purchase_label'))
- end
-
- failure(fulfillment, Spree.t('fulfillments.errors.order_draft')) if fulfillment.order&.draft?
- end
-
- # The provider is idempotent about an already-bought label (it returns
- # the stored purchase), so re-running after a partial failure is safe.
def purchase
- result = fulfillment.provider.create_fulfillment(fulfillment)
-
- unless result.is_a?(Hash) && result[:tracking_number].present?
- failure(fulfillment, Spree.t('fulfillments.errors.label_purchase_failed'))
- end
-
- return if fulfillment.tracking.present?
-
- # update! so carrier detection pins the badge and tracking URL.
- fulfillment.update!(tracking: result[:tracking_number])
+ result = Spree.shipping_label_purchase_workflow.call(owner: fulfillment)
+ failure(fulfillment, result.error.to_s) if result.failure?
end
end
end
diff --git a/spree/core/app/workflows/spree/fulfillments/update.rb b/spree/core/app/workflows/spree/fulfillments/update.rb
index 16c068ec9b..892769581e 100644
--- a/spree/core/app/workflows/spree/fulfillments/update.rb
+++ b/spree/core/app/workflows/spree/fulfillments/update.rb
@@ -20,7 +20,9 @@ module Spree
# @param fulfillment [Spree::Fulfillment] the fulfillment to update
# @param fulfillment_attributes [Hash] attributes to assign; +stock_location_id+
- # moves the fulfillment, +selected_delivery_rate_id+ changes its rate
+ # moves the fulfillment, +selected_delivery_rate_id+ changes its rate,
+ # +tracking+ (with +tracking_carrier+) creates or corrects the primary
+ # delivery — a corrected number starts its carrier journey over
# @param shipment [Spree::Fulfillment, nil] @deprecated use +fulfillment+
# @param shipment_attributes [Hash, nil] @deprecated use +fulfillment_attributes+
# @return [Spree::ServiceModule::Result] the updated fulfillment on success
@@ -35,7 +37,9 @@ module Spree
end
@fulfillment = fulfillment || shipment
- @attributes = (fulfillment_attributes || shipment_attributes || {}).to_h
+ @attributes = (fulfillment_attributes || shipment_attributes || {}).to_h.with_indifferent_access
+ @tracking = @attributes.delete(:tracking)
+ @tracking_carrier = @attributes.delete(:tracking_carrier)
@origin_changed = origin_change?
# Veto point — per-location policy, 3PL capacity, cut-off windows.
@@ -44,6 +48,7 @@ module Spree
ApplicationRecord.transaction do
step :assign_attributes
+ step :apply_tracking
step :requote_after_origin_change
step :reprice_after_rate_change
end
@@ -66,6 +71,24 @@ module Spree
failure(@fulfillment) unless @fulfillment.update(@attributes)
end
+ def apply_tracking
+ return if @tracking.blank?
+
+ primary = @fulfillment.primary_delivery
+ if primary
+ attributes = { tracking_number: @tracking.to_s.squish }
+ attributes[:carrier] = @tracking_carrier if @tracking_carrier.present?
+ attributes[:status] = 'pending' if attributes[:tracking_number] != primary.tracking_number
+ failure(primary) unless primary.update(attributes)
+ return
+ end
+
+ result = Spree.delivery_create_service.call(
+ owner: @fulfillment, tracking_number: @tracking, carrier: @tracking_carrier
+ )
+ failure(@fulfillment, result.error.to_s) if result.failure?
+ end
+
def requote_after_origin_change
return unless @origin_changed
@@ -95,14 +118,13 @@ module Spree
end
def rate_change?
- @attributes.key?(:selected_shipping_rate_id) || @attributes.key?('selected_shipping_rate_id') ||
- @attributes.key?(:selected_delivery_rate_id) || @attributes.key?('selected_delivery_rate_id')
+ @attributes.key?(:selected_shipping_rate_id) || @attributes.key?(:selected_delivery_rate_id)
end
# True only when the caller is actually moving the fulfillment, not
# resubmitting the location it already has.
def origin_change?
- requested = @attributes[:stock_location_id] || @attributes['stock_location_id']
+ requested = @attributes[:stock_location_id]
return false if requested.blank?
requested.to_s != @fulfillment.stock_location_id.to_s
diff --git a/spree/core/app/workflows/spree/fulfillments/update_tracking.rb b/spree/core/app/workflows/spree/fulfillments/update_tracking.rb
index 605732b8d6..eb8969de4e 100644
--- a/spree/core/app/workflows/spree/fulfillments/update_tracking.rb
+++ b/spree/core/app/workflows/spree/fulfillments/update_tracking.rb
@@ -1,90 +1,28 @@
module Spree
module Fulfillments
- # Records what the carrier says about a parcel in flight.
- #
- # This is the second axis: it never moves the fulfillment backwards and
- # never contradicts the merchant. A parcel that bounces or is damaged shows
- # up here as `return_to_sender` or `failure` while `status` still says
- # `fulfilled` — the merchant did hand it over, and that fact does not
- # change because the carrier had a bad day. The one status it does write is
- # `delivered`, by delegating to {MarkDelivered}.
- #
- # Providers call this from their webhook handlers, so it accepts the
- # already-normalized vocabulary rather than any carrier's raw payload:
- # translating a provider's status names is the provider gem's job.
+ # @deprecated Tracking is a Spree::Delivery since 6.0 — use
+ # Spree::Deliveries::UpdateTracking with +delivery:+. This shell resolves
+ # the fulfillment's primary delivery for one release; removed in 6.1.
class UpdateTracking < Spree::Workflow
hooks :validate, :after_update_tracking
- # @param fulfillment [Spree::Fulfillment] the fulfillment being tracked
- # @param tracking_status [String, nil] one of
- # {Spree::Fulfillment::TRACKING_STATUSES}
- # @param estimated_delivery_at [Time, nil] carrier's current estimate
- # @param delivered_at [Time, nil] when the carrier says it arrived; used
- # only when +tracking_status+ is `delivered`
- # @param details [Hash, nil] provider payload worth keeping — scan events,
- # the signature, the failure reason
- # @param notify_customer [Boolean] passed through to {MarkDelivered} when
- # this update completes the delivery
- # @return [Spree::ServiceModule::Result] the updated fulfillment on success
- def perform(fulfillment:, tracking_status: nil, estimated_delivery_at: nil, delivered_at: nil,
- details: nil, notify_customer: true)
- super
+ # @param fulfillment [Spree::Fulfillment]
+ # @return [Spree::ServiceModule::Result] the fulfillment on success
+ def perform(fulfillment:, **arguments)
+ super(fulfillment: fulfillment)
- run_hooks :validate
-
- step :ensure_known_status
- step :apply_carrier_report
- step :confirm_delivery_if_reported
-
- run_hooks :after_update_tracking
- success(fulfillment.reload)
- end
-
- private
-
- def ensure_known_status
- return if tracking_status.blank?
- return if Spree::Fulfillment::TRACKING_STATUSES.include?(tracking_status.to_s)
-
- failure(fulfillment, Spree.t('fulfillments.errors.unknown_tracking_status', status: tracking_status))
- end
-
- # Overwrite rather than accumulate: this axis answers "where is it now",
- # and carriers resend the whole picture on every update. Only attributes
- # the caller actually supplied are touched, so a webhook carrying just a
- # scan does not wipe an estimate from an earlier one.
- def apply_carrier_report
- attributes = {}
- attributes[:tracking_status] = tracking_status.to_s if tracking_status.present?
- attributes[:estimated_delivery_at] = estimated_delivery_at unless estimated_delivery_at.nil?
- attributes[:tracking_details] = details unless details.nil?
-
- return if attributes.empty?
-
- # update_columns, deliberately: carrier scans arrive many times per
- # parcel, and a lifecycle event per scan would run the full order
- # status rollup (via Spree::OrderStatusSubscriber) for writes that
- # cannot change any status. The after_update_tracking hook and the
- # fulfillment.delivered event are the notification surface for this
- # axis. Values are already validated by ensure_known_status.
- fulfillment.update_columns(attributes.merge(updated_at: Time.current))
- end
-
- # Delivery is the one carrier report that is also a merchant fact, so it
- # crosses over to the status axis — but only from `fulfilled`, and
- # MarkDelivered enforces that. A carrier reporting delivery on a canceled
- # parcel is noise on the tracking axis, not a lifecycle event.
- def confirm_delivery_if_reported
- return unless tracking_status.to_s == 'delivered'
- return unless fulfillment.can_mark_delivered?
-
- result = Spree.fulfillment_mark_delivered_workflow.call(
- fulfillment: fulfillment,
- delivered_at: delivered_at,
- notify_customer: notify_customer
+ Spree::Deprecation.warn(
+ 'Spree::Fulfillments::UpdateTracking is deprecated and will be removed in Spree 6.1. ' \
+ 'Use Spree::Deliveries::UpdateTracking with delivery: instead.'
)
+ delivery = fulfillment.primary_delivery
+ failure(fulfillment, Spree.t('deliveries.errors.not_found')) if delivery.nil?
+
+ result = Spree.delivery_update_tracking_workflow.call(delivery: delivery, **arguments)
failure(fulfillment, result.error.to_s) if result.failure?
+
+ success(fulfillment.reload)
end
end
end
diff --git a/spree/core/app/workflows/spree/orders/cancel.rb b/spree/core/app/workflows/spree/orders/cancel.rb
index 9d52dbca1c..7c8729f157 100644
--- a/spree/core/app/workflows/spree/orders/cancel.rb
+++ b/spree/core/app/workflows/spree/orders/cancel.rb
@@ -130,7 +130,7 @@ module Spree
# going out either way, and the failure surfaces through the provider.
def notify_fulfillment_providers
order.fulfillments.each do |fulfillment|
- fulfillment.provider.cancel_fulfillment(fulfillment)
+ Spree::Fulfillments::StandDownProvider.new.call(fulfillment: fulfillment)
end
end
diff --git a/spree/core/app/workflows/spree/returns/purchase_label.rb b/spree/core/app/workflows/spree/returns/purchase_label.rb
new file mode 100644
index 0000000000..0243d0229d
--- /dev/null
+++ b/spree/core/app/workflows/spree/returns/purchase_label.rb
@@ -0,0 +1,32 @@
+module Spree
+ module Returns
+ # Buys the customer's return label: an inbound parcel from the address
+ # the order shipped to back to the return's stock location, bought
+ # through the provider that shipped the goods out. The label attaches to
+ # the return as its owner and mints the inbound delivery, whose arrival
+ # never receives the return — Spree::Returns::Receive stays a staff act.
+ class PurchaseLabel < Spree::Workflow
+ hooks :validate, :after_purchase_label
+
+ # @param return_record [Spree::Return]
+ # @return [Spree::ServiceModule::Result] the return with its label on success
+ def perform(return_record:)
+ super
+
+ run_hooks :validate
+
+ step :purchase
+
+ run_hooks :after_purchase_label
+ success(return_record.reload)
+ end
+
+ private
+
+ def purchase
+ result = Spree.shipping_label_purchase_workflow.call(owner: return_record)
+ failure(return_record, result.error.to_s) if result.failure?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/shipping_labels/purchase.rb b/spree/core/app/workflows/spree/shipping_labels/purchase.rb
new file mode 100644
index 0000000000..9ad9554377
--- /dev/null
+++ b/spree/core/app/workflows/spree/shipping_labels/purchase.rb
@@ -0,0 +1,129 @@
+module Spree
+ module ShippingLabels
+ # Buys a carrier label for a parcel through the owner's fulfillment
+ # provider and records it as a Spree::ShippingLabel with the delivery it
+ # mints (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ #
+ # Idempotency lives here, not in the provider: an owner already holding an
+ # active label is refused, so a provider is never asked twice and needs no
+ # bookkeeping of its own. The file is fetched into private storage right
+ # after purchase; a fetch that fails is retried in the background and the
+ # provider's URL is kept until then.
+ #
+ # In the workflow tier for the carrier I/O and its hooks: a host app that
+ # wants to veto a purchase (a cut-off window, a carrier allowlist) or act
+ # on a bought label (print queue, cost ledger) hangs it here.
+ class Purchase < Spree::Workflow
+ hooks :validate, :after_purchase
+
+ # The label that was bought, readable by hook handlers.
+ attr_reader :shipping_label
+
+ # @param owner [Spree::Fulfillment, Spree::Return] what the label ships
+ # @return [Spree::ServiceModule::Result] the shipping label on success
+ def perform(owner:)
+ super
+
+ run_hooks :validate
+
+ step :ensure_purchasable
+
+ # Carrier I/O — never inside a transaction.
+ external_step :purchase
+
+ ApplicationRecord.transaction do
+ step :record_label
+ step :record_delivery
+ end
+
+ external_step :store_file
+
+ shipping_label.publish_event('shipping_label.purchased')
+ run_hooks :after_purchase
+ success(shipping_label.reload)
+ end
+
+ private
+
+ def provider
+ @provider ||= owner.provider
+ end
+
+ def ensure_purchasable
+ failure(owner, Spree.t('shipping_labels.errors.provider_has_no_labels')) unless provider.class.generates_labels?
+ failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+
+ case owner
+ when Spree::Fulfillment
+ failure(owner, Spree.t('fulfillments.errors.cannot_purchase_label')) unless owner.unfulfilled?
+ failure(owner, Spree.t('fulfillments.errors.order_draft')) if owner.order&.draft?
+ when Spree::Return
+ failure(owner, Spree.t('shipping_labels.errors.return_closed')) if owner.received? || owner.refunded? || owner.canceled?
+ end
+ end
+
+ def purchase
+ @purchase = provider.purchase_label(owner)
+
+ return if @purchase.is_a?(Spree::LabelPurchase) && @purchase.valid?
+
+ failure(owner, Spree.t('fulfillments.errors.label_purchase_failed'))
+ end
+
+ def record_label
+ @shipping_label = owner.shipping_labels.create!(
+ store: owner.store,
+ integration: provider.integration_for(owner),
+ source: 'purchased',
+ status: 'purchased',
+ external_id: @purchase.external_id,
+ carrier: @purchase.carrier,
+ service: @purchase.service,
+ tracking_number: @purchase.tracking_number,
+ cost: @purchase.cost || 0,
+ currency: @purchase.currency,
+ format: @purchase.format,
+ metadata: (@purchase.metadata || {}).merge('file_url' => @purchase.file_url).compact
+ )
+ end
+
+ # A label mints its own consignment. When the merchant already typed the
+ # same number by hand, that delivery becomes the label's rather than a
+ # duplicate row being refused.
+ def record_delivery
+ existing = owner.deliveries.find_by(tracking_number: @purchase.tracking_number)
+
+ if existing
+ existing.update!(
+ shipping_label: shipping_label,
+ carrier: @purchase.carrier.presence || existing.carrier,
+ service: @purchase.service.presence || existing.service,
+ tracking_url: @purchase.tracking_url.presence || existing.read_attribute(:tracking_url)
+ )
+ return
+ end
+
+ result = Spree.delivery_create_service.call(
+ owner: owner,
+ tracking_number: @purchase.tracking_number,
+ carrier: @purchase.carrier,
+ service: @purchase.service,
+ tracking_url: @purchase.tracking_url,
+ shipping_label: shipping_label
+ )
+ failure(shipping_label, result.error.to_s) if result.failure?
+ end
+
+ # The purchase is recorded whether or not the file comes down now — a
+ # slow carrier CDN must not lose a label the merchant has paid for.
+ def store_file
+ return if @purchase.file_url.blank?
+
+ result = Spree.shipping_label_store_file_service.call(shipping_label: shipping_label)
+ return if result.success?
+
+ Spree::ShippingLabels::StoreFileJob.perform_later(shipping_label.id)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/shipping_labels/record.rb b/spree/core/app/workflows/spree/shipping_labels/record.rb
new file mode 100644
index 0000000000..bbb3f5f0f7
--- /dev/null
+++ b/spree/core/app/workflows/spree/shipping_labels/record.rb
@@ -0,0 +1,108 @@
+module Spree
+ module ShippingLabels
+ # Records a label the merchant bought elsewhere — postage from a carrier
+ # site, a 3PL's PDF — so the parcel still has its file, its tracking
+ # number and what it cost, with no carrier integration involved.
+ #
+ # The uploaded label mints its delivery like a purchased one; what it
+ # cannot do is be refunded through Spree, so deleting it is the way out.
+ class Record < Spree::Workflow
+ hooks :validate, :after_record
+
+ # The label that was recorded, readable by hook handlers.
+ attr_reader :shipping_label
+
+ # @param owner [Spree::Fulfillment, Spree::Return]
+ # @param file [ActionDispatch::Http::UploadedFile, String] the file, or a signed blob id from a direct upload
+ # @param tracking_number [String] the number printed on the label
+ # @param carrier [String, nil] free text; detected from the number when omitted
+ # @param service [String, nil]
+ # @param cost [Numeric, nil] what the merchant paid; 0 when unknown
+ # @param currency [String, nil]
+ # @param file_format [String, nil] pdf | png | zpl; taken from the file when omitted
+ # @param tracking_url [String, nil]
+ # @return [Spree::ServiceModule::Result] the shipping label on success
+ def perform(owner:, file:, tracking_number:, carrier: nil, service: nil, cost: nil, currency: nil, file_format: nil, tracking_url: nil)
+ super
+
+ run_hooks :validate
+
+ step :ensure_recordable
+
+ ApplicationRecord.transaction do
+ step :record_label
+ step :record_delivery
+ end
+
+ run_hooks :after_record
+ success(shipping_label.reload)
+ end
+
+ private
+
+ def ensure_recordable
+ failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+ failure(owner, Spree.t('shipping_labels.errors.tracking_number_required')) if tracking_number.blank?
+ failure(owner, Spree.t('shipping_labels.errors.file_required')) if file.blank?
+
+ case owner
+ when Spree::Fulfillment
+ failure(owner, Spree.t('fulfillments.errors.cannot_purchase_label')) if owner.canceled? || owner.delivered?
+ when Spree::Return
+ failure(owner, Spree.t('shipping_labels.errors.return_closed')) if owner.received? || owner.refunded? || owner.canceled?
+ end
+ end
+
+ def record_label
+ @shipping_label = owner.shipping_labels.new(
+ store: owner.store,
+ source: 'uploaded',
+ status: 'purchased',
+ carrier: carrier,
+ service: service,
+ tracking_number: tracking_number,
+ cost: cost.presence || 0,
+ currency: currency.presence || owner.store.default_currency,
+ file: file
+ )
+ @shipping_label.format = file_format.presence || format_from_file
+ failure(@shipping_label) unless @shipping_label.save
+ end
+
+ # A direct-upload blob carries the type the client declared, which the
+ # attachment validator re-decides from the bytes; either way the
+ # extension is the merchant-visible answer, so it wins when it names a
+ # format Spree knows.
+ def format_from_file
+ blob = @shipping_label.file.blob
+ extension = File.extname(blob&.filename.to_s).delete('.').downcase
+ return extension if Spree::ShippingLabel::FORMATS.include?(extension)
+
+ case blob&.content_type.to_s
+ when 'image/png' then 'png'
+ when 'text/plain', 'application/zpl' then 'zpl'
+ else 'pdf'
+ end
+ end
+
+ def record_delivery
+ existing = owner.deliveries.find_by(tracking_number: shipping_label.tracking_number)
+
+ if existing
+ existing.update!(shipping_label: shipping_label, carrier: carrier.presence || existing.carrier)
+ return
+ end
+
+ result = Spree.delivery_create_service.call(
+ owner: owner,
+ tracking_number: shipping_label.tracking_number,
+ carrier: carrier,
+ service: service,
+ tracking_url: tracking_url,
+ shipping_label: shipping_label
+ )
+ failure(shipping_label, result.error.to_s) if result.failure?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/shipping_labels/refund.rb b/spree/core/app/workflows/spree/shipping_labels/refund.rb
new file mode 100644
index 0000000000..3c716b762d
--- /dev/null
+++ b/spree/core/app/workflows/spree/shipping_labels/refund.rb
@@ -0,0 +1,69 @@
+module Spree
+ module ShippingLabels
+ # Asks the carrier to refund a purchased label. The carrier answers
+ # either way at once (+refunded+) or later (+refund_requested+, settled
+ # through Spree::ShippingLabels::ConfirmRefund); an uploaded label has
+ # nothing to refund and is deleted instead.
+ #
+ # The delivery the label minted is removed only when the consignment
+ # never moved — once the parcel has shipped the journey is history and
+ # the delivery stays, label or no label.
+ class Refund < Spree::Workflow
+ hooks :validate, :after_refund
+
+ # @param shipping_label [Spree::ShippingLabel]
+ # @return [Spree::ServiceModule::Result] the label on success
+ def perform(shipping_label:)
+ super
+
+ run_hooks :validate
+
+ step :ensure_refundable
+
+ # Carrier I/O — never inside a transaction.
+ external_step :refund
+
+ ApplicationRecord.transaction do
+ step :record_outcome
+ step :remove_delivery_if_never_moved
+ end
+
+ shipping_label.publish_event('shipping_label.refunded') if shipping_label.refunded?
+ run_hooks :after_refund
+ success(shipping_label.reload)
+ end
+
+ private
+
+ def ensure_refundable
+ failure(shipping_label, Spree.t('shipping_labels.errors.uploaded_not_refundable')) if shipping_label.uploaded?
+ failure(shipping_label, Spree.t('shipping_labels.errors.not_refundable')) unless shipping_label.purchased?
+ end
+
+ def refund
+ @outcome = shipping_label.owner.provider.refund_label(shipping_label).to_s
+
+ return if %w[refunded refund_requested].include?(@outcome)
+
+ failure(shipping_label, Spree.t('shipping_labels.errors.refund_failed'))
+ end
+
+ def record_outcome
+ attributes = { status: @outcome }
+ attributes[:refunded_at] = Time.current if @outcome == 'refunded'
+ shipping_label.update!(attributes)
+ end
+
+ def remove_delivery_if_never_moved
+ delivery = shipping_label.delivery
+ return if delivery.nil?
+
+ owner = shipping_label.owner
+ moved = owner.is_a?(Spree::Fulfillment) ? owner.fulfilled_or_delivered? : owner.received?
+ return if moved
+
+ delivery.destroy!
+ end
+ end
+ end
+end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 099a87785a..229a487cd7 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -1098,6 +1098,24 @@ en:
order_not_paid: This order is not paid for yet
provider_has_no_labels: This delivery method's provider does not produce labels
unknown_tracking_status: "%{status} is not a known tracking status"
+ deliveries:
+ errors:
+ has_label: This delivery was created by a shipping label — refund the label instead of deleting the delivery
+ not_found: This fulfillment has no delivery to track yet
+ shipping_labels:
+ errors:
+ already_purchased: This parcel already has an active shipping label
+ file_fetch_failed: The label file could not be fetched from the carrier (HTTP %{status})
+ file_required: An uploaded label needs a file
+ no_file_url: The carrier did not provide a file for this label
+ not_refund_requested: Only a label awaiting the carrier's refund decision can be confirmed refunded
+ not_refundable: Only a purchased label that has not been refunded can be refunded
+ provider_has_no_labels: This delivery method's provider does not produce labels
+ purchased_not_deletable: A purchased label is refunded, never deleted
+ refund_failed: The carrier refused to refund this label
+ return_closed: A return label can only be bought while the return is open
+ tracking_number_required: An uploaded label needs its tracking number
+ uploaded_not_refundable: An uploaded label was not bought through Spree and cannot be refunded — delete it instead
gateway: Gateway
gateway_error: Gateway Error
general: General
diff --git a/spree/core/db/migrate/20260811000001_add_delivery_tracking_to_fulfillments.rb b/spree/core/db/migrate/20260811000001_add_delivery_tracking_to_fulfillments.rb
index f8e4003e60..ede09b282e 100644
--- a/spree/core/db/migrate/20260811000001_add_delivery_tracking_to_fulfillments.rb
+++ b/spree/core/db/migrate/20260811000001_add_delivery_tracking_to_fulfillments.rb
@@ -1,26 +1,16 @@
class AddDeliveryTrackingToFulfillments < ActiveRecord::Migration[8.1]
- # The carrier axis (docs/plans/6.0-fulfillment-and-delivery.md, "Status model
- # — two axes"): what the carrier reports, kept apart from what the merchant
- # did. Overwritten on every carrier update, so no history table and no
- # transition graph.
+ # The lifecycle stamp for confirmed receipt (docs/plans/6.0-fulfillment-and-delivery.md,
+ # "Status model — two axes"). The carrier axis itself — status, estimate,
+ # scan details, carrier — lives on spree_deliveries
+ # (docs/plans/6.0-shipping-labels-and-deliveries.md), never here.
#
# Status values themselves are remapped by spree:migrate_fulfillment_statuses
# rather than here — data transformations never live in migrations.
def change
- change_table :spree_fulfillments, bulk: true do |t|
- t.string :tracking_status
- t.datetime :estimated_delivery_at
- t.datetime :delivered_at
+ add_column :spree_fulfillments, :delivered_at, :datetime
- if t.respond_to?(:jsonb)
- t.jsonb :tracking_details
- else
- t.json :tracking_details
- end
- end
-
- # Carrier webhooks arrive keyed by tracking code, so the lookup that
- # resolves one to a fulfillment has to be indexed.
+ # `tracking` is the 5.6 column spree:migrate_deliveries reads; it is
+ # dropped in 6.1 once every row has its delivery.
add_index :spree_fulfillments, :tracking
add_index :spree_fulfillments, :status
end
diff --git a/spree/core/db/migrate/20260811100001_add_tracking_carrier_to_fulfillments.rb b/spree/core/db/migrate/20260811100001_add_tracking_carrier_to_fulfillments.rb
deleted file mode 100644
index 5f821aa522..0000000000
--- a/spree/core/db/migrate/20260811100001_add_tracking_carrier_to_fulfillments.rb
+++ /dev/null
@@ -1,10 +0,0 @@
-class AddTrackingCarrierToFulfillments < ActiveRecord::Migration[8.1]
- # Which carrier a tracking number belongs to. One delivery method can quote
- # several carriers since the multi-rate work, so the method-level tracking
- # URL format cannot answer this; the carrier is pinned per fulfillment —
- # picked by the merchant, detected from the number's format, or implied by
- # the provider that bought the label.
- def change
- add_column :spree_fulfillments, :tracking_carrier, :string
- end
-end
diff --git a/spree/core/db/migrate/20260903000001_create_spree_shipping_labels_and_deliveries.rb b/spree/core/db/migrate/20260903000001_create_spree_shipping_labels_and_deliveries.rb
new file mode 100644
index 0000000000..20d9bff138
--- /dev/null
+++ b/spree/core/db/migrate/20260903000001_create_spree_shipping_labels_and_deliveries.rb
@@ -0,0 +1,62 @@
+class CreateSpreeShippingLabelsAndDeliveries < ActiveRecord::Migration[8.1]
+ # Two records with a polymorphic owner (Fulfillment | Return): a shipping
+ # label is the carrier document the merchant bought or uploaded, a delivery
+ # is one consignment's carrier journey (docs/plans/6.0-shipping-labels-and-deliveries.md).
+ # `status` on both is written by the creating workflow, never a database
+ # default.
+ def change
+ create_table :spree_shipping_labels do |t|
+ t.references :owner, polymorphic: true, null: false
+ t.references :store, null: false
+ t.references :integration
+ t.string :source, null: false
+ t.string :external_id
+ t.string :carrier
+ t.string :service
+ t.string :tracking_number
+ t.decimal :cost, precision: 10, scale: 2, null: false, default: 0
+ t.string :currency
+ t.string :format
+ t.string :status, null: false
+ t.datetime :refunded_at
+
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+
+ t.timestamps
+ end
+
+ add_index :spree_shipping_labels, [:owner_type, :owner_id, :status],
+ name: 'index_spree_shipping_labels_on_owner_and_status'
+
+ create_table :spree_deliveries do |t|
+ t.references :owner, polymorphic: true, null: false
+ t.references :store, null: false
+ t.references :shipping_label, index: { unique: true }
+ t.string :tracking_number, null: false
+ t.string :tracking_url
+ t.string :carrier
+ t.string :service
+ t.string :status, null: false
+ t.datetime :estimated_delivery_at
+ t.datetime :delivered_at
+
+ if t.respond_to?(:jsonb)
+ t.jsonb :details
+ else
+ t.json :details
+ end
+
+ t.timestamps
+ end
+
+ # Carrier webhooks arrive keyed by tracking number and are matched inside
+ # the integration's store.
+ add_index :spree_deliveries, [:store_id, :tracking_number]
+ add_index :spree_deliveries, [:owner_type, :owner_id, :tracking_number],
+ unique: true, name: 'index_spree_deliveries_on_owner_and_tracking_number'
+ end
+end
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index 0964ddd0e9..9e5d50491b 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -817,6 +817,11 @@ module Spree
module Core
class GatewayError < RuntimeError; end
+ # A label purchase that failed inside the one-click fulfill path, where
+ # the parcel ships regardless — reported so the merchant's error tracker
+ # sees why there is no label.
+ class LabelPurchaseFailed < RuntimeError; end
+
# The call may or may not have taken effect — a timeout, a dropped
# connection, anything that leaves the answer at the provider rather than
# in the response. Distinct from its parent because the safe reaction is
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 8d89ae0109..3974634a38 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -81,8 +81,22 @@ module Spree
fulfillment_cancel_workflow: 'Spree::Fulfillments::Cancel',
fulfillment_mark_delivered_workflow: 'Spree::Fulfillments::MarkDelivered',
fulfillment_purchase_label_workflow: 'Spree::Fulfillments::PurchaseLabel',
+ # @deprecated Tracking is a delivery since 6.0 — see
+ # delivery_update_tracking_workflow. The shell resolves the primary
+ # delivery one release; removed in 6.1.
fulfillment_update_tracking_workflow: 'Spree::Fulfillments::UpdateTracking',
+ # shipping labels + deliveries
+ shipping_label_purchase_workflow: 'Spree::ShippingLabels::Purchase',
+ shipping_label_refund_workflow: 'Spree::ShippingLabels::Refund',
+ shipping_label_record_workflow: 'Spree::ShippingLabels::Record',
+ shipping_label_confirm_refund_service: 'Spree::ShippingLabels::ConfirmRefund',
+ shipping_label_store_file_service: 'Spree::ShippingLabels::StoreFile',
+ delivery_update_tracking_workflow: 'Spree::Deliveries::UpdateTracking',
+ delivery_create_service: 'Spree::Deliveries::Create',
+ delivery_destroy_service: 'Spree::Deliveries::Destroy',
+ return_purchase_label_workflow: 'Spree::Returns::PurchaseLabel',
+
# returns
return_create_workflow: 'Spree::Returns::Create',
return_approve_workflow: 'Spree::Returns::Approve',
diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rb
index c3c649e7c9..20b2c86422 100644
--- a/spree/core/lib/spree/core/permission_configuration.rb
+++ b/spree/core/lib/spree/core/permission_configuration.rb
@@ -297,7 +297,9 @@ module Spree
Spree::CustomField, Spree::DigitalLink]
})
register_resource(:payments, group: :orders, subjects: -> { [Spree::Payment, Spree::PaymentSplit] })
- register_resource(:fulfillments, group: :orders, audiences: %i[seller], subjects: -> { [Spree::Fulfillment] })
+ register_resource(:fulfillments, group: :orders, audiences: %i[seller], subjects: -> {
+ [Spree::Fulfillment, Spree::ShippingLabel, Spree::Delivery]
+ })
register_resource(:refunds, group: :orders, subjects: -> { [Spree::Refund] })
register_resource(:gift_cards, group: :orders, subjects: -> {
[Spree::GiftCard, Spree::GiftCardBatch]
diff --git a/spree/core/lib/spree/testing_support/factories/delivery_factory.rb b/spree/core/lib/spree/testing_support/factories/delivery_factory.rb
new file mode 100644
index 0000000000..c8c4735ae8
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/delivery_factory.rb
@@ -0,0 +1,13 @@
+FactoryBot.define do
+ factory :delivery, class: Spree::Delivery do
+ association :owner, factory: :fulfillment, tracking: nil
+ store { owner.store }
+ sequence(:tracking_number) { |n| "1Z999AA1012345#{n.to_s.rjust(4, '0')}" }
+ status { 'pending' }
+
+ trait :delivered do
+ status { 'delivered' }
+ delivered_at { Time.current }
+ end
+ end
+end
diff --git a/spree/core/lib/spree/testing_support/factories/fulfillment_factory.rb b/spree/core/lib/spree/testing_support/factories/fulfillment_factory.rb
index 69e88af24a..d782645f6b 100644
--- a/spree/core/lib/spree/testing_support/factories/fulfillment_factory.rb
+++ b/spree/core/lib/spree/testing_support/factories/fulfillment_factory.rb
@@ -1,12 +1,18 @@
FactoryBot.define do
factory :fulfillment, aliases: [:shipment], class: Spree::Fulfillment do
- tracking { 'U10000' }
+ transient do
+ # Tracking is a Spree::Delivery since 6.0; the number given here becomes
+ # the fulfillment's primary delivery once it is created. nil for a
+ # parcel that has no tracking yet.
+ tracking { 'U10000' }
+ end
+
cost { 100.00 }
status { 'unfulfilled' }
order { cart.present? ? nil : association(:order) }
stock_location
- after(:create) do |fulfillment, _evalulator|
+ after(:create) do |fulfillment, evaluator|
fulfillment.add_delivery_method(create(:delivery_method), true)
(fulfillment.order || fulfillment.cart).line_items.map do |line_item|
fulfillment.fulfillment_items.create(
@@ -16,6 +22,11 @@ FactoryBot.define do
quantity: line_item.quantity
)
end
+
+ if evaluator.tracking.present?
+ create(:delivery, owner: fulfillment, store: fulfillment.store, tracking_number: evaluator.tracking)
+ fulfillment.deliveries.reset
+ end
end
end
end
diff --git a/spree/core/lib/spree/testing_support/factories/shipping_label_factory.rb b/spree/core/lib/spree/testing_support/factories/shipping_label_factory.rb
new file mode 100644
index 0000000000..af17523c41
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/shipping_label_factory.rb
@@ -0,0 +1,44 @@
+FactoryBot.define do
+ factory :shipping_label, class: Spree::ShippingLabel do
+ association :owner, factory: :fulfillment, tracking: nil
+ store { owner.store }
+ source { 'purchased' }
+ status { 'purchased' }
+ carrier { 'ups' }
+ service { 'Ground' }
+ sequence(:tracking_number) { |n| "1Z879E93034683#{n.to_s.rjust(4, '0')}" }
+ sequence(:external_id) { |n| "shp_#{n}" }
+ cost { 7.25 }
+ currency { 'USD' }
+ format { 'pdf' }
+
+ trait :uploaded do
+ source { 'uploaded' }
+ external_id { nil }
+ end
+
+ trait :with_file do
+ after(:build) do |shipping_label|
+ shipping_label.file.attach(
+ io: StringIO.new("%PDF-1.4\n%label\n"),
+ filename: 'label.pdf',
+ content_type: 'application/pdf'
+ )
+ end
+ end
+
+ trait :with_delivery do
+ after(:create) do |shipping_label|
+ create(
+ :delivery,
+ owner: shipping_label.owner,
+ store: shipping_label.store,
+ shipping_label: shipping_label,
+ tracking_number: shipping_label.tracking_number,
+ carrier: shipping_label.carrier
+ )
+ shipping_label.owner.deliveries.reset
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/testing_support/label_provider.rb b/spree/core/lib/spree/testing_support/label_provider.rb
new file mode 100644
index 0000000000..a9e45d99b6
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/label_provider.rb
@@ -0,0 +1,49 @@
+module Spree
+ module TestingSupport
+ # A fulfillment provider that "buys" labels without a carrier, for specs
+ # exercising the label workflows and the surfaces built on them.
+ class LabelProvider < Spree::FulfillmentProvider::Base
+ def self.generates_labels?
+ true
+ end
+
+ # Class-level so specs can swap the purchase or make it fail.
+ class << self
+ attr_accessor :purchase_result, :refund_result
+
+ def reset!
+ self.purchase_result = nil
+ self.refund_result = 'refunded'
+ end
+ end
+ reset!
+
+ def purchase_label(owner)
+ self.class.purchase_result || Spree::LabelPurchase.new(
+ external_id: "shp_#{owner.id}",
+ carrier: 'ups',
+ service: 'Ground',
+ tracking_number: '1Z879E930346834440',
+ tracking_url: 'https://tracker.example/1Z879E930346834440',
+ cost: 7.25,
+ currency: 'USD',
+ format: 'pdf',
+ file_url: 'https://carrier.example/label.pdf',
+ metadata: { 'tracker_id' => 'trk_1' }
+ )
+ end
+
+ def refund_label(_shipping_label)
+ self.class.refund_result
+ end
+
+ def create_fulfillment(_fulfillment)
+ {}
+ end
+
+ def cancel_fulfillment(_fulfillment)
+ true
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
index fcb1fd0c7f..c947e30332 100644
--- a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
+++ b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
@@ -241,6 +241,19 @@ steps:
migrate_delivery_profiles (it reads delivery-method providers to tell
pickup methods apart). Idempotent.
+ - id: migrate_deliveries
+ name: "Move tracking numbers onto deliveries"
+ task: "spree:migrate_deliveries"
+ notes: |
+ Every fulfillment carrying a 5.6 tracking number gets one delivery row
+ with that number: the carrier axis (tracking number, carrier, carrier
+ status, estimate, arrival) lives on spree_deliveries in 6.0, and the
+ fulfillment only summarizes its primary delivery. A pasted tracking link
+ lands in the delivery's tracking_url; the carrier is detected from the
+ number's format. Run after migrate_fulfillment_statuses. Idempotent —
+ a fulfillment that already has a delivery is skipped. No labels are
+ backfilled: nothing before 6.0 recorded one.
+
- id: migrate_zones_to_delivery_zones
name: "Convert delivery zones"
task: "spree:migrate_zones_to_delivery_zones"
diff --git a/spree/core/lib/tasks/deliveries_migration.rake b/spree/core/lib/tasks/deliveries_migration.rake
new file mode 100644
index 0000000000..f8a4fc651e
--- /dev/null
+++ b/spree/core/lib/tasks/deliveries_migration.rake
@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# 5.6 → 6.0: the tracking number that lived on the fulfillment becomes its
+# primary Spree::Delivery (docs/plans/6.0-shipping-labels-and-deliveries.md).
+# Idempotent — a fulfillment that already has a delivery for its number is
+# skipped, so an interrupted run resumes for free. Labels are not backfilled:
+# the provider metadata keys only ever existed on the unreleased 6.0 edge.
+namespace :spree do
+ desc 'Create a delivery for every fulfillment that carries a 5.6 tracking number'
+ task migrate_deliveries: :environment do
+ batch_size = ENV.fetch('BATCH_SIZE', 1_000).to_i
+ say = ->(message) { puts message }
+
+ created = 0
+ skipped = 0
+
+ # The column is dropped in 6.1; until then the model reads tracking from
+ # the delivery, so the legacy value is read straight off the row.
+ fulfillments = Spree::Fulfillment.unscoped.
+ where.not(tracking: [nil, '']).
+ where.not(id: Spree::Delivery.where(owner_type: 'Spree::Fulfillment').select(:owner_id))
+
+ fulfillments.includes(:order, :cart).find_in_batches(batch_size: batch_size) do |batch|
+ batch.each do |fulfillment|
+ tracking = fulfillment.read_attribute(:tracking).to_s.squish
+ store = fulfillment.owner&.store
+ if store.nil?
+ skipped += 1
+ next
+ end
+
+ # A dev database that ran the withdrawn 20260811 carrier migration
+ # still has the column; anywhere else it never existed.
+ carrier = fulfillment.has_attribute?(:tracking_carrier) ? fulfillment.read_attribute(:tracking_carrier) : nil
+
+ result = Spree::Deliveries::Create.new.call(
+ owner: fulfillment, tracking_number: tracking, carrier: carrier
+ )
+
+ if result.success?
+ created += 1
+ else
+ skipped += 1
+ say.call " skipped #{fulfillment.number}: #{result.error}"
+ end
+ end
+ end
+
+ say.call "spree_deliveries: #{created} created, #{skipped} skipped"
+ say.call 'migrate_deliveries done.'
+ end
+end
diff --git a/spree/core/spec/lib/tasks/six_zero_data_migrations_spec.rb b/spree/core/spec/lib/tasks/six_zero_data_migrations_spec.rb
index ae098609ee..a735e54e67 100644
--- a/spree/core/spec/lib/tasks/six_zero_data_migrations_spec.rb
+++ b/spree/core/spec/lib/tasks/six_zero_data_migrations_spec.rb
@@ -12,6 +12,7 @@ describe '6.0 data migration tasks' do
load Spree::Core::Engine.root.join('lib', 'tasks', 'order_market_backfill.rake')
load Spree::Core::Engine.root.join('lib', 'tasks', 'store_binding_migration.rake')
load Spree::Core::Engine.root.join('lib', 'tasks', 'fulfillment_statuses_migration.rake')
+ load Spree::Core::Engine.root.join('lib', 'tasks', 'deliveries_migration.rake')
load Spree::Core::Engine.root.join('lib', 'tasks', 'tax_zones_migration.rake')
load Spree::Core::Engine.root.join('lib', 'tasks', 'capture_methods_migration.rake')
load Spree::Core::Engine.root.join('lib', 'tasks', 'typed_stock_movements_migration.rake')
@@ -631,6 +632,51 @@ describe '6.0 data migration tasks' do
end
end
+ describe 'spree:migrate_deliveries' do
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+
+ before do
+ # A 5.6 row: the number on the fulfillment column, no delivery yet.
+ fulfillment.deliveries.destroy_all
+ fulfillment.update_column(:tracking, ' 1Z879E930346834440 ')
+ end
+
+ it 'gives every tracked fulfillment its primary delivery' do
+ run_task('spree:migrate_deliveries')
+
+ delivery = fulfillment.reload.primary_delivery
+ expect(delivery.tracking_number).to eq('1Z879E930346834440')
+ expect(delivery.carrier).to eq('ups')
+ expect(delivery.status).to eq('pending')
+ expect(delivery.store).to eq(store)
+ expect(fulfillment.tracking).to eq('1Z879E930346834440')
+ end
+
+ it 'lands a pasted link in tracking_url' do
+ fulfillment.update_column(:tracking, 'https://carrier.example/t/1')
+
+ run_task('spree:migrate_deliveries')
+
+ expect(fulfillment.reload.primary_delivery.read_attribute(:tracking_url)).to eq('https://carrier.example/t/1')
+ end
+
+ it 'is idempotent' do
+ run_task('spree:migrate_deliveries')
+ run_task('spree:migrate_deliveries')
+
+ expect(fulfillment.reload.deliveries.count).to eq(1)
+ end
+
+ it 'skips fulfillments without a legacy number' do
+ untracked = create(:fulfillment, order: order, tracking: nil)
+
+ run_task('spree:migrate_deliveries')
+
+ expect(untracked.reload.deliveries).to be_empty
+ end
+ end
+
describe 'spree:migrate_capture_methods' do
it 'converts capture-on-authorization into charging at checkout' do
payment_method = create(:payment_method, store: store)
diff --git a/spree/core/spec/models/spree/delivery_spec.rb b/spree/core/spec/models/spree/delivery_spec.rb
new file mode 100644
index 0000000000..d0544b678c
--- /dev/null
+++ b/spree/core/spec/models/spree/delivery_spec.rb
@@ -0,0 +1,129 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Delivery, type: :model do
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+
+ describe 'validations' do
+ it 'requires a tracking number' do
+ delivery = build(:delivery, owner: fulfillment, tracking_number: nil)
+
+ expect(delivery).not_to be_valid
+ expect(delivery.errors[:tracking_number]).to be_present
+ end
+
+ it 'refuses the same number twice on one owner' do
+ create(:delivery, owner: fulfillment, tracking_number: 'DUP-1')
+ duplicate = build(:delivery, owner: fulfillment, tracking_number: 'DUP-1')
+
+ expect(duplicate).not_to be_valid
+ end
+
+ it 'allows the same number on another owner' do
+ create(:delivery, owner: fulfillment, tracking_number: 'SHARED-1')
+ other = build(:delivery, owner: create(:fulfillment, order: create(:order, store: store), tracking: nil), tracking_number: 'SHARED-1')
+
+ expect(other).to be_valid
+ end
+
+ it 'rejects a status outside the carrier vocabulary' do
+ delivery = build(:delivery, owner: fulfillment, status: 'teleported')
+
+ expect(delivery).not_to be_valid
+ end
+
+ # A forwarder's PRO number belongs to a carrier the registry has never
+ # heard of, and must still be enterable.
+ it 'accepts a carrier the registry does not know' do
+ delivery = build(:delivery, owner: fulfillment, carrier: 'Maersk Line')
+
+ expect(delivery).to be_valid
+ expect(delivery.carrier_name).to eq('Maersk Line')
+ end
+ end
+
+ describe 'carrier detection' do
+ it 'pins the detected carrier when a recognisable number is saved' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: '1Z879E930346834440')
+
+ expect(delivery.carrier).to eq('ups')
+ expect(delivery.carrier_name).to eq('UPS')
+ end
+
+ it 'leaves an explicit pick alone' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: '1Z879E930346834440', carrier: 'inpost')
+
+ expect(delivery.carrier).to eq('inpost')
+ expect(delivery.carrier_name).to eq('InPost')
+ end
+
+ it 'pins nothing for an unrecognisable number' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: '421432')
+
+ expect(delivery.carrier).to be_nil
+ end
+ end
+
+ describe '#tracking_url' do
+ it 'returns a pasted link as-is' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: 'https://carrier.example/track/ABC')
+
+ expect(delivery.tracking_url).to eq('https://carrier.example/track/ABC')
+ end
+
+ it 'prefers the stored link' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: '1Z879E930346834440', tracking_url: 'https://tracker.example/t/1')
+
+ expect(delivery.tracking_url).to eq('https://tracker.example/t/1')
+ end
+
+ # The provider bought the label, so its tracker page wins over anything
+ # derived — it is the one link guaranteed to show this parcel.
+ it 'asks the owner provider next' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: 'RANDOM123')
+ allow(fulfillment).to receive(:provider).and_return(
+ instance_double(Spree::FulfillmentProvider::Manual, tracking_url: 'https://provider.example/t/1')
+ )
+ delivery.owner = fulfillment
+
+ expect(delivery.tracking_url).to eq('https://provider.example/t/1')
+ end
+
+ it 'builds from the pinned carrier registry entry' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: '421432', carrier: 'inpost')
+
+ expect(delivery.tracking_url).to eq('https://inpost.pl/sledzenie-przesylek?number=421432')
+ end
+
+ it 'uses the delivery method format when there is no carrier' do
+ allow(fulfillment.delivery_method).to receive(:build_tracking_url).with('ABC-1').and_return('https://method.example/ABC-1')
+ delivery = create(:delivery, owner: fulfillment, tracking_number: 'ABC-1')
+ delivery.owner = fulfillment
+
+ expect(delivery.tracking_url).to eq('https://method.example/ABC-1')
+ end
+
+ # No method, no carrier, no provider — a recognisable number still yields
+ # its carrier's page through the tracking_number gem.
+ it 'falls back to detection from the number format' do
+ delivery = create(:delivery, owner: fulfillment, tracking_number: '1Z879E930346834440', carrier: 'unknown_courier')
+ allow(fulfillment).to receive(:delivery_method).and_return(nil)
+ delivery.owner = fulfillment
+
+ expect(delivery.tracking_url).to include('ups.com')
+ end
+ end
+
+ describe 'scopes' do
+ it 'orders chronologically and tells delivered from open' do
+ fulfillment.deliveries.destroy_all
+ first = create(:delivery, owner: fulfillment, tracking_number: 'A1', created_at: 2.days.ago)
+ second = create(:delivery, :delivered, owner: fulfillment, tracking_number: 'A2')
+
+ expect(fulfillment.deliveries.chronological).to eq([first, second])
+ expect(fulfillment.deliveries.delivered).to eq([second])
+ expect(fulfillment.deliveries.undelivered).to eq([first])
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/shipment_spec.rb b/spree/core/spec/models/spree/shipment_spec.rb
index 93c48a4cca..d921ae58c7 100644
--- a/spree/core/spec/models/spree/shipment_spec.rb
+++ b/spree/core/spec/models/spree/shipment_spec.rb
@@ -183,20 +183,31 @@ describe Spree::Shipment, type: :model do
end
end
- describe 'tracking_status' do
- it 'accepts a carrier status' do
- shipment.tracking_status = 'in_transit'
- expect(shipment).to be_valid
+ # The carrier axis lives on Spree::Delivery; the fulfillment only ever
+ # summarizes its primary delivery.
+ describe 'tracking summary' do
+ it 'reads the primary delivery' do
+ shipment.deliveries.destroy_all
+ first = create(:delivery, owner: shipment, tracking_number: 'FIRST-1', tracking_url: 'https://t.example/1', created_at: 1.day.ago)
+ create(:delivery, owner: shipment, tracking_number: 'SECOND-2')
+
+ expect(shipment.reload.primary_delivery).to eq(first)
+ expect(shipment.tracking).to eq('FIRST-1')
+ expect(shipment.tracking_url).to eq('https://t.example/1')
+ expect(shipment).to be_tracked
end
- it 'rejects one outside the carrier vocabulary' do
- shipment.tracking_status = 'lost_in_space'
- expect(shipment).not_to be_valid
+ it 'is nil without a delivery' do
+ shipment.deliveries.destroy_all
+
+ expect(shipment.reload.tracking).to be_nil
+ expect(shipment.tracking_url).to be_nil
+ expect(shipment).not_to be_tracked
end
- it 'is optional' do
- shipment.tracking_status = nil
- expect(shipment).to be_valid
+ it 'has no carrier axis of its own' do
+ expect(shipment).not_to respond_to(:tracking_status)
+ expect(shipment).not_to respond_to(:tracking_carrier)
end
end
@@ -962,77 +973,26 @@ describe Spree::Shipment, type: :model do
end
end
- describe '#tracking_url' do
- it 'uses shipping method to determine url' do
- allow(shipping_method).to receive(:build_tracking_url).with('1Z12345').and_return(:some_url)
- shipment.tracking = '1Z12345'
-
- expect(shipment.tracking_url).to eq(:some_url)
- end
-
- it 'returns the tracking value as-is when it is already a full URL' do
- shipment.tracking = 'https://carrier.example/track/ABC'
-
- expect(shipment.tracking_url).to eq('https://carrier.example/track/ABC')
- end
-
- it 'is nil without a tracking number' do
- shipment.tracking = nil
-
- expect(shipment.tracking_url).to be_nil
- end
-
- # The provider bought the label, so its tracker page wins over anything
- # derived — it is the one link guaranteed to show this parcel.
- it 'prefers the fulfillment provider answer' do
- allow(shipment.provider).to receive(:tracking_url).with(shipment).and_return('https://provider.example/t/1')
- shipment.tracking = 'RANDOM123'
-
- expect(shipment.tracking_url).to eq('https://provider.example/t/1')
- end
-
- it 'builds from the pinned carrier registry entry' do
- shipment.tracking = '421432'
- shipment.tracking_carrier = 'inpost'
+ # Legacy writer — removed in 6.1. Host code assigning tracking the old way
+ # still lands it where every reader looks.
+ describe '#tracking= (deprecated)' do
+ before { allow(Spree::Deprecation).to receive(:warn) }
- expect(shipment.tracking_url).to eq('https://inpost.pl/sledzenie-przesylek?number=421432')
- end
-
- # No method, no carrier, no provider — a recognisable number still yields
- # its carrier's page through the tracking_number gem.
- it 'falls back to detection from the number format' do
- allow(shipment).to receive(:delivery_method).and_return(nil)
- shipment.tracking = '1Z879E930346834440'
+ it 'creates the primary delivery on save' do
+ shipment.deliveries.destroy_all
- expect(shipment.tracking_url).to include('ups.com')
- end
- end
-
- describe 'tracking carrier detection' do
- it 'pins the detected carrier when a recognisable number is saved' do
shipment.update!(tracking: '1Z879E930346834440')
- expect(shipment.tracking_carrier).to eq('ups')
- expect(shipment.tracking_carrier_name).to eq('UPS')
- end
-
- it 'leaves an explicit pick alone' do
- shipment.update!(tracking: '1Z879E930346834440', tracking_carrier: 'inpost')
-
- expect(shipment.tracking_carrier).to eq('inpost')
- expect(shipment.tracking_carrier_name).to eq('InPost')
- end
-
- it 'pins nothing for an unrecognisable number' do
- shipment.update!(tracking: '421432')
-
- expect(shipment.tracking_carrier).to be_nil
+ expect(Spree::Deprecation).to have_received(:warn).with(/tracking=/)
+ expect(shipment.reload.tracking).to eq('1Z879E930346834440')
+ expect(shipment.primary_delivery.carrier).to eq('ups')
end
- it 'titleizes a carrier the registry does not know' do
- shipment.tracking_carrier = 'some_courier'
+ it 'corrects the primary delivery when one exists' do
+ shipment.update!(tracking: 'CORRECTED-1')
- expect(shipment.tracking_carrier_name).to eq('Some Courier')
+ expect(shipment.reload.deliveries.count).to eq(1)
+ expect(shipment.tracking).to eq('CORRECTED-1')
end
end
diff --git a/spree/core/spec/models/spree/shipping_label_spec.rb b/spree/core/spec/models/spree/shipping_label_spec.rb
new file mode 100644
index 0000000000..32c0b53afd
--- /dev/null
+++ b/spree/core/spec/models/spree/shipping_label_spec.rb
@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+RSpec.describe Spree::ShippingLabel, type: :model do
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+
+ it 'accepts a fulfillment and a return as owners, nothing else' do
+ expect(build(:shipping_label, owner: fulfillment)).to be_valid
+ expect(build(:shipping_label, owner: create(:return, order: create(:shipped_order, store: store)))).to be_valid
+ expect(build(:shipping_label, owner: order)).not_to be_valid
+ end
+
+ it 'refuses an unknown source or format' do
+ expect(build(:shipping_label, owner: fulfillment, source: 'found')).not_to be_valid
+ expect(build(:shipping_label, owner: fulfillment, format: 'docx')).not_to be_valid
+ end
+
+ describe '#refundable?' do
+ it 'is true only for a purchased label that has not been refunded' do
+ expect(build(:shipping_label, owner: fulfillment)).to be_refundable
+ expect(build(:shipping_label, owner: fulfillment, status: 'refund_requested')).not_to be_refundable
+ expect(build(:shipping_label, :uploaded, owner: fulfillment)).not_to be_refundable
+ end
+ end
+
+ describe '.active' do
+ it 'excludes refunded labels' do
+ live = create(:shipping_label, owner: fulfillment)
+ create(:shipping_label, owner: fulfillment, status: 'refunded', refunded_at: Time.current)
+
+ expect(fulfillment.shipping_labels.active).to eq([live])
+ expect(fulfillment.active_shipping_label).to eq(live)
+ end
+ end
+
+ describe 'the file' do
+ it 'accepts a PDF and refuses a file whose bytes say otherwise' do
+ label = build(:shipping_label, :with_file, owner: fulfillment)
+ expect(label).to be_valid
+
+ spoofed = build(:shipping_label, owner: fulfillment)
+ spoofed.file.attach(io: StringIO.new('<html><script>alert(1)</script></html>'), filename: 'label.pdf', content_type: 'application/pdf')
+ expect(spoofed).not_to be_valid
+ end
+
+ it 'knows when the provider copy still has to be fetched' do
+ label = build(:shipping_label, owner: fulfillment, metadata: { 'file_url' => 'https://carrier.example/l.pdf' })
+
+ expect(label).to be_file_pending
+ expect(label.file_url).to eq('https://carrier.example/l.pdf')
+ end
+ end
+
+ it 'displays the cost in the label currency' do
+ label = build(:shipping_label, owner: fulfillment, cost: 7.25, currency: 'EUR')
+
+ expect(label.display_cost.to_s).to eq('€7.25')
+ end
+end
diff --git a/spree/core/spec/services/spree/deliveries/create_spec.rb b/spree/core/spec/services/spree/deliveries/create_spec.rb
new file mode 100644
index 0000000000..a47a5983c3
--- /dev/null
+++ b/spree/core/spec/services/spree/deliveries/create_spec.rb
@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Deliveries::Create do
+ subject(:service) { described_class.new }
+
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+
+ it 'records a consignment on the owner, in the owner store, starting pending' do
+ result = service.call(owner: fulfillment, tracking_number: ' 1Z879E930346834440 ')
+
+ expect(result).to be_success
+ delivery = result.value
+ expect(delivery.store).to eq(store)
+ expect(delivery.tracking_number).to eq('1Z879E930346834440')
+ expect(delivery.status).to eq('pending')
+ expect(delivery.carrier).to eq('ups')
+ expect(fulfillment.reload.deliveries).to include(delivery)
+ end
+
+ it 'copies a pasted link into tracking_url' do
+ result = service.call(owner: fulfillment, tracking_number: 'https://carrier.example/t/1')
+
+ expect(result.value.read_attribute(:tracking_url)).to eq('https://carrier.example/t/1')
+ end
+
+ it 'refuses a duplicate number on the same owner' do
+ service.call(owner: fulfillment, tracking_number: 'DUP-1')
+
+ result = service.call(owner: fulfillment, tracking_number: 'DUP-1')
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to include('Tracking number')
+ end
+
+ it 'works for a return owner' do
+ return_record = create(:return, order: create(:shipped_order, store: store))
+
+ result = service.call(owner: return_record, tracking_number: 'RET-1', carrier: 'Maersk')
+
+ expect(result).to be_success
+ expect(return_record.deliveries.first.carrier).to eq('Maersk')
+ end
+end
diff --git a/spree/core/spec/services/spree/deliveries/destroy_spec.rb b/spree/core/spec/services/spree/deliveries/destroy_spec.rb
new file mode 100644
index 0000000000..62d5bef342
--- /dev/null
+++ b/spree/core/spec/services/spree/deliveries/destroy_spec.rb
@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Deliveries::Destroy do
+ subject(:service) { described_class.new }
+
+ let(:store) { @default_store }
+ let(:fulfillment) { create(:order_ready_to_ship, store: store).fulfillments.first }
+
+ it 'removes a hand-entered delivery' do
+ delivery = fulfillment.deliveries.first
+
+ expect(service.call(delivery: delivery)).to be_success
+ expect(Spree::Delivery.exists?(delivery.id)).to be(false)
+ end
+
+ it 'refuses a delivery minted by a label' do
+ label = create(:shipping_label, :with_delivery, owner: fulfillment)
+
+ result = service.call(delivery: label.delivery)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('deliveries.errors.has_label'))
+ expect(label.reload.delivery).to be_present
+ end
+end
diff --git a/spree/core/spec/services/spree/shipping_labels/confirm_refund_spec.rb b/spree/core/spec/services/spree/shipping_labels/confirm_refund_spec.rb
new file mode 100644
index 0000000000..ade8cd40f3
--- /dev/null
+++ b/spree/core/spec/services/spree/shipping_labels/confirm_refund_spec.rb
@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+RSpec.describe Spree::ShippingLabels::ConfirmRefund do
+ subject(:service) { described_class.new }
+
+ let(:fulfillment) { create(:order_ready_to_ship, store: @default_store).fulfillments.first }
+
+ it 'settles a refund the carrier answered later', events: true do
+ label = create(:shipping_label, owner: fulfillment, status: 'refund_requested')
+ allow(Spree::Events).to receive(:publish).and_call_original
+
+ result = service.call(shipping_label: label, refunded_at: 1.hour.ago)
+
+ expect(result).to be_success
+ expect(label.reload).to be_refunded
+ expect(label.refunded_at).to be_within(1.second).of(1.hour.ago)
+ expect(Spree::Events).to have_received(:publish).with('shipping_label.refunded', anything, anything)
+ end
+
+ it 'refuses a label the carrier was never asked about' do
+ label = create(:shipping_label, owner: fulfillment)
+
+ expect(service.call(shipping_label: label)).to be_failure
+ expect(label.reload).to be_purchased
+ end
+end
diff --git a/spree/core/spec/services/spree/shipping_labels/store_file_spec.rb b/spree/core/spec/services/spree/shipping_labels/store_file_spec.rb
new file mode 100644
index 0000000000..8d1279b593
--- /dev/null
+++ b/spree/core/spec/services/spree/shipping_labels/store_file_spec.rb
@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+RSpec.describe Spree::ShippingLabels::StoreFile do
+ subject(:service) { described_class.new }
+
+ let(:store) { @default_store }
+ let(:fulfillment) { create(:order_ready_to_ship, store: store).fulfillments.first }
+ let(:label) { create(:shipping_label, owner: fulfillment, metadata: { 'file_url' => 'https://carrier.example/label.pdf' }) }
+
+ def http_response(code, body)
+ Net::HTTPResponse::CODE_TO_OBJ[code].new('1.1', code, 'x').tap do |response|
+ allow(response).to receive(:body).and_return(body)
+ end
+ end
+
+ it 'fetches the provider copy into private storage' do
+ allow(SsrfFilter).to receive(:get).with('https://carrier.example/label.pdf', anything).
+ and_return(http_response('200', "%PDF-1.4\n%label\n"))
+
+ result = service.call(shipping_label: label)
+
+ expect(result).to be_success
+ expect(label.reload.file).to be_attached
+ expect(label.file.filename.to_s).to end_with('.pdf')
+ expect(label).not_to be_file_pending
+ end
+
+ it 'fails without touching the label when the carrier answers an error' do
+ allow(SsrfFilter).to receive(:get).and_return(http_response('404', ''))
+
+ result = service.call(shipping_label: label)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to include('404')
+ expect(label.reload.file).not_to be_attached
+ end
+
+ it 'refuses a file whose bytes are not a label' do
+ allow(SsrfFilter).to receive(:get).and_return(http_response('200', '<html>nope</html>'))
+
+ expect(service.call(shipping_label: label)).to be_failure
+ expect(label.reload.file).not_to be_attached
+ end
+
+ it 'is a no-op once the file is stored' do
+ stored = create(:shipping_label, :with_file, owner: fulfillment)
+ expect(SsrfFilter).not_to receive(:get)
+
+ expect(service.call(shipping_label: stored)).to be_success
+ end
+end
diff --git a/spree/core/spec/workflows/spree/deliveries/update_tracking_spec.rb b/spree/core/spec/workflows/spree/deliveries/update_tracking_spec.rb
new file mode 100644
index 0000000000..31d549e4e7
--- /dev/null
+++ b/spree/core/spec/workflows/spree/deliveries/update_tracking_spec.rb
@@ -0,0 +1,108 @@
+require 'spec_helper'
+
+module Spree
+ describe Deliveries::UpdateTracking do
+ subject { described_class }
+
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+ let(:delivery) { fulfillment.deliveries.first }
+
+ before { Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment) }
+
+ it 'records what the carrier reports' do
+ result = subject.call(
+ delivery: delivery,
+ tracking_status: 'in_transit',
+ estimated_delivery_at: 2.days.from_now,
+ details: { 'last_scan' => 'Leipzig' }
+ )
+
+ expect(result.success?).to eq(true)
+ expect(delivery.reload.status).to eq('in_transit')
+ expect(delivery.estimated_delivery_at).to be_present
+ expect(delivery.details).to eq('last_scan' => 'Leipzig')
+ end
+
+ it 'refuses a status outside the carrier vocabulary' do
+ result = subject.call(delivery: delivery, tracking_status: 'teleported')
+
+ expect(result.success?).to eq(false)
+ expect(delivery.reload.status).to eq('pending')
+ end
+
+ # A webhook carrying only a scan must not wipe an estimate an earlier one
+ # supplied.
+ it 'leaves attributes the caller did not mention alone' do
+ subject.call(delivery: delivery, estimated_delivery_at: 3.days.from_now)
+ estimate = delivery.reload.estimated_delivery_at
+
+ subject.call(delivery: delivery, tracking_status: 'out_for_delivery')
+
+ expect(delivery.reload.estimated_delivery_at).to be_within(1.second).of(estimate)
+ end
+
+ describe 'when the carrier reports delivery' do
+ it 'stamps the delivery and confirms receipt on the fulfillment' do
+ arrived = 1.hour.ago
+
+ subject.call(delivery: delivery, tracking_status: 'delivered', delivered_at: arrived)
+
+ expect(delivery.reload.delivered_at).to be_within(1.second).of(arrived)
+ expect(fulfillment.reload).to be_delivered
+ expect(fulfillment.delivered_at).to be_within(1.second).of(arrived)
+ end
+
+ it 'waits for every consignment before the fulfillment is delivered' do
+ second = Spree::Deliveries::Create.new.call(owner: fulfillment, tracking_number: 'BOX-2').value
+
+ subject.call(delivery: delivery, tracking_status: 'delivered', delivered_at: 2.hours.ago)
+ expect(fulfillment.reload).to be_fulfilled
+
+ subject.call(delivery: second, tracking_status: 'delivered', delivered_at: 1.hour.ago)
+ expect(fulfillment.reload).to be_delivered
+ expect(fulfillment.delivered_at).to be_within(1.second).of(1.hour.ago)
+ end
+
+ # Goods arriving is not goods inspected: Returns::Receive stays a staff act.
+ it 'never transitions a return' do
+ return_record = create(:return, order: create(:shipped_order, store: store))
+ inbound = Spree::Deliveries::Create.new.call(owner: return_record, tracking_number: 'RET-1').value
+
+ result = subject.call(delivery: inbound, tracking_status: 'delivered')
+
+ expect(result).to be_success
+ expect(inbound.reload).to be_delivered
+ expect(return_record.reload).to be_requested
+ end
+ end
+
+ # The whole point of the second axis: a parcel that bounces is still a
+ # parcel the merchant handed over.
+ describe 'when the carrier reports a problem' do
+ it 'records the trouble without moving the fulfillment backwards' do
+ subject.call(delivery: delivery, tracking_status: 'return_to_sender')
+
+ expect(delivery.reload.status).to eq('return_to_sender')
+ expect(fulfillment.reload).to be_fulfilled
+ end
+
+ it 'records a failed delivery attempt the same way' do
+ subject.call(delivery: delivery, tracking_status: 'failure')
+
+ expect(fulfillment.reload).to be_fulfilled
+ expect(order.reload.fulfillment_status).to eq('fulfilled')
+ end
+ end
+
+ it 'ignores a delivery report for a canceled parcel' do
+ fulfillment.update!(status: 'canceled')
+
+ subject.call(delivery: delivery, tracking_status: 'delivered')
+
+ expect(fulfillment.reload).to be_canceled
+ expect(delivery.reload.status).to eq('delivered')
+ end
+ end
+end
diff --git a/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb b/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb
index 39f30fde48..20889adb78 100644
--- a/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb
@@ -52,6 +52,24 @@ module Spree
subject.call(fulfillment: fulfillment)
end
+ it 'refunds every active label first' do
+ label = create(:shipping_label, :with_delivery, owner: fulfillment)
+ allow(fulfillment).to receive(:provider).and_return(provider)
+ allow(provider).to receive(:refund_label).with(label).and_return('refunded')
+
+ subject.call(fulfillment: fulfillment)
+
+ expect(label.reload).to be_refunded
+ expect(provider).to have_received(:cancel_fulfillment)
+ end
+
+ it 'leaves the carrier alone when the caller batches provider calls' do
+ allow(fulfillment).to receive(:provider).and_return(provider)
+ expect(provider).not_to receive(:cancel_fulfillment)
+
+ subject.call(fulfillment: fulfillment, notify_provider: false)
+ end
+
# The whole reason this moved out of the transition callback: a slow or
# failing carrier must not hold the stock movements' row locks, and must
# not roll back a release that already happened.
diff --git a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
index 22ab0da400..c27bb51c87 100644
--- a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
@@ -1,4 +1,5 @@
require 'spec_helper'
+require 'spree/testing_support/label_provider'
module Spree
describe Fulfillments::Fulfill do
@@ -219,10 +220,21 @@ module Spree
end
describe 'tracking' do
- it 'stores the tracking number on the fulfillment that ships' do
+ it 'records the tracking number as the primary delivery of the fulfillment that ships' do
+ fulfillment.deliveries.destroy_all
+
subject.call(fulfillment: fulfillment, tracking: '1Z999')
expect(fulfillment.reload.tracking).to eq('1Z999')
+ expect(fulfillment.deliveries.count).to eq(1)
+ expect(fulfillment.primary_delivery.status).to eq('pending')
+ end
+
+ it 'corrects the primary delivery rather than adding a second one' do
+ subject.call(fulfillment: fulfillment, tracking: '1Z999')
+
+ expect(fulfillment.reload.deliveries.count).to eq(1)
+ expect(fulfillment.tracking).to eq('1Z999')
end
it 'puts tracking on the split fulfillment, not the remainder' do
@@ -289,7 +301,7 @@ module Spree
# The shipped email renders from the fulfilled event — it used to race
# the label purchase for the tracking number and sometimes lose.
it 'publishes the fulfilled event only after provider tracking is persisted' do
- fulfillment.update_column(:tracking, nil)
+ fulfillment.deliveries.destroy_all
allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(label_provider)
tracking_at_publish = :never_published
@@ -321,14 +333,56 @@ module Spree
it 'stores an explicit carrier beside the number' do
subject.call(fulfillment: fulfillment, tracking: '421432', tracking_carrier: 'inpost')
- expect(fulfillment.reload.tracking_carrier).to eq('inpost')
+ expect(fulfillment.reload.primary_delivery.carrier).to eq('inpost')
expect(fulfillment.tracking_url).to include('inpost.pl')
end
it 'detects the carrier from a recognisable number' do
+ fulfillment.deliveries.destroy_all
+
subject.call(fulfillment: fulfillment, tracking: '1Z879E930346834440')
- expect(fulfillment.reload.tracking_carrier).to eq('ups')
+ expect(fulfillment.reload.primary_delivery.carrier).to eq('ups')
+ end
+ end
+
+ describe 'buying the label on the way out' do
+ before do
+ Spree::TestingSupport::LabelProvider.reset!
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
+ fulfillment.deliveries.destroy_all
+ end
+
+ it 'buys the label before marking fulfilled and ships with its tracking' do
+ result = subject.call(fulfillment: fulfillment)
+
+ expect(result).to be_success
+ expect(fulfillment.reload).to be_fulfilled
+ expect(fulfillment.active_shipping_label).to be_present
+ expect(fulfillment.tracking).to eq('1Z879E930346834440')
+ end
+
+ it 'does not buy twice when a label was bought beforehand' do
+ Spree.fulfillment_purchase_label_workflow.call(fulfillment: fulfillment)
+
+ subject.call(fulfillment: fulfillment)
+
+ expect(fulfillment.reload.shipping_labels.count).to eq(1)
+ end
+
+ # A carrier outage must never stop a merchant recording a parcel that
+ # physically left.
+ it 'still fulfills when the purchase fails, and reports it' do
+ allow_any_instance_of(Spree::TestingSupport::LabelProvider).to receive(:purchase_label).and_return(nil)
+ allow(Rails.error).to receive(:report)
+
+ result = subject.call(fulfillment: fulfillment)
+
+ expect(result).to be_success
+ expect(fulfillment.reload).to be_fulfilled
+ expect(fulfillment.shipping_labels).to be_empty
+ expect(Rails.error).to have_received(:report)
end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/mark_delivered_spec.rb b/spree/core/spec/workflows/spree/fulfillments/mark_delivered_spec.rb
index 7bd8771e4c..3f87b5fa2f 100644
--- a/spree/core/spec/workflows/spree/fulfillments/mark_delivered_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/mark_delivered_spec.rb
@@ -77,5 +77,24 @@ module Spree
expect(observed).to eq('delivered')
end
end
+
+ # A human saying "it arrived" outranks a carrier that never sent its
+ # last scan: every open consignment closes with the fulfillment.
+ it 'closes every open delivery at the same time' do
+ second = Spree::Deliveries::Create.new.call(owner: fulfillment, tracking_number: 'BOX-2').value
+ arrived = 30.minutes.ago
+
+ subject.call(fulfillment: fulfillment, delivered_at: arrived)
+
+ expect(fulfillment.deliveries.reload.map(&:status).uniq).to eq(['delivered'])
+ expect(second.reload.delivered_at).to be_within(1.second).of(arrived)
+ end
+
+ it 'works for a fulfillment with no delivery at all' do
+ fulfillment.deliveries.destroy_all
+
+ expect(subject.call(fulfillment: fulfillment)).to be_success
+ expect(fulfillment.reload).to be_delivered
+ end
end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/purchase_label_spec.rb b/spree/core/spec/workflows/spree/fulfillments/purchase_label_spec.rb
index c36063af4d..0730d6cc09 100644
--- a/spree/core/spec/workflows/spree/fulfillments/purchase_label_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/purchase_label_spec.rb
@@ -1,4 +1,5 @@
require 'spec_helper'
+require 'spree/testing_support/label_provider'
module Spree
describe Fulfillments::PurchaseLabel do
@@ -8,22 +9,12 @@ module Spree
let(:order) { create(:order_ready_to_ship, store: store) }
let(:fulfillment) { order.fulfillments.first }
- let(:label_provider_class) do
- Class.new(Spree::FulfillmentProvider::Base) do
- def self.generates_labels?
- true
- end
-
- def create_fulfillment(_fulfillment)
- { tracking_number: '1Z879E930346834440', tracking_url: 'https://carrier.example/t/1' }
- end
- end
- end
-
before do
- allow(fulfillment).to receive(:provider).and_return(label_provider_class.new)
+ Spree::TestingSupport::LabelProvider.reset!
+ allow(fulfillment).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
# The factory seeds a tracking number; a parcel awaiting its label has none.
- fulfillment.update_column(:tracking, nil)
+ fulfillment.deliveries.destroy_all
end
it 'buys the label and attaches tracking without fulfilling' do
@@ -31,19 +22,20 @@ module Spree
expect(result).to be_success
expect(fulfillment.reload.tracking).to eq('1Z879E930346834440')
+ expect(fulfillment.active_shipping_label).to be_present
expect(fulfillment).to be_unfulfilled
end
- it 'pins the carrier detected from the purchased number' do
+ it 'pins the carrier the provider sold the label for' do
subject.call(fulfillment: fulfillment)
- expect(fulfillment.reload.tracking_carrier).to eq('ups')
+ expect(fulfillment.reload.primary_delivery.carrier).to eq('ups')
end
# The one-click fulfill degrades a label failure; here nothing has left
# the building, so failing loudly is the point.
it 'fails when the provider cannot produce a label' do
- allow(fulfillment.provider).to receive(:create_fulfillment).and_return({})
+ allow(fulfillment.provider).to receive(:purchase_label).and_return(nil)
result = subject.call(fulfillment: fulfillment)
@@ -58,7 +50,16 @@ module Spree
result = subject.call(fulfillment: fulfillment)
expect(result).to be_failure
- expect(result.error.to_s).to eq(Spree.t('fulfillments.errors.provider_has_no_labels'))
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.provider_has_no_labels'))
+ end
+
+ it 'refuses a second label while one is active' do
+ subject.call(fulfillment: fulfillment)
+
+ result = subject.call(fulfillment: fulfillment)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.already_purchased'))
end
it 'refuses a fulfillment that already shipped' do
@@ -67,21 +68,27 @@ module Spree
expect(subject.call(fulfillment: fulfillment)).to be_failure
end
- it 'refuses a draft order' do
- order.update_columns(status: 'draft', completed_at: nil)
+ it 'binds the label to a merchant-entered tracking number' do
+ Spree::Deliveries::Create.new.call(owner: fulfillment, tracking_number: '1Z879E930346834440')
- result = subject.call(fulfillment: fulfillment)
+ subject.call(fulfillment: fulfillment)
- expect(result).to be_failure
- expect(result.error.to_s).to eq(Spree.t('fulfillments.errors.order_draft'))
+ expect(fulfillment.reload.deliveries.count).to eq(1)
+ expect(fulfillment.primary_delivery.shipping_label).to be_present
end
- it 'keeps a merchant-entered tracking number' do
- fulfillment.update!(tracking: 'MERCHANT-123')
+ describe 'hooks' do
+ before { Spree.hooks.clear! }
+ after { Spree.hooks.clear! }
- subject.call(fulfillment: fulfillment)
+ it 'runs its own hooks around the purchase' do
+ seen = []
+ Spree.hooks.register('fulfillments.purchase_label.after_purchase_label') { |flow| seen << flow.fulfillment }
- expect(fulfillment.reload.tracking).to eq('MERCHANT-123')
+ subject.call(fulfillment: fulfillment)
+
+ expect(seen).to eq([fulfillment])
+ end
end
end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/update_spec.rb b/spree/core/spec/workflows/spree/fulfillments/update_spec.rb
index 239b485b52..de09e9b494 100644
--- a/spree/core/spec/workflows/spree/fulfillments/update_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/update_spec.rb
@@ -84,4 +84,31 @@ RSpec.describe Spree::Fulfillments::Update do
expect(fulfillment.reload.tracking).to eq('ABC123')
end
end
+
+ describe 'tracking' do
+ it 'creates the primary delivery from the tracking shortcut' do
+ fulfillment.deliveries.destroy_all
+
+ result = described_class.call(
+ fulfillment: fulfillment,
+ fulfillment_attributes: { tracking: '421432', tracking_carrier: 'inpost' }
+ )
+
+ expect(result).to be_success
+ expect(fulfillment.reload.tracking).to eq('421432')
+ expect(fulfillment.primary_delivery.carrier).to eq('inpost')
+ end
+
+ # A corrected number is a different parcel as far as the carrier is
+ # concerned, so its journey starts over.
+ it 'corrects the primary delivery and resets its carrier status' do
+ fulfillment.primary_delivery.update_columns(status: 'in_transit')
+
+ described_class.call(fulfillment: fulfillment, fulfillment_attributes: { tracking: 'NEW-1' })
+
+ expect(fulfillment.reload.deliveries.count).to eq(1)
+ expect(fulfillment.primary_delivery.tracking_number).to eq('NEW-1')
+ expect(fulfillment.primary_delivery.status).to eq('pending')
+ end
+ end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb b/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb
index 12beae9537..4dd07c7ddc 100644
--- a/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb
@@ -4,80 +4,24 @@ module Spree
describe Fulfillments::UpdateTracking do
subject { described_class }
- let(:store) { @default_store }
- let(:order) { create(:order_ready_to_ship, store: store) }
- let(:fulfillment) { order.fulfillments.first }
+ let(:fulfillment) { create(:order_ready_to_ship, store: @default_store).fulfillments.first }
before { Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment) }
- it 'records what the carrier reports' do
- result = subject.call(
- fulfillment: fulfillment,
- tracking_status: 'in_transit',
- estimated_delivery_at: 2.days.from_now,
- details: { 'last_scan' => 'Leipzig' }
- )
+ it 'resolves the primary delivery for legacy callers, with a warning' do
+ expect(Spree::Deprecation).to receive(:warn).with(/Deliveries::UpdateTracking/)
- expect(result.success?).to eq(true)
- expect(fulfillment.reload.tracking_status).to eq('in_transit')
- expect(fulfillment.estimated_delivery_at).to be_present
- expect(fulfillment.tracking_details).to eq('last_scan' => 'Leipzig')
- end
-
- it 'refuses a status outside the carrier vocabulary' do
- result = subject.call(fulfillment: fulfillment, tracking_status: 'teleported')
-
- expect(result.success?).to eq(false)
- expect(fulfillment.reload.tracking_status).to be_nil
- end
-
- # A webhook carrying only a scan must not wipe an estimate an earlier one
- # supplied.
- it 'leaves attributes the caller did not mention alone' do
- subject.call(fulfillment: fulfillment, estimated_delivery_at: 3.days.from_now)
- estimate = fulfillment.reload.estimated_delivery_at
-
- subject.call(fulfillment: fulfillment, tracking_status: 'out_for_delivery')
-
- expect(fulfillment.reload.estimated_delivery_at).to be_within(1.second).of(estimate)
- end
+ result = subject.call(fulfillment: fulfillment, tracking_status: 'in_transit')
- describe 'when the carrier reports delivery' do
- it 'confirms receipt on the status axis too' do
- arrived = 1.hour.ago
-
- subject.call(fulfillment: fulfillment, tracking_status: 'delivered', delivered_at: arrived)
-
- expect(fulfillment.reload).to be_delivered
- expect(fulfillment.delivered_at).to be_within(1.second).of(arrived)
- end
- end
-
- # The whole point of the second axis: a parcel that bounces is still a
- # parcel the merchant handed over.
- describe 'when the carrier reports a problem' do
- it 'records the trouble without moving the fulfillment backwards' do
- subject.call(fulfillment: fulfillment, tracking_status: 'return_to_sender')
-
- expect(fulfillment.reload.tracking_status).to eq('return_to_sender')
- expect(fulfillment).to be_fulfilled
- end
-
- it 'records a failed delivery attempt the same way' do
- subject.call(fulfillment: fulfillment, tracking_status: 'failure')
-
- expect(fulfillment.reload).to be_fulfilled
- expect(order.reload.fulfillment_status).to eq('fulfilled')
- end
+ expect(result).to be_success
+ expect(fulfillment.primary_delivery.reload.status).to eq('in_transit')
end
- it 'ignores a delivery report for a canceled parcel' do
- fulfillment.update!(status: 'canceled')
-
- subject.call(fulfillment: fulfillment, tracking_status: 'delivered')
+ it 'fails for a fulfillment with no delivery' do
+ allow(Spree::Deprecation).to receive(:warn)
+ fulfillment.deliveries.destroy_all
- expect(fulfillment.reload).to be_canceled
- expect(fulfillment.tracking_status).to eq('delivered')
+ expect(subject.call(fulfillment: fulfillment, tracking_status: 'in_transit')).to be_failure
end
end
end
diff --git a/spree/core/spec/workflows/spree/returns/purchase_label_spec.rb b/spree/core/spec/workflows/spree/returns/purchase_label_spec.rb
new file mode 100644
index 0000000000..cd48c1e234
--- /dev/null
+++ b/spree/core/spec/workflows/spree/returns/purchase_label_spec.rb
@@ -0,0 +1,41 @@
+require 'spec_helper'
+require 'spree/testing_support/label_provider'
+
+module Spree
+ describe Returns::PurchaseLabel do
+ subject { described_class }
+
+ let(:store) { @default_store }
+ let(:return_record) { create(:return, order: create(:shipped_order, store: store)) }
+
+ before do
+ Spree::TestingSupport::LabelProvider.reset!
+ allow(return_record).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
+ end
+
+ it 'buys the return label and records the inbound consignment' do
+ result = subject.call(return_record: return_record)
+
+ expect(result).to be_success
+ expect(return_record.reload.active_shipping_label.tracking_number).to eq('1Z879E930346834440')
+ expect(return_record.deliveries.first.tracking_number).to eq('1Z879E930346834440')
+ expect(return_record).to be_requested
+ end
+
+ it 'passes the purchase failure through' do
+ allow(return_record.provider).to receive(:purchase_label).and_return(nil)
+
+ result = subject.call(return_record: return_record)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('fulfillments.errors.label_purchase_failed'))
+ end
+
+ it 'ships through the provider of the outbound parcel' do
+ allow(return_record).to receive(:provider).and_call_original
+
+ expect(return_record.provider).to be_a(Spree::FulfillmentProvider::Base)
+ end
+ end
+end
diff --git a/spree/core/spec/workflows/spree/shipping_labels/purchase_spec.rb b/spree/core/spec/workflows/spree/shipping_labels/purchase_spec.rb
new file mode 100644
index 0000000000..a35372295d
--- /dev/null
+++ b/spree/core/spec/workflows/spree/shipping_labels/purchase_spec.rb
@@ -0,0 +1,161 @@
+require 'spec_helper'
+require 'spree/testing_support/label_provider'
+
+module Spree
+ describe ShippingLabels::Purchase do
+ subject { described_class }
+
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+ let(:provider) { Spree::TestingSupport::LabelProvider.new }
+
+ before do
+ Spree::TestingSupport::LabelProvider.reset!
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(provider)
+ fulfillment.deliveries.destroy_all
+ allow(SsrfFilter).to receive(:get).and_return(
+ Net::HTTPOK.new('1.1', '200', 'OK').tap { |response| allow(response).to receive(:body).and_return("%PDF-1.4\n%label\n") }
+ )
+ end
+
+ it 'records the label, mints its delivery and stores the file' do
+ result = subject.call(owner: fulfillment)
+
+ expect(result).to be_success
+ label = result.value
+ expect(label).to be_purchased
+ expect(label.source).to eq('purchased')
+ expect(label.store).to eq(store)
+ expect(label.tracking_number).to eq('1Z879E930346834440')
+ expect(label.cost).to eq(7.25)
+ expect(label.currency).to eq('USD')
+ expect(label.metadata).to include('tracker_id' => 'trk_1', 'file_url' => 'https://carrier.example/label.pdf')
+ expect(label.file).to be_attached
+
+ delivery = label.delivery
+ expect(delivery.tracking_number).to eq('1Z879E930346834440')
+ expect(delivery.carrier).to eq('ups')
+ expect(delivery.tracking_url).to eq('https://tracker.example/1Z879E930346834440')
+ expect(fulfillment.reload.tracking).to eq('1Z879E930346834440')
+ expect(fulfillment).to be_unfulfilled
+ end
+
+ it 'binds the label to a delivery the merchant already typed' do
+ Spree::Deliveries::Create.new.call(owner: fulfillment, tracking_number: '1Z879E930346834440')
+
+ subject.call(owner: fulfillment)
+
+ expect(fulfillment.reload.deliveries.count).to eq(1)
+ expect(fulfillment.deliveries.first.shipping_label).to eq(fulfillment.active_shipping_label)
+ end
+
+ it 'publishes shipping_label.purchased', events: true do
+ allow(Spree::Events).to receive(:publish).and_call_original
+
+ subject.call(owner: fulfillment)
+
+ expect(Spree::Events).to have_received(:publish).with('shipping_label.purchased', anything, anything)
+ end
+
+ # The purchase is a fact the moment the carrier charged for it; a slow
+ # label CDN must not lose it.
+ it 'keeps the purchase and retries the file in the background when the fetch fails' do
+ allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('down'))
+
+ expect { subject.call(owner: fulfillment) }.to have_enqueued_job(Spree::ShippingLabels::StoreFileJob)
+
+ label = fulfillment.reload.active_shipping_label
+ expect(label).to be_present
+ expect(label).to be_file_pending
+ end
+
+ it 'refuses a second label while one is active — providers are never asked twice' do
+ subject.call(owner: fulfillment)
+ expect(provider).not_to receive(:purchase_label)
+
+ result = subject.call(owner: fulfillment)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.already_purchased'))
+ end
+
+ it 'buys again once the previous label was refunded' do
+ subject.call(owner: fulfillment)
+ fulfillment.active_shipping_label.update!(status: 'refunded', refunded_at: Time.current)
+
+ expect(subject.call(owner: fulfillment)).to be_success
+ expect(fulfillment.reload.shipping_labels.count).to eq(2)
+ end
+
+ it 'fails loudly when the provider cannot produce a label' do
+ Spree::TestingSupport::LabelProvider.purchase_result = false
+ allow(provider).to receive(:purchase_label).and_return(nil)
+
+ result = subject.call(owner: fulfillment)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('fulfillments.errors.label_purchase_failed'))
+ expect(fulfillment.reload.shipping_labels).to be_empty
+ end
+
+ it 'refuses a provider without labels' do
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(Spree::FulfillmentProvider::Manual.new)
+
+ result = subject.call(owner: fulfillment)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.provider_has_no_labels'))
+ end
+
+ it 'refuses a fulfillment that already shipped' do
+ fulfillment.update!(status: 'fulfilled')
+
+ expect(subject.call(owner: fulfillment)).to be_failure
+ end
+
+ it 'refuses a draft order' do
+ order.update_columns(status: 'draft', completed_at: nil)
+
+ result = subject.call(owner: fulfillment)
+
+ expect(result.error.to_s).to eq(Spree.t('fulfillments.errors.order_draft'))
+ end
+
+ describe 'for a return' do
+ let(:return_record) { create(:return, order: create(:shipped_order, store: store)) }
+
+ before { allow(return_record).to receive(:provider).and_return(provider) }
+
+ it 'attaches the label and the inbound delivery to the return' do
+ result = subject.call(owner: return_record)
+
+ expect(result).to be_success
+ expect(return_record.reload.active_shipping_label).to eq(result.value)
+ expect(return_record.deliveries.first.tracking_number).to eq('1Z879E930346834440')
+ expect(return_record).to be_requested
+ end
+
+ it 'refuses a closed return' do
+ return_record.update!(status: 'canceled')
+
+ expect(subject.call(owner: return_record)).to be_failure
+ end
+ end
+
+ describe 'hooks' do
+ before { Spree.hooks.clear! }
+ after { Spree.hooks.clear! }
+
+ it 'lets a validate handler veto the purchase before anything is bought' do
+ Spree.hooks.register('shipping_labels.purchase.validate') { |flow| flow.reject!('carrier blocked') }
+ expect(provider).not_to receive(:purchase_label)
+
+ result = subject.call(owner: fulfillment)
+
+ expect(result).to be_failure
+ expect(fulfillment.reload.shipping_labels).to be_empty
+ end
+ end
+ end
+end
diff --git a/spree/core/spec/workflows/spree/shipping_labels/record_spec.rb b/spree/core/spec/workflows/spree/shipping_labels/record_spec.rb
new file mode 100644
index 0000000000..bbe3d4b0c9
--- /dev/null
+++ b/spree/core/spec/workflows/spree/shipping_labels/record_spec.rb
@@ -0,0 +1,78 @@
+require 'spec_helper'
+
+module Spree
+ describe ShippingLabels::Record do
+ subject { described_class }
+
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+ let(:file) do
+ ActiveStorage::Blob.create_and_upload!(
+ io: StringIO.new("%PDF-1.4\n%label\n"), filename: 'label.pdf', content_type: 'application/pdf',
+ service_name: Spree.private_storage_service_name
+ ).signed_id
+ end
+
+ before { fulfillment.deliveries.destroy_all }
+
+ it 'records an uploaded label with its cost and mints the delivery' do
+ result = subject.call(
+ owner: fulfillment, file: file, tracking_number: '1Z879E930346834440', cost: 6.5, currency: 'USD'
+ )
+
+ expect(result).to be_success
+ label = result.value
+ expect(label.source).to eq('uploaded')
+ expect(label).to be_purchased
+ expect(label.format).to eq('pdf')
+ expect(label.cost).to eq(6.5)
+ expect(label.file).to be_attached
+ expect(label.integration).to be_nil
+ expect(label.delivery.tracking_number).to eq('1Z879E930346834440')
+ expect(label.delivery.carrier).to eq('ups')
+ expect(fulfillment.reload.tracking).to eq('1Z879E930346834440')
+ end
+
+ it 'takes a free-text carrier for a number nothing recognises' do
+ result = subject.call(owner: fulfillment, file: file, tracking_number: 'PRO-4471923', carrier: 'Estes Freight')
+
+ expect(result.value.delivery.carrier).to eq('Estes Freight')
+ end
+
+ it 'needs a tracking number and a file' do
+ expect(subject.call(owner: fulfillment, file: file, tracking_number: '')).to be_failure
+ expect(subject.call(owner: fulfillment, file: nil, tracking_number: 'X')).to be_failure
+ end
+
+ it 'refuses a second label while one is active' do
+ create(:shipping_label, owner: fulfillment)
+
+ result = subject.call(owner: fulfillment, file: file, tracking_number: 'X-1')
+
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.already_purchased'))
+ end
+
+ it 'refuses a file whose bytes are not a label' do
+ spoofed = ActiveStorage::Blob.create_and_upload!(
+ io: StringIO.new('<html></html>'), filename: 'label.pdf', content_type: 'application/pdf',
+ service_name: Spree.private_storage_service_name
+ ).signed_id
+
+ result = subject.call(owner: fulfillment, file: spoofed, tracking_number: 'X-1')
+
+ expect(result).to be_failure
+ expect(fulfillment.reload.shipping_labels).to be_empty
+ expect(fulfillment.deliveries).to be_empty
+ end
+
+ it 'records a label on a return' do
+ return_record = create(:return, order: create(:shipped_order, store: store))
+
+ result = subject.call(owner: return_record, file: file, tracking_number: 'RET-1')
+
+ expect(result).to be_success
+ expect(return_record.reload.active_shipping_label).to eq(result.value)
+ end
+ end
+end
diff --git a/spree/core/spec/workflows/spree/shipping_labels/refund_spec.rb b/spree/core/spec/workflows/spree/shipping_labels/refund_spec.rb
new file mode 100644
index 0000000000..04ceb8b00b
--- /dev/null
+++ b/spree/core/spec/workflows/spree/shipping_labels/refund_spec.rb
@@ -0,0 +1,77 @@
+require 'spec_helper'
+require 'spree/testing_support/label_provider'
+
+module Spree
+ describe ShippingLabels::Refund do
+ subject { described_class }
+
+ let(:store) { @default_store }
+ let(:order) { create(:order_ready_to_ship, store: store) }
+ let(:fulfillment) { order.fulfillments.first }
+ let(:provider) { Spree::TestingSupport::LabelProvider.new }
+ let!(:label) { create(:shipping_label, :with_delivery, owner: fulfillment) }
+
+ before do
+ Spree::TestingSupport::LabelProvider.reset!
+ allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(provider)
+ end
+
+ it 'records a refund the carrier settles at once and removes the unshipped delivery', events: true do
+ allow(Spree::Events).to receive(:publish).and_call_original
+
+ result = subject.call(shipping_label: label)
+
+ expect(result).to be_success
+ expect(label.reload).to be_refunded
+ expect(label.refunded_at).to be_present
+ expect(label.delivery).to be_nil
+ expect(fulfillment.reload.active_shipping_label).to be_nil
+ expect(Spree::Events).to have_received(:publish).with('shipping_label.refunded', anything, anything)
+ end
+
+ it 'waits when the carrier answers later' do
+ Spree::TestingSupport::LabelProvider.refund_result = 'refund_requested'
+
+ subject.call(shipping_label: label)
+
+ expect(label.reload).to be_refund_requested
+ expect(label.refunded_at).to be_nil
+ end
+
+ # Once the parcel moved, the journey is history whatever happened to the
+ # postage.
+ it 'keeps the delivery when the parcel already shipped' do
+ fulfillment.update!(status: 'fulfilled', fulfilled_at: Time.current)
+
+ subject.call(shipping_label: label)
+
+ expect(label.reload).to be_refunded
+ expect(label.delivery).to be_present
+ end
+
+ it 'fails when the carrier refuses' do
+ Spree::TestingSupport::LabelProvider.refund_result = false
+
+ result = subject.call(shipping_label: label)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.refund_failed'))
+ expect(label.reload).to be_purchased
+ end
+
+ it 'refuses an uploaded label' do
+ uploaded = create(:shipping_label, :uploaded, owner: fulfillment)
+
+ result = subject.call(shipping_label: uploaded)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('shipping_labels.errors.uploaded_not_refundable'))
+ end
+
+ it 'refuses a label already refunded' do
+ label.update!(status: 'refunded', refunded_at: Time.current)
+
+ expect(subject.call(shipping_label: label)).to be_failure
+ end
+ end
+end
diff --git a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
index 275380e12f..c91440a2ed 100644
--- a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
+++ b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
@@ -1,10 +1,37 @@
module SpreeEasyPost
- # Buys the EasyPost label when a fulfillment ships and refunds it on
- # cancel. Runs inside the fulfillment state transition, so nothing here
- # may raise — a purchase failure is reported and the fulfillment proceeds
- # without a label (the admin buys one manually, exactly as with the
- # Manual provider).
+ # Buys and refunds EasyPost labels for outbound parcels and returns
+ # (docs/plans/6.0-shipping-labels-and-deliveries.md). Core records what
+ # was bought as a Spree::ShippingLabel and never asks twice for a parcel
+ # that already holds one, so nothing here remembers a purchase — the label
+ # row does.
+ #
+ # Nothing here may raise: a purchase failure is reported and answered with
+ # nil, which the explicit buy-label step surfaces as a 422 and the one-click
+ # fulfill degrades to "no label yet".
class FulfillmentProvider < Spree::FulfillmentProvider::Base
+ # EasyPost carrier names → Spree.tracking_carriers keys, so a bought label
+ # gets the same badge and tracking page a hand-entered number would.
+ CARRIER_KEYS = {
+ 'USPS' => 'usps',
+ 'UPS' => 'ups',
+ 'FedEx' => 'fedex',
+ 'FedExDefault' => 'fedex',
+ 'DHLExpress' => 'dhl',
+ 'DhlEcs' => 'dhl',
+ 'DPD' => 'dpd',
+ 'GLS' => 'gls',
+ 'RoyalMail' => 'royal_mail',
+ 'CanadaPost' => 'canada_post',
+ 'AustraliaPost' => 'australia_post'
+ }.freeze
+
+ LABEL_FORMATS = {
+ 'application/pdf' => 'pdf',
+ 'image/png' => 'png',
+ 'application/zpl' => 'zpl',
+ 'text/plain' => 'zpl'
+ }.freeze
+
def self.integration_class
'SpreeEasyPost::Integration'
end
@@ -17,58 +44,90 @@ module SpreeEasyPost
true
end
- # Buys the rate quoted at checkout when it is still valid; EasyPost
- # quotes expire, so a stale or missing quote is re-quoted from the
- # actual fulfillment and bought only when a rate for the exact
+ # An outbound parcel buys the rate quoted at checkout when it is still
+ # valid; EasyPost quotes expire, so a stale or missing quote is re-quoted
+ # from the actual fulfillment and bought only when a rate for the exact
# carrier/service the customer selected comes back — silently shipping a
# different service than the customer paid for is worse than no label.
- def create_fulfillment(fulfillment)
- # Idempotent: a label bought through the explicit buy-label step must
- # not be bought again when the fulfillment is later marked fulfilled.
- if fulfillment.metadata['easypost_purchased_shipment_id'].present?
- return {
- tracking_number: fulfillment.tracking,
- tracking_url: fulfillment.metadata['easypost_tracker_url']
- }
- end
-
- integration = integration_for(fulfillment)
- return {} if integration.nil?
-
- shipment = buy_quoted(integration, fulfillment) || requote_and_buy(integration, fulfillment)
- return {} if shipment.nil?
-
- remember_purchase(fulfillment, shipment)
- { tracking_number: shipment.tracking_code, tracking_url: shipment.tracker&.public_url }
+ #
+ # A return buys an inbound shipment from the address the order shipped
+ # to back to the return's stock location, at the cheapest rate the
+ # account offers: return postage is the merchant's own money and no
+ # service was ever chosen for it.
+ #
+ # @param owner [Spree::Fulfillment, Spree::Return]
+ # @return [Spree::LabelPurchase, nil]
+ def purchase_label(owner)
+ integration = integration_for(owner)
+ return if integration.nil?
+
+ shipment =
+ if owner.is_a?(Spree::Return)
+ buy_return(integration, owner)
+ else
+ buy_quoted(integration, owner) || requote_and_buy(integration, owner)
+ end
+ return if shipment.nil?
+
+ label_purchase(shipment)
rescue StandardError => e
- report(e, fulfillment)
- {}
+ report(e, owner)
+ nil
end
- # Files a refund request for the purchased label. Refund failures never
- # block the cancellation — the money side is between the merchant and
- # EasyPost, the stock side must proceed regardless.
- def cancel_fulfillment(fulfillment)
- integration = integration_for(fulfillment)
- purchased_id = fulfillment.metadata['easypost_purchased_shipment_id']
- return true if integration.nil? || purchased_id.blank?
-
- integration.client.shipment.refund(purchased_id)
- true
+ # Files the refund with EasyPost. USPS refunds settle later and come
+ # back as `submitted`; commercial carriers usually answer at once.
+ #
+ # @param shipping_label [Spree::ShippingLabel]
+ # @return [String, false]
+ def refund_label(shipping_label)
+ integration = integration_for(shipping_label.owner)
+ return false if integration.nil? || shipping_label.external_id.blank?
+
+ shipment = integration.client.shipment.refund(shipping_label.external_id)
+ refund_outcome(shipment.try(:refund_status))
rescue StandardError => e
- report(e, fulfillment)
+ report(e, shipping_label.owner)
false
end
- def tracking_url(fulfillment)
- fulfillment.metadata['easypost_tracker_url']
+ # Dispatch is the label; there is nothing else to tell EasyPost.
+ def create_fulfillment(_fulfillment)
+ {}
+ end
+
+ def cancel_fulfillment(_fulfillment)
+ true
end
- def documents(fulfillment)
- label_url = fulfillment.metadata['easypost_label_url']
- return [] if label_url.blank?
+ # The tracker page EasyPost hosts for the delivery's label.
+ #
+ # @param delivery [Spree::Delivery]
+ # @return [String, nil]
+ def tracking_url(delivery)
+ if delivery.is_a?(Spree::Fulfillment)
+ Spree::Deprecation.warn(
+ 'SpreeEasyPost::FulfillmentProvider#tracking_url takes a Spree::Delivery since 6.0; ' \
+ 'passing a fulfillment will be removed in Spree 6.1.'
+ )
+ delivery = delivery.primary_delivery
+ end
+
+ delivery&.shipping_label&.metadata&.dig('easypost_tracker_url')
+ end
- [{ kind: 'label', url: label_url }]
+ # Customs forms and commercial invoices the purchase produced. The label
+ # itself is the Spree::ShippingLabel, never listed here.
+ #
+ # @param owner [Spree::Fulfillment, Spree::Return]
+ # @return [Array<Hash>]
+ def documents(owner)
+ forms = owner.active_shipping_label&.metadata&.dig('easypost_forms')
+ Array(forms).filter_map do |form|
+ next if form['url'].blank?
+
+ { kind: form['form_type'].presence || 'form', url: form['url'] }
+ end
end
private
@@ -79,7 +138,7 @@ module SpreeEasyPost
rate_id = quoted['easypost_rate_id']
return if shipment_id.blank? || rate_id.blank?
- buy(integration, fulfillment, shipment_id, rate_id)
+ buy(integration, fulfillment.stock_location, fulfillment.store, shipment_id, rate_id)
rescue EasyPost::Errors::EasyPostError
nil
end
@@ -92,14 +151,30 @@ module SpreeEasyPost
return if selected&.carrier.blank? || selected.service_level.blank? || address.nil?
shipment = integration.client.shipment.create(
- **shipment_params(integration, fulfillment, address)
+ **SpreeEasyPost.shipment_params(
+ fulfillment.to_package, fulfillment.stock_location, address, integration, fulfillment.store
+ )
)
rate = shipment.rates.find do |candidate|
candidate.carrier == selected.carrier && candidate.service == selected.service_level
end
return if rate.nil?
- buy(integration, fulfillment, shipment.id, rate.id)
+ buy(integration, fulfillment.stock_location, fulfillment.store, shipment.id, rate.id)
+ end
+
+ def buy_return(integration, return_record)
+ address = return_record.ship_from_address
+ return if address.nil? || return_record.stock_location.nil?
+
+ params = SpreeEasyPost.shipment_params(
+ return_record.to_package, address, return_record.stock_location, integration, return_record.store
+ )
+ shipment = integration.client.shipment.create(**params, is_return: true)
+ rate = EasyPost::Util.get_lowest_object_rate(shipment)
+ return if rate.nil?
+
+ buy(integration, return_record.stock_location, return_record.store, shipment.id, rate.id)
end
# Labels bought on EasyPost's own carrier accounts (USPS) require an
@@ -108,44 +183,68 @@ module SpreeEasyPost
# are rare enough that caching one would only buy staleness. When the
# mandatory contact fields cannot be assembled the purchase proceeds
# without one, and carriers that insist reject with their own message.
- def buy(integration, fulfillment, shipment_id, rate_id)
+ def buy(integration, stock_location, store, shipment_id, rate_id)
buy_params = { rate: { id: rate_id } }
- end_shipper_id = end_shipper_id(integration, fulfillment)
+ end_shipper_id = end_shipper_id(integration, stock_location, store)
buy_params[:end_shipper_id] = end_shipper_id if end_shipper_id.present?
integration.client.shipment.buy(shipment_id, **buy_params)
end
- def end_shipper_id(integration, fulfillment)
- params = SpreeEasyPost.end_shipper_params(fulfillment.stock_location, fulfillment.order&.store)
+ def end_shipper_id(integration, stock_location, store)
+ params = SpreeEasyPost.end_shipper_params(stock_location, store)
return if params.nil?
integration.client.end_shipper.create(**params).id
rescue EasyPost::Errors::EasyPostError => e
- report(e, fulfillment)
+ report(e, stock_location)
nil
end
- # Same builder the rate provider uses, so a re-quote is priced and labelled
- # under the same terms as the original quote.
- def shipment_params(integration, fulfillment, address)
- SpreeEasyPost.shipment_params(
- fulfillment.to_package, fulfillment.stock_location, address, integration, fulfillment.order&.store
+ def label_purchase(shipment)
+ rate = shipment.try(:selected_rate)
+ postage_label = shipment.try(:postage_label)
+ tracker = shipment.try(:tracker)
+
+ Spree::LabelPurchase.new(
+ external_id: shipment.id,
+ carrier: carrier_key(rate&.carrier),
+ service: rate&.service,
+ tracking_number: shipment.tracking_code,
+ tracking_url: tracker&.public_url,
+ cost: rate&.rate.to_d,
+ currency: rate&.currency,
+ format: LABEL_FORMATS[postage_label&.label_file_type.to_s],
+ file_url: postage_label&.label_url,
+ metadata: {
+ 'easypost_tracker_id' => tracker&.id,
+ 'easypost_tracker_url' => tracker&.public_url,
+ 'easypost_rate_id' => rate&.id,
+ 'easypost_forms' => Array(shipment.try(:forms)).map { |form| { 'form_type' => form.try(:form_type), 'url' => form.try(:form_url) } }
+ }.compact
)
end
- def remember_purchase(fulfillment, shipment)
- fulfillment.update_columns(
- metadata: fulfillment.metadata.merge(
- 'easypost_purchased_shipment_id' => shipment.id,
- 'easypost_label_url' => shipment.postage_label&.label_url,
- 'easypost_tracker_url' => shipment.tracker&.public_url
- )
- )
+ def carrier_key(carrier)
+ return if carrier.blank?
+
+ CARRIER_KEYS[carrier.to_s] || carrier.to_s
end
- def report(error, fulfillment)
- Rails.error.report(error, context: { fulfillment_id: fulfillment.id }, source: 'spree_easypost.fulfillment')
+ def refund_outcome(refund_status)
+ case refund_status.to_s
+ when 'refunded' then 'refunded'
+ when 'rejected', 'not_applicable' then false
+ else 'refund_requested'
+ end
+ end
+
+ def report(error, subject)
+ Rails.error.report(
+ error,
+ context: { subject_type: subject.class.name, subject_id: subject.try(:id) },
+ source: 'spree_easypost.fulfillment'
+ )
end
end
end
diff --git a/spree/providers/easypost/spec/models/spree_easypost/fulfillment_provider_spec.rb b/spree/providers/easypost/spec/models/spree_easypost/fulfillment_provider_spec.rb
index cea9d313c3..66f1f91ea4 100644
--- a/spree/providers/easypost/spec/models/spree_easypost/fulfillment_provider_spec.rb
+++ b/spree/providers/easypost/spec/models/spree_easypost/fulfillment_provider_spec.rb
@@ -15,7 +15,6 @@ end
def recorded_rate_or_default = recorded_rates.first
-
RSpec.describe SpreeEasyPost::FulfillmentProvider do
let(:store) { @default_store }
let!(:integration) do
@@ -39,34 +38,20 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
expect(Spree.fulfillment_providers).to include(described_class)
expect(described_class.digital?).to be false
expect(described_class.pickup?).to be false
+ expect(described_class.generates_labels?).to be true
expect(described_class.new.requires_address?).to be true
expect(described_class.provider_name).to eq('EasyPost')
end
- describe '#create_fulfillment' do
- it 'does not buy twice — an already-purchased label is returned as-is' do
- fulfillment.update_columns(
- tracking: 'EXISTING-123',
- metadata: fulfillment.metadata.merge(
- 'easypost_purchased_shipment_id' => 'shp_bought',
- 'easypost_tracker_url' => 'https://track.example/t/1'
- )
- )
-
- expect(client).not_to receive(:shipment)
-
- result = provider.create_fulfillment(fulfillment)
-
- expect(result[:tracking_number]).to eq('EXISTING-123')
- expect(result[:tracking_url]).to eq('https://track.example/t/1')
- end
-
+ describe '#purchase_label' do
let(:purchased_shipment) do
double(
id: 'shp_recorded1',
tracking_code: '9405500207552012345678',
- postage_label: double(label_url: 'https://example.com/label.png'),
- tracker: double(public_url: 'https://track.easypost.com/abc')
+ selected_rate: double(id: 'rate_recorded1', carrier: 'USPS', service: 'Priority', rate: '7.25', currency: 'USD'),
+ postage_label: double(label_url: 'https://example.com/label.png', label_file_type: 'image/png'),
+ tracker: double(id: 'trk_1', public_url: 'https://track.easypost.com/abc'),
+ forms: []
)
end
let(:shipment_service) { double }
@@ -80,20 +65,35 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
allow(end_shipper_service).to receive(:create).and_return(double(id: 'es_test1'))
end
- it 'buys the rate quoted at checkout and hands back tracking' do
+ it 'buys the rate quoted at checkout and answers with a typed purchase' do
allow(shipment_service).to receive(:buy).
with('shp_recorded1', rate: { id: 'rate_recorded1' }, end_shipper_id: 'es_test1').
and_return(purchased_shipment)
- result = provider.create_fulfillment(fulfillment)
+ purchase = provider.purchase_label(fulfillment)
+
+ expect(purchase).to be_a(Spree::LabelPurchase)
+ expect(purchase).to be_valid
+ expect(purchase.tracking_number).to eq('9405500207552012345678')
+ expect(purchase.external_id).to eq('shp_recorded1')
+ # Mapped onto the Spree.tracking_carriers key, so a bought label gets
+ # the same badge a hand-entered number would.
+ expect(purchase.carrier).to eq('usps')
+ expect(purchase.service).to eq('Priority')
+ expect(purchase.cost).to eq(7.25)
+ expect(purchase.currency).to eq('USD')
+ expect(purchase.format).to eq('png')
+ expect(purchase.file_url).to eq('https://example.com/label.png')
+ expect(purchase.tracking_url).to eq('https://track.easypost.com/abc')
+ expect(purchase.metadata).to include('easypost_tracker_url' => 'https://track.easypost.com/abc')
+ end
+
+ # Core refuses a second purchase while a label is active, so the provider
+ # keeps no state of its own.
+ it 'writes nothing onto the fulfillment' do
+ allow(shipment_service).to receive(:buy).and_return(purchased_shipment)
- expect(result[:tracking_number]).to eq('9405500207552012345678')
- # update_columns silently no-ops on an unknown column, so a rename
- # upstream would leave the label details unwritten rather than raise.
- expect(fulfillment.reload.metadata['easypost_purchased_shipment_id']).to eq('shp_recorded1')
- expect(fulfillment.metadata['easypost_label_url']).to eq('https://example.com/label.png')
- expect(provider.documents(fulfillment)).to eq([{ kind: 'label', url: 'https://example.com/label.png' }])
- expect(provider.tracking_url(fulfillment)).to eq('https://track.easypost.com/abc')
+ expect { provider.purchase_label(fulfillment) }.not_to change { fulfillment.reload.metadata }
end
# EasyPost quotes expire; a stale quote re-quotes from the fulfillment
@@ -107,8 +107,6 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
with('shp_recorded1', rate: { id: 'rate_recorded1' }, end_shipper_id: 'es_test1').
and_raise(EasyPost::Errors::EasyPostError.new('rate expired'))
allow(shipment_service).to receive(:create).and_return(fresh_shipment)
- # The selected rate carries the carrier service the customer chose —
- # the re-quote must buy exactly that.
fulfillment.selected_delivery_rate.update_columns(carrier: 'UPS', service_level: 'Ground')
end
@@ -117,15 +115,13 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
with('shp_fresh', rate: { id: 'rate_fresh' }, end_shipper_id: 'es_test1').
and_return(purchased_shipment)
- result = provider.create_fulfillment(fulfillment)
-
- expect(result[:tracking_number]).to eq('9405500207552012345678')
+ expect(provider.purchase_label(fulfillment).tracking_number).to eq('9405500207552012345678')
end
it 'buys nothing when the exact service is not offered' do
allow(fresh_rate).to receive(:service).and_return('Express')
- expect(provider.create_fulfillment(fulfillment)).to eq({})
+ expect(provider.purchase_label(fulfillment)).to be_nil
end
end
@@ -135,7 +131,7 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
it 'registers an end shipper from the warehouse with store contact fallbacks' do
allow(shipment_service).to receive(:buy).and_return(purchased_shipment)
- provider.create_fulfillment(fulfillment)
+ provider.purchase_label(fulfillment)
expect(end_shipper_service).to have_received(:create).with(
hash_including(
@@ -152,77 +148,132 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
allow(shipment_service).to receive(:buy).
with('shp_recorded1', rate: { id: 'rate_recorded1' }).and_return(purchased_shipment)
- result = provider.create_fulfillment(fulfillment)
-
- expect(result[:tracking_number]).to be_present
+ expect(provider.purchase_label(fulfillment)).to be_present
expect(end_shipper_service).not_to have_received(:create)
end
- # An end-shipper hiccup must not lose the label — the buy proceeds bare
- # and only carriers that insist on one reject it, with their message.
- it 'degrades to a bare buy when the end shipper cannot be registered' do
- allow(end_shipper_service).to receive(:create).
- and_raise(EasyPost::Errors::EasyPostError.new('nope'))
- allow(Rails.error).to receive(:report)
- allow(shipment_service).to receive(:buy).
- with('shp_recorded1', rate: { id: 'rate_recorded1' }).and_return(purchased_shipment)
-
- expect(provider.create_fulfillment(fulfillment)[:tracking_number]).to be_present
- expect(Rails.error).to have_received(:report)
- end
-
- # Runs inside the ship transition — a purchase failure must degrade to
- # "no label yet", never break the fulfillment.
- it 'reports and returns empty on an API failure' do
+ it 'reports and answers nil on an API failure' do
allow(shipment_service).to receive(:buy).and_raise(StandardError.new('boom'))
allow(shipment_service).to receive(:create).and_raise(StandardError.new('boom'))
allow(Rails.error).to receive(:report)
- expect(provider.create_fulfillment(fulfillment)).to eq({})
+ expect(provider.purchase_label(fulfillment)).to be_nil
expect(Rails.error).to have_received(:report)
end
it 'does nothing without a connected integration' do
integration.destroy!
- expect(provider.create_fulfillment(fulfillment)).to eq({})
+ expect(provider.purchase_label(fulfillment)).to be_nil
+ end
+
+ describe 'for a return' do
+ let(:shipped) { create(:shipped_order, store: store) }
+ let(:return_record) { create(:return, order: shipped) }
+ let(:return_shipment) do
+ double(
+ id: 'shp_return1',
+ rates: [
+ double(id: 'rate_cheap', carrier: 'USPS', service: 'Ground', rate: '4.10', currency: 'USD'),
+ double(id: 'rate_dear', carrier: 'UPS', service: 'Express', rate: '19.00', currency: 'USD')
+ ]
+ )
+ end
+
+ before do
+ allow(shipment_service).to receive(:create).and_return(return_shipment)
+ allow(shipment_service).to receive(:buy).and_return(purchased_shipment)
+ end
+
+ # Return postage is the merchant's own money and no service was ever
+ # chosen for it, so the cheapest the account offers wins.
+ it 'buys an inbound shipment at the cheapest rate' do
+ purchase = provider.purchase_label(return_record)
+
+ expect(purchase.tracking_number).to be_present
+ expect(shipment_service).to have_received(:create).with(hash_including(is_return: true))
+ expect(shipment_service).to have_received(:buy).with('shp_return1', hash_including(rate: { id: 'rate_cheap' }))
+ end
+
+ it 'ships from the customer address back to the return stock location' do
+ provider.purchase_label(return_record)
+
+ expect(shipment_service).to have_received(:create).with(
+ hash_including(
+ from_address: hash_including(zip: shipped.ship_address.zipcode),
+ to_address: hash_including(zip: return_record.stock_location.zipcode)
+ )
+ )
+ end
end
end
- describe '#cancel_fulfillment' do
+ describe '#refund_label' do
let(:shipment_service) { double }
let(:client) { instance_double(EasyPost::Client, shipment: shipment_service) }
+ let(:shipping_label) { create(:shipping_label, owner: fulfillment, store: store, external_id: 'shp_recorded1') }
before { allow_any_instance_of(SpreeEasyPost::Integration).to receive(:client).and_return(client) }
- it 'refunds the purchased label' do
- fulfillment.update_columns(metadata: { 'easypost_purchased_shipment_id' => 'shp_recorded1' })
- allow(shipment_service).to receive(:refund).with('shp_recorded1').and_return(double)
+ it 'reports a settled refund' do
+ allow(shipment_service).to receive(:refund).with('shp_recorded1').and_return(double(refund_status: 'refunded'))
+
+ expect(provider.refund_label(shipping_label)).to eq('refunded')
+ end
+
+ # USPS settles refunds later; the label waits in refund_requested until a
+ # webhook confirms it.
+ it 'reports a submitted refund as pending' do
+ allow(shipment_service).to receive(:refund).and_return(double(refund_status: 'submitted'))
- expect(provider.cancel_fulfillment(fulfillment)).to be(true)
- expect(shipment_service).to have_received(:refund)
+ expect(provider.refund_label(shipping_label)).to eq('refund_requested')
end
- it 'is a no-op without a purchase' do
- expect(provider.cancel_fulfillment(fulfillment)).to be(true)
+ it 'reports a rejection as a failure' do
+ allow(shipment_service).to receive(:refund).and_return(double(refund_status: 'rejected'))
+
+ expect(provider.refund_label(shipping_label)).to be(false)
end
- it 'never blocks cancellation on a refund failure' do
- fulfillment.update_columns(metadata: { 'easypost_purchased_shipment_id' => 'shp_recorded1' })
+ it 'never raises on an API failure' do
allow(shipment_service).to receive(:refund).and_raise(StandardError.new('boom'))
allow(Rails.error).to receive(:report)
- expect(provider.cancel_fulfillment(fulfillment)).to be(false)
+ expect(provider.refund_label(shipping_label)).to be(false)
expect(Rails.error).to have_received(:report)
end
end
+ describe '#tracking_url' do
+ it 'answers the tracker page recorded on the delivery label' do
+ label = create(:shipping_label, :with_delivery, owner: fulfillment, store: store,
+ metadata: { 'easypost_tracker_url' => 'https://track.easypost.com/abc' })
+
+ expect(provider.tracking_url(label.delivery)).to eq('https://track.easypost.com/abc')
+ end
+ end
+
+ describe '#documents' do
+ # The label is a Spree::ShippingLabel; only the paperwork beside it is
+ # reported here.
+ it 'lists customs forms and never the label' do
+ create(
+ :shipping_label, owner: fulfillment, store: store,
+ metadata: { 'easypost_forms' => [{ 'form_type' => 'commercial_invoice', 'url' => 'https://forms.example/ci.pdf' }] }
+ )
+
+ expect(provider.documents(fulfillment)).to eq([{ kind: 'commercial_invoice', url: 'https://forms.example/ci.pdf' }])
+ end
+
+ it 'is empty without a label' do
+ expect(provider.documents(fulfillment)).to eq([])
+ end
+ end
+
# Real client, HTTP played back from spec/vcr — the exact buy and refund
# calls against EasyPost's wire format. Ids come from the recorded rate
# quote so a re-record against any account stays self-consistent.
describe 'API contract (VCR)' do
- # USPS purchases demand an EndShipper; the provider registers one from
- # the warehouse before buying, so any recorded USPS service works.
let(:recorded_rate) do
rates = recorded_rates
rates.find { |rate| rate['service'] == 'Priority' } || rates.first
@@ -239,21 +290,21 @@ RSpec.describe SpreeEasyPost::FulfillmentProvider do
it 'buys the quoted rate end to end' do
VCR.use_cassette('buy_shipment') do
- result = provider.create_fulfillment(fulfillment)
+ purchase = provider.purchase_label(fulfillment)
- expect(result[:tracking_number]).to be_present
- expect(fulfillment.metadata['easypost_purchased_shipment_id']).to be_present
- expect(fulfillment.metadata['easypost_label_url']).to include('http')
+ expect(purchase.tracking_number).to be_present
+ expect(purchase.external_id).to be_present
+ expect(purchase.file_url).to include('http')
end
end
it 'refunds end to end' do
- fulfillment.update_columns(
- metadata: { 'easypost_purchased_shipment_id' => recorded_rate['shipment_id'] }
+ shipping_label = create(
+ :shipping_label, owner: fulfillment, store: store, external_id: recorded_rate['shipment_id']
)
VCR.use_cassette('refund_shipment') do
- expect(provider.cancel_fulfillment(fulfillment)).to be(true)
+ expect(provider.refund_label(shipping_label)).to be_present
end
end
end
diff --git a/spree/providers/easypost/spec/requests/spree_easypost/fulfillment_webhooks_spec.rb b/spree/providers/easypost/spec/requests/spree_easypost/fulfillment_webhooks_spec.rb
index b4a34e308e..a2f16a0d59 100644
--- a/spree/providers/easypost/spec/requests/spree_easypost/fulfillment_webhooks_spec.rb
+++ b/spree/providers/easypost/spec/requests/spree_easypost/fulfillment_webhooks_spec.rb
@@ -23,9 +23,12 @@ RSpec.describe 'EasyPost fulfillment webhooks', type: :request do
let(:order) { create(:order_ready_to_ship, store: store) }
let(:fulfillment) { order.fulfillments.first }
+ let(:delivery) { fulfillment.reload.primary_delivery }
+
before do
+ fulfillment.deliveries.destroy_all
+ Spree::Deliveries::Create.new.call(owner: fulfillment, tracking_number: 'EZ1000000001')
Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment)
- fulfillment.reload.update!(tracking: 'EZ1000000001')
host! store.url
end
@@ -45,11 +48,12 @@ RSpec.describe 'EasyPost fulfillment webhooks', type: :request do
headers: { 'CONTENT_TYPE' => 'application/json', 'X-Hmac-Signature' => sign(body, secret: secret) }
end
- it 'records the carrier update on the fulfillment' do
+ it 'records the carrier update on the consignment' do
post_tracker(status: 'out_for_delivery')
expect(response).to have_http_status(:ok)
- expect(fulfillment.reload.tracking_status).to eq('out_for_delivery')
+ expect(delivery.reload.status).to eq('out_for_delivery')
+ expect(fulfillment.reload).to be_fulfilled
end
it 'confirms receipt when the carrier reports delivery' do
@@ -65,8 +69,8 @@ RSpec.describe 'EasyPost fulfillment webhooks', type: :request do
it 'records a bounce without moving the fulfillment backwards' do
post_tracker(status: 'return_to_sender')
- expect(fulfillment.reload.tracking_status).to eq('return_to_sender')
- expect(fulfillment).to be_fulfilled
+ expect(delivery.reload.status).to eq('return_to_sender')
+ expect(fulfillment.reload).to be_fulfilled
end
describe 'signature verification' do
@@ -74,7 +78,7 @@ RSpec.describe 'EasyPost fulfillment webhooks', type: :request do
post_tracker(status: 'delivered', secret: 'not-the-secret')
expect(response).to have_http_status(:unauthorized)
- expect(fulfillment.reload.tracking_status).to be_nil
+ expect(delivery.reload.status).to eq('pending')
end
it 'refuses an unsigned request' do
@@ -118,6 +122,19 @@ RSpec.describe 'EasyPost fulfillment webhooks', type: :request do
end
end
+ # A tracking code can never address another tenant's parcel: the delivery
+ # is resolved inside the verified integration's own store.
+ it 'ignores a consignment belonging to another store' do
+ other_fulfillment = create(:order_ready_to_ship, store: create(:store, code: "other-#{SecureRandom.hex(4)}")).fulfillments.first
+ other_fulfillment.deliveries.destroy_all
+ Spree::Deliveries::Create.new.call(owner: other_fulfillment, tracking_number: 'EZ_OTHER_STORE')
+
+ post_tracker(status: 'delivered', tracking_code: 'EZ_OTHER_STORE')
+
+ expect(response).to have_http_status(:ok)
+ expect(other_fulfillment.reload.primary_delivery.status).to eq('pending')
+ end
+
it 'answers 404 for an unknown integration' do
body = { description: 'tracker.updated', result: {} }.to_json