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.

Changed API money to decimal strings in each currency's decimals

Damian Legawiec525959de11cf
diff --git a/.changeset/money-decimal-strings.md b/.changeset/money-decimal-strings.md
new file mode 100644
index 0000000000..a66678fcf2
--- /dev/null
+++ b/.changeset/money-decimal-strings.md
@@ -0,0 +1,7 @@
+---
+"@spree/sdk": minor
+"@spree/admin-sdk": minor
+"@spree/seller-sdk": minor
+---
+
+Money is a decimal string written to its currency's decimals, and Admin and Seller writes take money and rates only as decimal strings. Added `sumMoney`, `subtractMoney`, `multiplyMoney`, `negateMoney`, `compareMoney`, `isZeroMoney`, `isDecimalString` and `decimalPlaces` for exact arithmetic on those strings. Currencies carry `decimal_places`; prices no longer carry `amount_in_cents` or `compare_at_amount_in_cents`; tax rates read and write `rate` and `rate_percent` instead of `amount` and `amount_percentage`.
diff --git a/docs/api-reference/admin-api/monetary-amounts.mdx b/docs/api-reference/admin-api/monetary-amounts.mdx
index 49d7b51195..1772eb2fd0 100644
--- a/docs/api-reference/admin-api/monetary-amounts.mdx
+++ b/docs/api-reference/admin-api/monetary-amounts.mdx
@@ -4,7 +4,7 @@ sidebarTitle: "Monetary Amounts"
description: "How the Admin API represents money as decimal strings, why JSON numbers are avoided, and how to send prices, costs, and amounts safely in requests."
---
-All monetary values in the Admin API are **canonical decimal strings** (e.g., `"29.99"`, `"0.0"` — period decimal, no thousands grouping), both in responses and in request bodies. Strings preserve decimal precision and avoid the floating-point rounding issues common with JSON numbers — critical when an admin is setting prices and costs. The format is the same regardless of locale; localized formatting is a presentation concern handled by the client (see [Canonical format](#canonical-format-not-localized)).
+All monetary values in the Admin API are **canonical decimal strings** (period decimal, no thousands grouping), both in responses and in request bodies. Responses write each amount with exactly its currency's decimal places — `"29.99"` in USD, `"1.500"` in Kuwaiti dinar, `"1000"` in yen — and unit prices (`price`, `amount` on a price, `compare_at_amount`, `cost_price`, `unit_cost`) with up to four (`"0.0125"`). A currency's decimal places are its `decimal_places`, from ISO 4217. Strings preserve decimal precision and avoid the floating-point rounding issues common with JSON numbers — critical when an admin is setting prices and costs. The format is the same regardless of locale; localized formatting is a presentation concern handled by the client (see [Canonical format](#canonical-format-not-localized)).
## Reading
@@ -19,7 +19,7 @@ Every monetary field is returned as a string, alongside a `display_` companion t
}
```
-Use `display_*` for rendering and the raw string fields for calculations (`parseFloat(price.amount)`).
+Use `display_*` for rendering and the raw string fields for calculations, with a decimal library rather than `parseFloat`. The SDK exports `sumMoney`, `subtractMoney`, `multiplyMoney`, `compareMoney` and `isZeroMoney`, which work on the strings exactly.
## Writing
@@ -40,7 +40,19 @@ spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","
</CodeGroup>
-JSON numbers are also accepted (`"amount": 29.99`), but strings are recommended: they round-trip with what the API returns and sidestep float precision. A `null` clears the value.
+Only strings are accepted. A JSON number (`"amount": 29.99`), a localized or grouped string (`"1.234,56"`, `"1,234.56"`), or more decimals than the field holds (`"19.999"` in USD, `"100.5"` in yen; unit prices allow four) is refused with `422` and the error code `invalid_money_format`, naming the field:
+
+```json
+{
+ "error": {
+ "code": "invalid_money_format",
+ "message": "amount must be a decimal string like \"19.99\"",
+ "details": { "amount": ["must be a decimal string like \"19.99\""] }
+ }
+}
+```
+
+A `null` clears the value.
### Canonical format — not localized
@@ -77,4 +89,8 @@ Calculators and some promotion rules carry their amounts inside an untyped `pref
| **Calculator** `flat_rate` (shipping) | `amount`, `minimum_item_total`, `maximum_item_total` |
| **Promotion Rule** `item_total` | `amount_min`, `amount_max` |
-Percentage keys (`percent`, `flat_percent`, `base_percent`), weights (`minimum_weight`, `maximum_weight`), and quantities (`max_items`, `min_quantity`) are **not** money — those stay numbers. Promotion actions (`create_adjustment`, `create_item_adjustments`) hold their money inside a nested `calculator.preferences`, per the calculator rows above.
+Percentage keys (`percent`, `flat_percent`, `base_percent`) are rates: decimal strings too (`"10"`), with no fixed number of decimals. Weights (`minimum_weight`, `maximum_weight`) and quantities (`max_items`, `min_quantity`) are not money and stay numbers. Promotion actions (`create_adjustment`, `create_item_adjustments`) hold their money inside a nested `calculator.preferences`, per the calculator rows above.
+
+## Rates and percentages
+
+Rates and percentages are decimal strings without trailing zeros, on read and write. A field ending in `_percent` or `_percentage` holds 0–100 (`"23"`); a field named `rate` or ending in `_rate` holds a fraction (`"0.23"`). A tax rate has both: `rate` and `rate_percent`, and accepts either on write.
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 8da5db8f23..2c580c14be 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -391,6 +391,8 @@ paths:
- write_package_types
- read_webhooks
- write_webhooks
+ - read_email_templates
+ - write_email_templates
- read_integrations
- write_integrations
- read_api_keys
@@ -528,6 +530,8 @@ paths:
- write_package_types
- read_webhooks
- write_webhooks
+ - read_email_templates
+ - write_email_templates
- read_integrations
- write_integrations
- read_api_keys
@@ -859,9 +863,7 @@ paths:
name: Afghanistan
currency: AFN
locales:
- - ps
- - uz
- - tk
+ - en
- code: AG
name: Antigua and Barbuda
currency: XCD
@@ -876,12 +878,12 @@ paths:
name: Albania
currency: ALL
locales:
- - sq
+ - en
- code: AM
name: Armenia
currency: AMD
locales:
- - hy
+ - en
- code: AO
name: Angola
currency: AOA
@@ -892,13 +894,11 @@ paths:
currency: ARS
locales:
- es
- - gn
- code: AS
name: American Samoa
currency: USD
locales:
- en
- - sm
- code: AT
name: Austria
currency: EUR
@@ -918,15 +918,12 @@ paths:
name: Azerbaijan
currency: AZN
locales:
- - az
- - hy
+ - en
- code: BA
name: Bosnia and Herzegovina
currency: BAM
locales:
- - bs
- - hr
- - sr
+ - en
- code: BB
name: Barbados
currency: BBD
@@ -936,7 +933,7 @@ paths:
name: Bangladesh
currency: BDT
locales:
- - bn
+ - en
- code: BE
name: Belgium
currency: EUR
@@ -949,7 +946,6 @@ paths:
currency: XOF
locales:
- fr
- - ff
- code: BG
name: Bulgaria
currency: EUR
@@ -965,7 +961,6 @@ paths:
currency: BIF
locales:
- fr
- - rn
- code: BJ
name: Benin
currency: XOF
@@ -985,14 +980,12 @@ paths:
name: Brunei Darussalam
currency: BND
locales:
- - ms
+ - en
- code: BO
name: Bolivia
currency: BOB
locales:
- es
- - ay
- - qu
- code: BQ
name: Bonaire, Sint Eustatius and Saba
currency: USD
@@ -1013,13 +1006,12 @@ paths:
name: Bhutan
currency: BTN
locales:
- - dz
+ - en
- code: BW
name: Botswana
currency: BWP
locales:
- en
- - tn
- code: BY
name: Belarus
currency: BYN
@@ -1048,22 +1040,16 @@ paths:
currency: CDF
locales:
- fr
- - ln
- - kg
- - sw
- - lu
- code: CF
name: Central African Republic
currency: XAF
locales:
- fr
- - sg
- code: CG
name: Congo
currency: XAF
locales:
- fr
- - ln
- code: CH
name: Switzerland
currency: CHF
@@ -1071,7 +1057,6 @@ paths:
- de
- fr
- it
- - rm
- code: CI
name: Côte d'Ivoire
currency: XOF
@@ -1097,7 +1082,7 @@ paths:
name: China
currency: CNY
locales:
- - zh
+ - zh-CN
- code: CO
name: Colombia
currency: COP
@@ -1128,15 +1113,13 @@ paths:
currency: AUD
locales:
- en
- - zh
- - ms
+ - zh-CN
- code: CY
name: Cyprus
currency: EUR
locales:
- el
- tr
- - hy
- code: CZ
name: Czechia
currency: CZK
@@ -1194,7 +1177,6 @@ paths:
locales:
- en
- ar
- - ti
- code: ES
name: Spain
currency: EUR
@@ -1204,7 +1186,7 @@ paths:
name: Ethiopia
currency: ETB
locales:
- - am
+ - en
- code: FI
name: Finland
currency: EUR
@@ -1216,8 +1198,6 @@ paths:
currency: FJD
locales:
- en
- - fj
- - hi
- code: FK
name: Falkland Islands (Malvinas)
currency: FKP
@@ -1232,7 +1212,7 @@ paths:
name: Faroe Islands
currency: DKK
locales:
- - fo
+ - en
- code: FR
name: France
currency: EUR
@@ -1257,7 +1237,7 @@ paths:
name: Georgia
currency: GEL
locales:
- - ka
+ - en
- code: GF
name: French Guiana
currency: EUR
@@ -1283,7 +1263,7 @@ paths:
name: Greenland
currency: DKK
locales:
- - kl
+ - en
- code: GM
name: Gambia
currency: GMD
@@ -1294,7 +1274,6 @@ paths:
currency: GNF
locales:
- fr
- - ff
- code: GP
name: Guadeloupe
currency: EUR
@@ -1321,7 +1300,6 @@ paths:
currency: USD
locales:
- en
- - ch
- es
- code: GW
name: Guinea-Bissau
@@ -1338,7 +1316,7 @@ paths:
currency: HKD
locales:
- en
- - zh
+ - zh-CN
- code: HN
name: Honduras
currency: HNL
@@ -1348,13 +1326,12 @@ paths:
name: Croatia
currency: EUR
locales:
- - hr
+ - en
- code: HT
name: Haiti
currency: HTG
locales:
- fr
- - ht
- code: HU
name: Hungary
currency: HUF
@@ -1370,24 +1347,20 @@ paths:
currency: EUR
locales:
- en
- - ga
- code: IL
name: Israel
currency: ILS
locales:
- - he
- ar
- code: IM
name: Isle of Man
currency: GBP
locales:
- en
- - gv
- code: IN
name: India
currency: INR
locales:
- - hi
- en
- code: IQ
name: Iraq
@@ -1403,7 +1376,7 @@ paths:
name: Iceland
currency: ISK
locales:
- - is
+ - en
- code: IT
name: Italy
currency: EUR
@@ -1435,12 +1408,10 @@ paths:
currency: KES
locales:
- en
- - sw
- code: KG
name: Kyrgyzstan
currency: KGS
locales:
- - ky
- ru
- code: KH
name: Cambodia
@@ -1487,13 +1458,12 @@ paths:
name: Kazakhstan
currency: KZT
locales:
- - kk
- ru
- code: LA
name: Lao People's Democratic Republic
currency: LAK
locales:
- - lo
+ - en
- code: LB
name: Lebanon
currency: LBP
@@ -1514,8 +1484,7 @@ paths:
name: Sri Lanka
currency: LKR
locales:
- - si
- - ta
+ - en
- code: LR
name: Liberia
currency: LRD
@@ -1526,7 +1495,6 @@ paths:
currency: LSL
locales:
- en
- - st
- code: LT
name: Lithuania
currency: EUR
@@ -1538,7 +1506,6 @@ paths:
locales:
- fr
- de
- - lb
- code: LV
name: Latvia
currency: EUR
@@ -1568,10 +1535,7 @@ paths:
name: Montenegro
currency: EUR
locales:
- - sr
- - bs
- - sq
- - hr
+ - en
- code: MF
name: Saint Martin (French part)
currency: EUR
@@ -1584,18 +1548,16 @@ paths:
currency: MGA
locales:
- fr
- - mg
- code: MH
name: Marshall Islands
currency: USD
locales:
- en
- - mh
- code: MK
name: North Macedonia
currency: MKD
locales:
- - mk
+ - en
- code: ML
name: Mali
currency: XOF
@@ -1605,24 +1567,23 @@ paths:
name: Myanmar
currency: MMK
locales:
- - my
+ - en
- code: MN
name: Mongolia
currency: MNT
locales:
- - mn
+ - en
- code: MO
name: Macao
currency: MOP
locales:
- - zh
+ - zh-CN
- pt
- code: MP
name: Northern Mariana Islands
currency: USD
locales:
- en
- - ch
- code: MQ
name: Martinique
currency: EUR
@@ -1643,7 +1604,6 @@ paths:
name: Malta
currency: EUR
locales:
- - mt
- en
- code: MU
name: Mauritius
@@ -1654,13 +1614,12 @@ paths:
name: Maldives
currency: MVR
locales:
- - dv
+ - en
- code: MW
name: Malawi
currency: MWK
locales:
- en
- - ny
- code: MX
name: Mexico
currency: MXN
@@ -1670,7 +1629,6 @@ paths:
name: Malaysia
currency: MYR
locales:
- - ms
- en
- code: MZ
name: Mozambique
@@ -1682,7 +1640,6 @@ paths:
currency: NAD
locales:
- en
- - af
- code: NC
name: New Caledonia
currency: XPF
@@ -1718,7 +1675,6 @@ paths:
currency: NOK
locales:
- nb
- - nn
- code: NP
name: Nepal
currency: NPR
@@ -1729,7 +1685,6 @@ paths:
currency: AUD
locales:
- en
- - na
- code: NU
name: Niue
currency: NZD
@@ -1769,14 +1724,12 @@ paths:
name: Philippines
currency: PHP
locales:
- - tl
- en
- code: PK
name: Pakistan
currency: PKR
locales:
- en
- - ur
- code: PL
name: Poland
currency: PLN
@@ -1803,7 +1756,6 @@ paths:
currency: ILS
locales:
- ar
- - he
- en
- code: PT
name: Portugal
@@ -1820,7 +1772,6 @@ paths:
currency: PYG
locales:
- es
- - gn
- code: QA
name: Qatar
currency: QAR
@@ -1840,7 +1791,7 @@ paths:
name: Serbia
currency: RSD
locales:
- - sr
+ - en
- code: RU
name: Russian Federation
currency: RUB
@@ -1850,7 +1801,6 @@ paths:
name: Rwanda
currency: RWF
locales:
- - rw
- en
- fr
- code: SA
@@ -1885,8 +1835,6 @@ paths:
currency: SGD
locales:
- en
- - ms
- - ta
- code: SH
name: Saint Helena, Ascension and Tristan da Cunha
currency: SHP
@@ -1896,12 +1844,12 @@ paths:
name: Slovenia
currency: EUR
locales:
- - sl
+ - sl-SI
- code: SJ
name: Svalbard and Jan Mayen
currency: NOK
locales:
- - 'no'
+ - en
- code: SK
name: Slovakia
currency: EUR
@@ -1926,7 +1874,6 @@ paths:
name: Somalia
currency: SOS
locales:
- - so
- ar
- code: SR
name: Suriname
@@ -1965,7 +1912,6 @@ paths:
currency: SZL
locales:
- en
- - ss
- code: TC
name: Turks and Caicos Islands
currency: USD
@@ -1991,7 +1937,6 @@ paths:
name: Tajikistan
currency: TJS
locales:
- - tg
- ru
- code: TK
name: Tokelau
@@ -2007,7 +1952,7 @@ paths:
name: Turkmenistan
currency: TMT
locales:
- - tk
+ - en
- code: TN
name: Tunisia
currency: TND
@@ -2019,7 +1964,6 @@ paths:
currency: TOP
locales:
- en
- - to
- code: TR
name: Türkiye
currency: TRY
@@ -2039,12 +1983,11 @@ paths:
name: Taiwan
currency: TWD
locales:
- - zh
+ - zh-CN
- code: TZ
name: Tanzania
currency: TZS
locales:
- - sw
- en
- code: UA
name: Ukraine
@@ -2056,7 +1999,6 @@ paths:
currency: UGX
locales:
- en
- - sw
- code: US
name: United States
currency: USD
@@ -2071,13 +2013,12 @@ paths:
name: Uzbekistan
currency: UZS
locales:
- - uz
+ - en
- code: VA
name: Holy See (Vatican City State)
currency: EUR
locales:
- it
- - la
- code: VC
name: Saint Vincent and the Grenadines
currency: XCD
@@ -2107,7 +2048,6 @@ paths:
name: Vanuatu
currency: VUV
locales:
- - bi
- en
- fr
- code: WF
@@ -2119,7 +2059,6 @@ paths:
name: Samoa
currency: WST
locales:
- - sm
- en
- code: YE
name: Yemen
@@ -2135,16 +2074,7 @@ paths:
name: South Africa
currency: ZAR
locales:
- - af
- en
- - nr
- - st
- - ss
- - tn
- - ts
- - ve
- - xh
- - zu
- code: ZM
name: Zambia
currency: ZMW
@@ -2155,8 +2085,6 @@ paths:
currency: USD
locales:
- en
- - sn
- - nd
"/api/v3/admin/allowed_origins":
get:
summary: List allowed origins
@@ -5313,7 +5241,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Dan Ebert
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
@@ -5328,7 +5256,7 @@ paths:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
- total_spent: '0.0'
+ total_spent: '0.00'
display_total_spent: "$0.00"
last_order_completed_at:
customer_group_ids:
@@ -5621,7 +5549,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Redacted Redacted
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
@@ -5636,7 +5564,7 @@ paths:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
- total_spent: '0.0'
+ total_spent: '0.00'
display_total_spent: "$0.00"
last_order_completed_at:
customer_group_ids: []
@@ -6309,9 +6237,9 @@ paths:
example:
data:
- id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -6320,7 +6248,7 @@ paths:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount_authorized: '0.0'
+ amount_authorized: '0.00'
outstanding: true
display_amount_authorized: "$0.00"
customer_id: cust_UkLWZg9DAJ
@@ -6391,9 +6319,9 @@ paths:
application/json:
example:
id: credit_gbHJdmfrXB
- amount: '25.0'
- amount_used: '0.0'
- amount_remaining: '25.0'
+ amount: '25.00'
+ amount_used: '0.00'
+ amount_remaining: '25.00'
display_amount: "$25.00"
display_amount_used: "$0.00"
display_amount_remaining: "$25.00"
@@ -6402,7 +6330,7 @@ paths:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount_authorized: '0.0'
+ amount_authorized: '0.00'
outstanding: true
display_amount_authorized: "$0.00"
customer_id: cust_UkLWZg9DAJ
@@ -6484,9 +6412,9 @@ paths:
application/json:
example:
id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -6495,7 +6423,7 @@ paths:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount_authorized: '0.0'
+ amount_authorized: '0.00'
outstanding: true
display_amount_authorized: "$0.00"
customer_id: cust_UkLWZg9DAJ
@@ -6651,7 +6579,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Jane Doe
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
@@ -6666,7 +6594,7 @@ paths:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
- total_spent: '0'
+ total_spent: '0.00'
display_total_spent: "$0.00"
last_order_completed_at:
customer_group_ids: []
@@ -6739,7 +6667,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: New Customer
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
@@ -6754,7 +6682,7 @@ paths:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
- total_spent: '0.0'
+ total_spent: '0.00'
display_total_spent: "$0.00"
last_order_completed_at:
customer_group_ids: []
@@ -6859,7 +6787,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Jane Doe
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
@@ -6874,7 +6802,7 @@ paths:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
- total_spent: '0'
+ total_spent: '0.00'
display_total_spent: "$0.00"
last_order_completed_at:
customer_group_ids: []
@@ -6937,7 +6865,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Updated Doe
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
@@ -6952,7 +6880,7 @@ paths:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
- total_spent: '0.0'
+ total_spent: '0.00'
display_total_spent: "$0.00"
last_order_completed_at:
customer_group_ids: []
@@ -8161,20 +8089,20 @@ paths:
application/json:
example:
id:
- subject: ''
+ subject: Order R123456789 confirmed
html: "<!doctype html><html lang=\"en\" dir=\"auto\" xmlns=\"http://www.w3.org/1999/xhtml\"
- xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\"><head><title></title><!--[if
- !mso]><!--><meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\"><!--<![endif]--><meta
- http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\"><meta
- name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<style
- type=\"text/css\">\n#outlook a { padding: 0; }\nbody { margin: 0;
- padding: 0; -webkit-text-size-adjust: 100%; -ms-text-size-adjust:
- 100%; }\ntable, td { border-collapse: collapse; mso-table-lspace:
- 0pt; mso-table-rspace: 0pt; }\nimg { border: 0; height: auto; line-height:
- 100%; outline: none; text-decoration: none; -ms-interpolation-mode:
- bicubic; }\np { display: block; margin: 13px 0; }\n</style>\n<!--[if
- mso]>\n<noscript>\n<xml>\n<o:OfficeDocumentSettings>\n <o:AllowPNG/>\n
- \ <o:PixelsPerInch>96</o:PixelsPerInch>\n</o:OfficeDocumentSettings>\n</xml>\n</noscript>\n<![endif]-->\n<!--[if
+ xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\"><head><title>Order
+ R123456789 confirmed</title><!--[if !mso]><!--><meta http-equiv=\"X-UA-Compatible\"
+ content=\"IE=edge\"><!--<![endif]--><meta http-equiv=\"Content-Type\"
+ content=\"text/html; charset=UTF-8\"><meta name=\"viewport\" content=\"width=device-width,
+ initial-scale=1\">\n<style type=\"text/css\">\n#outlook a { padding:
+ 0; }\nbody { margin: 0; padding: 0; -webkit-text-size-adjust: 100%;
+ -ms-text-size-adjust: 100%; }\ntable, td { border-collapse: collapse;
+ mso-table-lspace: 0pt; mso-table-rspace: 0pt; }\nimg { border: 0;
+ height: auto; line-height: 100%; outline: none; text-decoration:
+ none; -ms-interpolation-mode: bicubic; }\np { display: block; margin:
+ 13px 0; }\n</style>\n<!--[if mso]>\n<noscript>\n<xml>\n<o:OfficeDocumentSettings>\n
+ \ <o:AllowPNG/>\n <o:PixelsPerInch>96</o:PixelsPerInch>\n</o:OfficeDocumentSettings>\n</xml>\n</noscript>\n<![endif]-->\n<!--[if
lte mso 11]>\n<style type=\"text/css\">\n.mj-outlook-group-fix {
width:100% !important; }\n</style>\n<![endif]-->\n<style type=\"text/css\">@media
only screen and (min-width:480px) { .mj-column-per-100 { width:100%
@@ -8469,6 +8397,75 @@ paths:
type: string
email_key:
type: string
+ "/api/v3/admin/email_templates/{email_template_id}/sample_records":
+ parameters:
+ - name: email_template_id
+ in: path
+ required: true
+ description: The template key with dots
+ schema:
+ type: string
+ get:
+ summary: List records to preview an email template with
+ tags:
+ - Email Templates
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ The store's five latest records the template can be previewed with,
+ newest first, to pass as `record_id` to the preview. For the layout
+ and partials, those of the email `email_key` names. Empty for an
+ email that needs no record.
+
+
+ **Required scope:** `write_email_templates` (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',
+ })
+
+ // The latest orders to preview the order confirmation with; pass one's id as `record_id`.
+ const { data: records } = await client.emailTemplates.sampleRecords.list(
+ 'spree.order_mailer.confirm_email',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /email_templates/{email_template_id}/sample_records
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: email_key
+ in: query
+ required: false
+ description: For the layout or a partial, the email to show it in
+ schema:
+ type: string
+ responses:
+ '200':
+ description: records found
+ content:
+ application/json:
+ example:
+ data:
+ - id: or_UkLWZg9DAJ
+ label: R1001
+ created_at: '2026-01-15T12:00:00.000Z'
"/api/v3/admin/email_templates/{email_template_id}/revisions":
parameters:
- name: email_template_id
@@ -8670,75 +8667,6 @@ paths:
example: any
lock_version:
type: integer
- "/api/v3/admin/email_templates/{email_template_id}/sample_records":
- parameters:
- - name: email_template_id
- in: path
- required: true
- description: The template key with dots
- schema:
- type: string
- get:
- summary: List records to preview an email template with
- tags:
- - Email Templates
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- The store's five latest records the template can be previewed with,
- newest first, to pass as `record_id` to the preview. For the layout
- and partials, those of the email `email_key` names. Empty for an
- email that needs no record.
-
-
- **Required scope:** `write_email_templates` (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',
- })
-
- // The latest orders to preview the order confirmation with; pass one's id as `record_id`.
- const { data: records } = await client.emailTemplates.sampleRecords.list(
- 'spree.order_mailer.confirm_email',
- )
- - lang: bash
- label: Spree CLI
- source: spree api get /email_templates/{email_template_id}/sample_records
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: email_key
- in: query
- required: false
- description: For the layout or a partial, the email to show it in
- schema:
- type: string
- responses:
- '200':
- description: records found
- content:
- application/json:
- example:
- data:
- - id: or_UkLWZg9DAJ
- label: R1001
- created_at: '2026-01-15T12:00:00.000Z'
"/api/v3/admin/exports":
get:
summary: List exports
@@ -9164,17 +9092,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -9199,10 +9127,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- 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'
+ adjustment_total: '0.00'
+ pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -9281,17 +9209,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_EfhxLZ9ck8
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
@@ -9316,10 +9244,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- adjustment_total: '0.0'
- pre_tax_amount: '0.0'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ adjustment_total: '0.00'
+ pre_tax_amount: '0.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -9473,17 +9401,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -9508,10 +9436,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- 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'
+ adjustment_total: '0.00'
+ pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -9582,17 +9510,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -9617,10 +9545,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- 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'
+ adjustment_total: '0.00'
+ pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -9705,17 +9633,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
@@ -9740,10 +9668,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- 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'
+ adjustment_total: '0.00'
+ pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -9818,17 +9746,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: delivered
fulfillment_type: shipping
@@ -9853,10 +9781,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- 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'
+ adjustment_total: '0.00'
+ pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -9949,17 +9877,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: canceled
fulfillment_type: shipping
@@ -9984,10 +9912,10 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
metadata: {}
- 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'
+ adjustment_total: '0.00'
+ pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -10069,17 +9997,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_EfhxLZ9ck8
unpriced: false
- cost: '10.0'
+ cost: '10.00'
display_cost: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -10091,10 +10019,10 @@ paths:
quantity: 1
deliveries: []
metadata: {}
- adjustment_total: '0.0'
- pre_tax_amount: '0.0'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ adjustment_total: '0.00'
+ pre_tax_amount: '0.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
documents: []
@@ -10198,7 +10126,7 @@ paths:
prefix: WELCOME
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '50.0'
+ amount: '50.00'
expires_at:
created_by_id:
meta:
@@ -10283,7 +10211,7 @@ paths:
prefix: NEWCAMP
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '25.0'
+ amount: '25.00'
expires_at: '2030-12-31'
created_by_id: adm_UkLWZg9DAJ
schema:
@@ -10390,7 +10318,7 @@ paths:
prefix: WELCOME
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '50.0'
+ amount: '50.00'
expires_at:
created_by_id:
schema:
@@ -10498,10 +10426,10 @@ paths:
code: C5BC700C4EF16A06
status: active
currency: USD
- amount: '50.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -10517,10 +10445,10 @@ paths:
code: 3BECEA5A776AD146
status: active
currency: USD
- amount: '25.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '25.0'
+ amount: '25.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '25.00'
display_amount: "$25.00"
display_amount_used: "$0.00"
display_amount_remaining: "$25.00"
@@ -10620,10 +10548,10 @@ paths:
code: A68048412201A26B
status: active
currency: USD
- amount: '25.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '25.0'
+ amount: '25.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '25.00'
display_amount: "$25.00"
display_amount_used: "$0.00"
display_amount_remaining: "$25.00"
@@ -10748,10 +10676,10 @@ paths:
code: 06BEABE5C26AA7E5
status: active
currency: USD
- amount: '50.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -10826,10 +10754,10 @@ paths:
code: E34E66F15D82A3CD
status: active
currency: USD
- amount: '75.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '75.0'
+ amount: '75.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '75.00'
display_amount: "$75.00"
display_amount_used: "$0.00"
display_amount_remaining: "$75.00"
@@ -11031,6 +10959,9 @@ paths:
- name: inventory_backorderable
label: Inventory Backorderable
required: false
+ - name: stock_location
+ label: Stock Location
+ required: false
- name: tax_category
label: Tax Category
required: false
@@ -11235,6 +11166,9 @@ paths:
- name: inventory_backorderable
label: Inventory Backorderable
required: false
+ - name: stock_location
+ label: Stock Location
+ required: false
- name: tax_category
label: Tax Category
required: false
@@ -11402,86 +11336,90 @@ paths:
file_column:
required: false
- id: immap_F0GX8NaP3Y
- schema_field: tax_category
+ schema_field: stock_location
file_column:
required: false
- id: immap_kOKT9MVfb0
- schema_field: product_type
+ schema_field: tax_category
file_column:
required: false
- id: immap_3uWpPTcf5W
- schema_field: hs_code
+ schema_field: product_type
file_column:
required: false
- id: immap_D6Psx31WaT
- schema_field: country_of_origin
+ schema_field: hs_code
file_column:
required: false
- id: immap_msx3nOJap6
- schema_field: customs_description
+ schema_field: country_of_origin
file_column:
required: false
- id: immap_5CQZnCRf8J
- schema_field: carton
+ schema_field: customs_description
file_column:
required: false
- id: immap_M2nyloHRUQ
- schema_field: units_per_carton
+ schema_field: carton
file_column:
required: false
- id: immap_prklVeMgbn
- schema_field: carton_weight
+ schema_field: units_per_carton
file_column:
required: false
- id: immap_so8jaGonyx
- schema_field: cartons_per_pallet
+ schema_field: carton_weight
file_column:
required: false
- id: immap_rsClYtECFI
- schema_field: image1_src
+ schema_field: cartons_per_pallet
file_column:
required: false
- id: immap_8DR0I7fEbw
- schema_field: image2_src
+ schema_field: image1_src
file_column:
required: false
- id: immap_aAtNvLSUAr
- schema_field: image3_src
+ schema_field: image2_src
file_column:
required: false
- id: immap_QiA48cIW7A
- schema_field: option1_name
+ schema_field: image3_src
file_column:
required: false
- id: immap_QDA48cIW7A
- schema_field: option1_value
+ schema_field: option1_name
file_column:
required: false
- id: immap_8cR0I7fEbw
- schema_field: option2_name
+ schema_field: option1_value
file_column:
required: false
- id: immap_oqlrKdXjaP
- schema_field: option2_value
+ schema_field: option2_name
file_column:
required: false
- id: immap_48Olu6p4zZ
- schema_field: option3_name
+ schema_field: option2_value
file_column:
required: false
- id: immap_qp31JYFduR
- schema_field: option3_value
+ schema_field: option3_name
file_column:
required: false
- id: immap_JgaEBgznCp
- schema_field: category1
+ schema_field: option3_value
file_column:
required: false
- id: immap_tXyJwvFCuK
- schema_field: category2
+ schema_field: category1
file_column:
required: false
- id: immap_NJzXvxTk8u
+ schema_field: category2
+ file_column:
+ required: false
+ - id: immap_XLbb5HTmVa
schema_field: category3
file_column:
required: false
@@ -11735,6 +11673,9 @@ paths:
- name: inventory_backorderable
label: Inventory Backorderable
required: false
+ - name: stock_location
+ label: Stock Location
+ required: false
- name: tax_category
label: Tax Category
required: false
@@ -11997,6 +11938,9 @@ paths:
- name: inventory_backorderable
label: Inventory Backorderable
required: false
+ - name: stock_location
+ label: Stock Location
+ required: false
- name: tax_category
label: Tax Category
required: false
@@ -12156,86 +12100,90 @@ paths:
file_column: inventory_backorderable
required: false
- id: immap_F0GX8NaP3Y
+ schema_field: stock_location
+ file_column:
+ required: false
+ - id: immap_kOKT9MVfb0
schema_field: tax_category
file_column: tax_category
required: false
- - id: immap_kOKT9MVfb0
+ - id: immap_3uWpPTcf5W
schema_field: product_type
file_column:
required: false
- - id: immap_3uWpPTcf5W
+ - id: immap_D6Psx31WaT
schema_field: hs_code
file_column:
required: false
- - id: immap_D6Psx31WaT
+ - id: immap_msx3nOJap6
schema_field: country_of_origin
file_column:
required: false
- - id: immap_msx3nOJap6
+ - id: immap_5CQZnCRf8J
schema_field: customs_description
file_column:
required: false
- - id: immap_5CQZnCRf8J
+ - id: immap_M2nyloHRUQ
schema_field: carton
file_column:
required: false
- - id: immap_M2nyloHRUQ
+ - id: immap_prklVeMgbn
schema_field: units_per_carton
file_column:
required: false
- - id: immap_prklVeMgbn
+ - id: immap_so8jaGonyx
schema_field: carton_weight
file_column:
required: false
- - id: immap_so8jaGonyx
+ - id: immap_rsClYtECFI
schema_field: cartons_per_pallet
file_column:
required: false
- - id: immap_rsClYtECFI
+ - id: immap_8DR0I7fEbw
schema_field: image1_src
file_column: image1_src
required: false
- - id: immap_8DR0I7fEbw
+ - id: immap_aAtNvLSUAr
schema_field: image2_src
file_column: image2_src
required: false
- - id: immap_aAtNvLSUAr
+ - id: immap_QiA48cIW7A
schema_field: image3_src
file_column: image3_src
required: false
- - id: immap_QiA48cIW7A
+ - id: immap_QDA48cIW7A
schema_field: option1_name
file_column: option1_name
required: false
- - id: immap_QDA48cIW7A
+ - id: immap_8cR0I7fEbw
schema_field: option1_value
file_column: option1_value
required: false
- - id: immap_8cR0I7fEbw
+ - id: immap_oqlrKdXjaP
schema_field: option2_name
file_column: option2_name
required: false
- - id: immap_oqlrKdXjaP
+ - id: immap_48Olu6p4zZ
schema_field: option2_value
file_column: option2_value
required: false
- - id: immap_48Olu6p4zZ
+ - id: immap_qp31JYFduR
schema_field: option3_name
file_column: option3_name
required: false
- - id: immap_qp31JYFduR
+ - id: immap_JgaEBgznCp
schema_field: option3_value
file_column: option3_value
required: false
- - id: immap_JgaEBgznCp
+ - id: immap_tXyJwvFCuK
schema_field: category1
file_column: category1
required: false
- - id: immap_tXyJwvFCuK
+ - id: immap_NJzXvxTk8u
schema_field: category2
file_column: category2
required: false
- - id: immap_NJzXvxTk8u
+ - id: immap_XLbb5HTmVa
schema_field: category3
file_column: category3
required: false
@@ -12386,6 +12334,9 @@ paths:
- name: inventory_backorderable
label: Inventory Backorderable
required: false
+ - name: stock_location
+ label: Stock Location
+ required: false
- name: tax_category
label: Tax Category
required: false
@@ -13590,7 +13541,7 @@ paths:
return_line_item_id:
claim_line_item_id:
exchange_line_item_id:
- amount: '1.5'
+ amount: '1.50'
display_amount: "$1.50"
provider_id: internal
metadata: {}
@@ -13671,7 +13622,7 @@ paths:
promotion_id:
line_item_id: li_UkLWZg9DAJ
fulfillment_id:
- amount: "-2.0"
+ amount: "-2.00"
display_amount: "-$2.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
@@ -13711,14 +13662,14 @@ paths:
// Line-item discount; omit line_item_id to distribute across the order.
const { data: discounts } = await client.orders.discounts.create('or_abc123', {
label: 'Customer appeasement',
- value: 10,
+ value: '10',
value_type: 'flat',
line_item_id: 'item_abc123',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/discounts -d '{"label":"Customer
- appeasement","value":10,"value_type":"flat","line_item_id":"item_abc123"}'
+ appeasement","value":"10","value_type":"flat","line_item_id":"item_abc123"}'
parameters:
- name: x-spree-api-key
in: header
@@ -13748,11 +13699,11 @@ paths:
kind: manual
code:
value_type: flat
- value: '3.0'
+ value: '3.00'
promotion_id:
line_item_id: li_UkLWZg9DAJ
fulfillment_id:
- amount: "-3.0"
+ amount: "-3.00"
display_amount: "-$3.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
@@ -13816,12 +13767,12 @@ paths:
const fee = await client.orders.fees.create('or_abc123', {
label: 'Gift wrap',
- amount: 4,
+ amount: '4.00',
kind: 'gift_wrap',
})
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":4,"kind":"gift_wrap"}'
+ source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":"4.00","kind":"gift_wrap"}'
parameters:
- name: x-spree-api-key
in: header
@@ -13850,7 +13801,7 @@ paths:
kind: gift_wrap
line_item_id:
fulfillment_id:
- amount: '4.0'
+ amount: '4.00'
display_amount: "$4.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
@@ -13879,8 +13830,8 @@ paths:
type: string
example: Gift wrap
amount:
- type: number
- example: 4
+ type: string
+ example: '4.00'
kind:
type: string
enum:
@@ -13959,10 +13910,10 @@ paths:
code: "************2F41"
status: active
currency: USD
- amount: '10.0'
- amount_used: '10.0'
- amount_authorized: '0.0'
- amount_remaining: '0.0'
+ amount: '10.00'
+ amount_used: '10.00'
+ amount_authorized: '0.00'
+ amount_remaining: '0.00'
display_amount: "$10.00"
display_amount_used: "$10.00"
display_amount_remaining: "$0.00"
@@ -14116,21 +14067,21 @@ paths:
name: Product 479180
slug: product-479180
options_text: 'Size: S'
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '20.0'
+ total: '20.00'
display_total: "$20.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '20.0'
+ pre_tax_amount: '20.00'
display_pre_tax_amount: "$20.00"
- discounted_amount: '20.0'
+ discounted_amount: '20.00'
display_discounted_amount: "$20.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -14158,7 +14109,7 @@ paths:
price_list_name:
catalog_id:
catalog_name:
- cost_price: '17.0'
+ cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
@@ -14237,13 +14188,13 @@ paths:
display_price: "$19.99"
total: '59.97'
display_total: "$59.97"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
pre_tax_amount: '59.97'
display_pre_tax_amount: "$59.97"
@@ -14275,7 +14226,7 @@ paths:
price_list_name:
catalog_id:
catalog_name:
- cost_price: '17.0'
+ cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
content:
@@ -14372,21 +14323,21 @@ paths:
name: Product 502714
slug: product-502714
options_text: 'Size: S'
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '20.0'
+ total: '20.00'
display_total: "$20.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '20.0'
+ pre_tax_amount: '20.00'
display_pre_tax_amount: "$20.00"
- discounted_amount: '20.0'
+ discounted_amount: '20.00'
display_discounted_amount: "$20.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -14414,7 +14365,7 @@ paths:
price_list_name:
catalog_id:
catalog_name:
- cost_price: '17.0'
+ cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
summary: Update an item
@@ -14488,13 +14439,13 @@ paths:
display_price: "$19.99"
total: '99.95'
display_total: "$99.95"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
pre_tax_amount: '99.95'
display_pre_tax_amount: "$99.95"
@@ -14526,7 +14477,7 @@ paths:
price_list_name:
catalog_id:
catalog_name:
- cost_price: '17.0'
+ cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
content:
@@ -14663,29 +14614,29 @@ paths:
fulfillment_status:
payment_status:
completed_at:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '60.0'
+ amount_due: '60.00'
display_amount_due: "$60.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '50.0'
+ store_credit_total: '50.00'
display_store_credit_total: "-$50.00"
covered_by_store_credit: false
gift_card:
@@ -14711,20 +14662,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -14929,29 +14880,29 @@ paths:
fulfillment_status:
payment_status:
completed_at:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '0.0'
+ total: '0.00'
display_total: "$0.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
fee_total:
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -14977,20 +14928,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -15172,29 +15123,29 @@ paths:
fulfillment_status:
payment_status:
completed_at:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '0.0'
+ total: '0.00'
display_total: "$0.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -15220,20 +15171,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id: sloc_UkLWZg9DAJ
po_document_url:
seller_id:
@@ -15448,29 +15399,29 @@ paths:
fulfillment_status:
payment_status:
completed_at:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '0.0'
+ total: '0.00'
display_total: "$0.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
fee_total:
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -15496,20 +15447,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -15610,31 +15561,31 @@ paths:
total_quantity: 0
coupon_code:
fulfillment_status:
- payment_status:
+ payment_status: none
completed_at:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '0.0'
+ total: '0.00'
display_total: "$0.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -15660,20 +15611,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -15895,29 +15846,29 @@ paths:
fulfillment_status: unfulfilled
payment_status: paid
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -15943,20 +15894,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '110.0'
- display_payment_total: "$110.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '110.00'
+ display_payment_total: "$110.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -16094,29 +16045,29 @@ paths:
fulfillment_status: canceled
payment_status: none
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: "-0.0"
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -16142,20 +16093,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at: '2026-01-15T12:00:00.000Z'
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -16271,29 +16222,29 @@ paths:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -16319,20 +16270,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -16422,29 +16373,29 @@ paths:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
gift_card:
@@ -16470,20 +16421,20 @@ paths:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
metadata: {}
cancel_note:
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ display_payment_total: "$0.00"
+ commission_amount_total: '0.00'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.00'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.00'
+ display_commission_total: "$0.00"
preferred_stock_location_id:
po_document_url:
seller_id:
@@ -16577,6 +16528,9 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
preferences: {}
preference_schema: []
+ logo_url:
+ docs_url:
+ third_party: false
meta:
page: 1
limit: 25
@@ -16642,10 +16596,16 @@ paths:
- key: dummy_secret_key
type: password
default:
+ logo_url:
+ docs_url:
+ third_party: true
- type: custom_payment_source_method
label: Custom Payment Source Method
description:
preference_schema: []
+ logo_url:
+ docs_url:
+ third_party: false
"/api/v3/admin/payment_methods/{id}":
get:
summary: Show a payment method
@@ -16726,6 +16686,9 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
preferences: {}
preference_schema: []
+ logo_url:
+ docs_url:
+ third_party: false
"/api/v3/admin/orders/{order_id}/payments":
get:
summary: List payments
@@ -16797,7 +16760,7 @@ paths:
response_code: BGS-343039b69b86
number: R1001-P1
status: completed
- amount: '110.0'
+ amount: '110.00'
display_amount: "$110.00"
source_type: credit_card
source_id: card_UkLWZg9DAJ
@@ -16821,7 +16784,7 @@ paths:
cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.0'
+ captured_amount: '0.00'
order_id: or_UkLWZg9DAJ
meta:
page: 1
@@ -16892,7 +16855,7 @@ paths:
response_code:
number: R1002-P1
status: checkout
- amount: '110.0'
+ amount: '110.00'
display_amount: "$110.00"
source_type:
source_id:
@@ -16903,7 +16866,7 @@ paths:
cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.0'
+ captured_amount: '0.00'
order_id: or_gbHJdmfrXB
requestBody:
content:
@@ -16998,7 +16961,7 @@ paths:
response_code: BGS-4a236d40ef07
number: R1001-P1
status: completed
- amount: '110.0'
+ amount: '110.00'
display_amount: "$110.00"
source_type: credit_card
source_id: card_UkLWZg9DAJ
@@ -17022,7 +16985,7 @@ paths:
cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.0'
+ captured_amount: '0.00'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
patch:
@@ -17087,7 +17050,7 @@ paths:
response_code: BGS-ccc19f06b194
number: R1001-P1
status: completed
- amount: '110.0'
+ amount: '110.00'
display_amount: "$110.00"
source_type: credit_card
source_id: card_UkLWZg9DAJ
@@ -17111,7 +17074,7 @@ paths:
cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '110.0'
+ captured_amount: '110.00'
order_id: or_UkLWZg9DAJ
'422':
description: capture failed
@@ -17185,7 +17148,7 @@ paths:
response_code: void-BGS-11f2e975ba0c
number: R1001-P1
status: void
- amount: '110.0'
+ amount: '110.00'
display_amount: "$110.00"
source_type: credit_card
source_id: card_UkLWZg9DAJ
@@ -17209,7 +17172,7 @@ paths:
cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.0'
+ captured_amount: '0.00'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
get:
@@ -18032,11 +17995,9 @@ paths:
example:
data:
- id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -18045,11 +18006,9 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- id: price_gbHJdmfrXB
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -18058,11 +18017,9 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- id: price_EfhxLZ9ck8
- amount: '5.0'
- amount_in_cents: 500
- compare_at_amount:
- compare_at_amount_in_cents:
currency: USD
+ amount: '5.00'
+ compare_at_amount:
display_amount: "$5.00"
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
@@ -18142,11 +18099,9 @@ paths:
application/json:
example:
id: price_uw2YK1rnl0
+ currency: EUR
amount: '9.99'
- amount_in_cents: 999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: EUR
display_amount: "€9.99"
display_compare_at_amount:
price_list_id:
@@ -18231,11 +18186,9 @@ paths:
application/json:
example:
id: price_EfhxLZ9ck8
- amount: '5.0'
- amount_in_cents: 500
- compare_at_amount:
- compare_at_amount_in_cents:
currency: USD
+ amount: '5.00'
+ compare_at_amount:
display_amount: "$5.00"
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
@@ -18298,11 +18251,9 @@ paths:
application/json:
example:
id: price_EfhxLZ9ck8
+ currency: USD
amount: '12.34'
- amount_in_cents: 1234
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$12.34"
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
@@ -19115,11 +19066,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -19510,11 +19459,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -19634,11 +19581,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -23186,7 +23131,7 @@ paths:
},
{
type: 'item_total',
- preferences: { amount_min: 100, operator_min: 'gte' },
+ preferences: { amount_min: '100.00', operator_min: 'gte' },
},
{
type: 'product',
@@ -23199,7 +23144,7 @@ paths:
type: 'create_item_adjustments',
calculator: {
type: 'percent_on_line_item',
- preferences: { percent: 25 },
+ preferences: { percent: '25' },
},
},
{ type: 'free_shipping' },
@@ -23470,7 +23415,7 @@ paths:
// Add a new rule
{
type: 'item_total',
- preferences: { amount_min: 50, operator_min: 'gte' },
+ preferences: { amount_min: '50.00', operator_min: 'gte' },
},
],
actions: [
@@ -23480,7 +23425,7 @@ paths:
type: 'create_item_adjustments',
calculator: {
type: 'percent_on_line_item',
- preferences: { percent: 15 },
+ preferences: { percent: '15' },
},
},
],
@@ -23717,7 +23662,8 @@ paths:
data:
- type: create_line_items
label: Create line items
- description: Populates the cart with the specified quantity of variant
+ description: Adds the specified quantity of a variant to the cart
+ free of charge
preference_schema: []
- type: create_item_adjustments
label: Create per-line-item adjustment
@@ -24006,7 +23952,7 @@ paths:
example:
id: re_UkLWZg9DAJ
transaction_id: BGS-c5ae59a82a25
- amount: '5.0'
+ amount: '5.00'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
originator_id:
@@ -24014,7 +23960,7 @@ paths:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- tax_amount: '0.0'
+ tax_amount: '0.00'
refunder_id: adm_UkLWZg9DAJ
refunder_type: admin_user
requestBody:
@@ -24066,7 +24012,7 @@ paths:
example:
data:
- code: de
- name: de
+ name: Deutsch
default: false
rtl: false
- code: en
@@ -24074,7 +24020,7 @@ paths:
default: true
rtl: false
- code: fr
- name: fr
+ name: Français
default: false
rtl: false
"/api/v3/admin/store":
@@ -24179,8 +24125,8 @@ paths:
preferred_order_routing_strategy: rules
preferred_payout_provider:
order_number_sequence_started: false
- preferred_default_minimum_payout_amount: 0.0
- preferred_default_commission_tax_rate: 0.0
+ preferred_default_minimum_payout_amount: '0.00'
+ preferred_default_commission_tax_rate: '0'
url: http://www.example.com:3000
api_url: http://www.example.com:3000
setup_tasks:
@@ -24518,8 +24464,8 @@ paths:
preferred_order_routing_strategy: rules
preferred_payout_provider:
order_number_sequence_started: false
- preferred_default_minimum_payout_amount: 0.0
- preferred_default_commission_tax_rate: 0.0
+ preferred_default_minimum_payout_amount: '0.00'
+ preferred_default_commission_tax_rate: '0'
url: http://www.example.com:3000
api_url: http://www.example.com:3000
setup_tasks:
@@ -24925,8 +24871,8 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
deleted_at:
- amount: '0.19'
- amount_percentage: 19.0
+ rate: '0.19'
+ rate_percent: '19'
tax_category_id: taxcat_UkLWZg9DAJ
store_id: store_UkLWZg9DAJ
country_code: DE
@@ -24971,8 +24917,8 @@ paths:
- api_key: []
bearer_auth: []
description: |-
- Creates a tax rate for the current store. Give either `amount` as a
- decimal (`0.19`) or `amount_percentage` as a percentage (`19`).
+ Creates a tax rate for the current store. Give either `rate` as a
+ decimal string (`"0.19"`) or `rate_percent` as a percentage string (`"19"`).
Name the jurisdiction with `country_code` (and `state_code` for a
state-level rate). Omitting the country makes the rate apply everywhere.
@@ -25008,8 +24954,8 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
deleted_at:
- amount: '0.19'
- amount_percentage: 19.0
+ rate: '0.19'
+ rate_percent: '19'
tax_category_id: taxcat_UkLWZg9DAJ
store_id: store_UkLWZg9DAJ
country_code: DE
@@ -25044,12 +24990,12 @@ paths:
name:
type: string
description: Customer-facing rate name, e.g. "VAT"
- amount:
+ rate:
type: string
- description: Rate as a decimal, e.g. "0.19"
- amount_percentage:
- type: number
- description: Rate as a percentage, e.g. 19
+ description: Rate as a decimal string, e.g. "0.19"
+ rate_percent:
+ type: string
+ description: Rate as a percentage string, e.g. "19"
included_in_price:
type: boolean
show_rate_in_label:
@@ -25108,8 +25054,8 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
deleted_at:
- amount: '0.19'
- amount_percentage: 19.0
+ rate: '0.19'
+ rate_percent: '19'
tax_category_id: taxcat_UkLWZg9DAJ
store_id: store_UkLWZg9DAJ
country_code: DE
@@ -25150,8 +25096,8 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
deleted_at:
- amount: '0.07'
- amount_percentage: 7.0
+ rate: '0.07'
+ rate_percent: '7'
tax_category_id: taxcat_UkLWZg9DAJ
store_id: store_UkLWZg9DAJ
country_code: DE
@@ -25166,10 +25112,10 @@ paths:
properties:
name:
type: string
- amount:
+ rate:
+ type: string
+ rate_percent:
type: string
- amount_percentage:
- type: number
included_in_price:
type: boolean
show_rate_in_label:
@@ -26364,6 +26310,20 @@ paths:
group_label: Settings
label: Webhooks
description: Webhook endpoints and deliveries
+ - key: read_email_templates
+ resource: email_templates
+ kind: read
+ group: settings
+ group_label: Settings
+ label: Email templates
+ description: Customer email templates and the email layout
+ - key: write_email_templates
+ resource: email_templates
+ kind: write
+ group: settings
+ group_label: Settings
+ label: Email templates
+ description: Customer email templates and the email layout
- key: read_integrations
resource: integrations
kind: read
@@ -26407,7 +26367,7 @@ paths:
label: Staff & roles
description: Team members, invitations, roles and their permissions
meta:
- count: 55
+ count: 57
"/api/v3/admin/roles":
get:
summary: List roles
@@ -26508,6 +26468,8 @@ paths:
- write_package_types
- read_webhooks
- write_webhooks
+ - read_email_templates
+ - write_email_templates
- read_integrations
- write_integrations
- read_api_keys
@@ -27530,9 +27492,9 @@ paths:
example:
data:
- id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -27541,7 +27503,7 @@ paths:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount_authorized: '0.0'
+ amount_authorized: '0.00'
outstanding: true
display_amount_authorized: "$0.00"
customer_id: cust_UkLWZg9DAJ
@@ -27646,9 +27608,9 @@ paths:
application/json:
example:
id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -27657,7 +27619,7 @@ paths:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount_authorized: '0.0'
+ amount_authorized: '0.00'
outstanding: true
display_amount_authorized: "$0.00"
customer_id: cust_UkLWZg9DAJ
@@ -27746,7 +27708,7 @@ paths:
action: allocation
authorization_code: 1-SC-20260115120000000000
display_action: Added
- amount: '50.0'
+ amount: '50.00'
display_amount: "$50.00"
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -27880,11 +27842,9 @@ paths:
units_per_carton:
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -27894,7 +27854,6 @@ paths:
external_references: {}
metadata: {}
position: 1
- cost_price: '17.0'
cost_currency: USD
barcode:
backorder_limit:
@@ -27906,8 +27865,9 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price: '17.00'
preorderable: false
- tax_category_id: taxcat_UkLWZg9DAJ
+ tax_category_id:
carton_package_type_id:
units_per_pallet:
available_stock: 0
@@ -27939,11 +27899,9 @@ paths:
units_per_carton:
price:
id: price_gbHJdmfrXB
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -27965,7 +27923,6 @@ paths:
external_references: {}
metadata: {}
position: 2
- cost_price: '17.0'
cost_currency: USD
barcode:
backorder_limit:
@@ -27977,8 +27934,9 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price: '17.00'
preorderable: false
- tax_category_id: taxcat_UkLWZg9DAJ
+ tax_category_id:
carton_package_type_id:
units_per_pallet:
available_stock: 0
@@ -28085,11 +28043,9 @@ paths:
units_per_carton:
price:
id: price_EfhxLZ9ck8
+ currency: USD
amount: '24.99'
- amount_in_cents: 2499
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$24.99"
display_compare_at_amount:
price_list_id:
@@ -28111,7 +28067,6 @@ paths:
external_references: {}
metadata: {}
position: 3
- cost_price:
cost_currency: USD
barcode:
backorder_limit:
@@ -28123,8 +28078,9 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price:
preorderable: false
- tax_category_id: taxcat_UkLWZg9DAJ
+ tax_category_id:
carton_package_type_id:
units_per_pallet:
available_stock: 0
@@ -28334,11 +28290,9 @@ paths:
units_per_carton:
price:
id: price_gbHJdmfrXB
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -28360,7 +28314,6 @@ paths:
external_references: {}
metadata: {}
position: 2
- cost_price: '17.0'
cost_currency: USD
barcode:
backorder_limit:
@@ -28372,8 +28325,9 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price: '17.00'
preorderable: false
- tax_category_id: taxcat_UkLWZg9DAJ
+ tax_category_id:
carton_package_type_id:
units_per_pallet:
available_stock: 0
@@ -28474,11 +28428,9 @@ paths:
units_per_carton:
price:
id: price_gbHJdmfrXB
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -28500,7 +28452,6 @@ paths:
external_references: {}
metadata: {}
position: 2
- cost_price: '17.0'
cost_currency: USD
barcode:
backorder_limit:
@@ -28512,8 +28463,9 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price: '17.00'
preorderable: false
- tax_category_id: taxcat_UkLWZg9DAJ
+ tax_category_id:
carton_package_type_id:
units_per_pallet:
available_stock: 0
@@ -29535,7 +29487,7 @@ paths:
data:
message: This is a test webhook from Spree.
metadata:
- spree_version: 6.0.0.beta2
+ spree_version: 6.0.0.rc1
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks/orders
"/api/v3/admin/webhook_endpoints/{id}/enable":
@@ -30000,6 +29952,18 @@ paths:
credential: false
deprecated: false
replaced_by:
+ - name: email_template.published
+ group: email_template
+ credential_permission:
+ credential: false
+ deprecated: false
+ replaced_by:
+ - name: email_template.reverted
+ group: email_template
+ credential_permission:
+ credential: false
+ deprecated: false
+ replaced_by:
- name: exchange.approved
group: exchange
credential_permission:
@@ -31546,7 +31510,7 @@ paths:
currency: USD
source: automatic
break_count: 0
- amount: '80.0'
+ amount: '80.00'
display_amount: "$80.00"
tiers: []
meta:
@@ -31706,7 +31670,7 @@ paths:
currency: USD
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '500.0'
+ amount: '500.00'
display_amount: "$500.00"
meta:
page: 1
@@ -31755,7 +31719,7 @@ paths:
currency: USD
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '500.0'
+ amount: '500.00'
display_amount: "$500.00"
'422':
description: invalid request
@@ -31830,7 +31794,7 @@ paths:
currency: USD
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '750.0'
+ amount: '750.00'
display_amount: "$750.00"
requestBody:
content:
@@ -32835,11 +32799,11 @@ paths:
state_code:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- rate: '10.0'
- tax_rate: '0.0'
- amount: '10.0'
- tax_amount: '2.1'
- total: '12.1'
+ rate: '10'
+ tax_rate: '0'
+ amount: '10.00'
+ tax_amount: '2.10'
+ total: '12.10'
display_amount: "$10.00"
display_tax_amount: "$2.10"
display_total: "$12.10"
@@ -32922,11 +32886,11 @@ paths:
state_code:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- rate: '10.0'
- tax_rate: '0.0'
- amount: '10.0'
- tax_amount: '2.1'
- total: '12.1'
+ rate: '10'
+ tax_rate: '0'
+ amount: '10.00'
+ tax_amount: '2.10'
+ total: '12.10'
display_amount: "$10.00"
display_tax_amount: "$2.10"
display_total: "$12.10"
@@ -33048,7 +33012,7 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- value: '10.0'
+ value: '10'
commission_tax_rate:
amounts: {}
bounds: {}
@@ -33129,12 +33093,12 @@ paths:
const commissionRate = await client.commissionRates.create({
name: 'Audio sellers',
kind: 'percentage',
- value: 12.5,
+ value: '12.5',
rules: [{ type: 'seller_rule', preferences: { seller_ids: ['sel_a1b2c3'] } }],
})
- lang: bash
label: Spree CLI
- source: spree api post /commission_rates -d '{"name":"Audio sellers","kind":"percentage","value":12.5,"rules":[{"type":"seller_rule","preferences":{"seller_ids":["sel_a1b2c3"]}}]}'
+ source: spree api post /commission_rates -d '{"name":"Audio sellers","kind":"percentage","value":"12.5","rules":[{"type":"seller_rule","preferences":{"seller_ids":["sel_a1b2c3"]}}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -33452,7 +33416,7 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- value: '10.0'
+ value: '10'
commission_tax_rate:
amounts: {}
bounds: {}
@@ -33501,7 +33465,7 @@ paths:
// Every rule has to hold, so this charges 15% only on camera sales worth 50 or
// more. Call ruleTypes() for the kinds this marketplace has.
const commissionRate = await client.commissionRates.update('crate_a1b2c3', {
- value: 15,
+ value: '15',
position: 1,
rules: [
{ type: 'category_rule', preferences: { category_ids: ['ctg_d4e5f6'] } },
@@ -33510,7 +33474,7 @@ paths:
})
- lang: bash
label: Spree CLI
- source: spree api patch /commission_rates/{id} -d '{"value":15,"position":1,"rules":[{"type":"category_rule","preferences":{"category_ids":["ctg_d4e5f6"]}},{"type":"item_total_rule","preferences":{"min_amount":"50"}}]}'
+ source: spree api patch /commission_rates/{id} -d '{"value":"15","position":1,"rules":[{"type":"category_rule","preferences":{"category_ids":["ctg_d4e5f6"]}},{"type":"item_total_rule","preferences":{"min_amount":"50"}}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -33540,7 +33504,7 @@ paths:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- value: '15.0'
+ value: '15'
commission_tax_rate:
amounts: {}
bounds: {}
@@ -35147,12 +35111,12 @@ paths:
admin_name:
storefront_visible: true
tracking_url:
- markup_flat: '0.0'
- markup_percent: '0.0'
available_to_sellers: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
deleted_at:
+ markup_flat: '0.00'
+ markup_percent: '0'
seller_id:
seller_name:
services: []
@@ -35206,11 +35170,11 @@ paths:
name: 'Express',
storefront_visible: true,
calculator_type: 'flat_rate',
- calculator_preferences: { amount: 12.5 },
+ calculator_preferences: { amount: '12.50' },
})
- lang: bash
label: Spree CLI
- source: spree api post /delivery_methods -d '{"name":"Express","storefront_visible":true,"calculator_type":"flat_rate","calculator_preferences":{"amount":12.5}}'
+ source: spree api post /delivery_methods -d '{"name":"Express","storefront_visible":true,"calculator_type":"flat_rate","calculator_preferences":{"amount":"12.50"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -35239,12 +35203,12 @@ paths:
admin_name:
storefront_visible: true
tracking_url:
- markup_flat: '0.0'
- markup_percent: '0.0'
available_to_sellers: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
deleted_at:
+ markup_flat: '0.00'
+ markup_percent: '0'
seller_id:
seller_name:
services: []
@@ -35306,7 +35270,7 @@ paths:
calculator_preferences:
type: object
example:
- amount: 12.5
+ amount: '12.50'
delivery_zone_id:
type: string
nullable: true
@@ -35764,6 +35728,7 @@ paths:
group: shipping
description:
logo_url:
+ docs_url:
preference_schema:
- key: api_key
type: password
@@ -35882,13 +35847,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--842df2157f0239c97e8da1cb68e59bad0bb1c65c/thinking-cat.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--efc4098d67c95b766076ffd76169e7d49199c517/thinking-cat.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e5a1c73260840c5ab2bb78ebed47f7f5db621e85/thinking-cat.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--60df672360d3d2c45cd72572b2e6faf9882995e1/thinking-cat.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--74872e2b62fcbb93875b99ea99356c004855f9d3/thinking-cat.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--e97abb6268b26c7a282c61cd0aedea525f75a555/thinking-cat.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d3a46db98d461edbc92f4d1d14f99f639cb15087/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--63ef6aa9ca6a6e3b5704dc687ed6f080fabf692f/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1e7847a62f1405e24752088eb14d831cf14ae3b1/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--4ff8dae08e622f6f0994f915853fb55ea5dd6096/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--a564119223492e47a2b9ea3bccabab85e29b91bb/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--1c91b3d2baa279b11c9ef793097134edaacbb97f/thinking-cat.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -35896,10 +35861,10 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8bb0d93bcda0e7a158700e75fe6ce3f53ca8d223/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b97c0026639f4fcf9a36eba47fe3cfe943cf96d7/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4
viewable_id: prod_UkLWZg9DAJ
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/thinking-cat.jpg?disposition=attachment
metadata: {}
viewable_type: product
meta:
@@ -35970,13 +35935,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/library-upload.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--842df2157f0239c97e8da1cb68e59bad0bb1c65c/library-upload.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--efc4098d67c95b766076ffd76169e7d49199c517/library-upload.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e5a1c73260840c5ab2bb78ebed47f7f5db621e85/library-upload.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--60df672360d3d2c45cd72572b2e6faf9882995e1/library-upload.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--74872e2b62fcbb93875b99ea99356c004855f9d3/library-upload.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--e97abb6268b26c7a282c61cd0aedea525f75a555/library-upload.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/library-upload.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d3a46db98d461edbc92f4d1d14f99f639cb15087/library-upload.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--63ef6aa9ca6a6e3b5704dc687ed6f080fabf692f/library-upload.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1e7847a62f1405e24752088eb14d831cf14ae3b1/library-upload.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--4ff8dae08e622f6f0994f915853fb55ea5dd6096/library-upload.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--a564119223492e47a2b9ea3bccabab85e29b91bb/library-upload.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--1c91b3d2baa279b11c9ef793097134edaacbb97f/library-upload.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -35984,10 +35949,10 @@ paths:
filename: library-upload.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8bb0d93bcda0e7a158700e75fe6ce3f53ca8d223/library-upload.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b97c0026639f4fcf9a36eba47fe3cfe943cf96d7/library-upload.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d
viewable_id:
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/library-upload.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--2f007f4f0a7103707989ed889e97fb9bb2b5259d/library-upload.jpg?disposition=attachment
metadata: {}
viewable_type:
schema:
@@ -36144,13 +36109,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--842df2157f0239c97e8da1cb68e59bad0bb1c65c/thinking-cat.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--efc4098d67c95b766076ffd76169e7d49199c517/thinking-cat.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e5a1c73260840c5ab2bb78ebed47f7f5db621e85/thinking-cat.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--60df672360d3d2c45cd72572b2e6faf9882995e1/thinking-cat.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--74872e2b62fcbb93875b99ea99356c004855f9d3/thinking-cat.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--e97abb6268b26c7a282c61cd0aedea525f75a555/thinking-cat.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d3a46db98d461edbc92f4d1d14f99f639cb15087/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--63ef6aa9ca6a6e3b5704dc687ed6f080fabf692f/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1e7847a62f1405e24752088eb14d831cf14ae3b1/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--4ff8dae08e622f6f0994f915853fb55ea5dd6096/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--a564119223492e47a2b9ea3bccabab85e29b91bb/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--1c91b3d2baa279b11c9ef793097134edaacbb97f/thinking-cat.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -36158,10 +36123,10 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8bb0d93bcda0e7a158700e75fe6ce3f53ca8d223/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b97c0026639f4fcf9a36eba47fe3cfe943cf96d7/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4
viewable_id: prod_gbHJdmfrXB
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4/thinking-cat.jpg?disposition=attachment
metadata: {}
viewable_type: product
schema:
@@ -37607,12 +37572,12 @@ paths:
currency: USD
source: base
break_count: 1
- amount: '100.0'
+ amount: '100.00'
display_amount: "$100.00"
tiers:
- min_quantity: 24
display_amount: "$80.00"
- amount: '80.0'
+ amount: '80.00'
meta:
page: 1
limit: 25
@@ -38239,7 +38204,7 @@ paths:
closed_short: false
quantity_ordered_total: 100
editable: true
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -38351,7 +38316,7 @@ paths:
closed_short: false
quantity_ordered_total: 100
editable: true
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -38480,7 +38445,7 @@ paths:
closed_short: false
quantity_ordered_total: 100
editable: true
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -38494,9 +38459,9 @@ paths:
currency: USD
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- unit_cost: '12.5'
- total_cost: '1250.0'
+ unit_cost: '12.50'
display_unit_cost: "$12.50"
+ total_cost: '1250.00'
display_total_cost: "$1,250.00"
purchase_order_id: po_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
@@ -38598,7 +38563,7 @@ paths:
closed_short: false
quantity_ordered_total: 100
editable: false
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -38902,7 +38867,7 @@ paths:
closed_short: false
quantity_ordered_total: 100
editable: true
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -38989,7 +38954,7 @@ paths:
closed_short: true
quantity_ordered_total: 100
editable: false
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -39068,7 +39033,7 @@ paths:
closed_short: false
quantity_ordered_total: 100
editable: false
- subtotal: '1250.0'
+ subtotal: '1250.00'
display_subtotal: "$1,250.00"
supplier_id: sup_UkLWZg9DAJ
destination_location_id: sloc_UkLWZg9DAJ
@@ -40876,15 +40841,15 @@ paths:
settlement_currency: USD
converted: false
seller_id: sel_UkLWZg9DAJ
- earned: '40.0'
+ earned: '40.00'
display_earned: "$40.00"
- payable: '40.0'
+ payable: '40.00'
display_payable: "$40.00"
- paid: '0.0'
+ paid: '0.00'
display_paid: "$0.00"
- balance: '40.0'
+ balance: '40.00'
display_balance: "$40.00"
- pending: '0.0'
+ pending: '0.00'
display_pending: "$0.00"
schema:
type: object
@@ -40965,7 +40930,7 @@ paths:
period_end: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '40.0'
+ amount: '40.00'
display_amount: "$40.00"
seller_id: sel_UkLWZg9DAJ
seller_name: Sparks Audio
@@ -41047,7 +41012,7 @@ paths:
period_end:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '40.0'
+ amount: '40.00'
display_amount: "$40.00"
seller_id: sel_UkLWZg9DAJ
seller_name: Sparks Audio
@@ -43960,10 +43925,10 @@ components:
items:
"$ref": "#/components/schemas/CheckoutRequirement"
order_minimum:
- type: number
+ type: string
nullable: true
order_minimum_shortfall:
- type: number
+ type: string
nullable: true
below_order_minimum:
type: boolean
@@ -45624,12 +45589,6 @@ components:
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:
@@ -45638,6 +45597,12 @@ components:
type: string
deleted_at:
type: string
+ markup_flat:
+ type: string
+ nullable: true
+ markup_percent:
+ type: string
+ nullable: true
seller_id:
type: string
nullable: true
@@ -45699,12 +45664,12 @@ components:
- admin_name
- storefront_visible
- tracking_url
- - markup_flat
- - markup_percent
- available_to_sellers
- created_at
- updated_at
- deleted_at
+ - markup_flat
+ - markup_percent
- seller_id
- seller_name
- services
@@ -46225,6 +46190,187 @@ components:
- created_at
- updated_at
x-typelizer: true
+ EmailTemplateDraft:
+ type: object
+ properties:
+ id:
+ type: string
+ subject:
+ type: string
+ nullable: true
+ body:
+ type: string
+ lock_version:
+ type: number
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ updated_by_id:
+ type: string
+ nullable: true
+ updated_by_type:
+ anyOf:
+ - type: string
+ enum:
+ - admin_user
+ - api_key
+ - type: string
+ nullable: true
+ description: The values listed are the built-in ones; extensions may add
+ more.
+ updated_by:
+ "$ref": "#/components/schemas/Actor"
+ required:
+ - id
+ - subject
+ - body
+ - lock_version
+ - created_at
+ - updated_at
+ - updated_by_id
+ - updated_by_type
+ x-typelizer: true
+ EmailTemplatePreview:
+ type: object
+ properties:
+ id:
+ type: string
+ nullable: true
+ subject:
+ type: string
+ html:
+ type: string
+ text:
+ type: string
+ email_key:
+ type: string
+ variables:
+ type: object
+ required:
+ - id
+ - subject
+ - html
+ - text
+ - email_key
+ - variables
+ x-typelizer: true
+ EmailTemplateRevision:
+ type: object
+ properties:
+ id:
+ type: string
+ subject:
+ type: string
+ nullable: true
+ body:
+ type: string
+ created_at:
+ type: string
+ published_by_id:
+ type: string
+ nullable: true
+ published_by_type:
+ anyOf:
+ - type: string
+ enum:
+ - admin_user
+ - api_key
+ - type: string
+ nullable: true
+ description: The values listed are the built-in ones; extensions may add
+ more.
+ published_by:
+ "$ref": "#/components/schemas/Actor"
+ required:
+ - id
+ - subject
+ - body
+ - created_at
+ - published_by_id
+ - published_by_type
+ x-typelizer: true
+ EmailTemplateSampleRecord:
+ type: object
+ properties:
+ id:
+ type: string
+ label:
+ type: string
+ created_at:
+ type: string
+ required:
+ - id
+ - label
+ - created_at
+ x-typelizer: true
+ EmailTemplate:
+ type: object
+ properties:
+ id:
+ type: string
+ key:
+ type: string
+ subject:
+ type: string
+ nullable: true
+ body:
+ type: string
+ language:
+ type: string
+ customized_languages:
+ type: array
+ items:
+ type: string
+ kind:
+ type: string
+ enum:
+ - email
+ - layout
+ - partial
+ customized:
+ type: boolean
+ published_at:
+ type: string
+ nullable: true
+ default_subject:
+ type: string
+ nullable: true
+ default_body:
+ type: string
+ published_language:
+ type: string
+ nullable: true
+ default_changed:
+ type: boolean
+ base_subject:
+ type: string
+ nullable: true
+ base_body:
+ type: string
+ nullable: true
+ draft:
+ allOf:
+ - "$ref": "#/components/schemas/EmailTemplateDraft"
+ nullable: true
+ required:
+ - id
+ - key
+ - subject
+ - body
+ - language
+ - customized_languages
+ - kind
+ - customized
+ - published_at
+ - default_subject
+ - default_body
+ - published_language
+ - default_changed
+ - base_subject
+ - base_body
+ - draft
+ x-typelizer: true
ExchangeLineItem:
type: object
properties:
@@ -46700,14 +46846,14 @@ components:
"$ref": "#/components/schemas/TaxLine"
metadata:
type: object
- adjustment_total:
- type: string
- pre_tax_amount:
- type: string
created_at:
type: string
updated_at:
type: string
+ adjustment_total:
+ type: string
+ pre_tax_amount:
+ type: string
order_id:
type: string
nullable: true
@@ -46755,10 +46901,10 @@ components:
- items
- deliveries
- metadata
- - adjustment_total
- - pre_tax_amount
- created_at
- updated_at
+ - adjustment_total
+ - pre_tax_amount
- order_id
- stock_location_id
- documents
@@ -47974,15 +48120,25 @@ components:
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
+ payment_total:
+ type: string
+ display_payment_total:
+ type: string
commission_amount_total:
type: string
display_commission_amount_total:
@@ -47995,16 +48151,6 @@ components:
type: string
display_commission_total:
type: string
- canceled_at:
- type: string
- nullable: true
- approved_at:
- type: string
- nullable: true
- created_at:
- type: string
- updated_at:
- type: string
preferred_stock_location_id:
type: string
nullable: true
@@ -48176,20 +48322,20 @@ components:
- considered_risky
- confirmation_delivered
- store_owner_notification_delivered
- - payment_total
- - display_payment_total
- metadata
- cancel_note
+ - canceled_at
+ - approved_at
+ - created_at
+ - updated_at
+ - payment_total
+ - display_payment_total
- commission_amount_total
- display_commission_amount_total
- commission_tax_total
- display_commission_tax_total
- commission_total
- display_commission_total
- - canceled_at
- - approved_at
- - created_at
- - updated_at
- preferred_stock_location_id
- po_document_url
- seller_id
@@ -48340,6 +48486,14 @@ components:
type: object
preference_schema:
type: object
+ logo_url:
+ type: string
+ nullable: true
+ docs_url:
+ type: string
+ nullable: true
+ third_party:
+ type: boolean
required:
- id
- name
@@ -48358,6 +48512,9 @@ components:
- updated_at
- preferences
- preference_schema
+ - logo_url
+ - docs_url
+ - third_party
x-typelizer: true
Payment:
type: object
@@ -48621,12 +48778,11 @@ components:
properties:
id:
type: string
- amount:
- type: string
- amount_in_cents:
- type: number
currency:
type: string
+ amount:
+ type: string
+ nullable: true
display_amount:
type: string
recorded_at:
@@ -48642,9 +48798,8 @@ components:
type: string
required:
- id
- - amount
- - amount_in_cents
- currency
+ - amount
- display_amount
- recorded_at
- variant_id
@@ -48804,19 +48959,13 @@ components:
properties:
id:
type: string
- amount:
+ currency:
type: string
nullable: true
- amount_in_cents:
- type: number
- nullable: true
- compare_at_amount:
+ amount:
type: string
nullable: true
- compare_at_amount_in_cents:
- type: number
- nullable: true
- currency:
+ compare_at_amount:
type: string
nullable: true
display_amount:
@@ -48841,11 +48990,9 @@ components:
"$ref": "#/components/schemas/Variant"
required:
- id
+ - currency
- amount
- - amount_in_cents
- compare_at_amount
- - compare_at_amount_in_cents
- - currency
- display_amount
- display_compare_at_amount
- price_list_id
@@ -49438,10 +49585,10 @@ components:
type: string
unit_cost:
type: string
- total_cost:
- type: string
display_unit_cost:
type: string
+ total_cost:
+ type: string
display_total_cost:
type: string
purchase_order_id:
@@ -49476,8 +49623,8 @@ components:
- created_at
- updated_at
- unit_cost
- - total_cost
- display_unit_cost
+ - total_cost
- display_total_cost
- purchase_order_id
- variant_id
@@ -50567,6 +50714,7 @@ components:
type: string
display_cost:
type: string
+ nullable: true
integration_id:
type: string
nullable: true
@@ -51490,9 +51638,11 @@ components:
order_number_sequence_started:
type: boolean
preferred_default_minimum_payout_amount:
- type: number
+ type: string
+ nullable: true
preferred_default_commission_tax_rate:
- type: number
+ type: string
+ nullable: true
url:
type: string
api_url:
@@ -51847,6 +51997,7 @@ components:
type: boolean
rate:
type: string
+ nullable: true
tax_rate_id:
type: string
nullable: true
@@ -51943,10 +52094,11 @@ components:
deleted_at:
type: string
nullable: true
- amount:
+ rate:
+ type: string
+ nullable: true
+ rate_percent:
type: string
- amount_percentage:
- type: number
nullable: true
tax_category_id:
type: string
@@ -51969,8 +52121,8 @@ components:
- created_at
- updated_at
- deleted_at
- - amount
- - amount_percentage
+ - rate
+ - rate_percent
- tax_category_id
- store_id
- country_code
@@ -52082,9 +52234,6 @@ components:
type: object
position:
type: number
- cost_price:
- type: string
- nullable: true
cost_currency:
type: string
nullable: true
@@ -52116,6 +52265,9 @@ components:
type: string
updated_at:
type: string
+ cost_price:
+ type: string
+ nullable: true
preorderable:
type: boolean
tax_category_id:
@@ -52178,7 +52330,6 @@ components:
- external_references
- metadata
- position
- - cost_price
- cost_currency
- barcode
- backorder_limit
@@ -52190,6 +52341,7 @@ components:
- deleted_at
- created_at
- updated_at
+ - cost_price
- preorderable
- tax_category_id
- carton_package_type_id
@@ -52343,184 +52495,4 @@ components:
- credential
- deprecated
- replaced_by
- EmailTemplateDraft:
- type: object
- properties:
- id:
- type: string
- subject:
- type: string
- nullable: true
- body:
- type: string
- lock_version:
- type: number
- created_at:
- type: string
- updated_at:
- type: string
- updated_by_id:
- type: string
- nullable: true
- updated_by_type:
- anyOf:
- - type: string
- enum:
- - admin_user
- - api_key
- - type: string
- nullable: true
- description: The values listed are the built-in ones; extensions may add
- more.
- updated_by:
- "$ref": "#/components/schemas/Actor"
- required:
- - id
- - subject
- - body
- - lock_version
- - created_at
- - updated_at
- - updated_by_id
- - updated_by_type
- x-typelizer: true
- EmailTemplatePreview:
- type: object
- properties:
- id:
- type: string
- nullable: true
- subject:
- type: string
- html:
- type: string
- text:
- type: string
- email_key:
- type: string
- variables:
- type: object
- required:
- - id
- - subject
- - html
- - text
- - email_key
- - variables
- x-typelizer: true
- EmailTemplateRevision:
- type: object
- properties:
- id:
- type: string
- subject:
- type: string
- nullable: true
- body:
- type: string
- created_at:
- type: string
- published_by_id:
- type: string
- nullable: true
- published_by_type:
- anyOf:
- - type: string
- enum:
- - admin_user
- - api_key
- - type: string
- nullable: true
- description: The values listed are the built-in ones; extensions may add
- more.
- published_by:
- "$ref": "#/components/schemas/Actor"
- required:
- - id
- - subject
- - body
- - created_at
- - published_by_id
- - published_by_type
- x-typelizer: true
- EmailTemplateSampleRecord:
- type: object
- properties:
- id:
- type: string
- label:
- type: string
- created_at:
- type: string
- required:
- - id
- - label
- - created_at
- x-typelizer: true
- EmailTemplate:
- type: object
- properties:
- id:
- type: string
- key:
- type: string
- subject:
- type: string
- nullable: true
- body:
- type: string
- language:
- type: string
- customized_languages:
- type: array
- items:
- type: string
- kind:
- type: string
- enum:
- - email
- - layout
- - partial
- customized:
- type: boolean
- published_at:
- type: string
- nullable: true
- default_subject:
- type: string
- nullable: true
- default_body:
- type: string
- published_language:
- type: string
- nullable: true
- default_changed:
- type: boolean
- base_subject:
- type: string
- nullable: true
- base_body:
- type: string
- nullable: true
- draft:
- allOf:
- - "$ref": "#/components/schemas/EmailTemplateDraft"
- nullable: true
- required:
- - id
- - key
- - subject
- - body
- - language
- - customized_languages
- - kind
- - customized
- - published_at
- - default_subject
- - default_body
- - published_language
- - default_changed
- - base_subject
- - base_body
- - draft
x-typelizer: true
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yaml
index f69cfaf78c..ff8593e2af 100644
--- a/docs/api-reference/seller.yaml
+++ b/docs/api-reference/seller.yaml
@@ -13687,11 +13687,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -13774,11 +13772,9 @@ paths:
tags: []
price:
id: price_gbHJdmfrXB
- amount: '24.0'
- amount_in_cents: 2400
- compare_at_amount:
- compare_at_amount_in_cents:
currency: USD
+ amount: '24.00'
+ compare_at_amount:
display_amount: "$24.00"
display_compare_at_amount:
price_list_id:
@@ -13926,11 +13922,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -14001,11 +13995,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -14941,10 +14933,10 @@ paths:
application/json:
example:
direct_upload:
- url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--484d46dd60be3523918976c0cc622ec8eb33a9be
+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--ec7df9540f9e5a58f349aa7f06f79714cb0b3186
headers:
Content-Type: application/pdf
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0308aece2ba2eba07d1537e46361140cca1800b4
schema:
"$ref": "#/components/schemas/DirectUploadResponse"
requestBody:
@@ -15008,15 +15000,15 @@ paths:
- currency: USD
settlement_currency: USD
converted: false
- earned: '40.0'
+ earned: '40.00'
display_earned: "$40.00"
- payable: '40.0'
+ payable: '40.00'
display_payable: "$40.00"
- paid: '15.0'
+ paid: '15.00'
display_paid: "$15.00"
- balance: '25.0'
+ balance: '25.00'
display_balance: "$25.00"
- pending: '0.0'
+ pending: '0.00'
display_pending: "$0.00"
schema:
type: object
@@ -15061,7 +15053,7 @@ paths:
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '0.0'
+ refund_total: '0.00'
display_refund_total: "$0.00"
approved_at:
resolved_at:
@@ -15117,7 +15109,7 @@ paths:
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '0.0'
+ refund_total: '0.00'
display_refund_total: "$0.00"
approved_at:
resolved_at:
@@ -15200,7 +15192,7 @@ paths:
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '0.0'
+ refund_total: '0.00'
display_refund_total: "$0.00"
approved_at: '2026-01-15T12:00:00Z'
resolved_at:
@@ -15250,7 +15242,7 @@ paths:
resolution: refund
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '0.0'
+ refund_total: '0.00'
display_refund_total: "$0.00"
approved_at: '2026-01-15T12:00:00Z'
resolved_at: '2026-01-15T12:00:00Z'
@@ -15322,7 +15314,7 @@ paths:
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '0.0'
+ refund_total: '0.00'
display_refund_total: "$0.00"
approved_at:
resolved_at:
@@ -15808,8 +15800,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 81
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -15915,8 +15907,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 82
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -16029,8 +16021,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 83
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -16123,8 +16115,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 84
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -16279,31 +16271,31 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
internal_note:
internal_note_html:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- payment_total: '0.0'
+ payment_total: '0.00'
display_payment_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- commission_amount_total: '0.0'
+ commission_amount_total: '0.00'
display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
+ commission_tax_total: '0.00'
display_commission_tax_total: "$0.00"
- commission_total: '0.0'
+ commission_total: '0.00'
display_commission_total: "$0.00"
canceled_at:
cancel_reason_name:
@@ -16314,12 +16306,12 @@ paths:
options_text: ''
quantity: 1
currency: USD
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
- additional_tax_total: '0.0'
- total: '10.0'
+ additional_tax_total: '0.00'
+ total: '10.00'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
sku: SKU-257
@@ -16351,8 +16343,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 86
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -16378,7 +16370,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 167 Lovely Street
+ address1: 168 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16400,7 +16392,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 166 Lovely Street
+ address1: 167 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16483,31 +16475,31 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
internal_note:
internal_note_html:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- payment_total: '0.0'
+ payment_total: '0.00'
display_payment_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- commission_amount_total: '0.0'
+ commission_amount_total: '0.00'
display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
+ commission_tax_total: '0.00'
display_commission_tax_total: "$0.00"
- commission_total: '0.0'
+ commission_total: '0.00'
display_commission_total: "$0.00"
canceled_at:
cancel_reason_name:
@@ -16518,12 +16510,12 @@ paths:
options_text: ''
quantity: 1
currency: USD
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
- additional_tax_total: '0.0'
- total: '10.0'
+ additional_tax_total: '0.00'
+ total: '10.00'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
sku: SKU-258
@@ -16555,8 +16547,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 87
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -16582,7 +16574,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 169 Lovely Street
+ address1: 170 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16604,7 +16596,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 168 Lovely Street
+ address1: 169 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16683,31 +16675,31 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
internal_note:
internal_note_html:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- payment_total: '0.0'
+ payment_total: '0.00'
display_payment_total: "$0.00"
- amount_due: "-0.0"
+ amount_due: '0.00'
display_amount_due: "$0.00"
- commission_amount_total: '0.0'
+ commission_amount_total: '0.00'
display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
+ commission_tax_total: '0.00'
display_commission_tax_total: "$0.00"
- commission_total: '0.0'
+ commission_total: '0.00'
display_commission_total: "$0.00"
canceled_at: '2026-01-15T12:00:00Z'
cancel_reason_name:
@@ -16718,12 +16710,12 @@ paths:
options_text: ''
quantity: 1
currency: USD
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
- additional_tax_total: '0.0'
- total: '10.0'
+ additional_tax_total: '0.00'
+ total: '10.00'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
sku: SKU-261
@@ -16755,8 +16747,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 90
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -16782,7 +16774,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 175 Lovely Street
+ address1: 176 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16804,7 +16796,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 174 Lovely Street
+ address1: 175 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -16890,31 +16882,31 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
internal_note:
internal_note_html:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- payment_total: '0.0'
+ payment_total: '0.00'
display_payment_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- commission_amount_total: '0.0'
+ commission_amount_total: '0.00'
display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
+ commission_tax_total: '0.00'
display_commission_tax_total: "$0.00"
- commission_total: '0.0'
+ commission_total: '0.00'
display_commission_total: "$0.00"
canceled_at:
cancel_reason_name:
@@ -16925,12 +16917,12 @@ paths:
options_text: ''
quantity: 1
currency: USD
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
- additional_tax_total: '0.0'
- total: '10.0'
+ additional_tax_total: '0.00'
+ total: '10.00'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
sku: SKU-262
@@ -16962,8 +16954,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 91
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -17011,7 +17003,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 176 Lovely Street
+ address1: 177 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17160,31 +17152,31 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
internal_note:
internal_note_html:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- payment_total: '0.0'
+ payment_total: '0.00'
display_payment_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- commission_amount_total: '0.0'
+ commission_amount_total: '0.00'
display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
+ commission_tax_total: '0.00'
display_commission_tax_total: "$0.00"
- commission_total: '0.0'
+ commission_total: '0.00'
display_commission_total: "$0.00"
canceled_at:
cancel_reason_name:
@@ -17195,12 +17187,12 @@ paths:
options_text: ''
quantity: 1
currency: USD
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
- additional_tax_total: '0.0'
- total: '10.0'
+ additional_tax_total: '0.00'
+ total: '10.00'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
sku: SKU-264
@@ -17232,8 +17224,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 93
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -17259,7 +17251,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 181 Lovely Street
+ address1: 182 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17281,7 +17273,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 180 Lovely Street
+ address1: 181 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17336,31 +17328,31 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
internal_note: Packed with the fragile insert.
internal_note_html: "<p>Packed with the fragile insert.</p>"
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- payment_total: '0.0'
+ payment_total: '0.00'
display_payment_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- commission_amount_total: '0.0'
+ commission_amount_total: '0.00'
display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
+ commission_tax_total: '0.00'
display_commission_tax_total: "$0.00"
- commission_total: '0.0'
+ commission_total: '0.00'
display_commission_total: "$0.00"
canceled_at:
cancel_reason_name:
@@ -17371,12 +17363,12 @@ paths:
options_text: ''
quantity: 1
currency: USD
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
- additional_tax_total: '0.0'
- total: '10.0'
+ additional_tax_total: '0.00'
+ total: '10.00'
display_total: "$10.00"
variant_id: variant_UkLWZg9DAJ
sku: SKU-265
@@ -17408,8 +17400,8 @@ paths:
- id: dr_gbHJdmfrXB
name: UPS Ground 94
selected: true
- cost: '10.0'
- total: '10.0'
+ cost: '10.00'
+ total: '10.00'
carrier:
service_level:
estimated_delivery_date:
@@ -17435,7 +17427,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 183 Lovely Street
+ address1: 184 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17457,7 +17449,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 182 Lovely Street
+ address1: 183 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17974,7 +17966,7 @@ paths:
period_end:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '120.0'
+ amount: '120.00'
display_amount: "$120.00"
transfers_count: 1
provider: system
@@ -18036,7 +18028,7 @@ paths:
period_end:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '120.0'
+ amount: '120.00'
display_amount: "$120.00"
transfers_count: 1
provider: system
@@ -18090,9 +18082,9 @@ paths:
status: requested
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '10.0'
+ refund_total: '10.00'
display_refund_total: "$10.00"
- refund_tax_total: '0.0'
+ refund_tax_total: '0.00'
display_refund_tax_total: "$0.00"
approved_at:
received_at:
@@ -18100,8 +18092,8 @@ paths:
canceled_at:
memo:
stock_location_id: sloc_UkLWZg9DAJ
- refunded_total: '0.0'
- refundable_total: '10.0'
+ refunded_total: '0.00'
+ refundable_total: '10.00'
display_refunded_total: "$0.00"
meta:
page: 1
@@ -18152,9 +18144,9 @@ paths:
status: requested
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '10.0'
+ refund_total: '10.00'
display_refund_total: "$10.00"
- refund_tax_total: '0.0'
+ refund_tax_total: '0.00'
display_refund_tax_total: "$0.00"
approved_at:
received_at:
@@ -18162,8 +18154,8 @@ paths:
canceled_at:
memo:
stock_location_id: sloc_UkLWZg9DAJ
- refunded_total: '0.0'
- refundable_total: '10.0'
+ refunded_total: '0.00'
+ refundable_total: '10.00'
display_refunded_total: "$0.00"
schema:
"$ref": "#/components/schemas/Return"
@@ -18240,9 +18232,9 @@ paths:
status: approved
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '10.0'
+ refund_total: '10.00'
display_refund_total: "$10.00"
- refund_tax_total: '0.0'
+ refund_tax_total: '0.00'
display_refund_tax_total: "$0.00"
approved_at: '2026-01-15T12:00:00Z'
received_at:
@@ -18250,8 +18242,8 @@ paths:
canceled_at:
memo:
stock_location_id: sloc_UkLWZg9DAJ
- refunded_total: '0.0'
- refundable_total: '10.0'
+ refunded_total: '0.00'
+ refundable_total: '10.00'
display_refunded_total: "$0.00"
schema:
"$ref": "#/components/schemas/Return"
@@ -18294,9 +18286,9 @@ paths:
status: received
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '10.0'
+ refund_total: '10.00'
display_refund_total: "$10.00"
- refund_tax_total: '0.0'
+ refund_tax_total: '0.00'
display_refund_tax_total: "$0.00"
approved_at: '2026-01-15T12:00:00Z'
received_at: '2026-01-15T12:00:00Z'
@@ -18304,8 +18296,8 @@ paths:
canceled_at:
memo:
stock_location_id: sloc_UkLWZg9DAJ
- refunded_total: '0.0'
- refundable_total: '10.0'
+ refunded_total: '0.00'
+ refundable_total: '10.00'
display_refunded_total: "$0.00"
schema:
"$ref": "#/components/schemas/Return"
@@ -18371,9 +18363,9 @@ paths:
status: refunded
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '10.0'
+ refund_total: '10.00'
display_refund_total: "$10.00"
- refund_tax_total: '0.0'
+ refund_tax_total: '0.00'
display_refund_tax_total: "$0.00"
approved_at: '2026-01-15T12:00:00Z'
received_at: '2026-01-15T12:00:00Z'
@@ -18381,8 +18373,8 @@ paths:
canceled_at:
memo:
stock_location_id: sloc_UkLWZg9DAJ
- refunded_total: '10.0'
- refundable_total: '0.0'
+ refunded_total: '10.00'
+ refundable_total: '0.00'
display_refunded_total: "$10.00"
schema:
"$ref": "#/components/schemas/Return"
@@ -18444,9 +18436,9 @@ paths:
status: canceled
order_id: or_UkLWZg9DAJ
reason_id:
- refund_total: '10.0'
+ refund_total: '10.00'
display_refund_total: "$10.00"
- refund_tax_total: '0.0'
+ refund_tax_total: '0.00'
display_refund_tax_total: "$0.00"
approved_at:
received_at:
@@ -18454,8 +18446,8 @@ paths:
canceled_at: '2026-01-15T12:00:00Z'
memo:
stock_location_id: sloc_UkLWZg9DAJ
- refunded_total: '0.0'
- refundable_total: '10.0'
+ refunded_total: '0.00'
+ refundable_total: '10.00'
display_refunded_total: "$0.00"
schema:
"$ref": "#/components/schemas/Return"
@@ -18779,9 +18771,9 @@ paths:
reference:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '42.0'
+ amount: '42.00'
display_amount: "$42.00"
- settled_amount: '42.0'
+ settled_amount: '42.00'
settled_currency: USD
converted: false
order_id: or_UkLWZg9DAJ
@@ -18846,9 +18838,9 @@ paths:
reference:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '42.0'
+ amount: '42.00'
display_amount: "$42.00"
- settled_amount: '42.0'
+ settled_amount: '42.00'
settled_currency: USD
converted: false
order_id: or_UkLWZg9DAJ
@@ -19658,21 +19650,19 @@ components:
properties:
id:
type: string
- amount:
- type: string
- amount_in_cents:
- type: number
currency:
type: string
+ amount:
+ type: string
+ nullable: true
display_amount:
type: string
recorded_at:
type: string
required:
- id
- - amount
- - amount_in_cents
- currency
+ - amount
- display_amount
- recorded_at
x-typelizer: true
@@ -19681,19 +19671,13 @@ components:
properties:
id:
type: string
- amount:
+ currency:
type: string
nullable: true
- amount_in_cents:
- type: number
- nullable: true
- compare_at_amount:
+ amount:
type: string
nullable: true
- compare_at_amount_in_cents:
- type: number
- nullable: true
- currency:
+ compare_at_amount:
type: string
nullable: true
display_amount:
@@ -19707,11 +19691,9 @@ components:
nullable: true
required:
- id
+ - currency
- amount
- - amount_in_cents
- compare_at_amount
- - compare_at_amount_in_cents
- - currency
- display_amount
- display_compare_at_amount
- price_list_id
@@ -21894,6 +21876,7 @@ components:
type: string
display_cost:
type: string
+ nullable: true
integration_id:
type: string
nullable: true
@@ -22279,9 +22262,6 @@ components:
type: object
position:
type: number
- cost_price:
- type: string
- nullable: true
cost_currency:
type: string
nullable: true
@@ -22304,6 +22284,9 @@ components:
type: string
updated_at:
type: string
+ cost_price:
+ type: string
+ nullable: true
preorderable:
type: boolean
available_stock:
@@ -22349,7 +22332,6 @@ components:
- option_values
- metadata
- position
- - cost_price
- cost_currency
- barcode
- backorder_limit
@@ -22358,6 +22340,7 @@ components:
- customs_description
- created_at
- updated_at
+ - cost_price
- preorderable
- available_stock
- total_on_hand
diff --git a/docs/api-reference/store-api/monetary-amounts.mdx b/docs/api-reference/store-api/monetary-amounts.mdx
index 405df72766..bb43d7dbb3 100644
--- a/docs/api-reference/store-api/monetary-amounts.mdx
+++ b/docs/api-reference/store-api/monetary-amounts.mdx
@@ -4,7 +4,7 @@ sidebarTitle: "Monetary Amounts"
description: "How monetary values are represented in API responses"
---
-All monetary values in the Store API are returned as **strings** (e.g., `"29.99"`, `"0.0"`), not numbers. This preserves decimal precision and avoids floating-point rounding issues common with JSON numbers.
+All monetary values in the Store API are returned as **decimal strings**, never JSON numbers, written with exactly the decimal places of their currency: `"29.99"` in USD, `"1.500"` in Kuwaiti dinar, `"1000"` in yen. Unit prices may carry up to four decimals (`"0.0125"`). This preserves decimal precision and avoids the rounding errors of JSON numbers. A currency's decimal places are its `decimal_places` (see [below](#currency-decimal-places)).
## Response Format
@@ -35,7 +35,13 @@ This convention applies to all monetary fields across all resources:
| **Payment** | `amount` |
| **Gift Card** | `amount`, `amount_used`, `amount_authorized`, `amount_remaining` |
| **Store Credit** | `amount`, `amount_used`, `amount_remaining` |
-| **Price** | `amount`, `compare_at_amount` |
+| **Price** | `amount`, `compare_at_amount` (unit prices, up to four decimals) |
+
+Rates, such as a tax line's `rate`, are decimal strings too, without trailing zeros (`"0.23"`).
+
+## Currency decimal places
+
+Each currency the store sells in (`GET /api/v3/store/currencies`) carries `decimal_places`, from ISO 4217: `2` for USD and EUR, `0` for JPY, `3` for KWD. Every amount in that currency is written with that many decimals.
## Working with Amounts
@@ -44,12 +50,15 @@ This convention applies to all monetary fields across all resources:
```typescript SDK
const order = await client.orders.get('or_abc123', {}, { token });
+import { compareMoney, sumMoney } from '@spree/sdk'
+
// Raw string values
order.total; // "129.99"
order.display_total; // "$129.99"
-// Convert to number for calculations
-const total = parseFloat(order.total);
+// Calculate on the strings, exactly
+const subtotal = sumMoney(order.items.map((item) => item.total), order.currency); // "129.99"
+const isFree = compareMoney(order.total, '0') === 0;
```
```javascript JavaScript
@@ -58,12 +67,12 @@ const data = await response.json();
// Use display fields for rendering
element.textContent = data.display_total; // "$129.99"
-// Use raw fields for calculations
-const total = parseFloat(data.total);
+// Calculate on the raw strings with a decimal library, never parseFloat:
+// 0.1 + 0.2 is 0.30000000000000004 as a JSON number.
```
</CodeGroup>
<Tip>
-Use `display_*` fields for rendering prices in the UI — they are pre-formatted with the correct currency symbol and decimal places based on the order's currency. Use the raw string fields when you need to perform calculations.
+Use `display_*` fields for rendering prices in the UI — they are pre-formatted with the correct currency symbol and decimal places based on the order's currency. Calculate on the raw strings with the SDK's `sumMoney`, `subtractMoney`, `multiplyMoney` and `compareMoney`, which work on decimal strings exactly.
</Tip>
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 65e8bcad40..53bda73bb8 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -98,7 +98,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Julie Bode
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
addresses: []
default_billing_address:
@@ -206,7 +206,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Yuki Harvey
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
addresses: []
default_billing_address:
@@ -403,7 +403,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Lucas Stiedemann
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
addresses: []
default_billing_address:
@@ -904,11 +904,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -1075,11 +1073,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -1116,11 +1112,9 @@ paths:
tags: []
price:
id: price_EfhxLZ9ck8
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -1237,11 +1231,9 @@ paths:
tags: []
price:
id: price_UkLWZg9DAJ
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -1249,9 +1241,8 @@ paths:
seller_id:
prior_price:
id: _AXs1igzRC6
- amount: '9.99'
- amount_in_cents: 999
currency: USD
+ amount: '9.99'
display_amount: "$9.99"
recorded_at: '2025-12-31T12:00:00Z'
schema:
@@ -1324,8 +1315,8 @@ paths:
filters:
- id: price
type: price_range
- min: 19.99
- max: 19.99
+ min: '19.99'
+ max: '19.99'
currency: USD
- id: availability
type: availability
@@ -1517,29 +1508,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -1579,21 +1570,21 @@ paths:
name: Product 225715
slug: product-225715
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -1638,29 +1629,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -1700,21 +1691,21 @@ paths:
name: Product 2262171
slug: product-2262171
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -1830,29 +1821,29 @@ paths:
total_quantity: 0
warnings: []
coupon_code:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '0.0'
+ total: '0.00'
display_total: "$0.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -2014,29 +2005,29 @@ paths:
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
coupon_code:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '17.0'
+ adjustment_total: '17.00'
display_adjustment_total: "$17.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '17.0'
+ total: '17.00'
display_total: "$17.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '17.0'
+ amount_due: '17.00'
display_amount_due: "$17.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '17.0'
+ fee_total: '17.00'
display_fee_total: "$17.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -2066,14 +2057,14 @@ paths:
kind: gift_wrap
line_item_id:
fulfillment_id:
- amount: '5.0'
+ amount: '5.00'
display_amount: "$5.00"
- id: fee_gbHJdmfrXB
label: Import duty
kind: duty
line_item_id:
fulfillment_id:
- amount: '12.0'
+ amount: '12.00'
display_amount: "$12.00"
items: []
fulfillments: []
@@ -2197,29 +2188,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -2255,21 +2246,21 @@ paths:
name: Product 2313263
slug: product-2313263
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -2488,29 +2479,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: delivery
@@ -2543,21 +2534,21 @@ paths:
name: Product 2338992
slug: product-2338992
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -2572,7 +2563,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 254 Lovely Street
+ address1: 255 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2594,7 +2585,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 253 Lovely Street
+ address1: 254 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2720,29 +2711,29 @@ paths:
fulfillment_status: backorder
payment_status: paid
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '20.0'
+ total: '20.00'
display_total: "$20.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '20.0'
+ amount_due: '20.00'
display_amount_due: "$20.00"
- delivery_total: '10.0'
+ delivery_total: '10.00'
display_delivery_total: "$10.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
@@ -2758,21 +2749,21 @@ paths:
name: Product 2364794
slug: product-2364794
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -2787,17 +2778,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '10.0'
+ cost: '10.00'
display_cost: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -2834,11 +2825,11 @@ paths:
delivery_method_id: dm_UkLWZg9DAJ
name: UPS Ground 113
selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
+ cost: '10.00'
+ total: '10.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ tax_total: '0.00'
carrier:
service_level:
estimated_delivery_date:
@@ -2864,7 +2855,7 @@ paths:
response_code: BGS-518d4ef9738e
number: R1001-P1
status: completed
- amount: '20.0'
+ amount: '20.00'
display_amount: "$20.00"
source_type: credit_card
source_id: card_UkLWZg9DAJ
@@ -2890,7 +2881,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 260 Lovely Street
+ address1: 261 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2912,7 +2903,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 259 Lovely Street
+ address1: 260 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3042,29 +3033,29 @@ paths:
- code: coupon_code_not_eligible
message: This coupon code can't be applied to orders less than $1,000,000.00.
coupon_code: big50
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -3100,21 +3091,21 @@ paths:
name: Product 2652614
slug: product-2652614
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -3243,29 +3234,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -3301,21 +3292,21 @@ paths:
name: Product 2663461
slug: product-2663461
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -3438,29 +3429,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '20.0'
+ total: '20.00'
display_total: "$20.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '20.0'
+ amount_due: '20.00'
display_amount_due: "$20.00"
- delivery_total: '10.0'
+ delivery_total: '10.00'
display_delivery_total: "$10.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: payment
@@ -3490,21 +3481,21 @@ paths:
name: Product 2688182
slug: product-2688182
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -3519,17 +3510,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '10.0'
+ cost: '10.00'
display_cost: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -3566,11 +3557,11 @@ paths:
delivery_method_id: dm_UkLWZg9DAJ
name: UPS Ground 130
selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
+ cost: '10.00'
+ total: '10.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ tax_total: '0.00'
carrier:
service_level:
estimated_delivery_date:
@@ -3598,7 +3589,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 356 Lovely Street
+ address1: 357 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3735,29 +3726,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '10.0'
+ gift_card_total: '10.00'
display_gift_card_total: "$10.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '10.0'
+ store_credit_total: '10.00'
display_store_credit_total: "-$10.00"
covered_by_store_credit: true
current_step: address
@@ -3789,21 +3780,21 @@ paths:
name: Product 2705702
slug: product-2705702
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -3817,15 +3808,15 @@ paths:
response_code: 1-SC-20260115120000000000
number: cart_UkLWZg9DAJ-P1
status: checkout
- amount: '10.0'
+ amount: '10.00'
display_amount: "$10.00"
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
id: credit_UkLWZg9DAJ
- amount: '10.0'
- amount_used: '0.0'
- amount_remaining: '10.0'
+ amount: '10.00'
+ amount_used: '0.00'
+ amount_remaining: '10.00'
display_amount: "$10.00"
display_amount_used: "$0.00"
display_amount_remaining: "$10.00"
@@ -3839,22 +3830,16 @@ paths:
source_required: true
billing_address:
shipping_address:
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: store_credit
- session_required: false
- source_required: true
+ payment_methods: []
gift_card:
id: gc_UkLWZg9DAJ
code: GIFTCODE1
status: active
currency: USD
- amount: '50.0'
- amount_used: '10.0'
- amount_authorized: '0.0'
- amount_remaining: '40.0'
+ amount: '50.00'
+ amount_used: '10.00'
+ amount_authorized: '0.00'
+ amount_remaining: '40.00'
display_amount: "$50.00"
display_amount_used: "$10.00"
display_amount_remaining: "$40.00"
@@ -3987,29 +3972,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -4045,21 +4030,21 @@ paths:
name: Product 2749569
slug: product-2749569
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -4073,15 +4058,15 @@ paths:
response_code: 1-SC-20260115120000000000
number: cart_UkLWZg9DAJ-P1
status: invalid
- amount: '10.0'
+ amount: '10.00'
display_amount: "$10.00"
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
id: credit_UkLWZg9DAJ
- amount: '10.0'
- amount_used: '0.0'
- amount_remaining: '10.0'
+ amount: '10.00'
+ amount_used: '0.00'
+ amount_remaining: '10.00'
display_amount: "$10.00"
display_amount_used: "$0.00"
display_amount_remaining: "$10.00"
@@ -4206,27 +4191,27 @@ paths:
coupon_code:
item_total: '29.99'
display_item_total: "$29.99"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
total: '29.99'
display_total: "$29.99"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
amount_due: '29.99'
display_amount_due: "$29.99"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -4262,21 +4247,21 @@ paths:
name: Product 27763
slug: product-27763
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -4297,13 +4282,13 @@ paths:
display_price: "$19.99"
total: '19.99'
display_total: "$19.99"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
pre_tax_amount: '19.99'
display_pre_tax_amount: "$19.99"
@@ -4467,29 +4452,29 @@ paths:
variant_id: variant_UkLWZg9DAJ
item_index: 0
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -4525,21 +4510,21 @@ paths:
name: Product 2849165
slug: product-2849165
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -4657,29 +4642,29 @@ paths:
total_quantity: 0
warnings: []
coupon_code:
- item_total: '0.0'
+ item_total: '0.00'
display_item_total: "$0.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '0.0'
+ total: '0.00'
display_total: "$0.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -4807,7 +4792,7 @@ paths:
client_secret: bogus_secret_a8b3afe691c933c1
customer_external_id:
expires_at:
- amount: '10.0'
+ amount: '10.00'
payment_method_id: pm_UkLWZg9DAJ
order_id: cart_UkLWZg9DAJ
cart_id: cart_UkLWZg9DAJ
@@ -4908,7 +4893,7 @@ paths:
client_secret: secret_123
customer_external_id:
expires_at:
- amount: '10.0'
+ amount: '10.00'
payment_method_id: pm_UkLWZg9DAJ
order_id: cart_UkLWZg9DAJ
cart_id: cart_UkLWZg9DAJ
@@ -4976,7 +4961,7 @@ paths:
client_secret: secret_123
customer_external_id:
expires_at:
- amount: '50.0'
+ amount: '50.00'
payment_method_id: pm_UkLWZg9DAJ
order_id: cart_UkLWZg9DAJ
cart_id: cart_UkLWZg9DAJ
@@ -5084,7 +5069,7 @@ paths:
client_secret: secret_123
customer_external_id:
expires_at:
- amount: '10.0'
+ amount: '10.00'
payment_method_id: pm_UkLWZg9DAJ
order_id: cart_UkLWZg9DAJ
cart_id: cart_UkLWZg9DAJ
@@ -5184,7 +5169,7 @@ paths:
response_code:
number: cart_UkLWZg9DAJ-P1
status: checkout
- amount: '10.0'
+ amount: '10.00'
display_amount: "$10.00"
source_type:
source_id:
@@ -5305,29 +5290,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '0.0'
+ amount_due: '0.00'
display_amount_due: "$0.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '10.0'
+ store_credit_total: '10.00'
display_store_credit_total: "-$10.00"
covered_by_store_credit: true
current_step: address
@@ -5359,21 +5344,21 @@ paths:
name: Product 3469789
slug: product-3469789
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -5387,15 +5372,15 @@ paths:
response_code: 1-SC-20260115120000000000
number: cart_UkLWZg9DAJ-P1
status: checkout
- amount: '10.0'
+ amount: '10.00'
display_amount: "$10.00"
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
+ amount: '50.00'
+ amount_used: '0.00'
+ amount_remaining: '50.00'
display_amount: "$50.00"
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
@@ -5409,13 +5394,7 @@ paths:
source_required: true
billing_address:
shipping_address:
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit 5
- description: Store Credit
- type: store_credit
- session_required: false
- source_required: true
+ payment_methods: []
gift_card:
market:
id: mkt_UkLWZg9DAJ
@@ -5521,29 +5500,29 @@ paths:
total_quantity: 1
warnings: []
coupon_code:
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '10.0'
+ amount_due: '10.00'
display_amount_due: "$10.00"
- delivery_total: '0.0'
+ delivery_total: '0.00'
display_delivery_total: "$0.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
current_step: address
@@ -5579,21 +5558,21 @@ paths:
name: Product 348179
slug: product-348179
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -5715,29 +5694,29 @@ paths:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '12.0'
+ adjustment_total: '12.00'
display_adjustment_total: "$12.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '122.0'
+ total: '122.00'
display_total: "$122.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '122.0'
+ amount_due: '122.00'
display_amount_due: "$122.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '12.0'
+ fee_total: '12.00'
display_fee_total: "$12.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
@@ -5747,7 +5726,7 @@ paths:
kind: duty
line_item_id:
fulfillment_id:
- amount: '12.0'
+ amount: '12.00'
display_amount: "$12.00"
items:
- id: li_UkLWZg9DAJ
@@ -5760,21 +5739,21 @@ paths:
name: Product 288496
slug: product-288496
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -5789,17 +5768,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -5845,11 +5824,11 @@ paths:
delivery_method_id: dm_UkLWZg9DAJ
name: UPS Ground 144
selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
+ cost: '10.00'
+ total: '10.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ tax_total: '0.00'
carrier:
service_level:
estimated_delivery_date:
@@ -5876,7 +5855,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 412 Lovely Street
+ address1: 413 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5898,7 +5877,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 413 Lovely Street
+ address1: 414 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6006,7 +5985,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 218 Lovely Street
+ address1: 219 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6027,7 +6006,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 219 Lovely Street
+ address1: 220 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6048,7 +6027,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 220 Lovely Street
+ address1: 221 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6306,7 +6285,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 232 Lovely Street
+ address1: 233 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6388,7 +6367,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 238 Lovely Street
+ address1: 239 Lovely Street
address2: Northwest
postal_code: '10118'
city: Los Angeles
@@ -6848,29 +6827,29 @@ paths:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
@@ -6886,21 +6865,21 @@ paths:
name: Product 2535270
slug: product-2535270
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -6915,17 +6894,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -6971,11 +6950,11 @@ paths:
delivery_method_id: dm_UkLWZg9DAJ
name: UPS Ground 123
selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
+ cost: '10.00'
+ total: '10.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ tax_total: '0.00'
carrier:
service_level:
estimated_delivery_date:
@@ -7002,7 +6981,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 304 Lovely Street
+ address1: 305 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7024,7 +7003,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 305 Lovely Street
+ address1: 306 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7172,29 +7151,29 @@ paths:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
@@ -7210,21 +7189,21 @@ paths:
name: Product 2555633
slug: product-2555633
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -7239,17 +7218,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -7295,11 +7274,11 @@ paths:
delivery_method_id: dm_UkLWZg9DAJ
name: UPS Ground 125
selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
+ cost: '10.00'
+ total: '10.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ tax_total: '0.00'
carrier:
service_level:
estimated_delivery_date:
@@ -7326,7 +7305,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 310 Lovely Street
+ address1: 311 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7348,7 +7327,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 311 Lovely Street
+ address1: 312 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7442,7 +7421,7 @@ paths:
accepts_email_marketing: true
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: John Doe
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
addresses: []
default_billing_address:
@@ -7563,7 +7542,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Felix Rowe
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
addresses:
- id: addr_UkLWZg9DAJ
@@ -7571,7 +7550,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 316 Lovely Street
+ address1: 317 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7592,7 +7571,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 317 Lovely Street
+ address1: 318 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7614,7 +7593,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 317 Lovely Street
+ address1: 318 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7636,7 +7615,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 316 Lovely Street
+ address1: 317 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7720,7 +7699,7 @@ paths:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Updated Name
- available_store_credit_total: '0'
+ available_store_credit_total: '0.00'
display_available_store_credit_total: "$0.00"
addresses:
- id: addr_UkLWZg9DAJ
@@ -7728,7 +7707,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 318 Lovely Street
+ address1: 319 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7749,7 +7728,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 319 Lovely Street
+ address1: 320 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7771,7 +7750,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 319 Lovely Street
+ address1: 320 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7793,7 +7772,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 318 Lovely Street
+ address1: 319 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8106,10 +8085,10 @@ paths:
code: 1A288BF2DA45E295
status: active
currency: USD
- amount: '10.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '10.0'
+ amount: '10.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '10.00'
display_amount: "$10.00"
display_amount_used: "$0.00"
display_amount_remaining: "$10.00"
@@ -8202,10 +8181,10 @@ paths:
code: B7180B830F0E5992
status: active
currency: USD
- amount: '10.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '10.0'
+ amount: '10.00'
+ amount_used: '0.00'
+ amount_authorized: '0.00'
+ amount_remaining: '10.00'
display_amount: "$10.00"
display_amount_used: "$0.00"
display_amount_remaining: "$10.00"
@@ -8554,9 +8533,9 @@ paths:
example:
data:
- id: credit_UkLWZg9DAJ
- amount: '100.0'
- amount_used: '0.0'
- amount_remaining: '100.0'
+ amount: '100.00'
+ amount_used: '0.00'
+ amount_remaining: '100.00'
display_amount: "$100.00"
display_amount_used: "$0.00"
display_amount_remaining: "$100.00"
@@ -8642,9 +8621,9 @@ paths:
application/json:
example:
id: credit_UkLWZg9DAJ
- amount: '100.0'
- amount_used: '0.0'
- amount_remaining: '100.0'
+ amount: '100.00'
+ amount_used: '0.00'
+ amount_remaining: '100.00'
display_amount: "$100.00"
display_amount_used: "$0.00"
display_amount_remaining: "$100.00"
@@ -8854,12 +8833,15 @@ paths:
- iso_code: USD
name: United States Dollar
symbol: "$"
+ decimal_places: 2
- iso_code: EUR
name: Euro
symbol: "€"
+ decimal_places: 2
- iso_code: GBP
name: British Pound
symbol: "£"
+ decimal_places: 2
schema:
type: object
properties:
@@ -8920,7 +8902,7 @@ paths:
example:
data:
- code: de
- name: de
+ name: Deutsch
default: false
rtl: false
- code: en
@@ -9199,14 +9181,14 @@ paths:
- en
- fr
countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- iso: DE
iso3: DEU
- name: Germany
+ name: Deutschland
+ states_required: false
+ zipcode_required: true
+ - iso: FR
+ iso3: FRA
+ name: Frankreich
states_required: false
zipcode_required: true
schema:
@@ -9805,11 +9787,9 @@ paths:
units_per_carton:
price:
id: price_gbHJdmfrXB
+ currency: USD
amount: '19.99'
- amount_in_cents: 1999
compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
display_amount: "$19.99"
display_compare_at_amount:
price_list_id:
@@ -10716,7 +10696,7 @@ paths:
first_name:
last_name:
full_name: ''
- address1: 277 Lovely Street
+ address1: 278 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -10787,7 +10767,7 @@ paths:
first_name:
last_name:
full_name: ''
- address1: 280 Lovely Street
+ address1: 281 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -10931,29 +10911,29 @@ paths:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
+ item_total: '10.00'
display_item_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- total: '110.0'
+ total: '110.00'
display_total: "$110.00"
- gift_card_total: '0.0'
+ gift_card_total: '0.00'
display_gift_card_total: "$0.00"
- amount_due: '110.0'
+ amount_due: '110.00'
display_amount_due: "$110.00"
- delivery_total: '100.0'
+ delivery_total: '100.00'
display_delivery_total: "$100.00"
- fee_total: '0.0'
+ fee_total: '0.00'
display_fee_total: "$0.00"
- store_credit_total: '0.0'
+ store_credit_total: '0.00'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
discounts: []
@@ -10969,21 +10949,21 @@ paths:
name: Product 2525649
slug: product-2525649
options_text: ''
- price: '10.0'
+ price: '10.00'
display_price: "$10.00"
- total: '10.0'
+ total: '10.00'
display_total: "$10.00"
- adjustment_total: '0.0'
+ adjustment_total: '0.00'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
+ pre_tax_amount: '10.00'
display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
+ discounted_amount: '10.00'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
compare_at_amount:
@@ -10997,17 +10977,17 @@ paths:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
- cost: '100.0'
+ cost: '100.00'
display_cost: "$100.00"
- total: '100.0'
+ total: '100.00'
display_total: "$100.00"
- discount_total: '0.0'
+ discount_total: '0.00'
display_discount_total: "$0.00"
- additional_tax_total: '0.0'
+ additional_tax_total: '0.00'
display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
+ included_tax_total: '0.00'
display_included_tax_total: "$0.00"
- tax_total: '0.0'
+ tax_total: '0.00'
display_tax_total: "$0.00"
status: unfulfilled
fulfillment_type: shipping
@@ -11053,11 +11033,11 @@ paths:
delivery_method_id: dm_UkLWZg9DAJ
name: UPS Ground 114
selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
+ cost: '10.00'
+ total: '10.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ tax_total: '0.00'
carrier:
service_level:
estimated_delivery_date:
@@ -11084,7 +11064,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 288 Lovely Street
+ address1: 289 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -11106,7 +11086,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 289 Lovely Street
+ address1: 290 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -12191,10 +12171,10 @@ components:
items:
"$ref": "#/components/schemas/CheckoutRequirement"
order_minimum:
- type: number
+ type: string
nullable: true
order_minimum_shortfall:
- type: number
+ type: string
nullable: true
below_order_minimum:
type: boolean
@@ -12425,18 +12405,25 @@ components:
nullable: true
refund_amount:
type: string
+ nullable: true
paid_amount:
type: string
+ nullable: true
pre_tax_amount:
type: string
+ nullable: true
included_tax_total:
type: string
+ nullable: true
additional_tax_total:
type: string
+ nullable: true
tax_total:
type: string
+ nullable: true
display_refund_amount:
type: string
+ nullable: true
variant_id:
type: string
nullable: true
@@ -12508,8 +12495,10 @@ components:
nullable: true
refund_total:
type: string
+ nullable: true
display_refund_total:
type: string
+ nullable: true
approved_at:
type: string
nullable: true
@@ -12734,10 +12723,13 @@ components:
type: string
symbol:
type: string
+ decimal_places:
+ type: number
required:
- iso_code
- name
- symbol
+ - decimal_places
x-typelizer: true
CustomField:
type: object
@@ -12968,14 +12960,19 @@ components:
type: boolean
cost:
type: string
+ nullable: true
total:
type: string
+ nullable: true
additional_tax_total:
type: string
+ nullable: true
included_tax_total:
type: string
+ nullable: true
tax_total:
type: string
+ nullable: true
carrier:
type: string
nullable: true
@@ -12993,14 +12990,19 @@ components:
nullable: true
display_cost:
type: string
+ nullable: true
display_total:
type: string
+ nullable: true
display_additional_tax_total:
type: string
+ nullable: true
display_included_tax_total:
type: string
+ nullable: true
display_tax_total:
type: string
+ nullable: true
delivery_method:
"$ref": "#/components/schemas/DeliveryMethod"
required:
@@ -13250,10 +13252,19 @@ components:
type: boolean
original_price:
type: string
+ nullable: true
new_variant_price:
type: string
+ nullable: true
price_difference:
type: string
+ nullable: true
+ original_tax_total:
+ type: string
+ nullable: true
+ new_tax_total:
+ type: string
+ nullable: true
original_variant_id:
type: string
nullable: true
@@ -13278,6 +13289,8 @@ components:
- original_price
- new_variant_price
- price_difference
+ - original_tax_total
+ - new_tax_total
- original_variant_id
- new_variant_id
- line_item_id
@@ -13310,8 +13323,10 @@ components:
nullable: true
price_difference:
type: string
+ nullable: true
display_price_difference:
type: string
+ nullable: true
approved_at:
type: string
nullable: true
@@ -14733,6 +14748,7 @@ components:
nullable: true
amount:
type: string
+ nullable: true
payment_method_id:
type: string
order_id:
@@ -14853,21 +14869,19 @@ components:
properties:
id:
type: string
- amount:
- type: string
- amount_in_cents:
- type: number
currency:
type: string
+ amount:
+ type: string
+ nullable: true
display_amount:
type: string
recorded_at:
type: string
required:
- id
- - amount
- - amount_in_cents
- currency
+ - amount
- display_amount
- recorded_at
x-typelizer: true
@@ -14876,19 +14890,13 @@ components:
properties:
id:
type: string
- amount:
+ currency:
type: string
nullable: true
- amount_in_cents:
- type: number
- nullable: true
- compare_at_amount:
+ amount:
type: string
nullable: true
- compare_at_amount_in_cents:
- type: number
- nullable: true
- currency:
+ compare_at_amount:
type: string
nullable: true
display_amount:
@@ -14902,11 +14910,9 @@ components:
nullable: true
required:
- id
+ - currency
- amount
- - amount_in_cents
- compare_at_amount
- - compare_at_amount_in_cents
- - currency
- display_amount
- display_compare_at_amount
- price_list_id
@@ -15047,9 +15053,9 @@ components:
enum:
- price_range
min:
- type: number
+ type: string
max:
- type: number
+ type: string
currency:
type: string
required:
@@ -15386,20 +15392,28 @@ components:
type: boolean
pre_tax_amount:
type: string
+ nullable: true
display_pre_tax_amount:
type: string
+ nullable: true
included_tax_total:
type: string
+ nullable: true
additional_tax_total:
type: string
+ nullable: true
tax_total:
type: string
+ nullable: true
display_tax_total:
type: string
+ nullable: true
refund_amount:
type: string
+ nullable: true
display_refund_amount:
type: string
+ nullable: true
variant_id:
type: string
nullable: true
@@ -15469,12 +15483,16 @@ components:
nullable: true
refund_total:
type: string
+ nullable: true
display_refund_total:
type: string
+ nullable: true
refund_tax_total:
type: string
+ nullable: true
display_refund_tax_total:
type: string
+ nullable: true
approved_at:
type: string
nullable: true
@@ -15825,8 +15843,10 @@ components:
nullable: true
amount:
type: string
+ nullable: true
display_amount:
type: string
+ nullable: true
created_at:
type: string
required:
@@ -15845,16 +15865,22 @@ components:
type: string
amount:
type: string
+ nullable: true
amount_used:
type: string
+ nullable: true
amount_remaining:
type: string
+ nullable: true
display_amount:
type: string
+ nullable: true
display_amount_used:
type: string
+ nullable: true
display_amount_remaining:
type: string
+ nullable: true
currency:
type: string
required:
@@ -15913,6 +15939,7 @@ components:
type: boolean
rate:
type: string
+ nullable: true
tax_rate_id:
type: string
nullable: true
diff --git a/docs/changelog.mdx b/docs/changelog.mdx
index 159a616044..95fb6836ef 100644
--- a/docs/changelog.mdx
+++ b/docs/changelog.mdx
@@ -15,6 +15,18 @@ Keep up with the latest features and improvements in Spree Commerce!
</div>
+<Update label="Exact money everywhere" description="October 9, 2026" tags={["API", "Payments"]}>
+ Money is now exact from the database to the payment provider, in every currency.
+
+ - Amounts in the API are written with exactly the decimals of their currency, such as `10.00` in dollars, `1000` in yen and `1.500` in Kuwaiti dinar. Unit prices can go below a cent (`0.0125`) for wholesale pricing.
+ - Payment providers now receive the amount with its currency, so captures and refunds in yen or dinar are charged and recorded exactly.
+ - Very large amounts, such as orders in Vietnamese dong above 100 million, are stored without overflow.
+
+ Integrations must now send amounts as text such as `"19.99"`. Numbers and localized formats are refused with a clear error.
+
+ **Learn more:** [Monetary amounts](/api-reference/admin-api/monetary-amounts) · [Upgrade guide](/developer/upgrades/5.6-to-6.0#money)
+</Update>
+
<Update label="Prices save correctly in every language" description="October 9, 2026" tags={["Pricing", "Dashboard"]}>
Stores whose language writes a comma as the decimal separator, such as Dutch, German or French, could save the wrong price. A price entered as €49,50 was stored as €4950,00, and saving an unchanged €99 again turned it into €990 and then €9900. Prices, costs, weights and dimensions are now saved exactly as entered, whatever the store's language.
diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdx
index 3ec0823a2b..81ac9a901b 100644
--- a/docs/developer/upgrades/5.6-to-6.0.mdx
+++ b/docs/developer/upgrades/5.6-to-6.0.mdx
@@ -822,6 +822,10 @@ Other changes that come with it:
- **Numbers are no longer parsed by locale.** Price, variant, payment, refund, store credit, gift card, discount and fee amounts take a number or a canonical decimal string (`"1234.56"`); any other text raises `Spree::Money::InvalidFormat`, which the API answers with `invalid_money_format`. Before 6.0 they were re-read under the request's language, so a store whose language writes a comma decimal (Dutch, German, French) saved the dashboard's `49.50` as 4950, and an unchanged price grew tenfold on each save. Send canonical decimal strings (`"1234.56"`) and convert localized input in the client. `Spree::LocalizedNumber` still works with a warning until 6.1. If your prices were saved in a comma-decimal store before upgrading, check them.
- **Rounding follows the currency.** Taxes, percentage discounts, promotion splits and shipping markups round to the currency's own decimal places from the ISO 4217 table: whole yen, three decimals for dinar. Two-decimal currencies are unchanged. Open carts in other currencies may change by less than one minor unit the next time they are recalculated. Placed orders do not change. Spree now gives the Hungarian forint two decimal places, as ISO 4217 does.
+- **Money on the API is written to each currency's decimals.** Every amount in the Store, Admin and Seller APIs, and so in webhook payloads and email variables, is a decimal string with exactly its currency's decimal places: `"10.00"` (was `"10.0"`), `"1000"` in yen (was `"1000.0"`), `"1.500"` in dinar. Unit prices keep up to four decimals. Fields that were JSON numbers are now strings: `cart.order_minimum` and `order_minimum_shortfall`, the product filter price range `min`/`max`, report money metrics and percentages, and the store's `preferred_default_minimum_payout_amount` and `preferred_default_commission_tax_rate`. Clients comparing these strings, or parsing them as numbers, should switch to exact decimal arithmetic; the SDKs export `sumMoney`, `subtractMoney`, `multiplyMoney`, `compareMoney` and `isZeroMoney`.
+- **Admin and Seller writes refuse JSON numbers for money.** Amounts and rates, including those inside `preferences`, must be canonical decimal strings (`"19.99"`). A number, a localized or grouped string, or more decimals than the field holds is answered with `422` and `invalid_money_format`, naming the field.
+- **Rates are decimal strings, and tax rates are renamed.** Rates and percentages read and write as strings without trailing zeros. A tax rate's `amount` (a fraction) is now `rate`, and `amount_percentage` is `rate_percent`; `Spree::TaxRate#amount_percentage` keeps working with a warning until 6.1.
+- **`amount_in_cents` and `compare_at_amount_in_cents` are removed** from prices and price history. Read `amount`, and each currency's `decimal_places` (new on `GET /api/v3/store/currencies`) if you need minor units.
- **Money columns widen to `decimal(19,4)`.** They now hold a Kuwaiti dinar's third decimal, unit prices below a cent (`0.0125`), and very large amounts in currencies like the Vietnamese dong. No stored value changes. Totals, payments and refunds are still rounded to the currency's decimals; only unit prices (`price`, `compare_at_amount`, `cost_price`, `unit_cost`) keep up to four. The migration rewrites each money table while it runs, which locks `spree_orders`, `spree_line_items` and `spree_adjustments` for as long as that takes. If you cannot take that lock, widen those columns online first (add a `decimal(19,4)` shadow column, backfill it in batches, swap it in), and the migration skips any column already at `(19,4)`. Extensions with their own money tables, such as `spree_stripe_payment_intents` from the standalone Stripe gem, should widen theirs the same way.
- **Payment gateways receive the amount with its currency.** `authorize`, `purchase`, `capture` and `credit` are called with a `Spree::Money` (amount and currency) instead of an integer in hundredths, which was wrong for yen and dinar. A gateway opts in with `self.accepts_money_amounts = true` and converts the amount to its provider's unit (Stripe's rules live in `SpreeStripe::Units`). A gateway that has not opted in still receives hundredths, with a deprecation warning, until 6.1. `Spree.payment_capture_workflow.call(amount:)` takes the amount in the currency's own units; an Integer is still read as hundredths, with a warning.
- **Capture records in yen and dinar written before 6.0 may be wrong.** A capture in a currency without two decimals could be recorded in the wrong unit: 100 times too much in yen, a tenth in dinar. New captures are recorded exactly. To list the old records, writing nothing, run:
@@ -898,6 +902,7 @@ Before 6.0 a cart was an incomplete order, so extensions written for 5.x (paymen
| `Spree.metafields` | `Spree.custom_fields` |
| `Spree.t`, `Spree.translate` | `I18n.t` with the full key, e.g. `I18n.t('spree.free')` |
| `Spree::LocalizedNumber.parse` | `BigDecimal(value)` on a canonical decimal string; Spree no longer parses numbers by locale |
+| `Spree::TaxRate#amount_percentage`, `#amount_percentage=` | `#rate_percent`, `#rate_percent=` (`#rate` is the fraction) |
| Gateway methods receiving an integer amount in hundredths | `self.accepts_money_amounts = true` and a `Spree::Money` argument |
| `Spree.payment_capture_workflow.call(amount: Integer)` (hundredths) | `amount:` as a `BigDecimal` in the currency's own units |
| `CustomFieldDefinition#name`, `#metafield_type`, `#display_on` | `#label`, `#field_type`, `#storefront_visible` (columns renamed) |
diff --git a/docs/plans/6.0-money-correctness.md b/docs/plans/6.0-money-correctness.md
index 8d7a3d3dd5..5fbf2332de 100644
--- a/docs/plans/6.0-money-correctness.md
+++ b/docs/plans/6.0-money-correctness.md
@@ -1,6 +1,6 @@
# Money Correctness
-**Status:** In Progress — A (floats out) and A2 (gateway amounts) built on spree/spree#14852; B (wire contract) and C (precision) in progress on the same pull request
+**Status:** In Progress — A, A2, B and C built on spree/spree#14852, awaiting review and merge
**Target:** Spree 6.0
**Depends on:** `5.5-client-side-money-normalization.md` (canonical decimal-string contract), `6.0-6.1-split-adjustments.md` (typed `spree_tax_lines` / `spree_discounts` / `spree_fees` — landed, so they are in scope), `6.0-json-preferences.md` (decimal preferences are exact strings), `6.0-payment-gateways-monorepo.md` (Stripe lives in the monorepo; Adyen and PayPal Checkout are separate gems patched in the same release)
**Author:** Damian + Claude
@@ -30,6 +30,9 @@ All decided 2026-10-08; the ones marked *review* were changed or added after the
- **Wrong capture events are reported, not repaired.** `spree:money:audit_capture_events` lists payments in non-two-decimal currencies whose capture events disagree with the corrected value, and writes nothing. Spree never rewrites money on completed orders.
- **The rule lives in `CLAUDE.md`, not in a lint tool** (decided 2026-10-09; supersedes the first pass's RuboCop cop and Biome twin). A cop was built and then dropped: the repository runs no RuboCop, and a name-matching rule needs an allowlist that is mostly noise. `CLAUDE.md` "Money" states it for people and agents alike.
- **Open carts in zero- and three-decimal currencies change on their next recalculation.** Accepted trade-off: a yen total can move by under one yen mid-checkout. Completed orders are frozen and do not change.
+- **The strict write check lives in one concern** (decided 2026-10-09). `Spree::Api::V3::StrictMoneyParams`, included in the Admin and Seller base and resource controllers, walks the request body and refuses a JSON number, malformed text or too many decimals for every money and rate key, `preferences` included, before anything is written. A money field checks its currency's decimals when the payload names the currency beside it, and allows four otherwise, so a store in one currency never wrongly refuses an amount in another; the model setters (`Spree::CanonicalDecimals`) still refuse anything malformed. Discount and commission `value` and custom field `value` are not covered by key name, because the same key holds unrelated data elsewhere.
+- **Store API money fields are gated and nullable** (decided 2026-10-09). Declaring them through `money_attributes` hides them from gated (prices-hidden) guests, so delivery rates, claims, returns, exchanges, store credit, refunds, payment sessions, order groups and gift card batches now answer `null` there, and their Store SDK types become `string | null`. Admin and Seller subclasses re-declare them non-null.
+- **The migration rewrites each table once** (decided 2026-10-09, after a review against strong_migrations). All of a table's columns change in one `ALTER TABLE`; `null` and `default` are not passed on PostgreSQL or MySQL, which keep them through a type change (passing `null: false` added a `SET NOT NULL` that scans every row); SQLite, which rebuilds the table, is given both. The rewrite is wrapped in `safety_assured` when strong_migrations is installed.
- **Spree stops parsing numbers by locale** (decided 2026-10-09; supersedes the 5.5 plan's "`LocalizedNumber` is not removed" and this plan's first-pass "out of scope"). The model setters that re-parsed strings with `Spree::LocalizedNumber` under the request locale are replaced by strict ones (`Spree::CanonicalDecimals`): a number or canonical decimal text is stored exactly, and any other text raises `Spree::Money::InvalidFormat` (422 `invalid_money_format` from the API) instead of Rails' lenient cast reading `"1,599.99"` as 1. Why: the legacy admin they served is gone, and under a store whose language writes a comma decimal they misread the dashboard's canonical `"49.50"` as 4950 and grew an untouched `"99.0"` tenfold on every save (a reported bug). `Spree::LocalizedNumber.parse` stays one release as a deprecated method nothing in Spree calls, and is removed in 6.1. The variant's `cost_price`/`weight`/`width`/`height`/`depth` writers keep ignoring a blank value. Ships in PR A.
- **The dashboard shows and reads money in the admin's own number format** (decided 2026-10-09, following Shopify; supersedes the 5.5 plan's "currency's market locale"). `useMoneyLocale()` returns the dashboard language; every money field formats and normalizes through it, whatever the currency or market. Why: a store can have several markets with one currency and different conventions (EUR in Germany and Ireland), so the market-based format depended on which market loaded first; the person typing knows their own convention, and the old reason against it, server re-parsing, is gone. Accepted trade-off: a German-speaking admin of a US store sees `1234,56` for dollars. Ships in PR A.
- **All four parts ship on one pull request** (decided 2026-10-09; supersedes "four pull requests"). A2, B and C land as their own commit series on spree/spree#14852, so nothing ships half-done; A2 is still revertible by its commits.
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index c67cfd5923..c2b418209d 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -10,7 +10,7 @@
**Context:** Money columns were already decimal, but several money paths went through floats (Ruby `.to_f`, dashboard `parseFloat`). A few serializers emitted JSON numbers while the rest emitted unnormalized strings (`"10.0"`). Every gateway call was made in hundredths of the currency while Stripe sessions used ISO minor units, so yen captures recorded 100× the amount and dinar captures a tenth, and Stripe's own units differ from both for ISK, HUF and TWD. `decimal(10,2)` could hold neither a dinar's third decimal, a sub-cent unit price, nor a large dong order.
-**Decision:** No float on a money path in Ruby or TypeScript, stated as a rule in `CLAUDE.md` (a lint cop was tried and dropped on 2026-10-09); `@spree/sdk-core` gets a string-based decimal helper. Currency exponents are ISO 4217 from one Spree-owned file, registered over the Money gem, imported by sdk-core and exposed as `decimal_places` on currencies. Gateways receive a `Spree::Money` and each adapter converts to its provider's unit; gateways that have not opted in keep receiving hundredths with a deprecation warning until 6.1. Every money field in every v3 serializer is a decimal string: exactly the exponent for totals and money that changes hands, up to four decimals for unit prices. Rates and percentages are decimal strings with trailing zeros stripped; `_percent` means 0–100, `rate` means a fraction, and no rate is named like money. Admin and Seller writes reject JSON numbers, non-canonical strings and over-precise strings with 422 `invalid_money_format`. Money columns become `decimal(19,4)` in one idempotent migration with a documented online path. Rounding happens only when persisting, in a gateway adapter, or when serializing, with the mode a parameter and tax providers owning theirs. Existing wrong capture events are reported, never rewritten.
+**Decision:** No float on a money path in Ruby or TypeScript, stated as a rule in `CLAUDE.md` (a lint cop was tried and dropped on 2026-10-09); `@spree/sdk-core` gets a string-based decimal helper. Currency exponents are ISO 4217 from one Spree-owned file, registered over the Money gem, imported by sdk-core and exposed as `decimal_places` on currencies. Gateways receive a `Spree::Money` and each adapter converts to its provider's unit; gateways that have not opted in keep receiving hundredths with a deprecation warning until 6.1. Every money field in every v3 serializer is a decimal string: exactly the exponent for totals and money that changes hands, up to four decimals for unit prices. Rates and percentages are decimal strings with trailing zeros stripped; `_percent` means 0–100, `rate` means a fraction, and no rate is named like money. Admin and Seller writes reject JSON numbers, non-canonical strings and over-precise strings with 422 `invalid_money_format`. Money columns become `decimal(19,4)` in one idempotent migration with a documented online path. Rounding happens only when persisting, in a gateway adapter, or when serializing, with the mode a parameter and tax providers owning theirs. Existing wrong capture events are reported, never rewritten. The migration changes all of a table's money columns in one `ALTER TABLE` and does not restate `null`/`default` (which PostgreSQL and MySQL keep through a type change), so each table is rewritten once; it is marked safe for apps using strong_migrations.
**Consequences:** Breaking for API clients sending numbers or comparing money strings, for clients reading the removed `*_in_cents` fields or the renamed tax rate fields, and (from 6.1) for gateways that never opt in. HUF stops rounding to whole forints. Open carts in zero- and three-decimal currencies change on their next recalculation; completed orders do not. Integer minor units are rejected as an API contract. Ships as four PRs: floats out, gateway amounts, wire contract, precision.
diff --git a/packages/admin-sdk/examples/commission_rates/create.ts b/packages/admin-sdk/examples/commission_rates/create.ts
index ea3a40a4df..7a075c68ec 100644
--- a/packages/admin-sdk/examples/commission_rates/create.ts
+++ b/packages/admin-sdk/examples/commission_rates/create.ts
@@ -12,7 +12,7 @@ const client = createAdminClient({
const commissionRate = await client.commissionRates.create({
name: 'Audio sellers',
kind: 'percentage',
- value: 12.5,
+ value: '12.5',
rules: [{ type: 'seller_rule', preferences: { seller_ids: ['sel_a1b2c3'] } }],
})
diff --git a/packages/admin-sdk/examples/commission_rates/update.ts b/packages/admin-sdk/examples/commission_rates/update.ts
index e03b4d5996..c08d5ef072 100644
--- a/packages/admin-sdk/examples/commission_rates/update.ts
+++ b/packages/admin-sdk/examples/commission_rates/update.ts
@@ -12,7 +12,7 @@ const client = createAdminClient({
// Every rule has to hold, so this charges 15% only on camera sales worth 50 or
// more. Call ruleTypes() for the kinds this marketplace has.
const commissionRate = await client.commissionRates.update('crate_a1b2c3', {
- value: 15,
+ value: '15',
position: 1,
rules: [
{ type: 'category_rule', preferences: { category_ids: ['ctg_d4e5f6'] } },
diff --git a/packages/admin-sdk/examples/delivery-methods/create.ts b/packages/admin-sdk/examples/delivery-methods/create.ts
index 46c0e1581b..6a3631ac08 100644
--- a/packages/admin-sdk/examples/delivery-methods/create.ts
+++ b/packages/admin-sdk/examples/delivery-methods/create.ts
@@ -10,7 +10,7 @@ const deliveryMethod = await client.deliveryMethods.create({
name: 'Express',
storefront_visible: true,
calculator_type: 'flat_rate',
- calculator_preferences: { amount: 12.5 },
+ calculator_preferences: { amount: '12.50' },
})
// endregion:example
diff --git a/packages/admin-sdk/examples/orders/discounts-create.ts b/packages/admin-sdk/examples/orders/discounts-create.ts
index a5517763f0..c610879e9b 100644
--- a/packages/admin-sdk/examples/orders/discounts-create.ts
+++ b/packages/admin-sdk/examples/orders/discounts-create.ts
@@ -9,7 +9,7 @@ const client = createAdminClient({
// Line-item discount; omit line_item_id to distribute across the order.
const { data: discounts } = await client.orders.discounts.create('or_abc123', {
label: 'Customer appeasement',
- value: 10,
+ value: '10',
value_type: 'flat',
line_item_id: 'item_abc123',
})
diff --git a/packages/admin-sdk/examples/orders/fees-create.ts b/packages/admin-sdk/examples/orders/fees-create.ts
index 6ac170c818..0048b942b2 100644
--- a/packages/admin-sdk/examples/orders/fees-create.ts
+++ b/packages/admin-sdk/examples/orders/fees-create.ts
@@ -8,7 +8,7 @@ const client = createAdminClient({
// region:example
const fee = await client.orders.fees.create('or_abc123', {
label: 'Gift wrap',
- amount: 4,
+ amount: '4.00',
kind: 'gift_wrap',
})
diff --git a/packages/admin-sdk/examples/promotions/create.ts b/packages/admin-sdk/examples/promotions/create.ts
index 6579f1a6b7..64ac36072e 100644
--- a/packages/admin-sdk/examples/promotions/create.ts
+++ b/packages/admin-sdk/examples/promotions/create.ts
@@ -29,7 +29,7 @@ const blackFriday = await client.promotions.create({
},
{
type: 'item_total',
- preferences: { amount_min: 100, operator_min: 'gte' },
+ preferences: { amount_min: '100.00', operator_min: 'gte' },
},
{
type: 'product',
@@ -42,7 +42,7 @@ const blackFriday = await client.promotions.create({
type: 'create_item_adjustments',
calculator: {
type: 'percent_on_line_item',
- preferences: { percent: 25 },
+ preferences: { percent: '25' },
},
},
{ type: 'free_shipping' },
diff --git a/packages/admin-sdk/examples/promotions/update.ts b/packages/admin-sdk/examples/promotions/update.ts
index 8307995d05..82af7b60ee 100644
--- a/packages/admin-sdk/examples/promotions/update.ts
+++ b/packages/admin-sdk/examples/promotions/update.ts
@@ -26,7 +26,7 @@ await client.promotions.update(promotionId, {
// Add a new rule
{
type: 'item_total',
- preferences: { amount_min: 50, operator_min: 'gte' },
+ preferences: { amount_min: '50.00', operator_min: 'gte' },
},
],
actions: [
@@ -36,7 +36,7 @@ await client.promotions.update(promotionId, {
type: 'create_item_adjustments',
calculator: {
type: 'percent_on_line_item',
- preferences: { percent: 15 },
+ preferences: { percent: '15' },
},
},
],
diff --git a/packages/admin-sdk/examples/tax-rates/create.ts b/packages/admin-sdk/examples/tax-rates/create.ts
index 98d9b19737..6f25ce4483 100644
--- a/packages/admin-sdk/examples/tax-rates/create.ts
+++ b/packages/admin-sdk/examples/tax-rates/create.ts
@@ -9,7 +9,7 @@ const client = createAdminClient({
// A rate names the jurisdiction it applies to; one naming no country taxes everywhere.
const taxRate = await client.taxRates.create({
name: 'German VAT',
- amount: 0.19,
+ rate_percent: '19',
country_code: 'DE',
tax_category_id: 'txc_UkLWZg9DAJ',
included_in_price: true,
diff --git a/packages/admin-sdk/src/index.ts b/packages/admin-sdk/src/index.ts
index a91391cb85..fd4f64cb3e 100644
--- a/packages/admin-sdk/src/index.ts
+++ b/packages/admin-sdk/src/index.ts
@@ -2,7 +2,17 @@
export type { RequestOptions, RetryConfig, ValidationErrorDetail } from '@spree/sdk-core'
// Request infrastructure (re-export from sdk-core)
-export { SpreeError } from '@spree/sdk-core'
+export {
+ compareMoney,
+ decimalPlaces,
+ isDecimalString,
+ isZeroMoney,
+ multiplyMoney,
+ negateMoney,
+ SpreeError,
+ subtractMoney,
+ sumMoney,
+} from '@spree/sdk-core'
export type {
AuthProvider,
AuthProvidersResponse,
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 37c524e26e..8707a3293f 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -130,15 +130,16 @@ export interface StoreUpdateParams {
/** Blank means the built-in provider: the marketplace settles by hand. */
preferred_payout_provider?: string
preferred_default_payouts_schedule_interval?: string
- preferred_default_minimum_payout_amount?: number
+ /** A decimal string in the store's currency, e.g. `"50.00"`. */
+ preferred_default_minimum_payout_amount?: string
/** Admits a seller as soon as they finish onboarding, with no operator review. */
preferred_auto_approve_sellers?: boolean
/** Puts a seller's product on sale the moment they submit it, with no review. */
preferred_auto_approve_seller_products?: boolean
/** When false, transactional seller emails (approval, payouts, etc.) are suppressed. */
preferred_send_seller_transactional_emails?: boolean
- /** Tax charged on commission as a fraction (0.23 is 23%), when neither the rate nor the tax provider names one. */
- preferred_default_commission_tax_rate?: number
+ /** Tax charged on commission as a fraction (`"0.23"` is 23%), when neither the rate nor the tax provider names one. */
+ preferred_default_commission_tax_rate?: string
}
export interface OptionValueParams {
@@ -204,14 +205,14 @@ export interface PaymentCreateParams {
* Decimal amount as a canonical string (`"1234.56"`: period decimal, no
* grouping). The API does not parse localized input; normalize it first.
*/
- amount?: string | number
+ amount?: string
source_id?: string
}
export interface RefundCreateParams {
payment_id: string
/** Decimal amount; see `PaymentCreateParams.amount` for the string rationale. */
- amount: string | number
+ amount: string
/** Refund reason ID (`rr_…`). Omitted → the store's first refund reason. */
refund_reason_id?: string
}
@@ -246,7 +247,7 @@ export interface FulfillmentCreateParams {
* `status: 'shipped'`; pending fulfillments are re-priced by the rate
* engine.
*/
- cost?: string | number
+ cost?: string
/** Pass 'shipped' to register an already-shipped external fulfillment */
status?: 'shipped'
/** Line item quantities to fulfill; omit to fulfill every not-yet-shipped unit */
@@ -311,7 +312,7 @@ interface ShippingLabelDetails {
/** 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
+ cost?: string
/** Currency of the cost. */
currency?: string
/** `pdf`, `png` or `zpl`; taken from the file when omitted. */
@@ -464,7 +465,7 @@ export interface ClaimCreateParams {
description?: string
send_replacement?: boolean
replacement_variant_id?: string
- refund_amount?: string | number
+ refund_amount?: string
}>
reason_id?: string
memo?: string
@@ -481,7 +482,7 @@ export interface ClaimResolveParams {
resolution: 'refund' | 'replacement' | 'refund_and_replacement'
refund_method?: 'original_payment' | 'store_credit'
/** Decimal amount; defaults to the claim total */
- amount?: string | number
+ amount?: string
/**
* Which claim lines to send a replacement for. Omit to keep whatever the
* claim was opened with — the merchant usually decides what to send when
@@ -495,7 +496,7 @@ export interface ReturnRefundParams {
* Decimal amount; see `PaymentCreateParams.amount` for the string
* rationale. Defaults to the value of what was actually received.
*/
- amount?: string | number
+ amount?: string
/**
* `store_credit` issues credit immediately; `original_payment` refunds
* through the gateway that took the money.
@@ -635,7 +636,7 @@ export interface OrderCancelParams {
* ordinary order, where the gateway returns the payment in full.
* Decimal amount; see `PaymentCreateParams.amount` for the string rationale.
*/
- refund_amount?: string | number
+ refund_amount?: string
notify_customer?: boolean
}
@@ -649,7 +650,7 @@ export interface GiftCardApplyParams {
* `customer_id` (customer prefixed ID) attaches the card to a specific customer.
*/
export interface GiftCardCreateParams {
- amount: string | number
+ amount: string
currency?: string
code?: string
expires_at?: string | null
@@ -657,7 +658,7 @@ export interface GiftCardCreateParams {
}
export interface GiftCardUpdateParams {
- amount?: string | number
+ amount?: string
expires_at?: string | null
customer_id?: string | null
}
@@ -670,7 +671,7 @@ export interface GiftCardUpdateParams {
*/
export interface GiftCardBatchCreateParams {
prefix: string
- amount: string | number
+ amount: string
codes_count: number
currency?: string
expires_at?: string | null
@@ -678,7 +679,7 @@ export interface GiftCardBatchCreateParams {
export interface StoreCreditApplyParams {
/** Decimal amount; see `PaymentCreateParams.amount` for the string rationale. */
- amount?: string | number
+ amount?: string
}
export interface CustomerCreateParams {
@@ -732,14 +733,14 @@ export interface CustomerAddressParams {
export interface CustomerStoreCreditCreateParams {
/** Decimal amount; see `PaymentCreateParams.amount` for the string rationale. */
- amount: string | number
+ amount: string
currency: string
memo?: string
}
export interface CustomerStoreCreditUpdateParams {
/** Decimal amount; see `PaymentCreateParams.amount` for the string rationale. */
- amount?: string | number
+ amount?: string
memo?: string
}
@@ -975,7 +976,7 @@ export interface ProductUpdateParams {
export interface ProductVariantInput {
id?: string
sku?: string
- cost_price?: string | number
+ cost_price?: string
cost_currency?: string
weight?: number
height?: number
@@ -1164,8 +1165,8 @@ export interface VariantPrice {
* Decimal amount as a canonical string (`"1234.56"`: period decimal, no
* grouping). The API does not parse localized input; normalize it first.
*/
- amount: string | number
- compare_at_amount?: string | number | null
+ amount: string
+ compare_at_amount?: string | null
}
/** Stock for one variant at one location. */
@@ -1187,7 +1188,7 @@ export interface VariantCreateParams {
external_references?: ExternalReferencesParams
sku?: string
/** Decimal amount; see `VariantPrice.amount` for the string rationale. */
- cost_price?: string | number
+ cost_price?: string
cost_currency?: string
weight?: number
height?: number
@@ -1228,7 +1229,7 @@ export interface VariantUpdateParams {
external_references?: ExternalReferencesParams
sku?: string
/** Decimal amount; see `VariantPrice.amount` for the string rationale. */
- cost_price?: string | number
+ cost_price?: string
cost_currency?: string
weight?: number
height?: number
@@ -1926,7 +1927,7 @@ export interface SellerCreateParams {
cover_photo?: string | null
tax_remittance?: 'seller' | 'platform'
payouts_schedule_interval?: 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'manual' | null
- minimum_payout_amount?: string | number | null
+ minimum_payout_amount?: string | null
/** Set while the seller is away: the catalog stays but stops selling. */
holiday_mode_until?: string | null
/**
@@ -2103,14 +2104,14 @@ export interface CommissionRateCreateParams {
/** `percentage` charges a share of the sale; `fixed` charges a flat fee. */
kind: 'percentage' | 'fixed'
/** A percentage (e.g. `10` for 10%) or a flat amount, per `kind`. */
- value: number
+ value: string
/**
* What a flat fee charges, keyed by currency: `{ USD: '5.00', GBP: '4.00' }`.
* A rate is skipped for a currency it states no amount in, so that sale
* falls through to the next matching rate rather than being charged a
* converted figure nobody set. Replaces the whole set on write.
*/
- amounts?: Record<string, string | number>
+ amounts?: Record<string, string>
/**
* Charge on the item's gross price rather than its net one. Off by default:
* in the EU the fee is a separate supply from the sale, so it is charged on
@@ -2129,12 +2130,12 @@ export interface CommissionRateCreateParams {
* than against a converted figure nobody set. Replaces the whole set on
* write, and never disturbs `amounts`.
*/
- bounds?: Record<string, { min_amount?: number | null; max_amount?: number | null }>
+ bounds?: Record<string, { min_amount?: string | null; max_amount?: string | null }>
/**
* VAT on the commission itself, as a fraction (e.g. `0.21`). Leave null to
* let the store's tax engine answer for the seller's own jurisdiction.
*/
- commission_tax_rate?: number | null
+ commission_tax_rate?: string | null
/** The rate's full targeting; the server replaces what it holds with this. */
rules?: CommissionRuleDraft[]
metadata?: Record<string, unknown>
@@ -2305,8 +2306,8 @@ export interface PriceListPriceOverrideParams {
currency: string
/** The rung of the variant's ladder. Omit for the bottom rung. */
min_quantity?: number
- amount?: string | number | null
- compare_at_amount?: string | number | null
+ amount?: string | null
+ compare_at_amount?: string | null
}
// ---------------------------------------------------------------------------
@@ -2326,8 +2327,8 @@ export interface PriceCreateParams {
* ladder's bottom rung. Anything above 1 requires a `price_list_id`.
*/
min_quantity?: number
- amount: string | number | null
- compare_at_amount?: string | number | null
+ amount: string | null
+ compare_at_amount?: string | null
/** Omit / null for a base price; prefixed `pl_…` for a list override. */
price_list_id?: string | null
}
@@ -2337,8 +2338,8 @@ export interface PriceUpdateParams {
* `(variant_id, currency, price_list_id, min_quantity)` index — not
* supported. Move a rung by deleting it and creating the new one. */
// variant_id, currency, price_list_id, min_quantity intentionally omitted.
- amount?: string | number | null
- compare_at_amount?: string | number | null
+ amount?: string | null
+ compare_at_amount?: string | null
}
/**
@@ -2370,8 +2371,8 @@ export interface PriceBulkUpsertRow {
* ten rungs on one list per currency.
*/
min_quantity?: number
- amount?: string | number | null
- compare_at_amount?: string | number | null
+ amount?: string | null
+ compare_at_amount?: string | null
}
export interface PaymentMethodCreateParams {
@@ -2812,9 +2813,9 @@ export interface DeliveryMethodParams {
* Method-level percentage handling fee added on top of provider-quoted
* rates. Ignored for calculator-priced methods.
*/
- markup_percent?: number | string | null
+ markup_percent?: string | null
/** Method-level flat handling fee added on top of provider-quoted rates. */
- markup_flat?: number | string | null
+ markup_flat?: string | null
/**
* Carrier service rows: which provider services this method offers, each
* with an optional display label and markup override. Replaces the full
@@ -2835,9 +2836,9 @@ export interface DeliveryMethodServiceParams {
/** Display label shown to customers instead of the carrier-derived name. */
label?: string | null
/** Overrides the method-level flat markup for this service. */
- markup_flat?: number | string | null
+ markup_flat?: string | null
/** Overrides the method-level percentage markup for this service. */
- markup_percent?: number | string | null
+ markup_percent?: string | null
position?: number
}
@@ -3033,7 +3034,7 @@ export interface CatalogQuantityRuleParams {
export interface CatalogOrderMinimumParams {
/** ISO 4217 code. Required on create; unique per catalog. */
currency?: string
- amount?: string | number
+ amount?: string
}
/**
@@ -3086,7 +3087,10 @@ export interface TaxExemptionCertificateParams {
export interface TaxRateParams {
name?: string
- amount?: number | string
+ /** The rate as a fraction in a decimal string, e.g. `"0.23"`. Send this or `rate_percent`. */
+ rate?: string
+ /** The rate as a percentage in a decimal string, e.g. `"23"`. */
+ rate_percent?: string
/** Where the rate applies. A rate naming no country taxes everywhere. */
country_code?: string | null
state_code?: string | null
diff --git a/packages/admin-sdk/src/types/generated/Cart.ts b/packages/admin-sdk/src/types/generated/Cart.ts
index f72ac41535..64501aa064 100644
--- a/packages/admin-sdk/src/types/generated/Cart.ts
+++ b/packages/admin-sdk/src/types/generated/Cart.ts
@@ -1,4 +1,4 @@
-// Typelizer digest fb45526c05a98d68a8e64ee27c9269f5
+// Typelizer digest a0ecf02c0220125bce0fbc5751402c5c
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {FreightSummary, LineItem, Address, Market, AppliedPromotion} from '@/types'
@@ -51,8 +51,8 @@ interface Cart {
current_step: string;
completed_steps: Array<string>;
requirements: Array<{step: string, field: string, code: string, message: string}>;
- order_minimum: number | null;
- order_minimum_shortfall: number | null;
+ order_minimum: string | null;
+ order_minimum_shortfall: string | null;
below_order_minimum: boolean | null;
freight_summary: FreightSummary | null;
shipping_eq_billing_address: boolean;
diff --git a/packages/admin-sdk/src/types/generated/DeliveryMethod.ts b/packages/admin-sdk/src/types/generated/DeliveryMethod.ts
index fa27aac93f..5e8f766511 100644
--- a/packages/admin-sdk/src/types/generated/DeliveryMethod.ts
+++ b/packages/admin-sdk/src/types/generated/DeliveryMethod.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 7c04a13d5653b17c637bb2aed2d3682e
+// Typelizer digest b2dab789219ed7e08f944230d1715dc6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {DeliveryMethodService, DeliveryMethodRule} from '@/types'
@@ -15,12 +15,12 @@ interface DeliveryMethod {
admin_name: string | null;
storefront_visible: boolean;
tracking_url: string | null;
- markup_flat: string | null;
- markup_percent: string | null;
available_to_sellers: boolean;
created_at: string;
updated_at: string;
deleted_at: string;
+ markup_flat: string | null;
+ markup_percent: string | null;
seller_id: string | null;
seller_name: string | null;
services: Array<DeliveryMethodService>;
diff --git a/packages/admin-sdk/src/types/generated/Fulfillment.ts b/packages/admin-sdk/src/types/generated/Fulfillment.ts
index 35f2280bdb..27a1485d90 100644
--- a/packages/admin-sdk/src/types/generated/Fulfillment.ts
+++ b/packages/admin-sdk/src/types/generated/Fulfillment.ts
@@ -1,4 +1,4 @@
-// Typelizer digest d4830cc2ae8046574918ec756c61e26d
+// Typelizer digest 5ed589c3fc54de735b614ead7ce94dad
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Delivery, DeliveryMethod, StockLocation, DeliveryRate, TaxLine, ShippingLabel, FulfillmentItem, Order, FulfillmentStatus} from '@/types'
@@ -34,10 +34,10 @@ interface Fulfillment {
delivery_rates?: Array<DeliveryRate>;
tax_lines?: Array<TaxLine>;
metadata: Record<string, unknown>;
- adjustment_total: string;
- pre_tax_amount: string;
created_at: string;
updated_at: string;
+ adjustment_total: string;
+ pre_tax_amount: string;
order_id: string | null;
stock_location_id: string | null;
documents: Array<{ kind: string; url: string }>;
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index 9fe76186ce..91fe1f66d6 100644
--- a/packages/admin-sdk/src/types/generated/Order.ts
+++ b/packages/admin-sdk/src/types/generated/Order.ts
@@ -1,4 +1,4 @@
-// Typelizer digest c9a017b95ca67ff60f1c0864f27f33ab
+// Typelizer digest cc47b1b04d4f8fd1a756ca9c684188fe
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {FreightSummary, LineItem, Fulfillment, Payment, Address, GiftCard, Market, Seller, Actor, AppliedPromotion, PaymentSplit, Cart, Channel, StockLocation, PaymentMethod, Customer, OrderCancellationReason, Return, Exchange, Claim, ActorKind} from '@/types'
@@ -63,20 +63,20 @@ interface Order {
considered_risky: boolean;
confirmation_delivered: boolean;
store_owner_notification_delivered: boolean;
- payment_total: string;
- display_payment_total: string;
metadata: Record<string, unknown>;
cancel_note: string | null;
+ canceled_at: string | null;
+ approved_at: string | null;
+ created_at: string;
+ updated_at: string;
+ payment_total: string;
+ display_payment_total: string;
commission_amount_total: string;
display_commission_amount_total: string;
commission_tax_total: string;
display_commission_tax_total: string;
commission_total: string;
display_commission_total: string;
- canceled_at: string | null;
- approved_at: string | null;
- created_at: string;
- updated_at: string;
preferred_stock_location_id: string | null;
po_document_url: string | null;
seller_id: string | null;
diff --git a/packages/admin-sdk/src/types/generated/Price.ts b/packages/admin-sdk/src/types/generated/Price.ts
index e28391c8a1..6e2f9754bf 100644
--- a/packages/admin-sdk/src/types/generated/Price.ts
+++ b/packages/admin-sdk/src/types/generated/Price.ts
@@ -1,15 +1,13 @@
-// Typelizer digest 3867326f06495708a3f0f6324e651582
+// Typelizer digest 4ee9d218cd35df49f1f7f936bf13a42e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Variant} from '@/types'
interface Price {
id: string;
+ currency: string | null;
amount: string | null;
- amount_in_cents: number | null;
compare_at_amount: string | null;
- compare_at_amount_in_cents: number | null;
- currency: string | null;
display_amount: string | null;
display_compare_at_amount: string | null;
price_list_id: string | null;
diff --git a/packages/admin-sdk/src/types/generated/PriceHistory.ts b/packages/admin-sdk/src/types/generated/PriceHistory.ts
index 6c9958954a..5989a018b0 100644
--- a/packages/admin-sdk/src/types/generated/PriceHistory.ts
+++ b/packages/admin-sdk/src/types/generated/PriceHistory.ts
@@ -1,12 +1,11 @@
-// Typelizer digest 3fbefc5e95ad6a0ae420cecc1dd410b4
+// Typelizer digest 0a531feb62eb37c0fabfe32f23369636
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface PriceHistory {
id: string;
- amount: string;
- amount_in_cents: number;
currency: string;
+ amount: string | null;
display_amount: string;
recorded_at: string;
variant_id: string;
diff --git a/packages/admin-sdk/src/types/generated/PurchaseOrderItem.ts b/packages/admin-sdk/src/types/generated/PurchaseOrderItem.ts
index d3cad40976..c57d5048e7 100644
--- a/packages/admin-sdk/src/types/generated/PurchaseOrderItem.ts
+++ b/packages/admin-sdk/src/types/generated/PurchaseOrderItem.ts
@@ -1,4 +1,4 @@
-// Typelizer digest c474f7542f371487955cda2abc4eec06
+// Typelizer digest 07ad2428e9033f6dffbcaec0fbe41769
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -13,8 +13,8 @@ interface PurchaseOrderItem {
created_at: string;
updated_at: string;
unit_cost: string;
- total_cost: string;
display_unit_cost: string;
+ total_cost: string;
display_total_cost: string;
purchase_order_id: string | null;
variant_id: string | null;
diff --git a/packages/admin-sdk/src/types/generated/ShippingLabel.ts b/packages/admin-sdk/src/types/generated/ShippingLabel.ts
index 19bcda48a1..55860ba19e 100644
--- a/packages/admin-sdk/src/types/generated/ShippingLabel.ts
+++ b/packages/admin-sdk/src/types/generated/ShippingLabel.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 63bf00d90369522947569216d8408672
+// Typelizer digest e20560b951b504e8062d2f13adf06216
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {ShippingLabelStatus} from '@/types'
@@ -21,7 +21,7 @@ interface ShippingLabel {
owner_id: string;
owner_type: 'fulfillment' | 'return';
cost: string;
- display_cost: string;
+ display_cost: string | null;
integration_id: string | null;
file_pending: boolean;
download_url: string | null;
diff --git a/packages/admin-sdk/src/types/generated/Store.ts b/packages/admin-sdk/src/types/generated/Store.ts
index 706f2d7fb3..db3cd057f4 100644
--- a/packages/admin-sdk/src/types/generated/Store.ts
+++ b/packages/admin-sdk/src/types/generated/Store.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 5314140659398ef1ea61ca4721eadb9b
+// Typelizer digest ecef3492ed9ea6c3b5e9855520a8cfcd
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {SetupTask} from '@/types'
@@ -63,8 +63,8 @@ interface Store {
/** Payout provider; null uses the installation default. Built-in: system. Provider gems register more (e.g. stripe). */
preferred_payout_provider: string | null;
order_number_sequence_started: boolean;
- preferred_default_minimum_payout_amount: number;
- preferred_default_commission_tax_rate: number;
+ preferred_default_minimum_payout_amount: string | null;
+ preferred_default_commission_tax_rate: string | null;
url: string;
api_url: string;
setup_tasks: Array<SetupTask>;
diff --git a/packages/admin-sdk/src/types/generated/TaxLine.ts b/packages/admin-sdk/src/types/generated/TaxLine.ts
index 4d7a2f094f..4a4ffbed4c 100644
--- a/packages/admin-sdk/src/types/generated/TaxLine.ts
+++ b/packages/admin-sdk/src/types/generated/TaxLine.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 4ca9f98aec3ca9523d982fe9cbcc3a36
+// Typelizer digest 40fc5a7cadf73dbcb85aa70651f1b316
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -7,7 +7,7 @@ interface TaxLine {
label: string;
included: boolean;
credit: boolean;
- rate: string;
+ rate: string | null;
tax_rate_id: string | null;
line_item_id: string | null;
fulfillment_id: string | null;
diff --git a/packages/admin-sdk/src/types/generated/TaxRate.ts b/packages/admin-sdk/src/types/generated/TaxRate.ts
index 3f7dc31f4b..313ce8eb84 100644
--- a/packages/admin-sdk/src/types/generated/TaxRate.ts
+++ b/packages/admin-sdk/src/types/generated/TaxRate.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 8e8127ce4fc16b3cff3947a6ea5d20a3
+// Typelizer digest 4b03a367a8150e55df52da427af8dbe0
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -11,8 +11,8 @@ interface TaxRate {
created_at: string;
updated_at: string;
deleted_at: string | null;
- amount: string;
- amount_percentage: number | null;
+ rate: string | null;
+ rate_percent: string | null;
tax_category_id: string | null;
store_id: string | null;
country_code: string | null;
diff --git a/packages/admin-sdk/src/types/generated/Variant.ts b/packages/admin-sdk/src/types/generated/Variant.ts
index 6c240e26dc..159c162805 100644
--- a/packages/admin-sdk/src/types/generated/Variant.ts
+++ b/packages/admin-sdk/src/types/generated/Variant.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 4d85958ceff0de29a62ec76c4bccd940
+// Typelizer digest e02a30b6f82fbd9309c1fd1cc18148f9
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Price, PriceHistory, Seller, Media, OptionValue, CustomField, StockLevel} from '@/types'
@@ -38,7 +38,6 @@ interface Variant {
external_references: Record<string, string>;
metadata: Record<string, unknown>;
position: number;
- cost_price: string | null;
cost_currency: string | null;
barcode: string | null;
backorder_limit: number | null;
@@ -50,6 +49,7 @@ interface Variant {
deleted_at: string | null;
created_at: string;
updated_at: string;
+ cost_price: string | null;
preorderable: boolean;
tax_category_id: string | null;
carton_package_type_id: string | null;
diff --git a/packages/admin-sdk/src/types/generated/emails/EmailDeliveryRate.ts b/packages/admin-sdk/src/types/generated/emails/EmailDeliveryRate.ts
index dd382e4ff1..22afba405a 100644
--- a/packages/admin-sdk/src/types/generated/emails/EmailDeliveryRate.ts
+++ b/packages/admin-sdk/src/types/generated/emails/EmailDeliveryRate.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 063686c62a9b464f15dffdd713e847c4
+// Typelizer digest 3da8add8702cca5913d5c8b30c86079a
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {EmailFreightSummary, EmailDeliveryMethod} from '.'
@@ -8,21 +8,21 @@ interface EmailDeliveryRate {
delivery_method_id: string;
name: string;
selected: boolean;
- cost: string;
- total: string;
- additional_tax_total: string;
- included_tax_total: string;
- tax_total: string;
+ cost: string | null;
+ total: string | null;
+ additional_tax_total: string | null;
+ included_tax_total: string | null;
+ tax_total: string | null;
carrier: string | null;
service_level: string | null;
estimated_delivery_date: string | null;
unpriced: boolean;
freight_summary: EmailFreightSummary | null;
- display_cost: string;
- display_total: string;
- display_additional_tax_total: string;
- display_included_tax_total: string;
- display_tax_total: string;
+ display_cost: string | null;
+ display_total: string | null;
+ display_additional_tax_total: string | null;
+ display_included_tax_total: string | null;
+ display_tax_total: string | null;
delivery_method: EmailDeliveryMethod;
}
diff --git a/packages/admin-sdk/src/types/generated/emails/EmailReturn.ts b/packages/admin-sdk/src/types/generated/emails/EmailReturn.ts
index 88ddbdb5b4..8d7d9d5aa2 100644
--- a/packages/admin-sdk/src/types/generated/emails/EmailReturn.ts
+++ b/packages/admin-sdk/src/types/generated/emails/EmailReturn.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 23285c5eec967a4291ed88f1e110a919
+// Typelizer digest ba8a0cdfd53df1bee4bccce8f3ae52d6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {EmailLineItem, ReturnStatus} from '.'
@@ -9,10 +9,10 @@ interface EmailReturn {
status: ReturnStatus;
order_id: string | null;
reason_id: string | null;
- refund_total: string;
- display_refund_total: string;
- refund_tax_total: string;
- display_refund_tax_total: string;
+ refund_total: string | null;
+ display_refund_total: string | null;
+ refund_tax_total: string | null;
+ display_refund_tax_total: string | null;
approved_at: string | null;
received_at: string | null;
refunded_at: string | null;
diff --git a/packages/admin-sdk/src/zod/generated/Cart.ts b/packages/admin-sdk/src/zod/generated/Cart.ts
index 29bbb7d16a..b676291198 100644
--- a/packages/admin-sdk/src/zod/generated/Cart.ts
+++ b/packages/admin-sdk/src/zod/generated/Cart.ts
@@ -54,8 +54,8 @@ export const CartSchema = z.object({
current_step: z.string(),
completed_steps: z.array(z.string()),
requirements: z.array(z.object({ step: z.string(), field: z.string(), code: z.string(), message: z.string() })),
- order_minimum: z.number().nullable(),
- order_minimum_shortfall: z.number().nullable(),
+ order_minimum: z.string().nullable(),
+ order_minimum_shortfall: z.string().nullable(),
below_order_minimum: z.boolean().nullable(),
freight_summary: FreightSummarySchema.nullable(),
shipping_eq_billing_address: z.boolean(),
diff --git a/packages/admin-sdk/src/zod/generated/DeliveryMethod.ts b/packages/admin-sdk/src/zod/generated/DeliveryMethod.ts
index 7314dcf5b9..5754302c48 100644
--- a/packages/admin-sdk/src/zod/generated/DeliveryMethod.ts
+++ b/packages/admin-sdk/src/zod/generated/DeliveryMethod.ts
@@ -15,12 +15,12 @@ export const DeliveryMethodSchema = z.object({
admin_name: z.string().nullable(),
storefront_visible: z.boolean(),
tracking_url: z.string().nullable(),
- markup_flat: z.string().nullable(),
- markup_percent: z.string().nullable(),
available_to_sellers: z.boolean(),
created_at: z.string(),
updated_at: z.string(),
deleted_at: z.string(),
+ markup_flat: z.string().nullable(),
+ markup_percent: z.string().nullable(),
seller_id: z.string().nullable(),
seller_name: z.string().nullable(),
services: z.array(DeliveryMethodServiceSchema),
diff --git a/packages/admin-sdk/src/zod/generated/Fulfillment.ts b/packages/admin-sdk/src/zod/generated/Fulfillment.ts
index 377ba44699..ebc050fb59 100644
--- a/packages/admin-sdk/src/zod/generated/Fulfillment.ts
+++ b/packages/admin-sdk/src/zod/generated/Fulfillment.ts
@@ -40,10 +40,10 @@ export const FulfillmentSchema = z.object({
delivery_rates: z.array(DeliveryRateSchema).optional(),
tax_lines: z.array(TaxLineSchema).optional(),
metadata: z.record(z.string(), z.unknown()),
- adjustment_total: z.string(),
- pre_tax_amount: z.string(),
created_at: z.string(),
updated_at: z.string(),
+ adjustment_total: z.string(),
+ pre_tax_amount: z.string(),
order_id: z.string().nullable(),
stock_location_id: z.string().nullable(),
documents: z.array(z.object({ kind: z.string(), url: z.string() })),
diff --git a/packages/admin-sdk/src/zod/generated/Order.ts b/packages/admin-sdk/src/zod/generated/Order.ts
index 8d95859054..96995b83f8 100644
--- a/packages/admin-sdk/src/zod/generated/Order.ts
+++ b/packages/admin-sdk/src/zod/generated/Order.ts
@@ -81,20 +81,20 @@ export const OrderSchema = z.object({
considered_risky: z.boolean(),
confirmation_delivered: z.boolean(),
store_owner_notification_delivered: z.boolean(),
- payment_total: z.string(),
- display_payment_total: z.string(),
metadata: z.record(z.string(), z.unknown()),
cancel_note: z.string().nullable(),
+ canceled_at: z.string().nullable(),
+ approved_at: z.string().nullable(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ payment_total: z.string(),
+ display_payment_total: z.string(),
commission_amount_total: z.string(),
display_commission_amount_total: z.string(),
commission_tax_total: z.string(),
display_commission_tax_total: z.string(),
commission_total: z.string(),
display_commission_total: z.string(),
- canceled_at: z.string().nullable(),
- approved_at: z.string().nullable(),
- created_at: z.string(),
- updated_at: z.string(),
preferred_stock_location_id: z.string().nullable(),
po_document_url: z.string().nullable(),
seller_id: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/Price.ts b/packages/admin-sdk/src/zod/generated/Price.ts
index 18595c854c..4721563274 100644
--- a/packages/admin-sdk/src/zod/generated/Price.ts
+++ b/packages/admin-sdk/src/zod/generated/Price.ts
@@ -4,11 +4,9 @@ import { VariantSchema } from './Variant';
export const PriceSchema = z.object({
id: z.string(),
+ currency: z.string().nullable(),
amount: z.string().nullable(),
- amount_in_cents: z.number().nullable(),
compare_at_amount: z.string().nullable(),
- compare_at_amount_in_cents: z.number().nullable(),
- currency: z.string().nullable(),
display_amount: z.string().nullable(),
display_compare_at_amount: z.string().nullable(),
price_list_id: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/PriceHistory.ts b/packages/admin-sdk/src/zod/generated/PriceHistory.ts
index ae9aa92577..5a422f71a9 100644
--- a/packages/admin-sdk/src/zod/generated/PriceHistory.ts
+++ b/packages/admin-sdk/src/zod/generated/PriceHistory.ts
@@ -3,9 +3,8 @@ import { z } from 'zod';
export const PriceHistorySchema = z.object({
id: z.string(),
- amount: z.string(),
- amount_in_cents: z.number(),
currency: z.string(),
+ amount: z.string().nullable(),
display_amount: z.string(),
recorded_at: z.string(),
variant_id: z.string(),
diff --git a/packages/admin-sdk/src/zod/generated/PurchaseOrderItem.ts b/packages/admin-sdk/src/zod/generated/PurchaseOrderItem.ts
index 6e4f670a3f..90733ac8e5 100644
--- a/packages/admin-sdk/src/zod/generated/PurchaseOrderItem.ts
+++ b/packages/admin-sdk/src/zod/generated/PurchaseOrderItem.ts
@@ -12,8 +12,8 @@ export const PurchaseOrderItemSchema = z.object({
created_at: z.string(),
updated_at: z.string(),
unit_cost: z.string(),
- total_cost: z.string(),
display_unit_cost: z.string(),
+ total_cost: z.string(),
display_total_cost: z.string(),
purchase_order_id: z.string().nullable(),
variant_id: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/ShippingLabel.ts b/packages/admin-sdk/src/zod/generated/ShippingLabel.ts
index 8e58b4b740..21b5890ccb 100644
--- a/packages/admin-sdk/src/zod/generated/ShippingLabel.ts
+++ b/packages/admin-sdk/src/zod/generated/ShippingLabel.ts
@@ -19,7 +19,7 @@ export const ShippingLabelSchema = z.object({
owner_id: z.string(),
owner_type: z.string(),
cost: z.string(),
- display_cost: z.string(),
+ display_cost: z.string().nullable(),
integration_id: z.string().nullable(),
file_pending: z.boolean(),
download_url: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/Store.ts b/packages/admin-sdk/src/zod/generated/Store.ts
index f237dc352e..7ffd18c85a 100644
--- a/packages/admin-sdk/src/zod/generated/Store.ts
+++ b/packages/admin-sdk/src/zod/generated/Store.ts
@@ -60,8 +60,8 @@ export const StoreSchema = z.object({
preferred_order_routing_strategy: z.string(),
preferred_payout_provider: z.string().nullable(),
order_number_sequence_started: z.boolean(),
- preferred_default_minimum_payout_amount: z.number(),
- preferred_default_commission_tax_rate: z.number(),
+ preferred_default_minimum_payout_amount: z.string().nullable(),
+ preferred_default_commission_tax_rate: z.string().nullable(),
url: z.string(),
api_url: z.string(),
setup_tasks: z.array(SetupTaskSchema),
diff --git a/packages/admin-sdk/src/zod/generated/TaxLine.ts b/packages/admin-sdk/src/zod/generated/TaxLine.ts
index 978a78e254..3bb65d7b7b 100644
--- a/packages/admin-sdk/src/zod/generated/TaxLine.ts
+++ b/packages/admin-sdk/src/zod/generated/TaxLine.ts
@@ -6,7 +6,7 @@ export const TaxLineSchema = z.object({
label: z.string(),
included: z.boolean(),
credit: z.boolean(),
- rate: z.string(),
+ rate: z.string().nullable(),
tax_rate_id: z.string().nullable(),
line_item_id: z.string().nullable(),
fulfillment_id: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/TaxRate.ts b/packages/admin-sdk/src/zod/generated/TaxRate.ts
index 028b58db10..fbdb1e3783 100644
--- a/packages/admin-sdk/src/zod/generated/TaxRate.ts
+++ b/packages/admin-sdk/src/zod/generated/TaxRate.ts
@@ -10,8 +10,8 @@ export const TaxRateSchema = z.object({
created_at: z.string(),
updated_at: z.string(),
deleted_at: z.string().nullable(),
- amount: z.string(),
- amount_percentage: z.number().nullable(),
+ rate: z.string().nullable(),
+ rate_percent: z.string().nullable(),
tax_category_id: z.string().nullable(),
store_id: z.string().nullable(),
country_code: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/Variant.ts b/packages/admin-sdk/src/zod/generated/Variant.ts
index 1d667300d2..7817e635d1 100644
--- a/packages/admin-sdk/src/zod/generated/Variant.ts
+++ b/packages/admin-sdk/src/zod/generated/Variant.ts
@@ -43,7 +43,6 @@ export const VariantSchema = z.object({
external_references: z.record(z.string(), z.string()),
metadata: z.record(z.string(), z.unknown()),
position: z.number(),
- cost_price: z.string().nullable(),
cost_currency: z.string().nullable(),
barcode: z.string().nullable(),
backorder_limit: z.number().nullable(),
@@ -55,6 +54,7 @@ export const VariantSchema = z.object({
deleted_at: z.string().nullable(),
created_at: z.string(),
updated_at: z.string(),
+ cost_price: z.string().nullable(),
preorderable: z.boolean(),
tax_category_id: z.string().nullable(),
carton_package_type_id: z.string().nullable(),
diff --git a/packages/admin-sdk/src/zod/generated/emails/EmailDeliveryRate.ts b/packages/admin-sdk/src/zod/generated/emails/EmailDeliveryRate.ts
index c4aef04167..527134f792 100644
--- a/packages/admin-sdk/src/zod/generated/emails/EmailDeliveryRate.ts
+++ b/packages/admin-sdk/src/zod/generated/emails/EmailDeliveryRate.ts
@@ -8,21 +8,21 @@ export const EmailDeliveryRateSchema = z.object({
delivery_method_id: z.string(),
name: z.string(),
selected: z.boolean(),
- cost: z.string(),
- total: z.string(),
- additional_tax_total: z.string(),
- included_tax_total: z.string(),
- tax_total: z.string(),
+ cost: z.string().nullable(),
+ total: z.string().nullable(),
+ additional_tax_total: z.string().nullable(),
+ included_tax_total: z.string().nullable(),
+ tax_total: z.string().nullable(),
carrier: z.string().nullable(),
service_level: z.string().nullable(),
estimated_delivery_date: z.string().nullable(),
unpriced: z.boolean(),
freight_summary: EmailFreightSummarySchema.nullable(),
- display_cost: z.string(),
- display_total: z.string(),
- display_additional_tax_total: z.string(),
- display_included_tax_total: z.string(),
- display_tax_total: z.string(),
+ display_cost: z.string().nullable(),
+ display_total: z.string().nullable(),
+ display_additional_tax_total: z.string().nullable(),
+ display_included_tax_total: z.string().nullable(),
+ display_tax_total: z.string().nullable(),
delivery_method: EmailDeliveryMethodSchema,
});
diff --git a/packages/admin-sdk/src/zod/generated/emails/EmailReturn.ts b/packages/admin-sdk/src/zod/generated/emails/EmailReturn.ts
index 403b736acd..f2c479fab7 100644
--- a/packages/admin-sdk/src/zod/generated/emails/EmailReturn.ts
+++ b/packages/admin-sdk/src/zod/generated/emails/EmailReturn.ts
@@ -8,10 +8,10 @@ export const EmailReturnSchema = z.object({
status: z.string(),
order_id: z.string().nullable(),
reason_id: z.string().nullable(),
- refund_total: z.string(),
- display_refund_total: z.string(),
- refund_tax_total: z.string(),
- display_refund_tax_total: z.string(),
+ refund_total: z.string().nullable(),
+ display_refund_total: z.string().nullable(),
+ refund_tax_total: z.string().nullable(),
+ display_refund_tax_total: z.string().nullable(),
approved_at: z.string().nullable(),
received_at: z.string().nullable(),
refunded_at: z.string().nullable(),
diff --git a/packages/admin-sdk/tests/money.test.ts b/packages/admin-sdk/tests/money.test.ts
new file mode 100644
index 0000000000..6158cd9b8a
--- /dev/null
+++ b/packages/admin-sdk/tests/money.test.ts
@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { CURRENCY_EXPONENTS } from '../../sdk-core/src/currency-exponents'
+import {
+ compareMoney,
+ decimalPlaces,
+ isDecimalString,
+ isZeroMoney,
+ multiplyMoney,
+ subtractMoney,
+ sumMoney,
+} from '../src'
+
+describe('money helpers', () => {
+ it('reads the same ISO 4217 table as Spree', () => {
+ const core = JSON.parse(
+ readFileSync(
+ resolve(__dirname, '../../../spree/core/config/currency_exponents.json'),
+ 'utf-8',
+ ),
+ )
+ expect(CURRENCY_EXPONENTS).toEqual(core)
+ })
+
+ it('knows each currency’s decimals', () => {
+ expect([
+ decimalPlaces('USD'),
+ decimalPlaces('jpy'),
+ decimalPlaces('KWD'),
+ decimalPlaces('ZZZ'),
+ ]).toEqual([2, 0, 3, 2])
+ })
+
+ it('adds exactly where floats drift', () => {
+ expect(sumMoney(['0.1', '0.2'])).toBe('0.3')
+ expect(sumMoney(['0.1', '0.2'], 'USD')).toBe('0.30')
+ expect(sumMoney(['1.500', '0.005'], 'KWD')).toBe('1.505')
+ expect(sumMoney(['100', '200'], 'JPY')).toBe('300')
+ expect(sumMoney([null, '', '19.99'], 'USD')).toBe('19.99')
+ })
+
+ it('subtracts and multiplies exactly', () => {
+ expect(subtractMoney('10.00', '10.01', 'USD')).toBe('-0.01')
+ expect(multiplyMoney('0.0125', 3)).toBe('0.0375')
+ expect(multiplyMoney('19.99', 3, 'USD')).toBe('59.97')
+ })
+
+ it('compares and tests for zero', () => {
+ expect(compareMoney('10.0', '10.00')).toBe(0)
+ expect(compareMoney('9.99', '10')).toBe(-1)
+ expect(compareMoney('-1', '-2')).toBe(1)
+ expect([
+ isZeroMoney('0.00'),
+ isZeroMoney('-0.0'),
+ isZeroMoney(''),
+ isZeroMoney('0.01'),
+ ]).toEqual([true, true, true, false])
+ })
+
+ it('accepts only canonical decimal strings', () => {
+ expect([
+ isDecimalString('19.99'),
+ isDecimalString('1,99'),
+ isDecimalString(19.99),
+ isDecimalString('1e3'),
+ ]).toEqual([true, false, false, false])
+ expect(() => sumMoney(['1,99'])).toThrow()
+ })
+})
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 3a9a1e6ccb..85d438cbac 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 is honoured only on the\ndashboard's origin and for an account that is staff of the store —\notherwise it is silently ignored and the link opens the dashboard's\nreset page. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Honoured only on the dashboard origin, for an account that is staff of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."},"sample_data":{"type":"boolean","description":"Load the demo catalog, customers and orders in the background once the admin account exists."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy shorthand (built-in: `rules`). `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 shorthand (built-in: `rules`). `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]=product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead."},"resource_type":{"type":"string","description":"Shorthand of the owning resource, e.g. `product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/email_templates":{"get":{"summary":"List email templates","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every email template merchants may edit: the emails customers\nreceive, the email layout and the shared partials. Each shows what\ncustomers receive now (the store's published version, else Spree's\ndefault) and any draft in progress. Staff emails are not editable.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default) for the version every language uses","schema":{"type":"string"}}],"responses":{"200":{"description":"email templates found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The template key with dots, e.g. `spree.order_mailer.confirm_email`","schema":{"type":"string"}}],"get":{"summary":"Get an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the template for one language: what customers receive now,\nSpree's default, and the draft with its `lock_version`. When Spree's\ndefault changed since the store's version started from it,\n`default_changed` is true and `base_body` holds the default it\nstarted from, to compare with `default_body`.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (`draft.updated_by`)","schema":{"type":"string"}}],"responses":{"200":{"description":"email template found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"404":{"description":"not an editable template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Revert an email template to Spree's default","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Goes back to Spree's default for one language and discards the draft.\nThe store's published versions are kept, so one can still be restored.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"email template reverted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/draft":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"put":{"summary":"Save an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Saves the draft, in any state; customers keep receiving the published\nversion until it is published. Send the `lock_version` the draft was\nloaded with: a save made from an older copy is refused with 409,\nnaming who saved last. The first save starts from what is published,\nelse Spree's default.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"draft saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"409":{"description":"saved by someone else since it was loaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"lock_version":{"type":"integer"},"rebase":{"type":"boolean","description":"Marks the draft as based on Spree's current default, after reviewing what changed in it"}}}}}}},"delete":{"summary":"Discard an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"draft discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/publication":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Publish an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Makes the draft what customers receive. The draft is first rendered\nwith sample data; one that does not render (for the layout or a\npartial: in any email using it) is refused with 422, listing each\nproblem with its email and line.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"draft published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"422":{"description":"the draft does not render","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer","description":"The draft's `lock_version` as reviewed; a draft saved since is refused with 409"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/preview":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Preview an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renders the template with sample data built from the store's latest\nmatching record, or the one `record_id` names, and returns the email\nwith the variables it was rendered with. An unsaved `subject` and\n`body` take the place of the current version. The layout and partials\nrender inside an email, `email_key` or the first one. `branding`\npreviews colors and a font before they are saved to the store.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"email template rendered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplatePreview"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string","description":"The record to build sample data from"},"email_key":{"type":"string","description":"For the layout or a partial, the email to show it in"},"branding":{"type":"object","description":"Unsaved colors and font to preview, named like the store's `preferred_email_*` settings without the prefix","properties":{"accent_color":{"type":"string"},"background_color":{"type":"string"},"card_color":{"type":"string"},"text_color":{"type":"string"},"heading_color":{"type":"string"},"font":{"type":"string","enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]}}}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/test_email":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Send a test email","tags":["Email Templates"],"security":[{"bearer_auth":[]}],"description":"Sends the template, rendered as the preview renders it, to the\nsigned-in admin, and never to another address: the sample data comes\nfrom a real customer's records. Takes the same body as the preview.\n","parameters":[{"name":"x-spree-api-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":"test email queued","content":{"application/json":{"schema":{"type":"object","properties":{"sent_to":{"type":"string"}},"required":["sent_to"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string"},"email_key":{"type":"string"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/sample_records":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List records to preview an email template with","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The store's five latest records the template can be previewed with,\nnewest first, to pass as `record_id` to the preview. For the layout\nand partials, those of the email `email_key` names. Empty for an\nemail that needs no record.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"email_key","in":"query","required":false,"description":"For the layout or a partial, the email to show it in","schema":{"type":"string"}}],"responses":{"200":{"description":"records found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List email template revisions","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every version of the template published in one language, newest\nfirst. Reverting to Spree's default keeps them.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","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 (`published_by`)","schema":{"type":"string"}}],"responses":{"200":{"description":"revisions found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions/{revision_id}/restoration":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Restore an email template revision","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Copies the revision into the draft, to be published like any change.\nSend the draft's `lock_version` when one is open, as when saving it.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"revision copied into the draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer"}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers","price_list_prices","purchase_orders"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange and claim replacements are moved only out of a named `source_fulfillment_id`, which is how a canceled replacement is sent again. 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"},"source_fulfillment_id":{"type":"string","description":"The only fulfillment of this order to move units from, its exchange and claim replacements included. Omit to take the customer's bought units from every unshipped fulfillment"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `customer_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"customer_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations","price_list_prices","purchase_orders"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\nOn a marketplace, an order holding several sellers' goods becomes one\norder per seller, and the response is the order group they belong to\nwith those orders nested inside it.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Shorthand of the tagged resource: `product`, `order` or `customer`","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores. Removing a role needs the same rights as granting it, and the store always keeps at least one admin.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{invitation_id}/acceptance_link":{"get":{"summary":"Get an invitation acceptance link","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"acceptance link found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationAcceptanceLink"}}}}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/store_credits":{"get":{"summary":"List store credits","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every store credit in the current store, across all customers.\nRead-only: issuing, editing and deleting a credit stays nested under\nthe customer that holds it.\n\n`meta.totals` carries the outstanding balance as one row per currency,\nsummed over the same filter this request used — so filtering by a\ncustomer answers that customer's balance and no filter answers the\nstore's liability.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[customer_id_eq]","in":"query","required":false,"description":"Filter by the customer holding the credit","schema":{"type":"string"}},{"name":"q[customer_email_cont]","in":"query","required":false,"description":"Filter by customer email (contains)","schema":{"type":"string"}},{"name":"q[currency_eq]","in":"query","required":false,"description":"Filter by currency","schema":{"type":"string"}},{"name":"q[memo_cont]","in":"query","required":false,"description":"Filter by the free-text reason (contains)","schema":{"type":"string"}},{"name":"q[outstanding]","in":"query","required":false,"description":"True for credits with money left, false for credits already spent","schema":{"type":"boolean"}},{"name":"q[from_gift_card]","in":"query","required":false,"description":"True for credits a gift card redemption created, false for every other origin","schema":{"type":"boolean"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a store credit","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredit"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{store_credit_id}/events":{"parameters":[{"name":"store_credit_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List a store credit's ledger","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every movement of the credit's balance, newest first: allocated when\nissued, authorized when a checkout starts against it, captured when\nthat order is paid, and voided or credited back if it is cancelled.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"events found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/webhook_events":{"get":{"summary":"List webhook events","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every event a webhook endpoint can subscribe to, including those installed extensions declare. Credential events reach only endpoints that name them, and subscribing to one needs the permission listed; deprecated events name their replacement.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"events returned","content":{"application/json":{}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit — send the value back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (`box`, `envelope`, `carton`, `pallet`, `container`)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/purchase_orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock bought from suppliers. A purchase order carries what a purchase\nhas and a stock transfer does not: a supplier, a unit cost per line and\nan expected arrival date.\n\nOrdered units never count toward availability. Nothing here changes\n`count_on_hand` until `receive` runs, because a merchant who has\nordered stock does not have it.\n\nStatuses are `draft`, `ordered`, `partially_received`, `received`, `over_received` and\n`canceled`. Each move between them is its own endpoint, not a `PATCH`\nthat writes `status`.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,\n`supplier` and `destination_location`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ordered', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase orders found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts an order. Nothing is on order and nothing touches availability\nuntil the order is marked as ordered and then received.\n\n`currency` defaults to the store's; set it for a foreign-currency\norder. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the\nsupplier promised means the same day in every timezone.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"purchase order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"supplier belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string"},"destination_location_id":{"type":"string"},"currency":{"type":"string","nullable":true},"expected_at":{"type":"string","format":"date","nullable":true},"reference":{"type":"string","nullable":true,"description":"The supplier's own order number"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_ordered":{"type":"integer"},"unit_cost":{"type":"string"}},"required":["variant_id","quantity_ordered"]}},"metadata":{"type":"object","nullable":true}},"required":["supplier_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/purchase_orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"Get a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"purchase order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_ordered":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Place the order with the supplier","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is\nstamped. Availability is still untouched — ordered stock is not stock\nthe merchant has.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts":{"parameters":[{"name":"purchase_order_id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries booked against an order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused.\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Book in a delivery","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment purchased goods first count toward availability. Records\none delivery as a stock receipt: what this delivery brought, per line,\nnot a running total — a second delivery adds to the first.\n\n`quantity_accepted` reaches the shelf; `quantity_rejected` is refused\nand recorded with a `rejection_reason` (`damaged`, `wrong_item`,\n`expired` or `other`), never stocked. Omit `items` to book in\neverything still outstanding, intact.\n\nEach `received` stock movement carries the line's `unit_cost` and\nnames the receipt, so a delivery can be reconciled against the ledger.\n\nThe order stays `partially_received` while any line is still owed,\nsettles in `received` once every line has what it expected, and in\n`over_received` once any line has more.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery booked in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"order has not been placed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true,"description":"The supplier's delivery note or packing slip"},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Take an order back to draft","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared.\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Close an order short","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received order whose balance the supplier will not\ndeliver. Nothing moves: what arrived stays on the shelf, the\noutstanding count stays on each line, and the order settles in\n`received` with `closed_short_at` and the `reason` recorded.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/purchase_orders/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Closes what is still outstanding. Nothing is unwound: a purchase order\nnever moved stock until units were received, and units already received\nstay on the shelf because the merchant has them.\n\nA `reason` is appended to the order's notes.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{seller_id}/balances":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's balances","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Where one seller stands with the marketplace, one row per currency:\nwhat they have earned (completed transfers, refund reversals\nincluded), what has been paid to them, what is still owed, and\nearnings the payout provider has not yet confirmed.\n\nComputed from the ledger rather than stored, so the rows carry no id.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"balances listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerBalance"}}},"required":["data"]}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/payouts":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Settle a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sweeps everything this seller is owed into a payout — one per currency,\nsince nothing is ever converted between them.\n\nThis is what the `manual` payout interval means: the scheduled sweep\nruns on each seller's own interval and skips anyone set to `manual`,\nleaving the operator to decide when. It also settles any other seller\nearly.\n\nIt records the settlement rather than sending money: the built-in\nprovider waits to be told the bank transfer went out, which is\n`PATCH /api/v3/admin/seller_payouts/{id}/complete`.\n\nAnswers `422` when there is nothing to settle — no payout account,\nnothing unsettled, or a balance below the seller's minimum.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller settled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}}},"required":["data"]}}}},"422":{"description":"nothing to settle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/seller_payouts/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller payout prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a payout paid","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the money reached the seller, which is what debits their\nbalance — a balance is earnings less *completed* settlements.\n\nThis is the step the built-in provider waits for: it files the\nsettlement when the payout is created and expects an operator to say\nthe bank transfer went out. A connected provider marks its own payouts\npaid when its webhook reports the money landed.\n\nSend the provider's own id for the transfer as `reference` when there\nis one. Completing a payout that is already complete answers `200`\nwithout recording it twice, so a redelivered webhook or a double click\nis safe.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"payout completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPayout"}}}},"404":{"description":"payout not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The provider's own id for the settlement, when one made it"}}}}}}}},"/api/v3/admin/stock_levels":{"get":{"summary":"List stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One row per variant per stock location, carrying every figure the\nInventory page shows: `count_on_hand` (on hand), `allocated_count`\n(committed to placed orders), `reserved_count` (held by checkouts in\nprogress), `available_count` (on hand minus committed) and\n`incoming_count` (on its way on an open purchase order or a transfer\nin transit). The variant and location are named flat on the row\n(`variant_name`, `variant_sku`, `stock_location_name`, `thumbnail_url`)\nso a list needs no expansion.\n\nFilter with `q[stock_location_id_eq]`, `q[variant_id_eq]` or\n`q[variant_sku_or_variant_product_name_cont]`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[stock_location_id_eq]","in":"query","required":false,"description":"Only levels at this stock location","schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"description":"Only levels for this variant","schema":{"type":"string"}},{"name":"q[variant_sku_or_variant_product_name_cont]","in":"query","required":false,"description":"Only levels whose variant SKU or product name contains this text","schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_transfers":{"get":{"summary":"List stock transfers","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock moving between two of the merchant's own warehouses.\n\nA transfer is a trip, not an instant. Units leave the source when the\ntransfer is marked in transit and land at the destination when somebody\ncounts them in — in between they are in flight, gone from one shelf and\nnot yet on the other.\n\nStatuses are `draft`, `ready_to_ship`, `in_transit`,\n`partially_received`, `received`, `over_received` and `canceled`. Each move between them\nis its own endpoint, not a `PATCH` that writes `status`.\n\nReceiving from a supplier is a purchase order, not a transfer with a\nmissing source.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand\n`items`, `source_location` and `destination_location`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ready_to_ship', 'in_transit', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Persists a draft — a packing list the merchant can still edit. Nothing\nmoves until the transfer is marked in transit.\n\nA draft may legitimately open empty and gain lines as the merchant\npacks. Both warehouses are required and must belong to the same store.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"warehouse belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"reference":{"type":"string","nullable":true,"description":"The merchant's own label for the trip"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_shipped":{"type":"integer"}},"required":["variant_id","quantity_shipped"]}},"metadata":{"type":"object","nullable":true}},"required":["source_location_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/stock_transfers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"stock transfer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts only. Past `draft` the transfer describes a box that physically\nexists, so it is cancelled rather than deleted — a 422 says so.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock transfer deleted"}}}},"/api/v3/admin/stock_transfers/{id}/mark_ready":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a transfer ready to ship","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Freezes the lines so the warehouse and the merchant are looking at the\nsame list. Nothing leaves the shelf yet.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is ready to ship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_in_transit":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Send a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment stock leaves the source warehouse: `shipped` movements are\nwritten against the source's levels and `shipped_at` is stamped. The\ndestination is deliberately untouched — the units are in flight.\n\nRefused with a 422 when the source does not hold enough. Pass\n`force: true` to record the departure anyway: a merchant forcing it has\ndecided the box left whatever the ledger claims.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is in transit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Ship even if it drives the source below zero"}}}}}}}},"/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts":{"parameters":[{"name":"stock_transfer_id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries counted in against a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the destination counted in, with what it accepted and refused.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Count a delivery in","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records one delivery the destination warehouse counted in, as a stock\nreceipt. Partial receipt is the normal case: ten left, eight arrived,\ntwo were crushed in transit. Quantities are this delivery's counts —\na second box adds to the first rather than restating it.\n\n`quantity_accepted` lands on the destination's shelf;\n`quantity_rejected` is refused and recorded with a `rejection_reason`\n(`damaged`, `wrong_item`, `expired` or `other`), never stocked. A\nrefused unit still arrived, so it counts toward the trip being over.\nOmit `items` to count in everything still outstanding, intact.\n\nThe transfer stays `partially_received` while units are still on the\nroad, settles in `received` once everything has arrived, and in\n`over_received` once more arrived than was shipped.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery counted in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"transfer has not shipped yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Take a transfer back to draft","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone.\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Close a transfer short","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received transfer whose missing units are not going\nto turn up. Nothing moves — they already left the source — and the\ntransfer settles in `received` with `closed_short_at` and the\n`reason` recorded, the outstanding count left on each line.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/stock_transfers/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Calls the trip off.\n\nCancelling a draft or a packed transfer costs nothing — no stock has\nmoved. Cancelling one already in transit needs `on_in_transit`, because\nthe units are physically gone from the source: either they come back\n(`restock`, as if the transfer had never shipped) or they are written\noff as lost (`write_off`). There is no default — guessing would either\ninvent stock or destroy it — so an in-flight cancellation without it is\nrefused with a 422.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"422":{"description":"in-transit cancellation needs a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"on_in_transit":{"type":"string","enum":["restock","write_off"],"description":"Required once the units have left the source"},"reason":{"type":"string","nullable":true,"description":"Recorded against the written-off lines"}}}}}}}},"/api/v3/admin/suppliers":{"get":{"summary":"List suppliers","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Who the merchant buys stock from. A supplier is an address-book entry\nwith a purchasing history — not a party that sells on the store, which\nis a seller.\n\nSuppliers belong to one store, and are soft-deleted so the purchase\norders that name them stay readable.\n\nFilter with Ransack predicates such as\n`q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_or_contact_name_or_email_cont]","in":"query","required":false,"description":"Search by name, contact name or email","schema":{"type":"string"}}],"responses":{"200":{"description":"suppliers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a supplier to this store's address book. The address is inline —\nstreet, city, state and country live on the supplier itself, the same\nshape a stock location uses.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"supplier created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"required":["name"]}}},"required":true}}},"/api/v3/admin/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Supplier ID","schema":{"type":"string"}}],"get":{"summary":"Get a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"404":{"description":"supplier not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}},"required":true}},"delete":{"summary":"Delete a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the supplier, so the purchase orders naming it stay\nreadable. Refused with a 422 while a purchase order still points at it.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"supplier deleted"}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject short names, e.g. [\"product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"label":{"type":"string","nullable":true}},"required":["id","type","label"],"x-typelizer":true},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by_label":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email","created_by_type","created_by_label"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string","enum":["explicit","automatic","base"]},"break_count":{"type":"number"},"amount":{"type":"string"},"display_amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","display_amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"display_amount":{"type":"string"},"amount":{"type":"string"}},"required":["min_quantity","display_amount","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","external_references","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Order routing strategy; null inherits the store setting. Built-in: rules. Extensions may register more."},"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_storefront_access","preferred_guest_checkout","created_at","updated_at","preferred_order_routing_strategy","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"},"pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"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","pre_tax_amount","included_tax_total","additional_tax_total","tax_total","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["open","approved","resolved","denied","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id","created_by_type"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["is_equal_to","is_not_equal_to","contains","does_not_contain"]},"type":{"type":"string","description":"Rule type. Built-in: tag, available_on, sale. Extensions may register more."}},"required":["id","value","match_policy","type"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["percentage","fixed"]},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string","enum":["percentage","fixed"]},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more."},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"object","nullable":true},"seller_ids":{"type":"object","nullable":true},"category_ids":{"type":"object","nullable":true},"sellers":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","product_ids","seller_ids","category_ids"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"]},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string","enum":["checkout","registration","account","admin","newsletter","anonymization","unknown","import","storefront"]},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"object"}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"resource_type":{"type":"string","description":"Shorthand of the resource the field attaches to, for example product, variant, order, customer or category. Discover the full list from the resource_types endpoint; extensions may register more."}},"required":["id","namespace","key","label","field_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at","resource_type"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"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","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DashboardCounter":{"type":"object","properties":{"key":{"type":"string","description":"Registered counter name. The dashboard translates it; built-in: orders_to_fulfill, payments_to_collect, open_returns, open_exchanges, open_claims, low_stock_items, out_of_stock_items."},"value":{"type":"number"},"link":{"type":"object","nullable":true,"description":"The list filter that shows exactly the rows counted, or null when no list can."},"nav":{"type":"string","nullable":true,"description":"Sidebar entry key this count badges, or null."}},"required":["key","value","link","nav"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["access","erasure"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more."},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"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"}},"fulfillment_provider":{"type":"string","description":"Fulfillment provider. Built-in: manual, digital, pickup, pickup_point. Provider gems register more (e.g. easy_post)."},"pickup_point_provider":{"type":"string","nullable":true,"description":"Pickup point network. None built in; provider gems register them."},"rate_provider":{"type":"string","nullable":true,"description":"Rate provider; null prices through the calculator. Built-in: internal, freight. Provider gems register more (e.g. easy_post)."},"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","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","fulfillment_provider","pickup_point_provider","rate_provider","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Profile kind. Built-in: shipping, digital. Extensions may register more."},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","unpriced","freight_summary","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","pre_transit","in_transit","out_for_delivery","available_for_pickup","delivered","return_to_sender","failure","unknown"]},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_type":{"type":"string","nullable":true,"description":"Digital asset provider; null is an uploaded file. Built-in: file. Extensions may register more."},"provider_name":{"type":"string","description":"Digital asset provider name. Built-in: File. Extensions may register more."},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_settings","created_at","updated_at","provider_type","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"expires_at":{"type":"string","nullable":true},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["promotion","manual"]},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"EmailTemplateDraft":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"lock_version":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"updated_by_id":{"type":"string","nullable":true},"updated_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"updated_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","lock_version","created_at","updated_at","updated_by_id","updated_by_type"],"x-typelizer":true},"EmailTemplatePreview":{"type":"object","properties":{"id":{"type":"string","nullable":true},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"email_key":{"type":"string"},"variables":{"type":"object"}},"required":["id","subject","html","text","email_key","variables"],"x-typelizer":true},"EmailTemplateRevision":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"created_at":{"type":"string"},"published_by_id":{"type":"string","nullable":true},"published_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"published_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","created_at","published_by_id","published_by_type"],"x-typelizer":true},"EmailTemplateSampleRecord":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"created_at":{"type":"string"}},"required":["id","label","created_at"],"x-typelizer":true},"EmailTemplate":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"language":{"type":"string"},"customized_languages":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["email","layout","partial"]},"customized":{"type":"boolean"},"published_at":{"type":"string","nullable":true},"default_subject":{"type":"string","nullable":true},"default_body":{"type":"string"},"published_language":{"type":"string","nullable":true},"default_changed":{"type":"boolean"},"base_subject":{"type":"string","nullable":true},"base_body":{"type":"string","nullable":true},"draft":{"allOf":[{"$ref":"#/components/schemas/EmailTemplateDraft"}],"nullable":true}},"required":["id","key","subject","body","language","customized_languages","kind","customized","published_at","default_subject","default_body","published_language","default_changed","base_subject","base_body","draft"],"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_tax_total":{"type":"string"},"new_tax_total":{"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_tax_total","new_tax_total","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","fulfilled","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"anyOf":[{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"]},{"type":"string"}],"description":"What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds."},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["on_hand","backordered","shipped","returned"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["unfulfilled","fulfilled","delivered","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","unpriced","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","labels","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["active","partially_redeemed","redeemed","canceled","expired"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true,"description":"Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more."},"status":{"anyOf":[{"type":"string","enum":["pending","mapping","completed_mapping","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","price_list_id","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none."},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"InvitationAcceptanceLink":{"type":"object","properties":{"id":{"type":"string"},"acceptance_url":{"type":"string"}},"required":["id","acceptance_url"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"price_list_name":{"type":"string","nullable":true},"catalog_id":{"type":"string","nullable":true},"catalog_name":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","price_list_id","price_list_name","catalog_id","catalog_name","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"country_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_provider":{"type":"string","nullable":true,"description":"Tax provider; null uses the store default. Built-in: internal. Provider gems register more."}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","country_isos","supported_locales","created_at","updated_at","tax_provider"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string","enum":["image","video","external_video"]},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string","enum":["dropdown","color_swatch","buttons"]},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"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","confirmation_delivered","store_owner_notification_delivered","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more."},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string","enum":["draft","placed","canceled"]},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"commission_amount_total":{"type":"string"},"display_commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"display_commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"display_commission_total":{"type":"string"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"approver_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"approver":{"$ref":"#/components/schemas/Actor"},"canceler_id":{"type":"string","nullable":true},"canceler_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"canceler":{"$ref":"#/components/schemas/Actor"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","commission_amount_total","display_commission_amount_total","commission_tax_total","display_commission_tax_total","commission_total","display_commission_total","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","approver_type","canceler_id","canceler_type","created_by_id","created_by_type","cancel_reason_id","cancel_reason_name","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","description":"Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe."},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"logo_url":{"type":"string","nullable":true},"docs_url":{"type":"string","nullable":true},"third_party":{"type":"boolean"}},"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","logo_url","docs_url","third_party"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["checkout","processing","pending","completed","failed","void","invalid"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"amount":{"type":"string"},"display_amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"PaymentSplit":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"authorized_amount":{"type":"string"},"display_authorized_amount":{"type":"string"},"captured_amount":{"type":"string"},"display_captured_amount":{"type":"string"},"refunded_amount":{"type":"string"},"display_refunded_amount":{"type":"string"},"claimed_amount":{"type":"string"},"display_claimed_amount":{"type":"string"},"net_captured_amount":{"type":"string"},"display_net_captured_amount":{"type":"string"},"refundable_amount":{"type":"string"},"display_refundable_amount":{"type":"string"},"payment_id":{"type":"string"},"payment_number":{"type":"string","nullable":true},"order_id":{"type":"string"},"order_number":{"type":"string","nullable":true}},"required":["id","currency","created_at","updated_at","authorized_amount","display_authorized_amount","captured_amount","display_captured_amount","refunded_amount","display_refunded_amount","claimed_amount","display_claimed_amount","net_captured_amount","display_net_captured_amount","refundable_amount","display_refundable_amount","payment_id","payment_number","order_id","order_number"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["draft","active","inactive","scheduled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"position":{"type":"number"},"match_policy":{"type":"string","enum":["all","any"]},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more."},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"min_quantity":{"type":"number"},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived","proposed","rejected"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","withdrawn"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"PurchaseOrderItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_ordered":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"unit_cost":{"type":"string"},"total_cost":{"type":"string"},"display_unit_cost":{"type":"string"},"display_total_cost":{"type":"string"},"purchase_order_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_ordered","quantity_received","quantity_rejected","quantity_over","outstanding","currency","created_at","updated_at","unit_cost","total_cost","display_unit_cost","display_total_cost","purchase_order_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"ordered_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expected_at":{"type":"string","nullable":true},"cancel_by":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_ordered_total":{"type":"number"},"editable":{"type":"boolean"},"subtotal":{"type":"string"},"display_subtotal":{"type":"string"},"supplier_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"supplier":{"$ref":"#/components/schemas/Supplier"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","currency","reference","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","ordered_at","received_at","closed_short_at","created_at","updated_at","expected_at","cancel_by","closed_short","quantity_ordered_total","editable","subtotal","display_subtotal","supplier_id","destination_location_id"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_amount":{"type":"string"},"refunder_id":{"type":"string","nullable":true},"refunder_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"refunder":{"$ref":"#/components/schemas/Actor"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at","tax_amount","refunder_id","refunder_type"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"refund_amount":{"type":"string"},"display_refund_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"},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","included_tax_total","additional_tax_total","tax_total","display_tax_total","refund_amount","display_refund_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","refunded","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"refund_tax_total":{"type":"string"},"display_refund_tax_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"refunded_total":{"type":"string"},"display_refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","refund_tax_total","display_refund_tax_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type","refunded_total","display_refunded_total","refundable_total","documents","labels","deliveries"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SavedReport":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"query":{"type":"object"},"seeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true}},"required":["id","name","description","query","seeded","created_at","updated_at","user_id","author_name"],"x-typelizer":true},"SellerBalance":{"type":"object","properties":{"currency":{"type":"string"},"settlement_currency":{"type":"string"},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"earned":{"type":"string"},"display_earned":{"type":"string"},"payable":{"type":"string"},"display_payable":{"type":"string"},"paid":{"type":"string"},"display_paid":{"type":"string"},"balance":{"type":"string"},"display_balance":{"type":"string"},"pending":{"type":"string"},"display_pending":{"type":"string"}},"required":["currency","settlement_currency","converted","seller_id","earned","display_earned","payable","display_payable","paid","display_paid","balance","display_balance","pending","display_pending"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"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"},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","status","currency","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count","provider"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string","enum":["complete","incomplete","pending","rejected"]},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted","rejected","waived"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["pending","invited","canceled","onboarding","ready_for_review","approved","rejected","suspended"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["earning","refund_reversal"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"settled_amount":{"type":"string","nullable":true},"settled_currency":{"type":"string","nullable":true},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","kind","status","currency","reference","metadata","created_at","updated_at","amount","display_amount","settled_amount","settled_currency","converted","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number","provider"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["purchased","uploaded"]},"status":{"anyOf":[{"type":"string","enum":["purchased","refund_requested","refunded"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string","enum":["fulfillment","return"]},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"reserved_count":{"type":"number"},"incoming_count":{"type":"number"},"purchasable_count":{"type":"number"},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_name":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","reserved_count","incoming_count","purchasable_count","variant_name","variant_sku","created_at","updated_at","stock_location_name","product_id","options_text","thumbnail_url","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"anyOf":[{"type":"string","enum":["warehouse","store","fulfillment_center"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true,"enum":["received","allocated","shipped","released","adjusted"]},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"stock_location_name":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true},"stock_receipt_id":{"type":"string","nullable":true},"purchase_order_id":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"return_number":{"type":"string","nullable":true},"exchange_number":{"type":"string","nullable":true},"stock_transfer_number":{"type":"string","nullable":true},"purchase_order_number":{"type":"string","nullable":true},"unit_cost":{"type":"string","nullable":true},"display_unit_cost":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","stock_location_id","stock_location_name","variant_id","variant_name","variant_sku","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id","stock_receipt_id","purchase_order_id","order_number","return_number","exchange_number","stock_transfer_number","purchase_order_number","unit_cost","display_unit_cost"],"x-typelizer":true},"StockReceiptItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"number"},"quantity_rejected":{"type":"number"},"rejection_reason":{"type":"string","nullable":true,"enum":["damaged","wrong_item","expired","other"]},"notes":{"type":"string","nullable":true},"line_type":{"type":"string","enum":["purchase_order_item","stock_transfer_item"]},"line_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_accepted","quantity_rejected","rejection_reason","notes","line_type","line_id","variant_id","product_id","variant_name","variant_sku","thumbnail_url"],"x-typelizer":true},"StockReceipt":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"quantity_accepted_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"received_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"receivable_type":{"type":"string","enum":["purchase_order","stock_transfer"]},"receivable_id":{"type":"string"},"received_by_id":{"type":"string","nullable":true},"received_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"received_by":{"$ref":"#/components/schemas/Actor"},"items_count":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockReceiptItem"}}},"required":["id","number","reference","notes","metadata","quantity_accepted_total","quantity_rejected_total","received_at","created_at","updated_at","receivable_type","receivable_id","received_by_id","received_by_type","items_count"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransferItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_shipped":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_transfer_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_shipped","quantity_received","quantity_rejected","quantity_over","outstanding","created_at","updated_at","stock_transfer_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"shipped_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_shipped_total":{"type":"number"},"editable":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","created_at","updated_at","source_location_id","destination_location_id","status","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","shipped_at","received_at","closed_short_at","deleted_at","closed_short","quantity_shipped_total","editable"],"x-typelizer":true},"StoreCreditEvent":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"authorization_code":{"type":"string","nullable":true},"display_action":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"store_credit_id":{"type":"string"},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true}},"required":["id","action","authorization_code","display_action","amount","display_amount","created_at","updated_at","store_credit_id","originator_type","originator_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount_authorized":{"type":"string"},"outstanding":{"type":"boolean"},"display_amount_authorized":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","amount_authorized","outstanding","display_amount_authorized","customer_id","created_by_id","originator_type","originator_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_email_accent_color":{"type":"string","nullable":true},"preferred_email_background_color":{"type":"string","nullable":true},"preferred_email_card_color":{"type":"string","nullable":true},"preferred_email_text_color":{"type":"string","nullable":true},"preferred_email_heading_color":{"type":"string","nullable":true},"preferred_email_font":{"type":"string","nullable":true,"enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_always_include_confirm_step":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_low_stock_threshold":{"type":"number"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_auto_approve_sellers":{"type":"boolean"},"preferred_auto_approve_seller_products":{"type":"boolean"},"preferred_send_seller_transactional_emails":{"type":"boolean"},"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"},"preferred_order_routing_strategy":{"type":"string","description":"Order routing strategy. Built-in: rules. Extensions may register more."},"preferred_payout_provider":{"type":"string","nullable":true,"description":"Payout provider; null uses the installation default. Built-in: system. Provider gems register more (e.g. stripe)."},"order_number_sequence_started":{"type":"boolean"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_default_commission_tax_rate":{"type":"number"},"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_email_accent_color","preferred_email_background_color","preferred_email_card_color","preferred_email_text_color","preferred_email_heading_color","preferred_email_font","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_always_include_confirm_step","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_low_stock_threshold","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_default_payouts_schedule_interval","preferred_auto_approve_sellers","preferred_auto_approve_seller_products","preferred_send_seller_transactional_emails","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","preferred_order_routing_strategy","preferred_payout_provider","order_number_sequence_started","preferred_default_minimum_payout_amount","preferred_default_commission_tax_rate","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"Supplier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"purchase_orders_count":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"can_be_deleted":{"type":"boolean"}},"required":["id","name","contact_name","email","phone","notes","address1","address2","city","state_name","state_code","country_code","postal_code","purchase_orders_count","metadata","created_at","updated_at","deleted_at","can_be_deleted"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","verified","expired","revoked"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more."},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true,"enum":["pending","verified","unverified","unavailable","unsupported"]},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true,"enum":["override","company","customer"]},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"credit":{"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},"return_line_item_id":{"type":"string","nullable":true},"claim_line_item_id":{"type":"string","nullable":true},"exchange_line_item_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"},"original_tax_line_id":{"type":"string","nullable":true}},"required":["id","label","included","credit","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","return_line_item_id","claim_line_item_id","exchange_line_item_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at","original_tax_line_id"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true,"enum":["unit","carton"]},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","weight_unit","dimensions_unit","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","preorderable","tax_category_id","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true},"WebhookEvent":{"type":"object","properties":{"name":{"type":"string"},"group":{"type":"string"},"credential_permission":{"type":"string","nullable":true},"credential":{"type":"boolean"},"deprecated":{"type":"boolean"},"replaced_by":{"type":"string","nullable":true}},"required":["name","group","credential_permission","credential","deprecated","replaced_by"],"x-typelizer":true}}}}
\ No newline at end of file
+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It is honoured only on the\ndashboard's origin and for an account that is staff of the store —\notherwise it is silently ignored and the link opens the dashboard's\nreset page. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Honoured only on the dashboard origin, for an account that is staff of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."},"sample_data":{"type":"boolean","description":"Load the demo catalog, customers and orders in the background once the admin account exists."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy shorthand (built-in: `rules`). `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 shorthand (built-in: `rules`). `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]=product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead."},"resource_type":{"type":"string","description":"Shorthand of the owning resource, e.g. `product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/email_templates":{"get":{"summary":"List email templates","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every email template merchants may edit: the emails customers\nreceive, the email layout and the shared partials. Each shows what\ncustomers receive now (the store's published version, else Spree's\ndefault) and any draft in progress. Staff emails are not editable.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default) for the version every language uses","schema":{"type":"string"}}],"responses":{"200":{"description":"email templates found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The template key with dots, e.g. `spree.order_mailer.confirm_email`","schema":{"type":"string"}}],"get":{"summary":"Get an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the template for one language: what customers receive now,\nSpree's default, and the draft with its `lock_version`. When Spree's\ndefault changed since the store's version started from it,\n`default_changed` is true and `base_body` holds the default it\nstarted from, to compare with `default_body`.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (`draft.updated_by`)","schema":{"type":"string"}}],"responses":{"200":{"description":"email template found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"404":{"description":"not an editable template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Revert an email template to Spree's default","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Goes back to Spree's default for one language and discards the draft.\nThe store's published versions are kept, so one can still be restored.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"email template reverted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/draft":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"put":{"summary":"Save an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Saves the draft, in any state; customers keep receiving the published\nversion until it is published. Send the `lock_version` the draft was\nloaded with: a save made from an older copy is refused with 409,\nnaming who saved last. The first save starts from what is published,\nelse Spree's default.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"draft saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"409":{"description":"saved by someone else since it was loaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"lock_version":{"type":"integer"},"rebase":{"type":"boolean","description":"Marks the draft as based on Spree's current default, after reviewing what changed in it"}}}}}}},"delete":{"summary":"Discard an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"draft discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/publication":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Publish an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Makes the draft what customers receive. The draft is first rendered\nwith sample data; one that does not render (for the layout or a\npartial: in any email using it) is refused with 422, listing each\nproblem with its email and line.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"draft published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"422":{"description":"the draft does not render","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer","description":"The draft's `lock_version` as reviewed; a draft saved since is refused with 409"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/preview":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Preview an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renders the template with sample data built from the store's latest\nmatching record, or the one `record_id` names, and returns the email\nwith the variables it was rendered with. An unsaved `subject` and\n`body` take the place of the current version. The layout and partials\nrender inside an email, `email_key` or the first one. `branding`\npreviews colors and a font before they are saved to the store.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"email template rendered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplatePreview"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string","description":"The record to build sample data from"},"email_key":{"type":"string","description":"For the layout or a partial, the email to show it in"},"branding":{"type":"object","description":"Unsaved colors and font to preview, named like the store's `preferred_email_*` settings without the prefix","properties":{"accent_color":{"type":"string"},"background_color":{"type":"string"},"card_color":{"type":"string"},"text_color":{"type":"string"},"heading_color":{"type":"string"},"font":{"type":"string","enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]}}}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/test_email":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Send a test email","tags":["Email Templates"],"security":[{"bearer_auth":[]}],"description":"Sends the template, rendered as the preview renders it, to the\nsigned-in admin, and never to another address: the sample data comes\nfrom a real customer's records. Takes the same body as the preview.\n","parameters":[{"name":"x-spree-api-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":"test email queued","content":{"application/json":{"schema":{"type":"object","properties":{"sent_to":{"type":"string"}},"required":["sent_to"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string"},"email_key":{"type":"string"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/sample_records":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List records to preview an email template with","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The store's five latest records the template can be previewed with,\nnewest first, to pass as `record_id` to the preview. For the layout\nand partials, those of the email `email_key` names. Empty for an\nemail that needs no record.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"email_key","in":"query","required":false,"description":"For the layout or a partial, the email to show it in","schema":{"type":"string"}}],"responses":{"200":{"description":"records found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List email template revisions","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every version of the template published in one language, newest\nfirst. Reverting to Spree's default keeps them.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","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 (`published_by`)","schema":{"type":"string"}}],"responses":{"200":{"description":"revisions found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions/{revision_id}/restoration":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Restore an email template revision","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Copies the revision into the draft, to be published like any change.\nSend the draft's `lock_version` when one is open, as when saving it.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"revision copied into the draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer"}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers","price_list_prices","purchase_orders"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange and claim replacements are moved only out of a named `source_fulfillment_id`, which is how a canceled replacement is sent again. 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"},"source_fulfillment_id":{"type":"string","description":"The only fulfillment of this order to move units from, its exchange and claim replacements included. Omit to take the customer's bought units from every unshipped fulfillment"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `customer_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"customer_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations","price_list_prices","purchase_orders"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"string"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\nOn a marketplace, an order holding several sellers' goods becomes one\norder per seller, and the response is the order group they belong to\nwith those orders nested inside it.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Shorthand of the tagged resource: `product`, `order` or `customer`","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 `rate` as a\ndecimal string (`\"0.19\"`) or `rate_percent` as a percentage string (`\"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\""},"rate":{"type":"string","description":"Rate as a decimal string, e.g. \"0.19\""},"rate_percent":{"type":"string","description":"Rate as a percentage string, 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"},"rate":{"type":"string"},"rate_percent":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores. Removing a role needs the same rights as granting it, and the store always keeps at least one admin.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{invitation_id}/acceptance_link":{"get":{"summary":"Get an invitation acceptance link","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"acceptance link found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationAcceptanceLink"}}}}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/store_credits":{"get":{"summary":"List store credits","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every store credit in the current store, across all customers.\nRead-only: issuing, editing and deleting a credit stays nested under\nthe customer that holds it.\n\n`meta.totals` carries the outstanding balance as one row per currency,\nsummed over the same filter this request used — so filtering by a\ncustomer answers that customer's balance and no filter answers the\nstore's liability.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[customer_id_eq]","in":"query","required":false,"description":"Filter by the customer holding the credit","schema":{"type":"string"}},{"name":"q[customer_email_cont]","in":"query","required":false,"description":"Filter by customer email (contains)","schema":{"type":"string"}},{"name":"q[currency_eq]","in":"query","required":false,"description":"Filter by currency","schema":{"type":"string"}},{"name":"q[memo_cont]","in":"query","required":false,"description":"Filter by the free-text reason (contains)","schema":{"type":"string"}},{"name":"q[outstanding]","in":"query","required":false,"description":"True for credits with money left, false for credits already spent","schema":{"type":"boolean"}},{"name":"q[from_gift_card]","in":"query","required":false,"description":"True for credits a gift card redemption created, false for every other origin","schema":{"type":"boolean"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a store credit","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredit"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{store_credit_id}/events":{"parameters":[{"name":"store_credit_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List a store credit's ledger","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every movement of the credit's balance, newest first: allocated when\nissued, authorized when a checkout starts against it, captured when\nthat order is paid, and voided or credited back if it is cancelled.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"events found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/webhook_events":{"get":{"summary":"List webhook events","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every event a webhook endpoint can subscribe to, including those installed extensions declare. Credential events reach only endpoints that name them, and subscribing to one needs the permission listed; deprecated events name their replacement.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"events returned","content":{"application/json":{}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit — send the value back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (`box`, `envelope`, `carton`, `pallet`, `container`)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/purchase_orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock bought from suppliers. A purchase order carries what a purchase\nhas and a stock transfer does not: a supplier, a unit cost per line and\nan expected arrival date.\n\nOrdered units never count toward availability. Nothing here changes\n`count_on_hand` until `receive` runs, because a merchant who has\nordered stock does not have it.\n\nStatuses are `draft`, `ordered`, `partially_received`, `received`, `over_received` and\n`canceled`. Each move between them is its own endpoint, not a `PATCH`\nthat writes `status`.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,\n`supplier` and `destination_location`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ordered', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase orders found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts an order. Nothing is on order and nothing touches availability\nuntil the order is marked as ordered and then received.\n\n`currency` defaults to the store's; set it for a foreign-currency\norder. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the\nsupplier promised means the same day in every timezone.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"purchase order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"supplier belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string"},"destination_location_id":{"type":"string"},"currency":{"type":"string","nullable":true},"expected_at":{"type":"string","format":"date","nullable":true},"reference":{"type":"string","nullable":true,"description":"The supplier's own order number"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_ordered":{"type":"integer"},"unit_cost":{"type":"string"}},"required":["variant_id","quantity_ordered"]}},"metadata":{"type":"object","nullable":true}},"required":["supplier_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/purchase_orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"Get a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"purchase order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_ordered":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Place the order with the supplier","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is\nstamped. Availability is still untouched — ordered stock is not stock\nthe merchant has.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts":{"parameters":[{"name":"purchase_order_id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries booked against an order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused.\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Book in a delivery","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment purchased goods first count toward availability. Records\none delivery as a stock receipt: what this delivery brought, per line,\nnot a running total — a second delivery adds to the first.\n\n`quantity_accepted` reaches the shelf; `quantity_rejected` is refused\nand recorded with a `rejection_reason` (`damaged`, `wrong_item`,\n`expired` or `other`), never stocked. Omit `items` to book in\neverything still outstanding, intact.\n\nEach `received` stock movement carries the line's `unit_cost` and\nnames the receipt, so a delivery can be reconciled against the ledger.\n\nThe order stays `partially_received` while any line is still owed,\nsettles in `received` once every line has what it expected, and in\n`over_received` once any line has more.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery booked in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"order has not been placed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true,"description":"The supplier's delivery note or packing slip"},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Take an order back to draft","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared.\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Close an order short","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received order whose balance the supplier will not\ndeliver. Nothing moves: what arrived stays on the shelf, the\noutstanding count stays on each line, and the order settles in\n`received` with `closed_short_at` and the `reason` recorded.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/purchase_orders/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Closes what is still outstanding. Nothing is unwound: a purchase order\nnever moved stock until units were received, and units already received\nstay on the shelf because the merchant has them.\n\nA `reason` is appended to the order's notes.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{seller_id}/balances":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's balances","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Where one seller stands with the marketplace, one row per currency:\nwhat they have earned (completed transfers, refund reversals\nincluded), what has been paid to them, what is still owed, and\nearnings the payout provider has not yet confirmed.\n\nComputed from the ledger rather than stored, so the rows carry no id.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"balances listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerBalance"}}},"required":["data"]}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/payouts":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Settle a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sweeps everything this seller is owed into a payout — one per currency,\nsince nothing is ever converted between them.\n\nThis is what the `manual` payout interval means: the scheduled sweep\nruns on each seller's own interval and skips anyone set to `manual`,\nleaving the operator to decide when. It also settles any other seller\nearly.\n\nIt records the settlement rather than sending money: the built-in\nprovider waits to be told the bank transfer went out, which is\n`PATCH /api/v3/admin/seller_payouts/{id}/complete`.\n\nAnswers `422` when there is nothing to settle — no payout account,\nnothing unsettled, or a balance below the seller's minimum.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller settled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}}},"required":["data"]}}}},"422":{"description":"nothing to settle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/seller_payouts/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller payout prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a payout paid","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the money reached the seller, which is what debits their\nbalance — a balance is earnings less *completed* settlements.\n\nThis is the step the built-in provider waits for: it files the\nsettlement when the payout is created and expects an operator to say\nthe bank transfer went out. A connected provider marks its own payouts\npaid when its webhook reports the money landed.\n\nSend the provider's own id for the transfer as `reference` when there\nis one. Completing a payout that is already complete answers `200`\nwithout recording it twice, so a redelivered webhook or a double click\nis safe.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"payout completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPayout"}}}},"404":{"description":"payout not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The provider's own id for the settlement, when one made it"}}}}}}}},"/api/v3/admin/stock_levels":{"get":{"summary":"List stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One row per variant per stock location, carrying every figure the\nInventory page shows: `count_on_hand` (on hand), `allocated_count`\n(committed to placed orders), `reserved_count` (held by checkouts in\nprogress), `available_count` (on hand minus committed) and\n`incoming_count` (on its way on an open purchase order or a transfer\nin transit). The variant and location are named flat on the row\n(`variant_name`, `variant_sku`, `stock_location_name`, `thumbnail_url`)\nso a list needs no expansion.\n\nFilter with `q[stock_location_id_eq]`, `q[variant_id_eq]` or\n`q[variant_sku_or_variant_product_name_cont]`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[stock_location_id_eq]","in":"query","required":false,"description":"Only levels at this stock location","schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"description":"Only levels for this variant","schema":{"type":"string"}},{"name":"q[variant_sku_or_variant_product_name_cont]","in":"query","required":false,"description":"Only levels whose variant SKU or product name contains this text","schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_transfers":{"get":{"summary":"List stock transfers","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock moving between two of the merchant's own warehouses.\n\nA transfer is a trip, not an instant. Units leave the source when the\ntransfer is marked in transit and land at the destination when somebody\ncounts them in — in between they are in flight, gone from one shelf and\nnot yet on the other.\n\nStatuses are `draft`, `ready_to_ship`, `in_transit`,\n`partially_received`, `received`, `over_received` and `canceled`. Each move between them\nis its own endpoint, not a `PATCH` that writes `status`.\n\nReceiving from a supplier is a purchase order, not a transfer with a\nmissing source.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand\n`items`, `source_location` and `destination_location`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ready_to_ship', 'in_transit', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Persists a draft — a packing list the merchant can still edit. Nothing\nmoves until the transfer is marked in transit.\n\nA draft may legitimately open empty and gain lines as the merchant\npacks. Both warehouses are required and must belong to the same store.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"warehouse belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"reference":{"type":"string","nullable":true,"description":"The merchant's own label for the trip"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_shipped":{"type":"integer"}},"required":["variant_id","quantity_shipped"]}},"metadata":{"type":"object","nullable":true}},"required":["source_location_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/stock_transfers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"stock transfer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts only. Past `draft` the transfer describes a box that physically\nexists, so it is cancelled rather than deleted — a 422 says so.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock transfer deleted"}}}},"/api/v3/admin/stock_transfers/{id}/mark_ready":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a transfer ready to ship","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Freezes the lines so the warehouse and the merchant are looking at the\nsame list. Nothing leaves the shelf yet.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is ready to ship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_in_transit":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Send a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment stock leaves the source warehouse: `shipped` movements are\nwritten against the source's levels and `shipped_at` is stamped. The\ndestination is deliberately untouched — the units are in flight.\n\nRefused with a 422 when the source does not hold enough. Pass\n`force: true` to record the departure anyway: a merchant forcing it has\ndecided the box left whatever the ledger claims.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is in transit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Ship even if it drives the source below zero"}}}}}}}},"/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts":{"parameters":[{"name":"stock_transfer_id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries counted in against a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the destination counted in, with what it accepted and refused.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Count a delivery in","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records one delivery the destination warehouse counted in, as a stock\nreceipt. Partial receipt is the normal case: ten left, eight arrived,\ntwo were crushed in transit. Quantities are this delivery's counts —\na second box adds to the first rather than restating it.\n\n`quantity_accepted` lands on the destination's shelf;\n`quantity_rejected` is refused and recorded with a `rejection_reason`\n(`damaged`, `wrong_item`, `expired` or `other`), never stocked. A\nrefused unit still arrived, so it counts toward the trip being over.\nOmit `items` to count in everything still outstanding, intact.\n\nThe transfer stays `partially_received` while units are still on the\nroad, settles in `received` once everything has arrived, and in\n`over_received` once more arrived than was shipped.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery counted in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"transfer has not shipped yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Take a transfer back to draft","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone.\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Close a transfer short","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received transfer whose missing units are not going\nto turn up. Nothing moves — they already left the source — and the\ntransfer settles in `received` with `closed_short_at` and the\n`reason` recorded, the outstanding count left on each line.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/stock_transfers/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Calls the trip off.\n\nCancelling a draft or a packed transfer costs nothing — no stock has\nmoved. Cancelling one already in transit needs `on_in_transit`, because\nthe units are physically gone from the source: either they come back\n(`restock`, as if the transfer had never shipped) or they are written\noff as lost (`write_off`). There is no default — guessing would either\ninvent stock or destroy it — so an in-flight cancellation without it is\nrefused with a 422.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"422":{"description":"in-transit cancellation needs a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"on_in_transit":{"type":"string","enum":["restock","write_off"],"description":"Required once the units have left the source"},"reason":{"type":"string","nullable":true,"description":"Recorded against the written-off lines"}}}}}}}},"/api/v3/admin/suppliers":{"get":{"summary":"List suppliers","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Who the merchant buys stock from. A supplier is an address-book entry\nwith a purchasing history — not a party that sells on the store, which\nis a seller.\n\nSuppliers belong to one store, and are soft-deleted so the purchase\norders that name them stay readable.\n\nFilter with Ransack predicates such as\n`q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_or_contact_name_or_email_cont]","in":"query","required":false,"description":"Search by name, contact name or email","schema":{"type":"string"}}],"responses":{"200":{"description":"suppliers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a supplier to this store's address book. The address is inline —\nstreet, city, state and country live on the supplier itself, the same\nshape a stock location uses.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"supplier created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"required":["name"]}}},"required":true}}},"/api/v3/admin/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Supplier ID","schema":{"type":"string"}}],"get":{"summary":"Get a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"404":{"description":"supplier not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}},"required":true}},"delete":{"summary":"Delete a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the supplier, so the purchase orders naming it stay\nreadable. Refused with a 422 while a purchase order still points at it.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"supplier deleted"}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject short names, e.g. [\"product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"label":{"type":"string","nullable":true}},"required":["id","type","label"],"x-typelizer":true},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by_label":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email","created_by_type","created_by_label"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"order_minimum":{"type":"string","nullable":true},"order_minimum_shortfall":{"type":"string","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string","enum":["explicit","automatic","base"]},"break_count":{"type":"number"},"amount":{"type":"string"},"display_amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","display_amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"display_amount":{"type":"string"},"amount":{"type":"string"}},"required":["min_quantity","display_amount","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","external_references","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Order routing strategy; null inherits the store setting. Built-in: rules. Extensions may register more."},"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_storefront_access","preferred_guest_checkout","created_at","updated_at","preferred_order_routing_strategy","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"},"pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"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","pre_tax_amount","included_tax_total","additional_tax_total","tax_total","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["open","approved","resolved","denied","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id","created_by_type"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["is_equal_to","is_not_equal_to","contains","does_not_contain"]},"type":{"type":"string","description":"Rule type. Built-in: tag, available_on, sale. Extensions may register more."}},"required":["id","value","match_policy","type"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["percentage","fixed"]},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string","enum":["percentage","fixed"]},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more."},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"object","nullable":true},"seller_ids":{"type":"object","nullable":true},"category_ids":{"type":"object","nullable":true},"sellers":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","product_ids","seller_ids","category_ids"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"]},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string","enum":["checkout","registration","account","admin","newsletter","anonymization","unknown","import","storefront"]},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"object"}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"resource_type":{"type":"string","description":"Shorthand of the resource the field attaches to, for example product, variant, order, customer or category. Discover the full list from the resource_types endpoint; extensions may register more."}},"required":["id","namespace","key","label","field_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at","resource_type"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"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","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DashboardCounter":{"type":"object","properties":{"key":{"type":"string","description":"Registered counter name. The dashboard translates it; built-in: orders_to_fulfill, payments_to_collect, open_returns, open_exchanges, open_claims, low_stock_items, out_of_stock_items."},"value":{"type":"number"},"link":{"type":"object","nullable":true,"description":"The list filter that shows exactly the rows counted, or null when no list can."},"nav":{"type":"string","nullable":true,"description":"Sidebar entry key this count badges, or null."}},"required":["key","value","link","nav"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["access","erasure"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more."},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"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"}},"fulfillment_provider":{"type":"string","description":"Fulfillment provider. Built-in: manual, digital, pickup, pickup_point. Provider gems register more (e.g. easy_post)."},"pickup_point_provider":{"type":"string","nullable":true,"description":"Pickup point network. None built in; provider gems register them."},"rate_provider":{"type":"string","nullable":true,"description":"Rate provider; null prices through the calculator. Built-in: internal, freight. Provider gems register more (e.g. easy_post)."},"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","storefront_visible","tracking_url","available_to_sellers","created_at","updated_at","deleted_at","markup_flat","markup_percent","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","fulfillment_provider","pickup_point_provider","rate_provider","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Profile kind. Built-in: shipping, digital. Extensions may register more."},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","unpriced","freight_summary","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","pre_transit","in_transit","out_for_delivery","available_for_pickup","delivered","return_to_sender","failure","unknown"]},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_type":{"type":"string","nullable":true,"description":"Digital asset provider; null is an uploaded file. Built-in: file. Extensions may register more."},"provider_name":{"type":"string","description":"Digital asset provider name. Built-in: File. Extensions may register more."},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_settings","created_at","updated_at","provider_type","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"expires_at":{"type":"string","nullable":true},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["promotion","manual"]},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"EmailTemplateDraft":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"lock_version":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"updated_by_id":{"type":"string","nullable":true},"updated_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"updated_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","lock_version","created_at","updated_at","updated_by_id","updated_by_type"],"x-typelizer":true},"EmailTemplatePreview":{"type":"object","properties":{"id":{"type":"string","nullable":true},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"email_key":{"type":"string"},"variables":{"type":"object"}},"required":["id","subject","html","text","email_key","variables"],"x-typelizer":true},"EmailTemplateRevision":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"created_at":{"type":"string"},"published_by_id":{"type":"string","nullable":true},"published_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"published_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","created_at","published_by_id","published_by_type"],"x-typelizer":true},"EmailTemplateSampleRecord":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"created_at":{"type":"string"}},"required":["id","label","created_at"],"x-typelizer":true},"EmailTemplate":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"language":{"type":"string"},"customized_languages":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["email","layout","partial"]},"customized":{"type":"boolean"},"published_at":{"type":"string","nullable":true},"default_subject":{"type":"string","nullable":true},"default_body":{"type":"string"},"published_language":{"type":"string","nullable":true},"default_changed":{"type":"boolean"},"base_subject":{"type":"string","nullable":true},"base_body":{"type":"string","nullable":true},"draft":{"allOf":[{"$ref":"#/components/schemas/EmailTemplateDraft"}],"nullable":true}},"required":["id","key","subject","body","language","customized_languages","kind","customized","published_at","default_subject","default_body","published_language","default_changed","base_subject","base_body","draft"],"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_tax_total":{"type":"string"},"new_tax_total":{"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_tax_total","new_tax_total","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","fulfilled","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"anyOf":[{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"]},{"type":"string"}],"description":"What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds."},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["on_hand","backordered","shipped","returned"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["unfulfilled","fulfilled","delivered","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","unpriced","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","created_at","updated_at","adjustment_total","pre_tax_amount","order_id","stock_location_id","documents","labels","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["active","partially_redeemed","redeemed","canceled","expired"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true,"description":"Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more."},"status":{"anyOf":[{"type":"string","enum":["pending","mapping","completed_mapping","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","price_list_id","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none."},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"InvitationAcceptanceLink":{"type":"object","properties":{"id":{"type":"string"},"acceptance_url":{"type":"string"}},"required":["id","acceptance_url"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"price_list_name":{"type":"string","nullable":true},"catalog_id":{"type":"string","nullable":true},"catalog_name":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","price_list_id","price_list_name","catalog_id","catalog_name","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"country_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_provider":{"type":"string","nullable":true,"description":"Tax provider; null uses the store default. Built-in: internal. Provider gems register more."}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","country_isos","supported_locales","created_at","updated_at","tax_provider"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string","enum":["image","video","external_video"]},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string","enum":["dropdown","color_swatch","buttons"]},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"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","confirmation_delivered","store_owner_notification_delivered","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more."},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string","enum":["draft","placed","canceled"]},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"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"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"commission_amount_total":{"type":"string"},"display_commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"display_commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"display_commission_total":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"approver_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"approver":{"$ref":"#/components/schemas/Actor"},"canceler_id":{"type":"string","nullable":true},"canceler_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"canceler":{"$ref":"#/components/schemas/Actor"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","payment_total","display_payment_total","commission_amount_total","display_commission_amount_total","commission_tax_total","display_commission_tax_total","commission_total","display_commission_total","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","approver_type","canceler_id","canceler_type","created_by_id","created_by_type","cancel_reason_id","cancel_reason_name","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","description":"Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe."},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"logo_url":{"type":"string","nullable":true},"docs_url":{"type":"string","nullable":true},"third_party":{"type":"boolean"}},"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","logo_url","docs_url","third_party"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["checkout","processing","pending","completed","failed","void","invalid"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"amount":{"type":"string"},"display_amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"PaymentSplit":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"authorized_amount":{"type":"string"},"display_authorized_amount":{"type":"string"},"captured_amount":{"type":"string"},"display_captured_amount":{"type":"string"},"refunded_amount":{"type":"string"},"display_refunded_amount":{"type":"string"},"claimed_amount":{"type":"string"},"display_claimed_amount":{"type":"string"},"net_captured_amount":{"type":"string"},"display_net_captured_amount":{"type":"string"},"refundable_amount":{"type":"string"},"display_refundable_amount":{"type":"string"},"payment_id":{"type":"string"},"payment_number":{"type":"string","nullable":true},"order_id":{"type":"string"},"order_number":{"type":"string","nullable":true}},"required":["id","currency","created_at","updated_at","authorized_amount","display_authorized_amount","captured_amount","display_captured_amount","refunded_amount","display_refunded_amount","claimed_amount","display_claimed_amount","net_captured_amount","display_net_captured_amount","refundable_amount","display_refundable_amount","payment_id","payment_number","order_id","order_number"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"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","currency","amount","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["draft","active","inactive","scheduled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"position":{"type":"number"},"match_policy":{"type":"string","enum":["all","any"]},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more."},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"min_quantity":{"type":"number"},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","currency","amount","compare_at_amount","display_amount","display_compare_at_amount","price_list_id","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived","proposed","rejected"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","withdrawn"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"PurchaseOrderItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_ordered":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"unit_cost":{"type":"string"},"display_unit_cost":{"type":"string"},"total_cost":{"type":"string"},"display_total_cost":{"type":"string"},"purchase_order_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_ordered","quantity_received","quantity_rejected","quantity_over","outstanding","currency","created_at","updated_at","unit_cost","display_unit_cost","total_cost","display_total_cost","purchase_order_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"ordered_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expected_at":{"type":"string","nullable":true},"cancel_by":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_ordered_total":{"type":"number"},"editable":{"type":"boolean"},"subtotal":{"type":"string"},"display_subtotal":{"type":"string"},"supplier_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"supplier":{"$ref":"#/components/schemas/Supplier"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","currency","reference","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","ordered_at","received_at","closed_short_at","created_at","updated_at","expected_at","cancel_by","closed_short","quantity_ordered_total","editable","subtotal","display_subtotal","supplier_id","destination_location_id"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_amount":{"type":"string"},"refunder_id":{"type":"string","nullable":true},"refunder_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"refunder":{"$ref":"#/components/schemas/Actor"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at","tax_amount","refunder_id","refunder_type"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"refund_amount":{"type":"string"},"display_refund_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"},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","included_tax_total","additional_tax_total","tax_total","display_tax_total","refund_amount","display_refund_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","refunded","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"refund_tax_total":{"type":"string"},"display_refund_tax_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"refunded_total":{"type":"string"},"display_refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","refund_tax_total","display_refund_tax_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type","refunded_total","display_refunded_total","refundable_total","documents","labels","deliveries"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SavedReport":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"query":{"type":"object"},"seeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true}},"required":["id","name","description","query","seeded","created_at","updated_at","user_id","author_name"],"x-typelizer":true},"SellerBalance":{"type":"object","properties":{"currency":{"type":"string"},"settlement_currency":{"type":"string"},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"earned":{"type":"string"},"display_earned":{"type":"string"},"payable":{"type":"string"},"display_payable":{"type":"string"},"paid":{"type":"string"},"display_paid":{"type":"string"},"balance":{"type":"string"},"display_balance":{"type":"string"},"pending":{"type":"string"},"display_pending":{"type":"string"}},"required":["currency","settlement_currency","converted","seller_id","earned","display_earned","payable","display_payable","paid","display_paid","balance","display_balance","pending","display_pending"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"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"},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","status","currency","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count","provider"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string","enum":["complete","incomplete","pending","rejected"]},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted","rejected","waived"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["pending","invited","canceled","onboarding","ready_for_review","approved","rejected","suspended"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["earning","refund_reversal"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"settled_amount":{"type":"string","nullable":true},"settled_currency":{"type":"string","nullable":true},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","kind","status","currency","reference","metadata","created_at","updated_at","amount","display_amount","settled_amount","settled_currency","converted","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number","provider"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["purchased","uploaded"]},"status":{"anyOf":[{"type":"string","enum":["purchased","refund_requested","refunded"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string","enum":["fulfillment","return"]},"cost":{"type":"string"},"display_cost":{"type":"string","nullable":true},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"reserved_count":{"type":"number"},"incoming_count":{"type":"number"},"purchasable_count":{"type":"number"},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_name":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","reserved_count","incoming_count","purchasable_count","variant_name","variant_sku","created_at","updated_at","stock_location_name","product_id","options_text","thumbnail_url","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"anyOf":[{"type":"string","enum":["warehouse","store","fulfillment_center"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true,"enum":["received","allocated","shipped","released","adjusted"]},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"stock_location_name":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true},"stock_receipt_id":{"type":"string","nullable":true},"purchase_order_id":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"return_number":{"type":"string","nullable":true},"exchange_number":{"type":"string","nullable":true},"stock_transfer_number":{"type":"string","nullable":true},"purchase_order_number":{"type":"string","nullable":true},"unit_cost":{"type":"string","nullable":true},"display_unit_cost":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","stock_location_id","stock_location_name","variant_id","variant_name","variant_sku","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id","stock_receipt_id","purchase_order_id","order_number","return_number","exchange_number","stock_transfer_number","purchase_order_number","unit_cost","display_unit_cost"],"x-typelizer":true},"StockReceiptItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"number"},"quantity_rejected":{"type":"number"},"rejection_reason":{"type":"string","nullable":true,"enum":["damaged","wrong_item","expired","other"]},"notes":{"type":"string","nullable":true},"line_type":{"type":"string","enum":["purchase_order_item","stock_transfer_item"]},"line_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_accepted","quantity_rejected","rejection_reason","notes","line_type","line_id","variant_id","product_id","variant_name","variant_sku","thumbnail_url"],"x-typelizer":true},"StockReceipt":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"quantity_accepted_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"received_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"receivable_type":{"type":"string","enum":["purchase_order","stock_transfer"]},"receivable_id":{"type":"string"},"received_by_id":{"type":"string","nullable":true},"received_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"received_by":{"$ref":"#/components/schemas/Actor"},"items_count":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockReceiptItem"}}},"required":["id","number","reference","notes","metadata","quantity_accepted_total","quantity_rejected_total","received_at","created_at","updated_at","receivable_type","receivable_id","received_by_id","received_by_type","items_count"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransferItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_shipped":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_transfer_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_shipped","quantity_received","quantity_rejected","quantity_over","outstanding","created_at","updated_at","stock_transfer_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"shipped_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_shipped_total":{"type":"number"},"editable":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","created_at","updated_at","source_location_id","destination_location_id","status","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","shipped_at","received_at","closed_short_at","deleted_at","closed_short","quantity_shipped_total","editable"],"x-typelizer":true},"StoreCreditEvent":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"authorization_code":{"type":"string","nullable":true},"display_action":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"store_credit_id":{"type":"string"},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true}},"required":["id","action","authorization_code","display_action","amount","display_amount","created_at","updated_at","store_credit_id","originator_type","originator_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount_authorized":{"type":"string"},"outstanding":{"type":"boolean"},"display_amount_authorized":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","amount_authorized","outstanding","display_amount_authorized","customer_id","created_by_id","originator_type","originator_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_email_accent_color":{"type":"string","nullable":true},"preferred_email_background_color":{"type":"string","nullable":true},"preferred_email_card_color":{"type":"string","nullable":true},"preferred_email_text_color":{"type":"string","nullable":true},"preferred_email_heading_color":{"type":"string","nullable":true},"preferred_email_font":{"type":"string","nullable":true,"enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_always_include_confirm_step":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_low_stock_threshold":{"type":"number"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_auto_approve_sellers":{"type":"boolean"},"preferred_auto_approve_seller_products":{"type":"boolean"},"preferred_send_seller_transactional_emails":{"type":"boolean"},"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"},"preferred_order_routing_strategy":{"type":"string","description":"Order routing strategy. Built-in: rules. Extensions may register more."},"preferred_payout_provider":{"type":"string","nullable":true,"description":"Payout provider; null uses the installation default. Built-in: system. Provider gems register more (e.g. stripe)."},"order_number_sequence_started":{"type":"boolean"},"preferred_default_minimum_payout_amount":{"type":"string","nullable":true},"preferred_default_commission_tax_rate":{"type":"string","nullable":true},"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_email_accent_color","preferred_email_background_color","preferred_email_card_color","preferred_email_text_color","preferred_email_heading_color","preferred_email_font","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_always_include_confirm_step","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_low_stock_threshold","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_default_payouts_schedule_interval","preferred_auto_approve_sellers","preferred_auto_approve_seller_products","preferred_send_seller_transactional_emails","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","preferred_order_routing_strategy","preferred_payout_provider","order_number_sequence_started","preferred_default_minimum_payout_amount","preferred_default_commission_tax_rate","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"Supplier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"purchase_orders_count":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"can_be_deleted":{"type":"boolean"}},"required":["id","name","contact_name","email","phone","notes","address1","address2","city","state_name","state_code","country_code","postal_code","purchase_orders_count","metadata","created_at","updated_at","deleted_at","can_be_deleted"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","verified","expired","revoked"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more."},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true,"enum":["pending","verified","unverified","unavailable","unsupported"]},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true,"enum":["override","company","customer"]},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"credit":{"type":"boolean"},"rate":{"type":"string","nullable":true},"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},"return_line_item_id":{"type":"string","nullable":true},"claim_line_item_id":{"type":"string","nullable":true},"exchange_line_item_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"},"original_tax_line_id":{"type":"string","nullable":true}},"required":["id","label","included","credit","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","return_line_item_id","claim_line_item_id","exchange_line_item_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at","original_tax_line_id"],"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},"rate":{"type":"string","nullable":true},"rate_percent":{"type":"string","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","rate","rate_percent","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true,"enum":["unit","carton"]},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","weight_unit","dimensions_unit","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","cost_price","preorderable","tax_category_id","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true},"WebhookEvent":{"type":"object","properties":{"name":{"type":"string"},"group":{"type":"string"},"credential_permission":{"type":"string","nullable":true},"credential":{"type":"boolean"},"deprecated":{"type":"boolean"},"replaced_by":{"type":"string","nullable":true}},"required":["name","group","credential_permission","credential","deprecated","replaced_by"],"x-typelizer":true}}}}
\ No newline at end of file
diff --git a/packages/dashboard-core/src/components/preferences-form.tsx b/packages/dashboard-core/src/components/preferences-form.tsx
index 250eaa0953..cc5de7c283 100644
--- a/packages/dashboard-core/src/components/preferences-form.tsx
+++ b/packages/dashboard-core/src/components/preferences-form.tsx
@@ -1,4 +1,8 @@
-import type { PreferenceField as PreferenceFieldDef } from '@spree/admin-sdk'
+import {
+ compareMoney,
+ isDecimalString,
+ type PreferenceField as PreferenceFieldDef,
+} from '@spree/admin-sdk'
import {
Button,
Field,
@@ -40,7 +44,12 @@ export function defaultPreferences(
for (const field of schema) {
if (field.type === 'password') continue
if (field.default !== null && field.default !== undefined) {
- out[field.key] = field.default
+ // A decimal default declared as a Ruby integer arrives as a JSON number,
+ // and the API refuses money sent back that way.
+ out[field.key] =
+ field.type === 'decimal' && typeof field.default === 'number'
+ ? String(field.default)
+ : field.default
continue
}
const ctx = contextDefaults[field.key]
@@ -241,7 +250,10 @@ export function PreferenceField({
onChange={(e) => {
const raw = e.target.value
if (raw === '') return onChange(null)
- const parsed = field.type === 'integer' ? parseInt(raw, 10) : parseFloat(raw)
+ // A decimal (an amount, a percentage) stays the canonical string
+ // the number input yields; the API refuses money sent as a JSON number.
+ if (field.type === 'decimal') return onChange(isDecimalString(raw) ? raw : null)
+ const parsed = parseInt(raw, 10)
onChange(Number.isNaN(parsed) ? null : parsed)
}}
/>
@@ -516,5 +528,9 @@ function parseTiers(value: unknown, idPrefix: string): TierRowState[] {
threshold: threshold === null || threshold === undefined ? '' : String(threshold),
value: v === null || v === undefined ? '' : String(v),
}))
- .sort((a, b) => Number(a.threshold) - Number(b.threshold))
+ .sort((a, b) =>
+ isDecimalString(a.threshold) && isDecimalString(b.threshold)
+ ? compareMoney(a.threshold, b.threshold)
+ : 0,
+ )
}
diff --git a/packages/dashboard-core/src/index.ts b/packages/dashboard-core/src/index.ts
index c2b5219cf1..c28197ede7 100644
--- a/packages/dashboard-core/src/index.ts
+++ b/packages/dashboard-core/src/index.ts
@@ -99,11 +99,13 @@ export * from './lib/fulfillment-items'
export * from './lib/i18n'
export * from './lib/import-types'
export * from './lib/label-upload-form'
+export * from './lib/money'
export * from './lib/nav-registry'
export * from './lib/permissions'
export * from './lib/progress'
export * from './lib/query-client'
export * from './lib/query-keys'
+export * from './lib/return-refunds'
export * from './lib/route-registry'
export * from './lib/search-registry'
export * from './lib/settings-nav-registry'
diff --git a/packages/dashboard-core/src/lib/formatters.ts b/packages/dashboard-core/src/lib/formatters.ts
index 03b924129a..3556b5b68b 100644
--- a/packages/dashboard-core/src/lib/formatters.ts
+++ b/packages/dashboard-core/src/lib/formatters.ts
@@ -7,6 +7,18 @@ export function formatPrice(price: Pick<Price, 'amount' | 'currency' | 'display_
return price.display_amount ?? `${price.currency} ${price.amount}`
}
+/**
+ * Formats a decimal-string amount ("1234.50") in a currency and locale. The
+ * string goes to `Intl` as it is — `Intl` reads numeric strings exactly — so
+ * the amount never passes through a JavaScript number.
+ */
+export function formatMoney(amount: string, currency: string, locale?: string): string {
+ // ES2023's Intl typings accept a numeric string; this package targets ES2022.
+ return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(
+ amount as unknown as number,
+ )
+}
+
export function formatStoreDateTime(iso: string, timezone: string) {
return formatInTimeZone(parseISO(iso), timezone, 'PPP p')
}
diff --git a/packages/dashboard-core/src/lib/money.test.ts b/packages/dashboard-core/src/lib/money.test.ts
new file mode 100644
index 0000000000..b3b956d1ad
--- /dev/null
+++ b/packages/dashboard-core/src/lib/money.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import {
+ fractionToPercent,
+ isPositiveMoney,
+ percentOf,
+ percentToFraction,
+ prorateMoney,
+ shiftDecimalPoint,
+} from './money'
+
+describe('shiftDecimalPoint', () => {
+ it('moves the point exactly, without float noise', () => {
+ expect(shiftDecimalPoint('0.077', 2)).toBe('7.7')
+ expect(shiftDecimalPoint('7.7', -2)).toBe('0.077')
+ expect(shiftDecimalPoint('0.07', 2)).toBe('7')
+ expect(shiftDecimalPoint('1', 2)).toBe('100')
+ expect(shiftDecimalPoint('100', -2)).toBe('1')
+ expect(shiftDecimalPoint('-0.5', 2)).toBe('-50')
+ expect(shiftDecimalPoint('0', -2)).toBe('0')
+ })
+
+ it('leaves a value that is not a decimal string alone', () => {
+ expect(shiftDecimalPoint('abc', 2)).toBe('abc')
+ })
+})
+
+describe('fractionToPercent / percentToFraction', () => {
+ it('round-trips and keeps blanks blank', () => {
+ expect(fractionToPercent('0.23')).toBe('23')
+ expect(percentToFraction('23')).toBe('0.23')
+ expect(percentToFraction('7.25')).toBe('0.0725')
+ expect(fractionToPercent(null)).toBe('')
+ expect(percentToFraction('')).toBe('')
+ })
+})
+
+describe('percentOf', () => {
+ it('rounds to the currency decimals', () => {
+ expect(percentOf('19.99', '10', 'USD')).toBe('2.00')
+ expect(percentOf('100', '12.5', 'USD')).toBe('12.50')
+ expect(percentOf('1000', '0.05', 'JPY')).toBe('1')
+ expect(percentOf('1.005', '50', 'KWD')).toBe('0.503')
+ })
+})
+
+describe('isPositiveMoney', () => {
+ it('is true only for an amount above zero', () => {
+ expect(isPositiveMoney('0.01')).toBe(true)
+ expect(isPositiveMoney('0.00')).toBe(false)
+ expect(isPositiveMoney('-1')).toBe(false)
+ expect(isPositiveMoney(null)).toBe(false)
+ expect(isPositiveMoney('abc')).toBe(false)
+ })
+})
+
+describe('prorateMoney', () => {
+ it('shares an amount across units, rounded to the currency', () => {
+ expect(prorateMoney('10.00', 1, 3, 'USD')).toBe('3.33')
+ expect(prorateMoney('10.00', 2, 3, 'USD')).toBe('6.67')
+ expect(prorateMoney('10.00', 3, 3, 'USD')).toBe('10.00')
+ expect(prorateMoney('1000', 1, 3, 'JPY')).toBe('333')
+ })
+})
diff --git a/packages/dashboard-core/src/lib/money.ts b/packages/dashboard-core/src/lib/money.ts
new file mode 100644
index 0000000000..14ba144b79
--- /dev/null
+++ b/packages/dashboard-core/src/lib/money.ts
@@ -0,0 +1,99 @@
+import { compareMoney, decimalPlaces, isDecimalString, sumMoney } from '@spree/admin-sdk'
+
+/** Whether an amount is a decimal string above zero. Blank or malformed is not. */
+export function isPositiveMoney(value: string | null | undefined): boolean {
+ return isDecimalString(value) && compareMoney(value, '0') > 0
+}
+
+/**
+ * Moves the decimal point of a decimal string by whole places, exactly, and
+ * writes the result without trailing zeros ("0.077" shifted by 2 is "7.7").
+ * Anything that is not a decimal string comes back unchanged.
+ */
+export function shiftDecimalPoint(value: string, places: number): string {
+ if (!isDecimalString(value)) return value
+
+ const negative = value.startsWith('-')
+ const [whole, fraction = ''] = (negative ? value.slice(1) : value).split('.')
+ let digits = whole + fraction
+ let point = whole.length + places
+ if (point < 0) {
+ digits = '0'.repeat(-point) + digits
+ point = 0
+ }
+ digits = digits.padEnd(point, '0')
+
+ const integer = digits.slice(0, point).replace(/^0+(?=\d)/, '') || '0'
+ const decimals = digits.slice(point).replace(/0+$/, '')
+ const text = decimals ? `${integer}.${decimals}` : integer
+ return negative && /[1-9]/.test(text) ? `-${text}` : text
+}
+
+/** A fraction rate ("0.23") as the percentage a merchant reads ("23"). Blank stays blank. */
+export function fractionToPercent(fraction: string | null | undefined): string {
+ return fraction == null || fraction === '' ? '' : shiftDecimalPoint(fraction, 2)
+}
+
+/** A typed percentage ("23") as the fraction rate the API stores ("0.23"). Blank stays blank. */
+export function percentToFraction(percent: string | null | undefined): string {
+ return percent == null || percent === '' ? '' : shiftDecimalPoint(percent.trim(), -2)
+}
+
+function scaled(value: string): { units: bigint; scale: number } {
+ const negative = value.startsWith('-')
+ const [whole, fraction = ''] = (negative ? value.slice(1) : value).split('.')
+ const units = BigInt(whole + fraction)
+ return { units: negative ? -units : units, scale: fraction.length }
+}
+
+/**
+ * numerator / denominator, where the numerator carries `scale` decimals,
+ * rounded half away from zero to the currency's decimals.
+ */
+function roundToCurrency(
+ numerator: bigint,
+ scale: number,
+ denominator: bigint,
+ currency: string,
+): string {
+ const places = decimalPlaces(currency)
+ const negative = numerator < 0n !== denominator < 0n
+ let dividend = numerator < 0n ? -numerator : numerator
+ let divisor = denominator < 0n ? -denominator : denominator
+ if (scale > places) divisor *= 10n ** BigInt(scale - places)
+ else dividend *= 10n ** BigInt(places - scale)
+
+ let units = dividend / divisor
+ if ((dividend % divisor) * 2n >= divisor) units += 1n
+
+ const text = shiftDecimalPoint((negative ? -units : units).toString(), -places)
+ return sumMoney([text], currency)
+}
+
+/**
+ * A percentage of an amount, exactly, rounded half away from zero to the
+ * currency's decimals ("10" percent of "19.99" USD is "2.00").
+ */
+export function percentOf(amount: string, percent: string, currency: string): string {
+ const left = scaled(amount)
+ const right = scaled(percent)
+ // The percentage is a hundredth, so the product carries two more places.
+ return roundToCurrency(left.units * right.units, left.scale + right.scale + 2, 1n, currency)
+}
+
+/**
+ * The share of an amount that `part` of `whole` units carries ("10.00" for 1
+ * of 3 is "3.33"), rounded half away from zero to the currency's decimals.
+ */
+export function prorateMoney(
+ amount: string,
+ part: number,
+ whole: number,
+ currency: string,
+): string {
+ if (!Number.isInteger(part) || !Number.isInteger(whole) || whole === 0) {
+ throw new Error(`Cannot prorate ${part} of ${whole}`)
+ }
+ const { units, scale } = scaled(amount)
+ return roundToCurrency(units * BigInt(part), scale, BigInt(whole), currency)
+}
diff --git a/packages/dashboard-core/src/lib/return-refunds.test.ts b/packages/dashboard-core/src/lib/return-refunds.test.ts
new file mode 100644
index 0000000000..ddb7f6105b
--- /dev/null
+++ b/packages/dashboard-core/src/lib/return-refunds.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { paidForUnits, returnOwesNothing, returnRefundSummary } from './return-refunds'
+
+const figures = {
+ status: 'received',
+ refund_total: '20.00',
+ display_refund_total: '$20.00',
+ refunded_total: '0.00',
+ display_refunded_total: '$0.00',
+}
+
+describe('returnRefundSummary', () => {
+ it('reports what is owed until money goes back', () => {
+ expect(returnRefundSummary(figures)).toEqual({ kind: 'owed', amount: '$20.00' })
+ })
+
+ it('names the full amount when less went back than was owed', () => {
+ expect(
+ returnRefundSummary({
+ ...figures,
+ status: 'refunded',
+ refunded_total: '15.00',
+ display_refunded_total: '$15.00',
+ }),
+ ).toEqual({ kind: 'refunded_short', amount: '$15.00', total: '$20.00' })
+ })
+
+ it('reports a full refund', () => {
+ expect(
+ returnRefundSummary({
+ ...figures,
+ status: 'refunded',
+ refunded_total: '20.00',
+ display_refunded_total: '$20.00',
+ }),
+ ).toEqual({ kind: 'refunded', amount: '$20.00' })
+ })
+})
+
+describe('returnOwesNothing', () => {
+ it('is true only for a zero amount', () => {
+ expect(returnOwesNothing('0.00')).toBe(true)
+ expect(returnOwesNothing('0.01')).toBe(false)
+ })
+})
+
+describe('paidForUnits', () => {
+ it('shares the paid amount and tax across the chosen units', () => {
+ const line = { quantity: 3, discounted_amount: '9.00', additional_tax_total: '1.00' }
+ expect(paidForUnits(line, 1, 'USD')).toBe('3.33')
+ expect(paidForUnits(line, 3, 'USD')).toBe('10.00')
+ })
+
+ it('is blank when nothing is chosen or the amount is unknown', () => {
+ expect(paidForUnits({ quantity: 2, discounted_amount: '5.00' }, 0, 'USD')).toBe('')
+ expect(paidForUnits({ quantity: 2, discounted_amount: null }, 1, 'USD')).toBe('')
+ })
+})
diff --git a/packages/dashboard-core/src/lib/return-refunds.ts b/packages/dashboard-core/src/lib/return-refunds.ts
new file mode 100644
index 0000000000..5bc33ca712
--- /dev/null
+++ b/packages/dashboard-core/src/lib/return-refunds.ts
@@ -0,0 +1,64 @@
+import { compareMoney, isDecimalString, isZeroMoney, sumMoney } from '@spree/admin-sdk'
+import { prorateMoney } from './money'
+
+/** True when a received return is owed nothing, so completing it moves no money. */
+export function returnOwesNothing(refundableTotal: string): boolean {
+ return isZeroMoney(refundableTotal)
+}
+
+export type ReturnRefundFigures = {
+ status: string
+ refund_total: string
+ display_refund_total: string
+ refunded_total: string
+ display_refunded_total: string
+}
+
+/**
+ * What a return's card reports: what it is owed until money goes back, then
+ * what actually went back — which a merchant keeping a restocking fee makes
+ * less than it was owed, so that case also names the full amount. Money that
+ * went back counts even before the return is marked refunded: a refund that
+ * succeeded on one payment and was declined on the next leaves it received.
+ */
+export function returnRefundSummary(
+ returnRecord: ReturnRefundFigures,
+):
+ | { kind: 'owed'; amount: string }
+ | { kind: 'refunded'; amount: string }
+ | { kind: 'refunded_short'; amount: string; total: string } {
+ if (returnRecord.status !== 'refunded' && isZeroMoney(returnRecord.refunded_total)) {
+ return { kind: 'owed', amount: returnRecord.display_refund_total }
+ }
+
+ if (compareMoney(returnRecord.refunded_total || '0', returnRecord.refund_total || '0') < 0) {
+ return {
+ kind: 'refunded_short',
+ amount: returnRecord.display_refunded_total,
+ total: returnRecord.display_refund_total,
+ }
+ }
+
+ return { kind: 'refunded', amount: returnRecord.display_refunded_total }
+}
+
+/**
+ * What the customer paid, tax included, for `quantity` units of a line — the
+ * refund a claim offers until the merchant types their own. Blank when the
+ * line's amounts are unknown.
+ */
+export function paidForUnits(
+ line: {
+ quantity: number
+ discounted_amount?: string | null
+ additional_tax_total?: string | null
+ },
+ quantity: number,
+ currency: string,
+): string {
+ if (quantity <= 0 || line.quantity <= 0 || !isDecimalString(line.discounted_amount)) return ''
+
+ const tax = isDecimalString(line.additional_tax_total) ? line.additional_tax_total : '0'
+ const paid = sumMoney([line.discounted_amount, tax])
+ return prorateMoney(paid, quantity, line.quantity, currency)
+}
diff --git a/packages/dashboard-ui/src/spree/calculator-summary.tsx b/packages/dashboard-ui/src/spree/calculator-summary.tsx
index ef192dc72a..632306370c 100644
--- a/packages/dashboard-ui/src/spree/calculator-summary.tsx
+++ b/packages/dashboard-ui/src/spree/calculator-summary.tsx
@@ -114,12 +114,15 @@ function formatField(
}
function formatMoney(value: unknown, currency: string): string {
- const n = typeof value === 'number' ? value : Number(value)
- if (Number.isNaN(n)) return String(value)
+ const amount = String(value)
+ if (!/^-?\d+(\.\d+)?$/.test(amount)) return amount
try {
- return new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(n)
+ // `Intl` reads a numeric string exactly; its ES2022 typings only list numbers.
+ return new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(
+ amount as unknown as number,
+ )
} catch {
- return `${n} ${currency}`
+ return `${amount} ${currency}`
}
}
diff --git a/packages/dashboard-ui/src/spree/claim-resolve-dialog.tsx b/packages/dashboard-ui/src/spree/claim-resolve-dialog.tsx
index c040509966..f814cc8778 100644
--- a/packages/dashboard-ui/src/spree/claim-resolve-dialog.tsx
+++ b/packages/dashboard-ui/src/spree/claim-resolve-dialog.tsx
@@ -93,8 +93,11 @@ export function ClaimResolveDialog({
// Refunding nothing, or replacing nothing, is what the server rejects —
// say so here instead of letting the request fail.
+ // The amount is the canonical decimal string a number input yields, so
+ // "above zero" is unsigned digits with a non-zero digit among them.
+ const positiveAmount = /^\d*\.?\d+$/.test(amount) && /[1-9]/.test(amount)
const ready =
- (!refunding || Number(amount) > 0) && (!sendingReplacement || chosenReplacements.length > 0)
+ (!refunding || positiveAmount) && (!sendingReplacement || chosenReplacements.length > 0)
return (
<Dialog open onOpenChange={(open) => !open && onClose()}>
diff --git a/packages/dashboard-ui/src/spree/post-sale-create-dialogs.tsx b/packages/dashboard-ui/src/spree/post-sale-create-dialogs.tsx
index 6b0bf0b15d..c29086ad00 100644
--- a/packages/dashboard-ui/src/spree/post-sale-create-dialogs.tsx
+++ b/packages/dashboard-ui/src/spree/post-sale-create-dialogs.tsx
@@ -100,18 +100,11 @@ export function CreateReturnDialog({
/** A line the claim can name, with what the customer paid for it. */
export type ClaimableLine = PostSaleUnit & {
- /** The whole line after discounts, used to default the refund to what was actually paid. */
- discountedAmount?: string | null
- /** Tax charged on top of the line's price, which a claim refunds with it. */
- additionalTaxTotal?: string | null
-}
-
-/** What the customer paid for `quantity` units of the line, or blank when that is unknown. */
-function paidForUnits(line: ClaimableLine, quantity: number): string {
- const paid = Number(line.discountedAmount) + Number(line.additionalTaxTotal ?? 0)
- if (quantity <= 0 || line.discountedAmount == null || !Number.isFinite(paid)) return ''
-
- return ((paid * quantity) / line.quantity).toFixed(2)
+ /**
+ * What the customer paid, tax included, for that many units of the line, as
+ * a decimal string — the default refund. Blank when it is unknown.
+ */
+ paidFor?: (quantity: number) => string
}
/**
@@ -189,7 +182,7 @@ export function CreateClaimDialog({
if (!typedAmounts[line.id]) {
setAmounts((current) => ({
...current,
- [line.id]: paidForUnits(line, quantity),
+ [line.id]: quantity > 0 ? (line.paidFor?.(quantity) ?? '') : '',
}))
}
}}
diff --git a/packages/dashboard-ui/src/spree/return-dialogs.tsx b/packages/dashboard-ui/src/spree/return-dialogs.tsx
index ae8c32be26..3c9e26718a 100644
--- a/packages/dashboard-ui/src/spree/return-dialogs.tsx
+++ b/packages/dashboard-ui/src/spree/return-dialogs.tsx
@@ -139,49 +139,6 @@ export function ReturnReceiveDialog({
)
}
-/** True when a received return is owed nothing, so completing it moves no money. */
-export function returnOwesNothing(refundableTotal: string): boolean {
- return Number(refundableTotal) === 0
-}
-
-export type ReturnRefundFigures = {
- status: string
- refund_total: string
- display_refund_total: string
- refunded_total: string
- display_refunded_total: string
-}
-
-/**
- * What a return's card reports: what it is owed until money goes back, then
- * what actually went back — which a merchant keeping a restocking fee makes
- * less than it was owed, so that case also names the full amount. Money that
- * went back counts even before the return is marked refunded: a refund that
- * succeeded on one payment and was declined on the next leaves it received.
- */
-export function returnRefundSummary(
- returnRecord: ReturnRefundFigures,
-):
- | { kind: 'owed'; amount: string }
- | { kind: 'refunded'; amount: string }
- | { kind: 'refunded_short'; amount: string; total: string } {
- const refunded = Number(returnRecord.refunded_total)
-
- if (returnRecord.status !== 'refunded' && refunded === 0) {
- return { kind: 'owed', amount: returnRecord.display_refund_total }
- }
-
- if (refunded < Number(returnRecord.refund_total)) {
- return {
- kind: 'refunded_short',
- amount: returnRecord.display_refunded_total,
- total: returnRecord.display_refund_total,
- }
- }
-
- return { kind: 'refunded', amount: returnRecord.display_refunded_total }
-}
-
/**
* Gives the money back: how much, and by what means. A return owed nothing
* (a free gift sent back) is completed instead, with nothing to choose.
@@ -193,6 +150,7 @@ export function returnRefundSummary(
*/
export function ReturnRefundDialog({
refundableTotal,
+ owesNothing,
refundTaxTotal,
currencySymbol,
onClose,
@@ -200,6 +158,8 @@ export function ReturnRefundDialog({
pending = false,
}: {
refundableTotal: string
+ /** True when the return is owed nothing, so it is completed rather than refunded. */
+ owesNothing: boolean
refundTaxTotal?: string
currencySymbol: string
onClose: () => void
@@ -209,7 +169,6 @@ export function ReturnRefundDialog({
const { t } = useTranslation()
const [refundMethod, setRefundMethod] = useState<RefundMethod>('original_payment')
const [amount, setAmount] = useState(refundableTotal)
- const owesNothing = returnOwesNothing(refundableTotal)
const methodOptions = [
{
diff --git a/packages/dashboard/e2e/tax-rates.spec.ts b/packages/dashboard/e2e/tax-rates.spec.ts
index 5149641c80..588b88150c 100644
--- a/packages/dashboard/e2e/tax-rates.spec.ts
+++ b/packages/dashboard/e2e/tax-rates.spec.ts
@@ -12,7 +12,7 @@ async function createTaxRate(
await expect(page.getByRole('heading', { name: /new tax rate/i })).toBeVisible()
await page.locator('#name').fill(attrs.name)
- await page.locator('#amount_percentage').fill(attrs.amount)
+ await page.locator('#rate_percent').fill(attrs.amount)
// The seeded store always carries a `Default` tax category.
await page.locator('#tax_category_id').click()
await page.getByRole('option', { name: /^default$/i }).click()
@@ -60,8 +60,8 @@ test.describe('tax rates', () => {
await expect(rowButton(page, name)).toBeVisible({ timeout: 15_000 })
await rowButton(page, name).click()
- await expect(page.locator('#amount_percentage')).toHaveValue('10', { timeout: 15_000 })
- await page.locator('#amount_percentage').fill('12.5')
+ await expect(page.locator('#rate_percent')).toHaveValue('10', { timeout: 15_000 })
+ await page.locator('#rate_percent').fill('12.5')
await page.getByRole('button', { name: /^save$/i }).click()
const row = page.getByRole('row').filter({ has: rowButton(page, name) })
diff --git a/packages/dashboard/src/components/spree/catalog-terms-card.tsx b/packages/dashboard/src/components/spree/catalog-terms-card.tsx
index d2453e844d..fe5b9c62e5 100644
--- a/packages/dashboard/src/components/spree/catalog-terms-card.tsx
+++ b/packages/dashboard/src/components/spree/catalog-terms-card.tsx
@@ -1,5 +1,10 @@
import type { CatalogProductTerm } from '@spree/admin-sdk'
-import { CurrencySelect, normalizeQuantityRule, useStore } from '@spree/dashboard-core'
+import {
+ CurrencySelect,
+ isPositiveMoney,
+ normalizeQuantityRule,
+ useStore,
+} from '@spree/dashboard-core'
import {
Button,
Card,
@@ -192,7 +197,7 @@ function OrderMinimums({
<div className="flex flex-col gap-2">
{rows.map((row, index) => {
const duplicate = usedCurrencies.indexOf(row.currency) !== index
- const amountValid = !row.amount.trim() || Number(row.amount) > 0
+ const amountValid = !row.amount.trim() || isPositiveMoney(row.amount.trim())
return (
<div key={row.currency} className="flex flex-col gap-1">
diff --git a/packages/dashboard/src/components/spree/customers/customer-lifetime-stats-card.tsx b/packages/dashboard/src/components/spree/customers/customer-lifetime-stats-card.tsx
index 0901ad9e90..e3bd1acbba 100644
--- a/packages/dashboard/src/components/spree/customers/customer-lifetime-stats-card.tsx
+++ b/packages/dashboard/src/components/spree/customers/customer-lifetime-stats-card.tsx
@@ -1,5 +1,5 @@
-import type { Customer } from '@spree/admin-sdk'
-import { useMoneyLocale, useStore } from '@spree/dashboard-core'
+import { type Customer, decimalPlaces } from '@spree/admin-sdk'
+import { isPositiveMoney, useMoneyLocale, useStore } from '@spree/dashboard-core'
import { Card, CardContent, RelativeTime } from '@spree/dashboard-ui'
import type { ReactNode } from 'react'
import { useTranslation } from 'react-i18next'
@@ -10,14 +10,17 @@ export function CustomerLifetimeStatsCard({ customer }: { customer: Customer })
const moneyLocale = useMoneyLocale()
const { defaultCurrency } = useStore()
const orders = customer.orders_count ?? 0
- const totalSpent = Number(customer.total_spent ?? '0')
- // Format the average from the number rather than rewriting the digits inside
+ const totalSpent = customer.total_spent
+ // Format the average from the amount rather than rewriting the digits inside
// `display_total_spent`: that string is already localized, so substituting a
// period-decimal figure into it mixes separators (`1.234,56 €` → `1234.57 €`).
+ // Dividing needs a number; the average is only displayed, never sent or compared.
+ const averageForDisplay =
+ orders > 0 && isPositiveMoney(totalSpent)
+ ? (Number(totalSpent) / orders).toFixed(decimalPlaces(defaultCurrency))
+ : null
const aovDisplay =
- orders > 0 && totalSpent > 0
- ? formatAmount(totalSpent / orders, defaultCurrency, moneyLocale)
- : '—'
+ averageForDisplay === null ? '—' : formatAmount(averageForDisplay, defaultCurrency, moneyLocale)
return (
<Card>
diff --git a/packages/dashboard/src/components/spree/order-post-sale-cards.tsx b/packages/dashboard/src/components/spree/order-post-sale-cards.tsx
index 690c75d4e5..0ab5b70635 100644
--- a/packages/dashboard/src/components/spree/order-post-sale-cards.tsx
+++ b/packages/dashboard/src/components/spree/order-post-sale-cards.tsx
@@ -1,4 +1,5 @@
import type { Claim, Exchange, Order } from '@spree/admin-sdk'
+import { isPositiveMoney } from '@spree/dashboard-core'
import {
Badge,
Button,
@@ -129,7 +130,7 @@ export function OrderExchangesCard({ order }: { order: Order }) {
// A dearer replacement leaves the customer owing
// the difference, which fulfilling puts on the order.
if (
- Number(exchange.price_difference) > 0 &&
+ isPositiveMoney(exchange.price_difference) &&
!(await confirm({
message: t(
'admin.pages.orders.detail.exchanges.confirm.balance_due',
diff --git a/packages/dashboard/src/components/spree/order-returns-card.tsx b/packages/dashboard/src/components/spree/order-returns-card.tsx
index a8e180d2d0..9539baa6bd 100644
--- a/packages/dashboard/src/components/spree/order-returns-card.tsx
+++ b/packages/dashboard/src/components/spree/order-returns-card.tsx
@@ -1,5 +1,11 @@
import type { Order, Return, ReturnLineItem } from '@spree/admin-sdk'
-import { currencyParts, useStore } from '@spree/dashboard-core'
+import {
+ currencyParts,
+ isPositiveMoney,
+ returnOwesNothing,
+ returnRefundSummary,
+ useStore,
+} from '@spree/dashboard-core'
import {
Badge,
Button,
@@ -17,8 +23,6 @@ import {
type RefundMethod,
ReturnReceiveDialog,
ReturnRefundDialog,
- returnOwesNothing,
- returnRefundSummary,
StatusBadge,
useConfirm,
} from '@spree/dashboard-ui'
@@ -408,8 +412,9 @@ function RefundDialog({
return (
<ReturnRefundDialog
refundableTotal={returnRecord.refundable_total}
+ owesNothing={returnOwesNothing(returnRecord.refundable_total)}
refundTaxTotal={
- Number(returnRecord.refund_tax_total) > 0
+ isPositiveMoney(returnRecord.refund_tax_total)
? returnRecord.display_refund_tax_total
: undefined
}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-edit-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-edit-dialog.tsx
index 6d19932994..466dc9b5f2 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillment-edit-dialog.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-edit-dialog.tsx
@@ -1,4 +1,4 @@
-import { type Fulfillment, type Order, SpreeError } from '@spree/admin-sdk'
+import { type Fulfillment, isZeroMoney, type Order, SpreeError } from '@spree/admin-sdk'
import { useStockLocations } from '@spree/dashboard-core'
import { FulfillmentEditDialog as SharedFulfillmentEditDialog } from '@spree/dashboard-ui'
import { useState } from 'react'
@@ -58,7 +58,7 @@ export function FulfillmentEditDialog({
const rateOptions = (fulfillment.delivery_rates ?? []).map((rate) => ({
value: rate.id,
label: `${rate.name} — ${
- !rate.unpriced && Number.parseFloat(rate.cost) === 0
+ !rate.unpriced && isZeroMoney(rate.cost)
? t('admin.orders.detail.fulfillments.free')
: rate.display_cost
}`,
diff --git a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
index cad3a4f7c0..df22a7ac96 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
@@ -2,6 +2,7 @@ import type { Delivery, Fulfillment, Order } from '@spree/admin-sdk'
import {
type FulfillmentItemRow,
fulfillmentItemRows,
+ isPositiveMoney,
unfulfilledItemRows,
useStockLocations,
} from '@spree/dashboard-core'
@@ -562,7 +563,7 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
is still pending. */}
{(fulfillment.delivery_method ||
fulfillment.unpriced ||
- Number.parseFloat(fulfillment.cost) > 0) && (
+ isPositiveMoney(fulfillment.cost)) && (
<CardContent className="flex items-center justify-between border-b border-border-subtle py-3 text-sm">
<span className="text-muted-foreground">
{/* The selected rate names the carrier service that actually
diff --git a/packages/dashboard/src/components/spree/orders/order-adjustments-cards.tsx b/packages/dashboard/src/components/spree/orders/order-adjustments-cards.tsx
index 1ee2297f6c..0ed2c06ee8 100644
--- a/packages/dashboard/src/components/spree/orders/order-adjustments-cards.tsx
+++ b/packages/dashboard/src/components/spree/orders/order-adjustments-cards.tsx
@@ -1,5 +1,19 @@
-import type { Discount, Fee, Order } from '@spree/admin-sdk'
-import { adminClient, currencyParts, formatPrice } from '@spree/dashboard-core'
+import {
+ compareMoney,
+ type Discount,
+ type Fee,
+ isDecimalString,
+ isZeroMoney,
+ type Order,
+ sumMoney,
+} from '@spree/admin-sdk'
+import {
+ adminClient,
+ currencyParts,
+ formatMoney,
+ formatPrice,
+ percentOf,
+} from '@spree/dashboard-core'
import {
Badge,
Button,
@@ -131,7 +145,7 @@ export function TaxLinesCard({ order }: { order: Order }) {
const { t } = useTranslation()
const orderId = order.id
const { data: taxLines, isPending, isError, isSuccess } = useOrderTaxLines(orderId)
- const taxGroups = groupTaxLines(taxLines?.data ?? [])
+ const taxGroups = groupTaxLines(taxLines?.data ?? [], order.currency)
const emptyMessage = isPending
? t('admin.common.loading')
: isError
@@ -186,7 +200,7 @@ export function TaxLinesCard({ order }: { order: Order }) {
</TableCell>
<TableCell className="text-right tabular-nums">
{formatPrice({
- amount: group.amount.toFixed(2),
+ amount: group.amount,
currency: order.currency,
display_amount: null,
})}
@@ -426,21 +440,19 @@ function AddDiscountDialog({
// Mirrors Orders::AddManualDiscount: percent applies to the already-
// discounted line amounts, clamped so no line goes below zero.
- const numericValue = Number.parseFloat(value)
- let previewAmount: number | null = null
- if (valueType === 'percent' && Number.isFinite(numericValue) && numericValue > 0) {
+ const positive = (amount: string | null | undefined) =>
+ isDecimalString(amount) && compareMoney(amount, '0') > 0 ? amount : '0'
+ let previewAmount: string | null = null
+ if (valueType === 'percent' && isDecimalString(value) && compareMoney(value, '0') > 0) {
const items = order.items ?? []
const base =
target === 'order'
- ? items.reduce(
- (sum, item) => sum + Math.max(Number.parseFloat(item.discounted_amount), 0),
- 0,
- )
- : Math.max(
- Number.parseFloat(items.find((item) => item.id === target)?.discounted_amount ?? '0'),
- 0,
- )
- if (base > 0) previewAmount = Math.min((base * numericValue) / 100, base)
+ ? sumMoney(items.map((item) => positive(item.discounted_amount)))
+ : positive(items.find((item) => item.id === target)?.discounted_amount)
+ if (!isZeroMoney(base)) {
+ const discount = percentOf(base, value, order.currency)
+ previewAmount = compareMoney(discount, base) > 0 ? base : discount
+ }
}
return (
@@ -533,10 +545,7 @@ function AddDiscountDialog({
{previewAmount !== null && (
<p className="text-sm text-muted-foreground">
{t('admin.orders.detail.adjustment_lines.percent_preview', {
- amount: new Intl.NumberFormat(i18n.language, {
- style: 'currency',
- currency: order.currency,
- }).format(previewAmount),
+ amount: formatMoney(previewAmount, order.currency, i18n.language),
})}
</p>
)}
diff --git a/packages/dashboard/src/components/spree/orders/order-discounts-sidebar-card.tsx b/packages/dashboard/src/components/spree/orders/order-discounts-sidebar-card.tsx
index 5f5b2205fb..731bdb0241 100644
--- a/packages/dashboard/src/components/spree/orders/order-discounts-sidebar-card.tsx
+++ b/packages/dashboard/src/components/spree/orders/order-discounts-sidebar-card.tsx
@@ -1,4 +1,5 @@
import type { Order } from '@spree/admin-sdk'
+import { isZeroMoney } from '@spree/admin-sdk'
import { adminClient, useResourceKey } from '@spree/dashboard-core'
import {
Button,
@@ -42,7 +43,7 @@ export function DiscountsCard({ order }: { order: Order }) {
)
const isEditable = !order.completed_at
- const couponPending = Boolean(order.coupon_code) && Number.parseFloat(order.discount_total) === 0
+ const couponPending = Boolean(order.coupon_code) && isZeroMoney(order.discount_total)
return (
<>
diff --git a/packages/dashboard/src/components/spree/orders/order-edit-items-table.tsx b/packages/dashboard/src/components/spree/orders/order-edit-items-table.tsx
index ce73917618..707a676baa 100644
--- a/packages/dashboard/src/components/spree/orders/order-edit-items-table.tsx
+++ b/packages/dashboard/src/components/spree/orders/order-edit-items-table.tsx
@@ -1,3 +1,4 @@
+import { compareMoney, isDecimalString, multiplyMoney } from '@spree/admin-sdk'
import {
Badge,
Button,
@@ -91,9 +92,13 @@ function OrderEditItemRow({
const negotiated = row.price_source === 'manual'
const projectedTotal = projectedLineTotal(row)
- const savedTotal = Number(row.saved_price) * row.saved_quantity
+ const savedTotal = isDecimalString(row.saved_price)
+ ? multiplyMoney(row.saved_price, row.saved_quantity)
+ : null
const totalChanged =
- !row.added && projectedTotal !== null && Math.abs(projectedTotal - savedTotal) > 0.004
+ !row.added &&
+ projectedTotal !== null &&
+ (savedTotal === null || compareMoney(projectedTotal, savedTotal) !== 0)
const revertPreview = row.revert_price ? projectedPrice(row) : null
function toggleRemoved() {
@@ -252,7 +257,7 @@ function OrderEditItemRow({
) : totalChanged ? (
<span className="flex items-center justify-end gap-2">
<span className="text-muted-foreground line-through">{row.display_total}</span>
- <span className="font-medium">{formatAmount(projectedTotal as number, currency)}</span>
+ <span className="font-medium">{formatAmount(projectedTotal as string, currency)}</span>
</span>
) : (
row.display_total
diff --git a/packages/dashboard/src/components/spree/orders/order-summary-card.tsx b/packages/dashboard/src/components/spree/orders/order-summary-card.tsx
index 54d5c966a0..24b1be8be9 100644
--- a/packages/dashboard/src/components/spree/orders/order-summary-card.tsx
+++ b/packages/dashboard/src/components/spree/orders/order-summary-card.tsx
@@ -1,5 +1,6 @@
import type { Order } from '@spree/admin-sdk'
-import { LocaleLabel, useStore } from '@spree/dashboard-core'
+import { isZeroMoney } from '@spree/admin-sdk'
+import { isPositiveMoney, LocaleLabel, useStore } from '@spree/dashboard-core'
import { Card, CardHeader, CardTitle, cn, Separator } from '@spree/dashboard-ui'
import { Link } from '@tanstack/react-router'
import i18n from 'i18next'
@@ -46,11 +47,11 @@ function SummaryRow({
export function OrderSummaryCard({ order }: { order: Order }) {
const { t } = useTranslation()
const { storeId } = useStore()
- const outstandingBalance = Number.parseFloat(order.amount_due)
+ const outstanding = isPositiveMoney(order.amount_due)
// Read off the order rather than summed from its commission lines: the
// figures are persisted columns, so the fee VAT the platform files and the
// seller reclaims is the same number everywhere it is shown.
- const commissionTax = Number.parseFloat(order.commission_tax_total)
+ const commissionTaxed = isPositiveMoney(order.commission_tax_total)
// Keyed on the seller, not on the amount: a zero-rated or exempt rate still
// writes commission lines, and the card below lists them, so hiding the
// summary at zero would have the two panels disagree about the same order.
@@ -167,36 +168,36 @@ export function OrderSummaryCard({ order }: { order: Order }) {
<SummaryRow label={t('admin.fields.subtotal.label')} value={order.display_item_total} />
- {Number.parseFloat(order.delivery_total) > 0 && (
+ {isPositiveMoney(order.delivery_total) && (
<SummaryRow
label={t('admin.fields.shipping.label')}
value={order.display_delivery_total}
/>
)}
- {Number.parseFloat(order.discount_total) !== 0 && (
+ {!isZeroMoney(order.discount_total) && (
<SummaryRow
label={t('admin.orders.detail.summary.promotions')}
value={order.display_discount_total}
/>
)}
- {Number.parseFloat(order.adjustment_total) !== 0 && (
+ {!isZeroMoney(order.adjustment_total) && (
<SummaryRow
label={t('admin.orders.detail.summary.adjustments')}
value={order.display_adjustment_total}
/>
)}
- {Number.parseFloat(order.included_tax_total) > 0 && (
+ {isPositiveMoney(order.included_tax_total) && (
<SummaryRow
label={t('admin.orders.detail.summary.tax_included')}
value={order.display_included_tax_total}
/>
)}
- {(Number.parseFloat(order.additional_tax_total) > 0 ||
- (Boolean(order.completed_at) && Number.parseFloat(order.included_tax_total) === 0)) && (
+ {(isPositiveMoney(order.additional_tax_total) ||
+ (Boolean(order.completed_at) && isZeroMoney(order.included_tax_total))) && (
<SummaryRow
label={t('admin.orders.detail.summary.tax_additional')}
value={order.display_additional_tax_total}
@@ -218,7 +219,7 @@ export function OrderSummaryCard({ order }: { order: Order }) {
label={t('admin.orders.detail.summary.commission_fee')}
value={order.display_commission_amount_total}
/>
- {commissionTax > 0 && (
+ {commissionTaxed && (
<SummaryRow
label={t('admin.orders.detail.summary.commission_tax')}
value={order.display_commission_tax_total}
@@ -243,7 +244,7 @@ export function OrderSummaryCard({ order }: { order: Order }) {
label={t('admin.orders.detail.summary.outstanding_balance')}
value={order.display_amount_due}
highlight
- danger={outstandingBalance > 0}
+ danger={outstanding}
/>
</div>
</Card>
diff --git a/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx b/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx
index ccd7a6be5c..9fd626e421 100644
--- a/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx
+++ b/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx
@@ -1,7 +1,10 @@
import type { Claim, Order, Variant } from '@spree/admin-sdk'
+import { sumMoney } from '@spree/admin-sdk'
import {
adminClient,
currencyParts,
+ isPositiveMoney,
+ paidForUnits,
ResourceCombobox,
useStockLocations,
useStore,
@@ -304,8 +307,7 @@ export function CreateClaimDialog({
id: item.id,
label: [item.name, item.options_text].filter(Boolean).join(' — ') || item.id,
quantity: item.quantity,
- discountedAmount: item.discounted_amount,
- additionalTaxTotal: item.additional_tax_total,
+ paidFor: (quantity: number) => paidForUnits(item, quantity, order.currency),
}))}
currencySymbol={currencySymbol}
reasonField={<ReasonField kind="claim-reasons" value={reasonId} onChange={setReasonId} />}
@@ -336,14 +338,9 @@ export function ResolveClaimDialog({
// A claim opened without per-item amounts has a refund_total of zero, and
// the workflow refuses to refund nothing — offer what the customer paid for
// the claimed items instead, which is also the ceiling it enforces.
- const recorded = Number(claim.refund_total)
- const paid = lines.reduce((sum, line) => sum + Number(line.paid_amount ?? 0), 0)
+ const paid = sumMoney(lines.map((line) => line.paid_amount))
const defaultAmount =
- Number.isFinite(recorded) && recorded > 0
- ? claim.refund_total
- : paid > 0
- ? paid.toFixed(2)
- : claim.refund_total
+ isPositiveMoney(claim.refund_total) || !isPositiveMoney(paid) ? claim.refund_total : paid
return (
<ClaimResolveDialog
diff --git a/packages/dashboard/src/components/spree/purchase-order-form.tsx b/packages/dashboard/src/components/spree/purchase-order-form.tsx
index d74d7813fe..3d680d1859 100644
--- a/packages/dashboard/src/components/spree/purchase-order-form.tsx
+++ b/packages/dashboard/src/components/spree/purchase-order-form.tsx
@@ -1,4 +1,5 @@
import type { Supplier } from '@spree/admin-sdk'
+import { isDecimalString } from '@spree/admin-sdk'
import {
CurrencySelect,
PageHeader,
@@ -106,11 +107,10 @@ export function PurchaseOrderForm({
const [pickerOpen, setPickerOpen] = useState(false)
// A cleared cost input is not zero — it is nothing, which the server rejects
- // field-by-field. `Number('')` is 0 and finite, so the emptiness has to be
- // checked before the number is.
+ // field-by-field.
const hasCost = (value?: string) => {
const trimmed = value?.trim()
- return !!trimmed && Number.isFinite(Number(trimmed)) && Number(trimmed) >= 0
+ return isDecimalString(trimmed) && !trimmed.startsWith('-')
}
const canSubmit =
diff --git a/packages/dashboard/src/components/spree/reporting/growth-badge.tsx b/packages/dashboard/src/components/spree/reporting/growth-badge.tsx
index c4162a31f9..aa5486acf8 100644
--- a/packages/dashboard/src/components/spree/reporting/growth-badge.tsx
+++ b/packages/dashboard/src/components/spree/reporting/growth-badge.tsx
@@ -1,16 +1,17 @@
import { Badge, cn } from '@spree/dashboard-ui'
import { MinusIcon, TrendingDownIcon, TrendingUpIcon } from '@spree/dashboard-ui/icons'
import { useTranslation } from 'react-i18next'
+import { formatMetricNumber, metricNumberForChart } from './metric-numbers'
/**
* Period-over-period delta indicator: green/red trend arrow + percentage, a
* neutral dash at 0, and a "New" badge when there is no previous-period
- * baseline (`growth === null`).
+ * baseline (`growth === null`). Growth arrives as a decimal string ("12.5").
*/
-export function GrowthBadge({ growth }: { growth: number | null | undefined }) {
+export function GrowthBadge({ growth }: { growth: number | string | null | undefined }) {
const { t, i18n } = useTranslation()
- if (growth === null || growth === undefined) {
+ if (growth === null || growth === undefined || growth === '') {
return (
<Badge variant="secondary" title={t('admin.pages.home.growth.vs_previous')}>
{t('admin.pages.home.growth.new')}
@@ -18,9 +19,10 @@ export function GrowthBadge({ growth }: { growth: number | null | undefined }) {
)
}
- const formatted = `${growth > 0 ? '+' : ''}${growth.toLocaleString(i18n.language)}%`
+ const direction = Math.sign(metricNumberForChart(growth))
+ const formatted = `${direction > 0 ? '+' : ''}${formatMetricNumber(growth, i18n.language)}%`
- if (growth === 0) {
+ if (direction === 0) {
return (
<span
className="inline-flex items-center gap-0.5 text-xs font-medium text-muted-foreground"
@@ -39,11 +41,15 @@ export function GrowthBadge({ growth }: { growth: number | null | undefined }) {
// The status trio, not a raw Tailwind ramp: a hand-picked green needs
// re-tinting for dark mode at every call site, which is what the
// token family exists to stop.
- growth > 0 ? 'text-success' : 'text-danger',
+ direction > 0 ? 'text-success' : 'text-danger',
)}
title={t('admin.pages.home.growth.vs_previous')}
>
- {growth > 0 ? <TrendingUpIcon className="size-3" /> : <TrendingDownIcon className="size-3" />}
+ {direction > 0 ? (
+ <TrendingUpIcon className="size-3" />
+ ) : (
+ <TrendingDownIcon className="size-3" />
+ )}
{formatted}
</span>
)
diff --git a/packages/dashboard/src/components/spree/reporting/metric-numbers.ts b/packages/dashboard/src/components/spree/reporting/metric-numbers.ts
new file mode 100644
index 0000000000..4547d992aa
--- /dev/null
+++ b/packages/dashboard/src/components/spree/reporting/metric-numbers.ts
@@ -0,0 +1,22 @@
+/**
+ * A metric value as a number, for plotting, bar widths and trend arrows only. Money, ratios
+ * and growth arrive as decimal strings; nothing derived from this number is
+ * sent anywhere or shown as a figure.
+ */
+export function metricNumberForChart(value: number | string | null | undefined): number {
+ if (value === null || value === undefined || value === '') return 0
+ const parsed = typeof value === 'number' ? value : Number(value)
+ return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * Formats a metric figure in the admin's locale. A decimal string goes to
+ * `Intl` as it is, which reads it exactly; its ES2022 typings only list numbers.
+ */
+export function formatMetricNumber(
+ value: number | string,
+ locale: string,
+ options?: Intl.NumberFormatOptions,
+): string {
+ return new Intl.NumberFormat(locale, options).format(value as number)
+}
diff --git a/packages/dashboard/src/components/spree/reporting/report-view.tsx b/packages/dashboard/src/components/spree/reporting/report-view.tsx
index de052c42b8..2d84bd6899 100644
--- a/packages/dashboard/src/components/spree/reporting/report-view.tsx
+++ b/packages/dashboard/src/components/spree/reporting/report-view.tsx
@@ -38,6 +38,7 @@ import { useTranslation } from 'react-i18next'
import { Bar, CartesianGrid, ComposedChart, Line, XAxis } from 'recharts'
import { entityDimension, metaString, rawDimension } from '../../../hooks/use-reporting'
import { GrowthBadge } from './growth-badge'
+import { formatMetricNumber, metricNumberForChart } from './metric-numbers'
import { inferViz, queryDimension } from './report-draft'
interface ReportViewProps {
@@ -174,7 +175,7 @@ export function formatMetric(
// a null total rather than a misleading store-wide one.
if (!value || value.value == null) return '—'
if (value.display) return value.display
- const formatted = value.value.toLocaleString(locale, {
+ const formatted = formatMetricNumber(value.value, locale, {
maximumFractionDigits: metric.format === 'integer' ? 0 : 2,
})
// The server sends the number a merchant reads (42.5), so only the sign is missing.
@@ -333,8 +334,8 @@ export function TimeSeriesChart({
() =>
result.rows.map((row) => ({
bucket: rawDimension(row, dimension),
- current: row.metrics[active.name]?.value ?? 0,
- previous: row.metrics[active.name]?.previous ?? 0,
+ current: metricNumberForChart(row.metrics[active.name]?.value),
+ previous: metricNumberForChart(row.metrics[active.name]?.previous),
})),
[result.rows, dimension, active.name],
)
@@ -466,7 +467,7 @@ function ResultTable({
// The first metric doubles as the share bar on a ranking, like the home rankings.
const shareMetric = ranked ? metrics[0] : undefined
const maxShare = shareMetric
- ? Math.max(...rows.map((row) => row.metrics[shareMetric.name]?.value ?? 0), 0)
+ ? Math.max(...rows.map((row) => metricNumberForChart(row.metrics[shareMetric.name]?.value)), 0)
: 0
return (
@@ -489,7 +490,9 @@ function ResultTable({
</TableHeader>
<TableBody>
{rows.map((row, index) => {
- const share = shareMetric ? (row.metrics[shareMetric.name]?.value ?? 0) : 0
+ const share = shareMetric
+ ? metricNumberForChart(row.metrics[shareMetric.name]?.value)
+ : 0
return (
<TableRow key={JSON.stringify(row.dimensions)}>
{ranked && (
diff --git a/packages/dashboard/src/components/spree/sellers/seller-balance-card.tsx b/packages/dashboard/src/components/spree/sellers/seller-balance-card.tsx
index d820eb435e..bd5359f81b 100644
--- a/packages/dashboard/src/components/spree/sellers/seller-balance-card.tsx
+++ b/packages/dashboard/src/components/spree/sellers/seller-balance-card.tsx
@@ -1,5 +1,5 @@
import type { Seller } from '@spree/admin-sdk'
-import { Subject, usePermissions } from '@spree/dashboard-core'
+import { isPositiveMoney, Subject, usePermissions } from '@spree/dashboard-core'
import {
Button,
Card,
@@ -36,7 +36,7 @@ export function SellerBalanceCard({ seller }: { seller: Seller }) {
const balances = data?.data ?? []
if (balances.length === 0) return null
- const owed = balances.some((balance) => Number.parseFloat(balance.balance) > 0)
+ const owed = balances.some((balance) => isPositiveMoney(balance.balance))
const canSettle = permissions.can('update', Subject.SellerPayout) && owed
// Settling moves money, so it is asked for rather than fired from a click.
diff --git a/packages/dashboard/src/components/spree/shipping/delivery-method-sheet.tsx b/packages/dashboard/src/components/spree/shipping/delivery-method-sheet.tsx
index 77198aacbe..b27fc9f12a 100644
--- a/packages/dashboard/src/components/spree/shipping/delivery-method-sheet.tsx
+++ b/packages/dashboard/src/components/spree/shipping/delivery-method-sheet.tsx
@@ -1,5 +1,6 @@
import { zodResolver } from '@hookform/resolvers/zod'
import type { DeliveryProfile, DeliveryZone } from '@spree/admin-sdk'
+import { isDecimalString, isZeroMoney } from '@spree/admin-sdk'
import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
import {
Button,
@@ -31,7 +32,7 @@ import { DeliveryMethodFormCards } from './delivery-method-form'
/** API decimals arrive as strings ("0.0"); show blank instead of a noisy zero. */
function decimalToForm(value: string | null | undefined) {
if (value === null || value === undefined || value === '') return ''
- return Number(value) === 0 ? '' : String(value)
+ return isDecimalString(value) && isZeroMoney(value) ? '' : String(value)
}
/** Whether a rule kind is configured with a product list rather than preferences. */
diff --git a/packages/dashboard/src/components/spree/store-credits/edit-store-credit-dialog.tsx b/packages/dashboard/src/components/spree/store-credits/edit-store-credit-dialog.tsx
index 44a3384ad0..5fe7352c4d 100644
--- a/packages/dashboard/src/components/spree/store-credits/edit-store-credit-dialog.tsx
+++ b/packages/dashboard/src/components/spree/store-credits/edit-store-credit-dialog.tsx
@@ -3,6 +3,7 @@ import type { StoreCredit } from '@spree/admin-sdk'
import {
CurrencySelect,
currencyParts,
+ isPositiveMoney,
mapSpreeErrorsToForm,
normalizeMoneyInput,
useMoneyLocale,
@@ -50,7 +51,7 @@ export function EditStoreCreditDialog({
// Server rejects amount changes once any of it has been used. Lock the
// field so the merchant doesn't submit a value that will only come back
// as a 422 store_credit_in_use.
- const amountLocked = Number(credit.amount_used ?? 0) > 0
+ const amountLocked = isPositiveMoney(credit.amount_used)
// The amount hydrates from the canonical API value ("50.00") and is shown in
// the person's own number format ("50,00" in German); submit normalizes it
diff --git a/packages/dashboard/src/lib/commission-line-rate-label.ts b/packages/dashboard/src/lib/commission-line-rate-label.ts
index e2985dbc54..f17689ce2c 100644
--- a/packages/dashboard/src/lib/commission-line-rate-label.ts
+++ b/packages/dashboard/src/lib/commission-line-rate-label.ts
@@ -1,5 +1,5 @@
-import type { CommissionLine, Order } from '@spree/admin-sdk'
-import { formatPrice } from '@spree/dashboard-core'
+import { type CommissionLine, isDecimalString, type Order } from '@spree/admin-sdk'
+import { formatPrice, prorateMoney } from '@spree/dashboard-core'
import type { TFunction } from 'i18next'
function snapshottedFixedAmount(line: CommissionLine, order: Order, t: TFunction) {
@@ -8,11 +8,10 @@ function snapshottedFixedAmount(line: CommissionLine, order: Order, t: TFunction
const quantity = item?.quantity ?? 1
if (quantity <= 0) return line.display_amount || t('admin.common.empty_value')
- const perUnit = Number.parseFloat(line.amount) / quantity
- if (!Number.isFinite(perUnit)) return t('admin.common.empty_value')
+ if (!isDecimalString(line.amount)) return t('admin.common.empty_value')
return formatPrice({
- amount: perUnit.toFixed(2),
+ amount: prorateMoney(line.amount, 1, quantity, line.currency),
currency: line.currency,
display_amount: null,
})
diff --git a/packages/dashboard/src/lib/delivery-method-summary.test.ts b/packages/dashboard/src/lib/delivery-method-summary.test.ts
index 17064c611e..9d1574799e 100644
--- a/packages/dashboard/src/lib/delivery-method-summary.test.ts
+++ b/packages/dashboard/src/lib/delivery-method-summary.test.ts
@@ -8,50 +8,52 @@ import {
describe('listedAmounts', () => {
it('reads the legacy single amount as the store default currency', () => {
- expect(listedAmounts({ amount: 5 }, 'USD')).toEqual([{ amount: 5, currency: 'USD' }])
+ expect(listedAmounts({ amount: '5' }, 'USD')).toEqual([{ amount: '5', currency: 'USD' }])
})
it('attributes the legacy amount to its own currency preference', () => {
- expect(listedAmounts({ amount: 7, currency: 'EUR' }, 'USD')).toEqual([
- { amount: 7, currency: 'EUR' },
+ expect(listedAmounts({ amount: '7', currency: 'EUR' }, 'USD')).toEqual([
+ { amount: '7', currency: 'EUR' },
])
})
it('reads a non-default currency from the amounts hash when the default is empty', () => {
- expect(listedAmounts({ amounts: { EUR: 7 } }, 'USD')).toEqual([{ amount: 7, currency: 'EUR' }])
+ expect(listedAmounts({ amounts: { EUR: '7' } }, 'USD')).toEqual([
+ { amount: '7', currency: 'EUR' },
+ ])
})
it('reads the editor-written hash even when the single amount is zero', () => {
- expect(listedAmounts({ amount: 0, amounts: { EUR: 11 } }, 'USD')).toEqual([
- { amount: 0, currency: 'USD' },
- { amount: 11, currency: 'EUR' },
+ expect(listedAmounts({ amount: '0', amounts: { EUR: '11' } }, 'USD')).toEqual([
+ { amount: '0', currency: 'USD' },
+ { amount: '11', currency: 'EUR' },
])
})
it('keeps each hash amount against the currency it was entered in', () => {
- expect(listedAmounts({ amounts: { GBP: 8, EUR: 7 } }, 'USD')).toEqual([
- { amount: 7, currency: 'EUR' },
- { amount: 8, currency: 'GBP' },
+ expect(listedAmounts({ amounts: { GBP: '8', EUR: '7' } }, 'USD')).toEqual([
+ { amount: '7', currency: 'EUR' },
+ { amount: '8', currency: 'GBP' },
])
})
it('lists the default-currency amount first when both sources have a price', () => {
- expect(listedAmounts({ amount: 5, amounts: { EUR: 7 } }, 'USD')).toEqual([
- { amount: 5, currency: 'USD' },
- { amount: 7, currency: 'EUR' },
+ expect(listedAmounts({ amount: '5', amounts: { EUR: '7' } }, 'USD')).toEqual([
+ { amount: '5', currency: 'USD' },
+ { amount: '7', currency: 'EUR' },
])
})
it('lets the amounts hash override the legacy amount for the same currency', () => {
- expect(listedAmounts({ amount: 5, amounts: { USD: 6, EUR: 7 } }, 'USD')).toEqual([
- { amount: 6, currency: 'USD' },
- { amount: 7, currency: 'EUR' },
+ expect(listedAmounts({ amount: '5', amounts: { USD: '6', EUR: '7' } }, 'USD')).toEqual([
+ { amount: '6', currency: 'USD' },
+ { amount: '7', currency: 'EUR' },
])
})
it('ignores blank hash entries so an emptied currency is not offered', () => {
- expect(listedAmounts({ amounts: { EUR: '', GBP: 8 } }, 'USD')).toEqual([
- { amount: 8, currency: 'GBP' },
+ expect(listedAmounts({ amounts: { EUR: '', GBP: '8' } }, 'USD')).toEqual([
+ { amount: '8', currency: 'GBP' },
])
})
})
@@ -60,95 +62,101 @@ describe('formatListedPrice', () => {
const separator = ' · '
it('formats a default-currency amount with that currency symbol', () => {
- expect(formatListedPrice({ amount: 5 }, 'USD', 'en', 'Free', separator)).toBe('$5.00')
+ expect(formatListedPrice({ amount: '5' }, 'USD', 'en', 'Free', separator)).toBe('$5.00')
})
it('formats an EUR-only method with a euro sign, not the store default symbol', () => {
- expect(formatListedPrice({ amounts: { EUR: 7 } }, 'USD', 'en', 'Free', separator)).toBe('€7.00')
+ expect(formatListedPrice({ amounts: { EUR: '7' } }, 'USD', 'en', 'Free', separator)).toBe(
+ '€7.00',
+ )
})
it('formats a GBP-only method with a pound sign', () => {
- expect(formatListedPrice({ amounts: { GBP: 8 } }, 'USD', 'en', 'Free', separator)).toBe('£8.00')
+ expect(formatListedPrice({ amounts: { GBP: '8' } }, 'USD', 'en', 'Free', separator)).toBe(
+ '£8.00',
+ )
})
it('joins one price per stored currency', () => {
expect(
- formatListedPrice({ amount: 5, amounts: { EUR: 7 } }, 'USD', 'en', 'Free', separator),
+ formatListedPrice({ amount: '5', amounts: { EUR: '7' } }, 'USD', 'en', 'Free', separator),
).toBe('$5.00 · €7.00')
})
it('reads an empty or zero-only method as free', () => {
expect(formatListedPrice({}, 'USD', 'en', 'Free', separator)).toBe('Free')
- expect(formatListedPrice({ amount: 0 }, 'USD', 'en', 'Free', separator)).toBe('Free')
- expect(formatListedPrice({ amounts: { EUR: 0 } }, 'USD', 'en', 'Free', separator)).toBe('Free')
+ expect(formatListedPrice({ amount: '0' }, 'USD', 'en', 'Free', separator)).toBe('Free')
+ expect(formatListedPrice({ amounts: { EUR: '0' } }, 'USD', 'en', 'Free', separator)).toBe(
+ 'Free',
+ )
})
it('does not read a zero single amount as free when the hash has a real price', () => {
expect(
- formatListedPrice({ amount: 0, amounts: { EUR: 11 } }, 'USD', 'en', 'Free', separator),
+ formatListedPrice({ amount: '0', amounts: { EUR: '11' } }, 'USD', 'en', 'Free', separator),
).toBe('€11.00')
})
})
describe('amountForCurrency', () => {
it('puts a pre-6.0 euro amount in the euro row, not the store default', () => {
- const preferences = { amount: 7, currency: 'EUR' }
- expect(amountForCurrency(preferences, 'EUR', 'USD')).toBe(7)
+ const preferences = { amount: '7', currency: 'EUR' }
+ expect(amountForCurrency(preferences, 'EUR', 'USD')).toBe('7')
expect(amountForCurrency(preferences, 'USD', 'USD')).toBeNull()
})
it('reads an editor-written euro price from the amounts hash', () => {
- const preferences = { amount: 0, amounts: { EUR: 11 } }
- expect(amountForCurrency(preferences, 'EUR', 'USD')).toBe(11)
- expect(amountForCurrency(preferences, 'USD', 'USD')).toBe(0)
+ const preferences = { amount: '0', amounts: { EUR: '11' } }
+ expect(amountForCurrency(preferences, 'EUR', 'USD')).toBe('11')
+ expect(amountForCurrency(preferences, 'USD', 'USD')).toBe('0')
})
it('treats a blank currency preference as the store default', () => {
- expect(amountForCurrency({ amount: 5 }, 'USD', 'USD')).toBe(5)
- expect(amountForCurrency({ amount: 5 }, 'EUR', 'USD')).toBeNull()
+ expect(amountForCurrency({ amount: '5' }, 'USD', 'USD')).toBe('5')
+ expect(amountForCurrency({ amount: '5' }, 'EUR', 'USD')).toBeNull()
})
it('trims surrounding space on the legacy currency preference', () => {
- const preferences = { amount: 7, currency: ' EUR ' }
- expect(amountForCurrency(preferences, 'EUR', 'USD')).toBe(7)
+ const preferences = { amount: '7', currency: ' EUR ' }
+ expect(amountForCurrency(preferences, 'EUR', 'USD')).toBe('7')
expect(amountForCurrency(preferences, 'USD', 'USD')).toBeNull()
})
it('reads a lowercase amounts-hash key as that currency', () => {
- expect(amountForCurrency({ amounts: { eur: 7 } }, 'EUR', 'USD')).toBe(7)
+ expect(amountForCurrency({ amounts: { eur: '7' } }, 'EUR', 'USD')).toBe('7')
})
})
describe('applyCurrencyAmount', () => {
it('keeps a pre-6.0 euro price when the dollar row is edited', () => {
- expect(applyCurrencyAmount({ amount: 7, currency: 'EUR' }, 'USD', '10', 'USD')).toEqual({
- amount: 10,
+ expect(applyCurrencyAmount({ amount: '7', currency: 'EUR' }, 'USD', '10', 'USD')).toEqual({
+ amount: '10',
currency: 'USD',
- amounts: { EUR: 7 },
+ amounts: { EUR: '7' },
})
})
it('updates the named currency in place on a pre-6.0 method', () => {
- expect(applyCurrencyAmount({ amount: 7, currency: 'EUR' }, 'EUR', '11', 'USD')).toEqual({
- amount: 11,
+ expect(applyCurrencyAmount({ amount: '7', currency: 'EUR' }, 'EUR', '11', 'USD')).toEqual({
+ amount: '11',
currency: 'EUR',
- amounts: { EUR: 11 },
+ amounts: { EUR: '11' },
})
})
it('writes a non-default currency into the amounts hash', () => {
- expect(applyCurrencyAmount({ amount: 5, currency: 'USD' }, 'EUR', '11', 'USD')).toEqual({
- amount: 5,
+ expect(applyCurrencyAmount({ amount: '5', currency: 'USD' }, 'EUR', '11', 'USD')).toEqual({
+ amount: '5',
currency: 'USD',
- amounts: { EUR: 11 },
+ amounts: { EUR: '11' },
})
})
it('updates and clears a lowercase stored hash key without leaving a stale entry', () => {
- expect(applyCurrencyAmount({ amounts: { eur: 7 } }, 'EUR', '11', 'USD')).toEqual({
- amounts: { EUR: 11 },
+ expect(applyCurrencyAmount({ amounts: { eur: '7' } }, 'EUR', '11', 'USD')).toEqual({
+ amounts: { EUR: '11' },
})
- expect(applyCurrencyAmount({ amounts: { eur: 7 } }, 'EUR', '', 'USD')).toEqual({
+ expect(applyCurrencyAmount({ amounts: { eur: '7' } }, 'EUR', '', 'USD')).toEqual({
amounts: {},
})
})
diff --git a/packages/dashboard/src/lib/delivery-method-summary.ts b/packages/dashboard/src/lib/delivery-method-summary.ts
index d370b5a92a..3b9a33f9e0 100644
--- a/packages/dashboard/src/lib/delivery-method-summary.ts
+++ b/packages/dashboard/src/lib/delivery-method-summary.ts
@@ -1,15 +1,20 @@
-import type { DeliveryMethodRule } from '@spree/admin-sdk'
+import { type DeliveryMethodRule, isDecimalString, isZeroMoney } from '@spree/admin-sdk'
+import { formatMoney } from '@spree/dashboard-core'
import type { TFunction } from 'i18next'
-function toNumber(value: unknown): number | null {
- if (value === null || value === undefined || value === '') return null
- const parsed = Number(value)
- return Number.isNaN(parsed) ? null : parsed
+/**
+ * A stored preference as a decimal string. The API answers with strings; a
+ * number still sitting in preferences saved before 6.0 is read as its digits.
+ */
+function toDecimal(value: unknown): string | null {
+ const text =
+ typeof value === 'number' ? String(value) : typeof value === 'string' ? value.trim() : ''
+ return isDecimalString(text) ? text : null
}
/** One stored delivery amount and the ISO currency it was entered in. */
export type ListedAmount = {
- amount: number
+ amount: string
currency: string
}
@@ -34,7 +39,7 @@ function hashEntry(amounts: Record<string, unknown>, currency: string): unknown
function writeHashAmount(
amounts: Record<string, unknown>,
currency: string,
- value: number | null,
+ value: string | null,
): void {
const existing = hashKey(amounts, currency)
if (existing !== undefined) delete amounts[existing]
@@ -66,15 +71,15 @@ export function amountForCurrency(
preferences: Record<string, unknown> | null | undefined,
currency: string,
defaultCurrency: string,
-): number | null {
+): string | null {
const code = currency.toUpperCase()
const fromHash = hashEntry(amountsHash(preferences), code)
if (fromHash !== undefined && fromHash !== null && fromHash !== '') {
- return toNumber(fromHash)
+ return toDecimal(fromHash)
}
if (legacyCurrency(preferences, defaultCurrency) !== code) return null
- return toNumber(preferences?.amount)
+ return toDecimal(preferences?.amount)
}
/**
@@ -94,7 +99,7 @@ export function applyCurrencyAmount(
): Record<string, unknown> {
const code = currency.toUpperCase()
const defaultCode = defaultCurrency.toUpperCase()
- const parsed = raw === '' ? null : toNumber(raw)
+ const parsed = toDecimal(raw)
const nextAmounts = { ...amountsHash(preferences) }
const namedCurrency = legacyCurrency(preferences, defaultCurrency)
@@ -145,14 +150,14 @@ export function listedAmounts(
const defaultCode = defaultCurrency.toUpperCase()
for (const [code, value] of Object.entries(amountsHash(preferences))) {
- const parsed = toNumber(value)
+ const parsed = toDecimal(value)
if (parsed === null) continue
const currency = code.toUpperCase()
listed.push({ amount: parsed, currency })
seen.add(currency)
}
- const legacyAmount = toNumber(preferences?.amount)
+ const legacyAmount = toDecimal(preferences?.amount)
if (legacyAmount !== null) {
const named = legacyCurrency(preferences, defaultCurrency)
if (!seen.has(named)) {
@@ -172,14 +177,14 @@ export function listedAmounts(
* priced some other way (per item, tiered, per carrier quote) and has no
* single number to show. Prefer `listedAmounts` when the currency matters.
*/
-export function flatAmount(preferences: Record<string, unknown> | null | undefined): number | null {
- return toNumber(preferences?.amount)
+export function flatAmount(preferences: Record<string, unknown> | null | undefined): string | null {
+ return toDecimal(preferences?.amount)
}
/** Formats an amount in the given currency, falling back to a bare number. */
-export function formatAmount(amount: number, currency: string, locale?: string): string {
+export function formatAmount(amount: string, currency: string, locale?: string): string {
try {
- return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount)
+ return formatMoney(amount, currency, locale)
} catch {
return `${amount} ${currency}`
}
@@ -197,7 +202,9 @@ export function formatListedPrice(
freeLabel: string,
separator: string,
): string {
- const priced = listedAmounts(preferences, defaultCurrency).filter((row) => row.amount !== 0)
+ const priced = listedAmounts(preferences, defaultCurrency).filter(
+ (row) => !isZeroMoney(row.amount),
+ )
if (priced.length === 0) return freeLabel
return priced.map((row) => formatAmount(row.amount, row.currency, locale)).join(separator)
}
@@ -224,8 +231,8 @@ function summarizeRule(
const preferences = (rule.preferences ?? {}) as Record<string, unknown>
if (rule.type === 'weight_rule') {
- const min = toNumber(preferences.minimum_weight)
- const max = toNumber(preferences.maximum_weight)
+ const min = toDecimal(preferences.minimum_weight)
+ const max = toDecimal(preferences.maximum_weight)
if (min !== null && max !== null) {
return t('admin.delivery_methods.rule_summary.weight_between', {
min,
@@ -243,9 +250,9 @@ function summarizeRule(
}
if (rule.type === 'item_total_rule') {
- const min = toNumber(preferences.minimum_amount)
- const max = toNumber(preferences.maximum_amount)
- const money = (value: number) => formatAmount(value, currency, locale)
+ const min = toDecimal(preferences.minimum_amount)
+ const max = toDecimal(preferences.maximum_amount)
+ const money = (value: string) => formatAmount(value, currency, locale)
if (min !== null && max !== null) {
return t('admin.delivery_methods.rule_summary.total_between', {
min: money(min),
diff --git a/packages/dashboard/src/lib/packing-slip.ts b/packages/dashboard/src/lib/packing-slip.ts
index 5933442c89..0a50d76ff2 100644
--- a/packages/dashboard/src/lib/packing-slip.ts
+++ b/packages/dashboard/src/lib/packing-slip.ts
@@ -1,4 +1,12 @@
-import type { Fulfillment, LineItem, Order } from '@spree/admin-sdk'
+import {
+ type Fulfillment,
+ isDecimalString,
+ isZeroMoney,
+ type LineItem,
+ multiplyMoney,
+ type Order,
+ sumMoney,
+} from '@spree/admin-sdk'
import { fulfillmentItemRows } from '@spree/dashboard-core'
import type { TFunction } from 'i18next'
import i18n from 'i18next'
@@ -97,8 +105,8 @@ function buildRows(order: Order, fulfillment: Fulfillment): PackingSlipRow[] {
return fulfillmentItemRows(fulfillment, order.items ?? []).map((row) => {
const lineItem = byId.get(row.key)
- const unitPrice = lineItem ? Number(lineItem.price) : Number.NaN
- const canPrice = lineItem != null && Number.isFinite(unitPrice)
+ const unitPrice = lineItem?.price
+ const canPrice = lineItem != null && isDecimalString(unitPrice)
// Prefer the server's formatted total when this parcel holds the whole
// line; compute per-parcel only when a partial quantity ships, so the
@@ -107,7 +115,7 @@ function buildRows(order: Order, fulfillment: Fulfillment): PackingSlipRow[] {
? null
: row.quantity === lineItem.quantity
? lineItem.display_total
- : formatAmount(unitPrice * row.quantity, currency)
+ : formatAmount(multiplyMoney(unitPrice, row.quantity, currency), currency)
return {
key: row.key,
@@ -142,21 +150,21 @@ function buildSummary(
const lines: SummaryLine[] = [
{ label: key('packing_slip_subtotal'), value: order.display_item_total, emphasized: false },
]
- if (Number(order.delivery_total) !== 0) {
+ if (!isZeroMoney(order.delivery_total)) {
lines.push({
label: key('packing_slip_shipping'),
value: order.display_delivery_total,
emphasized: false,
})
}
- if (Number(order.discount_total) !== 0) {
+ if (!isZeroMoney(order.discount_total)) {
lines.push({
label: key('packing_slip_discount'),
value: order.display_discount_total,
emphasized: false,
})
}
- if (Number(order.tax_total) !== 0) {
+ if (!isZeroMoney(order.tax_total)) {
lines.push({
label: key('packing_slip_tax'),
value: order.display_tax_total,
@@ -167,12 +175,13 @@ function buildSummary(
return lines
}
- const subtotal = (order.items ?? []).reduce((sum, item) => {
- const row = rows.find((candidate) => candidate.key === item.id)
- if (!row) return sum
- const price = Number(item.price)
- return Number.isFinite(price) ? sum + price * row.quantity : sum
- }, 0)
+ const subtotal = sumMoney(
+ (order.items ?? []).map((item) => {
+ const row = rows.find((candidate) => candidate.key === item.id)
+ return row && isDecimalString(item.price) ? multiplyMoney(item.price, row.quantity) : null
+ }),
+ order.currency,
+ )
const formatted = formatAmount(subtotal, order.currency)
return [
diff --git a/packages/dashboard/src/lib/tax-line-groups.test.ts b/packages/dashboard/src/lib/tax-line-groups.test.ts
index b9fb772cb3..5d553fb474 100644
--- a/packages/dashboard/src/lib/tax-line-groups.test.ts
+++ b/packages/dashboard/src/lib/tax-line-groups.test.ts
@@ -40,10 +40,10 @@ describe('taxLineExemption', () => {
describe('groupTaxLines', () => {
it('sums lines that share a label and the same treatment', () => {
- const groups = groupTaxLines([taxLine({ amount: '4.35' }), taxLine({ amount: '4.35' })])
+ const groups = groupTaxLines([taxLine({ amount: '4.35' }), taxLine({ amount: '4.35' })], 'USD')
expect(groups).toHaveLength(1)
- expect(groups[0]?.amount).toBeCloseTo(8.7)
+ expect(groups[0]?.amount).toBe('8.70')
expect(groups[0]?.taxabilityReason).toBe('standard_rated')
})
@@ -58,8 +58,8 @@ describe('groupTaxLines', () => {
])
expect(groups.map((group) => [group.taxabilityReason, group.amount])).toEqual([
- ['standard_rated', 8.7],
- ['customer_exempt', 0],
+ ['standard_rated', '8.70'],
+ ['customer_exempt', '0.00'],
])
expect(groups[1]?.exemption).toEqual({
reason_code: 'resale',
diff --git a/packages/dashboard/src/lib/tax-line-groups.ts b/packages/dashboard/src/lib/tax-line-groups.ts
index 1de46e2c04..e30b1eaded 100644
--- a/packages/dashboard/src/lib/tax-line-groups.ts
+++ b/packages/dashboard/src/lib/tax-line-groups.ts
@@ -1,3 +1,5 @@
+import { isDecimalString, sumMoney } from '@spree/admin-sdk'
+
/**
* How tax rows are shown on an order: one rate charged on many lines
* collapses to a single amount, but a different treatment (exempt vs
@@ -25,7 +27,7 @@ export interface TaxLineExemption {
export interface TaxLineGroup {
key: string
label: string
- amount: number
+ amount: string
taxabilityReason: string | null
exemption: TaxLineExemption | null
countryCode: string | null
@@ -57,9 +59,10 @@ export function taxLineExemption(row: GroupableTaxLine): TaxLineExemption | null
* not collapse into a single $0.00 row.
*
* @param rows - Tax lines for one order
+ * @param currency - The order's currency, so sums keep its decimals
* @returns Display groups in first-seen order
*/
-export function groupTaxLines(rows: GroupableTaxLine[]): TaxLineGroup[] {
+export function groupTaxLines(rows: GroupableTaxLine[], currency?: string): TaxLineGroup[] {
const groups = new Map<string, TaxLineGroup>()
for (const row of rows) {
@@ -70,12 +73,11 @@ export function groupTaxLines(rows: GroupableTaxLine[]): TaxLineGroup[] {
exemption?.certificate_number ?? '',
exemption?.reason_code ?? '',
].join('\0')
- const parsed = Number.parseFloat(row.amount)
- const amount = Number.isFinite(parsed) ? parsed : 0
+ const amount = isDecimalString(row.amount) ? row.amount : '0'
const existing = groups.get(key)
if (existing) {
- existing.amount += amount
+ existing.amount = sumMoney([existing.amount, amount], currency)
continue
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/index.tsx
index 5c46922e8d..2869bc07ac 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/index.tsx
@@ -56,6 +56,7 @@ import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import { ALL_CHANNELS, ChannelSelect } from '../../../components/spree/channel-select'
import { GrowthBadge } from '../../../components/spree/reporting/growth-badge'
+import { metricNumberForChart } from '../../../components/spree/reporting/metric-numbers'
import {
DimensionLabel,
ReportSkeleton,
@@ -549,7 +550,7 @@ function RankingsCard({
return {
key: dimension.id ?? dimension.label,
dimension,
- amount: amount?.value ?? 0,
+ amount: metricNumberForChart(amount?.value),
display: amount?.display ?? String(amount?.value ?? 0),
// Named after the metric being counted, not the tab: companies count
// orders and sellers count units, so a tab-based ternary mislabels one
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/loyalty/store-credits.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/loyalty/store-credits.tsx
index 1405ef379a..49a5790e66 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/loyalty/store-credits.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/loyalty/store-credits.tsx
@@ -1,4 +1,5 @@
import type { StoreCredit, StoreCreditCurrencyTotal } from '@spree/admin-sdk'
+import { isZeroMoney } from '@spree/admin-sdk'
import {
Can,
PageHeader,
@@ -203,7 +204,7 @@ function useStoreCreditActions() {
const canDelete = (credit: StoreCredit) =>
!!credit.customer_id &&
- Number(credit.amount_used) === 0 &&
+ isZeroMoney(credit.amount_used) &&
permissions.can('destroy', Subject.StoreCredit)
/** Resolves to whether the credit was deleted, so a cancel keeps the panel open. */
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/edit.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/edit.tsx
index e785172e9a..2351a272d8 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/edit.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/edit.tsx
@@ -1,9 +1,10 @@
import { zodResolver } from '@hookform/resolvers/zod'
-import { type Order, SpreeError, type Variant } from '@spree/admin-sdk'
+import { compareMoney, isZeroMoney, type Order, SpreeError, type Variant } from '@spree/admin-sdk'
import {
adminClient,
formatPrice,
GONE_STATUSES,
+ isPositiveMoney,
mapSpreeErrorsToForm,
PageHeader,
} from '@spree/dashboard-core'
@@ -64,12 +65,10 @@ function OrderTotalsCard({ order, items }: { order: Order; items: OrderEditItemV
const { t } = useTranslation()
const projected = projectedSubtotal(items)
- const savedSubtotal = Number(order.item_total)
- const subtotalChanged = projected !== null && Math.abs(projected - savedSubtotal) > 0.004
+ const subtotalChanged = projected !== null && compareMoney(projected, order.item_total) !== 0
// Derived from the order's own totals, so charges not itemised here count.
- const serverAddedCharges = Number(order.total) - savedSubtotal
- const totalProjectable = subtotalChanged && Math.abs(serverAddedCharges) <= 0.004
+ const totalProjectable = subtotalChanged && compareMoney(order.total, order.item_total) === 0
return (
<Card className="gap-0 py-0">
@@ -87,7 +86,7 @@ function OrderTotalsCard({ order, items }: { order: Order; items: OrderEditItemV
{order.display_item_total}
</span>
<span className="font-medium">
- {formatAmount(projected as number, order.currency)}
+ {formatAmount(projected as string, order.currency)}
</span>
</span>
) : (
@@ -96,26 +95,26 @@ function OrderTotalsCard({ order, items }: { order: Order; items: OrderEditItemV
}
/>
- {Number.parseFloat(order.delivery_total) > 0 && (
+ {isPositiveMoney(order.delivery_total) && (
<TotalRow label={t('admin.fields.shipping.label')} value={order.display_delivery_total} />
)}
- {Number.parseFloat(order.discount_total) !== 0 && (
+ {!isZeroMoney(order.discount_total) && (
<TotalRow
label={t('admin.orders.detail.summary.promotions')}
value={order.display_discount_total}
/>
)}
- {Number.parseFloat(order.included_tax_total) > 0 && (
+ {isPositiveMoney(order.included_tax_total) && (
<TotalRow
label={t('admin.orders.detail.summary.tax_included')}
value={order.display_included_tax_total}
/>
)}
- {(Number.parseFloat(order.additional_tax_total) > 0 ||
- (Boolean(order.completed_at) && Number.parseFloat(order.included_tax_total) === 0)) && (
+ {(isPositiveMoney(order.additional_tax_total) ||
+ (Boolean(order.completed_at) && isZeroMoney(order.included_tax_total))) && (
<TotalRow
label={t('admin.orders.detail.summary.tax_additional')}
value={order.display_additional_tax_total}
@@ -132,7 +131,7 @@ function OrderTotalsCard({ order, items }: { order: Order; items: OrderEditItemV
<span className="font-normal text-muted-foreground line-through">
{order.display_total}
</span>
- <span>{formatAmount(projected as number, order.currency)}</span>
+ <span>{formatAmount(projected as string, order.currency)}</span>
</span>
) : (
order.display_total
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/marketplace.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/marketplace.tsx
index b2365544e8..e8c5b18cf3 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/marketplace.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/marketplace.tsx
@@ -1,6 +1,12 @@
import { zodResolver } from '@hookform/resolvers/zod'
import { SpreeError, type Store } from '@spree/admin-sdk'
-import { currencyParts, mapSpreeErrorsToForm, PageHeader } from '@spree/dashboard-core'
+import {
+ currencyParts,
+ fractionToPercent,
+ mapSpreeErrorsToForm,
+ PageHeader,
+ percentToFraction,
+} from '@spree/dashboard-core'
import {
Alert,
AlertDescription,
@@ -49,11 +55,9 @@ import {
useUpdateStoreSettings,
} from '../../../../hooks/use-store-settings'
import {
- fractionToPercentage,
type MarketplaceSettingsFormValues,
marketplaceSettingsFormSchema,
PAYOUT_SCHEDULE_INTERVALS,
- percentageToFraction,
} from '../../../../schemas/marketplace'
export const Route = createFileRoute('/_authenticated/$storeId/settings/marketplace')({
@@ -92,16 +96,16 @@ function MarketplaceSettingsPage({ store }: { store: Store }) {
preferred_default_payouts_schedule_interval:
(store.preferred_default_payouts_schedule_interval as (typeof PAYOUT_SCHEDULE_INTERVALS)[number]) ??
'monthly',
- preferred_default_minimum_payout_amount: Number(
- store.preferred_default_minimum_payout_amount ?? 0,
+ // `String` only until the regenerated Store type reads these as the decimal strings the API sends.
+ preferred_default_minimum_payout_amount: String(
+ store.preferred_default_minimum_payout_amount ?? '0',
),
preferred_auto_approve_sellers: store.preferred_auto_approve_sellers ?? false,
preferred_auto_approve_seller_products: store.preferred_auto_approve_seller_products ?? false,
preferred_send_seller_transactional_emails:
store.preferred_send_seller_transactional_emails ?? true,
- commission_tax_rate_percentage: fractionToPercentage(
- store.preferred_default_commission_tax_rate,
- ),
+ commission_tax_rate_percentage:
+ fractionToPercent(String(store.preferred_default_commission_tax_rate ?? '')) || '0',
},
})
@@ -157,7 +161,7 @@ function MarketplaceSettingsPage({ store }: { store: Store }) {
preferred_auto_approve_seller_products: values.preferred_auto_approve_seller_products,
preferred_send_seller_transactional_emails:
values.preferred_send_seller_transactional_emails,
- preferred_default_commission_tax_rate: percentageToFraction(
+ preferred_default_commission_tax_rate: percentToFraction(
values.commission_tax_rate_percentage,
),
})
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/tax-rates.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/tax-rates.tsx
index d166c74f83..f9ea120049 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/tax-rates.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/tax-rates.tsx
@@ -232,7 +232,7 @@ function EditTaxRateSheet({
if (taxRate) {
form.reset({
name: taxRate.name,
- amount_percentage: taxRate.amount_percentage ?? 0,
+ rate_percent: taxRate.rate_percent ?? '0',
tax_category_id: taxRate.tax_category_id ?? '',
country_code: taxRate.country_code ?? '',
state_code: taxRate.state_code ?? '',
@@ -319,26 +319,24 @@ function TaxRateFormFields({ form }: { form: UseFormReturn<TaxRateFormValues> })
</Field>
<Field>
- <FieldLabel htmlFor="amount_percentage">
- {t('admin.fields.tax_rate.amount.label')}
- </FieldLabel>
+ <FieldLabel htmlFor="rate_percent">{t('admin.fields.tax_rate.amount.label')}</FieldLabel>
<InputGroup>
<InputGroupInput
- id="amount_percentage"
+ id="rate_percent"
type="number"
step="0.01"
min="0"
max="100"
inputMode="decimal"
- aria-invalid={!!errors.amount_percentage || undefined}
- {...form.register('amount_percentage')}
+ aria-invalid={!!errors.rate_percent || undefined}
+ {...form.register('rate_percent')}
/>
<InputGroupAddon align="inline-end">
<InputGroupText>%</InputGroupText>
</InputGroupAddon>
</InputGroup>
<FieldDescription>{t('admin.fields.tax_rate.amount.help')}</FieldDescription>
- <FieldError errors={[errors.amount_percentage]} />
+ <FieldError errors={[errors.rate_percent]} />
</Field>
<Field>
diff --git a/packages/dashboard/src/schemas/catalog.ts b/packages/dashboard/src/schemas/catalog.ts
index 5da40d0193..d3e42ed851 100644
--- a/packages/dashboard/src/schemas/catalog.ts
+++ b/packages/dashboard/src/schemas/catalog.ts
@@ -1,5 +1,11 @@
import type { CatalogParams, PriceList } from '@spree/admin-sdk'
-import { blankToNull, normalizeQuantityRule } from '@spree/dashboard-core'
+import { compareMoney, negateMoney } from '@spree/admin-sdk'
+import {
+ blankToNull,
+ isPositiveMoney,
+ normalizeQuantityRule,
+ shiftDecimalPoint,
+} from '@spree/dashboard-core'
import { requiredMessage } from '@spree/dashboard-ui'
import i18n from 'i18next'
import { z } from 'zod/v4'
@@ -149,7 +155,7 @@ export const catalogFormSchema = z
(v) => {
if (v.pricing_mode !== 'automatic' || v.adjustment_direction !== 'decrease') return true
const magnitude = parsePercentage(v.adjustment_magnitude)
- return magnitude === null || magnitude < 100
+ return magnitude === null || compareMoney(magnitude, '100') < 0
},
{
path: ['adjustment_magnitude'],
@@ -319,9 +325,8 @@ function priceListPayload(values: CatalogFormValues, loaded?: CatalogPricingValu
adjust_compare_at: values.adjust_compare_at,
}
: {
- price_adjustment_percentage: String(
- values.adjustment_direction === 'decrease' ? -magnitude : magnitude,
- ),
+ price_adjustment_percentage:
+ values.adjustment_direction === 'decrease' ? negateMoney(magnitude) : magnitude,
adjust_compare_at: values.adjust_compare_at,
}
@@ -384,7 +389,7 @@ function adjustmentTiersPayload(
return [
{
min_quantity: quantity,
- percentage: String(direction === 'decrease' ? -magnitude : magnitude),
+ percentage: direction === 'decrease' ? negateMoney(magnitude) : magnitude,
},
]
})
@@ -407,7 +412,7 @@ function tierPercentageIsUsable(
const magnitude = parsePercentage(tier.percentage)
if (magnitude === null) return false
- return direction === 'increase' || magnitude < 100
+ return direction === 'increase' || compareMoney(magnitude, '100') < 0
}
function volumeRulePayload(minimumQuantity: string | undefined) {
@@ -470,7 +475,7 @@ export function catalogPricingValues(
// The shallowest band decides the whole ladder's direction: the form offers
// one increase/decrease control, and the magnitudes below are read through
// it.
- const bandDirection = Number(bands[0]?.percentage) > 0 ? 'increase' : 'decrease'
+ const bandDirection = isPositiveMoney(bands[0]?.percentage) ? 'increase' : 'decrease'
return {
pricing_mode: bandsOnly ? 'automatic' : pricing_mode,
@@ -484,7 +489,7 @@ export function catalogPricingValues(
// above them carries the sign for the whole ladder.
adjustment_tiers: bands.map((tier) => ({
min_quantity: String(tier.min_quantity),
- percentage: String(Math.abs(Number(tier.percentage))),
+ percentage: shiftDecimalPoint(String(tier.percentage).replace(/^-/, ''), 0),
})),
}
}
diff --git a/packages/dashboard/src/schemas/commission-rate.test.ts b/packages/dashboard/src/schemas/commission-rate.test.ts
index c85847c430..d0b44ce198 100644
--- a/packages/dashboard/src/schemas/commission-rate.test.ts
+++ b/packages/dashboard/src/schemas/commission-rate.test.ts
@@ -70,7 +70,7 @@ describe('commissionRateValuesToParams', () => {
code: '',
enabled: true,
kind: 'percentage',
- value: 10,
+ value: '10',
amounts: {},
bounds: {},
tax_inclusive: false,
@@ -97,4 +97,24 @@ describe('commissionRateValuesToParams', () => {
expect(params.rules?.[0]?.preferences).toEqual({ seller_ids: ['sel_abc'] })
expect(params.rules?.[1]?.preferences).toEqual({ category_ids: ['ctg_xyz'] })
})
+
+ it('sends the rate, bounds and tax rate as decimal strings', () => {
+ const params = commissionRateValuesToParams({
+ name: 'Audio',
+ code: '',
+ enabled: true,
+ kind: 'percentage',
+ value: '12.5',
+ amounts: {},
+ bounds: { USD: { min_amount: '1.50', max_amount: '' } },
+ tax_inclusive: false,
+ include_shipping: false,
+ commission_tax_rate: '7.7',
+ rules: [],
+ })
+
+ expect(params.value).toBe('12.5')
+ expect(params.bounds).toEqual({ USD: { min_amount: '1.50', max_amount: null } })
+ expect(params.commission_tax_rate).toBe('0.077')
+ })
})
diff --git a/packages/dashboard/src/schemas/commission-rate.ts b/packages/dashboard/src/schemas/commission-rate.ts
index e9cff9cce5..9afaab1e1e 100644
--- a/packages/dashboard/src/schemas/commission-rate.ts
+++ b/packages/dashboard/src/schemas/commission-rate.ts
@@ -3,7 +3,8 @@ import type {
CommissionRateCreateParams,
CommissionRateUpdateParams,
} from '@spree/admin-sdk'
-import { blankToNull, i18n } from '@spree/dashboard-core'
+import { compareMoney, isDecimalString } from '@spree/admin-sdk'
+import { blankToNull, fractionToPercent, i18n, percentToFraction } from '@spree/dashboard-core'
import { requiredMessage } from '@spree/dashboard-ui'
import { z } from 'zod/v4'
@@ -14,7 +15,11 @@ const commissionRateFieldsSchema = z.object({
code: z.string().optional(),
enabled: z.boolean(),
kind: z.enum(COMMISSION_RATE_KINDS),
- value: z.coerce.number().min(0),
+ // A canonical decimal string from a number input, sent as typed.
+ value: z
+ .string()
+ .trim()
+ .refine((value) => isDecimalString(value) && !value.startsWith('-')),
// What a flat fee charges, keyed by currency. Held as strings because they
// come from number inputs and an empty one means "not charged here".
amounts: z.record(z.string(), z.string()).default({}),
@@ -47,7 +52,11 @@ const commissionRateFieldsSchema = z.object({
})
export const commissionRateFormSchema = commissionRateFieldsSchema.superRefine((values, ctx) => {
- if (values.kind === 'percentage' && values.value > 100) {
+ if (
+ values.kind === 'percentage' &&
+ isDecimalString(values.value) &&
+ compareMoney(values.value, '100') > 0
+ ) {
ctx.addIssue({
code: 'custom',
path: ['value'],
@@ -63,7 +72,7 @@ export const COMMISSION_RATE_DEFAULTS: CommissionRateFormValues = {
code: '',
enabled: true,
kind: 'percentage',
- value: 10,
+ value: '10',
amounts: {},
bounds: {},
tax_inclusive: false,
@@ -78,7 +87,7 @@ export function commissionRateToFormValues(rate: CommissionRate): CommissionRate
code: rate.code ?? '',
enabled: rate.enabled,
kind: (rate.kind as CommissionRateFormValues['kind']) ?? 'percentage',
- value: Number(rate.value ?? 0),
+ value: rate.value ?? '0',
amounts: Object.fromEntries(
Object.entries(rate.amounts ?? {}).map(([code, amount]) => [code, String(amount ?? '')]),
),
@@ -93,8 +102,7 @@ export function commissionRateToFormValues(rate: CommissionRate): CommissionRate
),
tax_inclusive: rate.tax_inclusive,
include_shipping: rate.include_shipping,
- commission_tax_rate:
- rate.commission_tax_rate == null ? '' : String(Number(rate.commission_tax_rate) * 100),
+ commission_tax_rate: fractionToPercent(rate.commission_tax_rate),
rules: (rate.rules ?? []).map((rule) => {
const preferences = { ...(rule.preferences ?? {}) } as Record<string, unknown>
// Top-level id lists are the picker source of truth; raw ids in
@@ -114,16 +122,13 @@ export function commissionRateToFormValues(rate: CommissionRate): CommissionRate
}
}
-function decimalOrNull(value: string | undefined): number | null {
- const trimmed = value?.trim()
- return trimmed ? Number(trimmed) : null
+function decimalOrNull(value: string | undefined): string | null {
+ return value?.trim() || null
}
export function commissionRateValuesToParams(
v: CommissionRateFormValues,
): CommissionRateCreateParams & CommissionRateUpdateParams {
- const taxPercentage = decimalOrNull(v.commission_tax_rate)
-
return {
name: v.name,
code: blankToNull(v.code),
@@ -154,7 +159,7 @@ export function commissionRateValuesToParams(
.filter((entry) => {
const [currencyCode, bound] = entry as [
string,
- { min_amount: number | null; max_amount: number | null },
+ { min_amount: string | null; max_amount: string | null },
]
const { min_amount, max_amount } = bound
const hasBound = min_amount !== null || max_amount !== null
@@ -166,7 +171,7 @@ export function commissionRateValuesToParams(
return true
}),
),
- commission_tax_rate: taxPercentage === null ? null : taxPercentage / 100,
+ commission_tax_rate: percentToFraction(v.commission_tax_rate) || null,
rules: v.rules.map((rule) => {
const preferences = { ...rule.preferences }
diff --git a/packages/dashboard/src/schemas/gift-card.ts b/packages/dashboard/src/schemas/gift-card.ts
index d17b140df5..6173b76fce 100644
--- a/packages/dashboard/src/schemas/gift-card.ts
+++ b/packages/dashboard/src/schemas/gift-card.ts
@@ -3,7 +3,7 @@ import type {
GiftCardCreateParams,
GiftCardUpdateParams,
} from '@spree/admin-sdk'
-import { blankToNull, blankToUndefined, i18n } from '@spree/dashboard-core'
+import { blankToNull, blankToUndefined, i18n, isPositiveMoney } from '@spree/dashboard-core'
import { z } from 'zod/v4'
// Mirrors `Spree::Config[:gift_card_batch_limit]`. Hardcoded for now; if the
@@ -17,16 +17,9 @@ const prefixRequired = () => i18n.t('admin.pages.promotions.gift_cards.validatio
const currencyRequired = () =>
i18n.t('admin.pages.promotions.gift_cards.validation.currency_required')
-// Amounts stay STRINGS, from a number input that always yields a canonical
-// value ("49.5"), and are sent as typed. `Number()` is used only to check the
-// value is positive, never to compute or send an amount.
-const positiveAmountString = z.string().refine(
- (s) => {
- const n = Number(s)
- return Number.isFinite(n) && n > 0
- },
- { error: amountPositive },
-)
+// Amounts stay strings, from a number input that always yields a canonical
+// value ("49.5"), and are sent as typed.
+const positiveAmountString = z.string().refine(isPositiveMoney, { error: amountPositive })
export const giftCardCreateFormSchema = z
.object({
diff --git a/packages/dashboard/src/schemas/marketplace.ts b/packages/dashboard/src/schemas/marketplace.ts
index 9f54ed2b81..14fdff8c1c 100644
--- a/packages/dashboard/src/schemas/marketplace.ts
+++ b/packages/dashboard/src/schemas/marketplace.ts
@@ -1,5 +1,11 @@
+import { compareMoney, isDecimalString } from '@spree/admin-sdk'
import { z } from 'zod'
+const nonNegativeDecimal = z
+ .string()
+ .trim()
+ .refine((value) => isDecimalString(value) && !value.startsWith('-'))
+
/** How often a marketplace settles its sellers, unless one carries its own. */
export const PAYOUT_SCHEDULE_INTERVALS = [
'daily',
@@ -14,22 +20,17 @@ export const marketplaceSettingsFormSchema = z.object({
// settles by hand.
preferred_payout_provider: z.string(),
preferred_default_payouts_schedule_interval: z.enum(PAYOUT_SCHEDULE_INTERVALS),
- // A number, because the preference is a decimal and the API answers with one.
- preferred_default_minimum_payout_amount: z.coerce.number().min(0),
+ // A canonical decimal string from a number input, sent as typed.
+ preferred_default_minimum_payout_amount: nonNegativeDecimal,
preferred_auto_approve_sellers: z.boolean(),
preferred_auto_approve_seller_products: z.boolean(),
preferred_send_seller_transactional_emails: z.boolean(),
// A percentage, because that is how a merchant states a VAT rate. The
// preference behind it is a fraction bounded at 1, so the field is bounded
- // at 100 and converted on the way in and out.
- commission_tax_rate_percentage: z.coerce.number().min(0).max(100),
+ // at 100 and converted on the way in and out (see `percentToFraction`).
+ commission_tax_rate_percentage: nonNegativeDecimal.refine(
+ (value) => compareMoney(value, '100') <= 0,
+ ),
})
export type MarketplaceSettingsFormValues = z.infer<typeof marketplaceSettingsFormSchema>
-
-/** Rounded because a fraction like 0.077 becomes 7.700000000000001 unrounded. */
-export const fractionToPercentage = (fraction: number | string | null | undefined): number =>
- Math.round(Number(fraction ?? 0) * 100 * 1e6) / 1e6
-
-export const percentageToFraction = (percentage: number): number =>
- Math.round((percentage / 100) * 1e8) / 1e8
diff --git a/packages/dashboard/src/schemas/order.test.ts b/packages/dashboard/src/schemas/order.test.ts
index 8145cbb627..e14501d677 100644
--- a/packages/dashboard/src/schemas/order.test.ts
+++ b/packages/dashboard/src/schemas/order.test.ts
@@ -166,8 +166,8 @@ describe('projections', () => {
it('projects a typed price against the current quantity', () => {
const item = row({ price: '7.20', saved_price: '10.0', quantity: 25 })
- expect(projectedPrice(item)).toBe(7.2)
- expect(projectedLineTotal(item)).toBe(180)
+ expect(projectedPrice(item)).toBe('7.20')
+ expect(projectedLineTotal(item)).toBe('180.00')
})
it('projects a staged revert at the catalog price, not the negotiated one', () => {
@@ -180,8 +180,8 @@ describe('projections', () => {
quantity: 4,
})
- expect(projectedPrice(item)).toBe(25)
- expect(projectedLineTotal(item)).toBe(100)
+ expect(projectedPrice(item)).toBe('25.0')
+ expect(projectedLineTotal(item)).toBe('100.0')
})
it('gives up rather than guessing when a revert has no catalog price', () => {
@@ -192,7 +192,7 @@ describe('projections', () => {
})
it('counts a removed row as nothing', () => {
- expect(projectedLineTotal(row({ removed: true, quantity: 3 }))).toBe(0)
+ expect(projectedLineTotal(row({ removed: true, quantity: 3 }))).toBe('0')
})
it('sums the rows into a subtotal', () => {
@@ -202,7 +202,7 @@ describe('projections', () => {
row({ removed: true, price: '99.0', quantity: 1 }),
]
- expect(projectedSubtotal(items)).toBe(200)
+ expect(projectedSubtotal(items)).toBe('200')
})
// A partial sum rendered as a total is a wrong number stated confidently.
diff --git a/packages/dashboard/src/schemas/order.ts b/packages/dashboard/src/schemas/order.ts
index 284a110b49..f1167a4c55 100644
--- a/packages/dashboard/src/schemas/order.ts
+++ b/packages/dashboard/src/schemas/order.ts
@@ -1,5 +1,16 @@
-import type { LineItem, OrderUpdateParams } from '@spree/admin-sdk'
-import { fulfilledQuantities, type GroupableFulfillment, i18n } from '@spree/dashboard-core'
+import {
+ isDecimalString,
+ type LineItem,
+ multiplyMoney,
+ type OrderUpdateParams,
+ sumMoney,
+} from '@spree/admin-sdk'
+import {
+ formatMoney,
+ fulfilledQuantities,
+ type GroupableFulfillment,
+ i18n,
+} from '@spree/dashboard-core'
import { z } from 'zod/v4'
/**
@@ -166,36 +177,30 @@ export function orderToEditForm(
}
/** Formats a client-computed preview amount; server money arrives as `display_*`. */
-export function formatAmount(amount: number, currency: string): string {
- return new Intl.NumberFormat(i18n.language, { style: 'currency', currency }).format(amount)
+export function formatAmount(amount: string, currency: string): string {
+ return formatMoney(amount, currency, i18n.language)
}
/** The price a row lands on once saved, or null when it cannot be known. */
-export function projectedPrice(item: OrderEditItemValues): number | null {
+export function projectedPrice(item: OrderEditItemValues): string | null {
const source = item.revert_price ? item.catalog_price : item.price
- if (source == null || source === '') return null
-
- const parsed = Number(source)
- return Number.isFinite(parsed) ? parsed : null
+ return isDecimalString(source) ? source : null
}
/** What the line costs after saving; null propagates so a total is never partial. */
-export function projectedLineTotal(item: OrderEditItemValues): number | null {
- if (item.removed) return 0
+export function projectedLineTotal(item: OrderEditItemValues): string | null {
+ if (item.removed) return '0'
const price = projectedPrice(item)
- return price === null ? null : price * item.quantity
+ return price === null || !Number.isInteger(item.quantity)
+ ? null
+ : multiplyMoney(price, item.quantity)
}
/** Projected item subtotal; null if any row is unprojectable. */
-export function projectedSubtotal(items: OrderEditItemValues[]): number | null {
- let sum = 0
- for (const item of items) {
- const total = projectedLineTotal(item)
- if (total === null) return null
- sum += total
- }
- return sum
+export function projectedSubtotal(items: OrderEditItemValues[]): string | null {
+ const totals = items.map(projectedLineTotal)
+ return totals.includes(null) ? null : sumMoney(totals)
}
export type OrderItemsPayload = NonNullable<OrderUpdateParams['items']>
diff --git a/packages/dashboard/src/schemas/price-list.ts b/packages/dashboard/src/schemas/price-list.ts
index 4116f4d1bb..2464d67e25 100644
--- a/packages/dashboard/src/schemas/price-list.ts
+++ b/packages/dashboard/src/schemas/price-list.ts
@@ -4,7 +4,13 @@ import type {
PriceListUpdateParams,
PriceRule,
} from '@spree/admin-sdk'
-import { blankToNull, defaultPreferences } from '@spree/dashboard-core'
+import { isDecimalString, isZeroMoney } from '@spree/admin-sdk'
+import {
+ blankToNull,
+ defaultPreferences,
+ isPositiveMoney,
+ shiftDecimalPoint,
+} from '@spree/dashboard-core'
import { requiredMessage } from '@spree/dashboard-ui'
import i18n from 'i18next'
import { z } from 'zod/v4'
@@ -133,10 +139,10 @@ export const priceListFormSchema = z
* now: a percentage adjustment is valid only on a list a catalog owns, so
* the standalone editor no longer offers it.
*/
-export function parsePercentage(value: string | undefined): number | null {
- if (!value?.trim()) return null
- const parsed = Number(value)
- return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+export function parsePercentage(value: string | undefined): string | null {
+ const trimmed = value?.trim()
+ // Rewritten without trailing zeros, so "5.0" and "5" are one percentage.
+ return isPositiveMoney(trimmed) ? shiftDecimalPoint(trimmed as string, 0) : null
}
/**
@@ -183,18 +189,18 @@ export function adjustmentFormValues(percentage: string | null | undefined): {
adjustment_direction: AdjustmentDirection
adjustment_magnitude: string
} {
- const parsed = percentage == null || percentage === '' ? null : Number(percentage)
// Zero is no adjustment, and the form's own rules require a magnitude
// above zero for automatic mode — loading it as automatic would leave the
// page unsaveable until the user noticed the error.
- if (parsed === null || !Number.isFinite(parsed) || parsed === 0) {
+ if (!isDecimalString(percentage) || isZeroMoney(percentage)) {
return { pricing_mode: 'fixed', adjustment_direction: 'decrease', adjustment_magnitude: '' }
}
+ const negative = percentage.startsWith('-')
return {
pricing_mode: 'automatic',
- adjustment_direction: parsed < 0 ? 'decrease' : 'increase',
- adjustment_magnitude: String(Math.abs(parsed)),
+ adjustment_direction: negative ? 'decrease' : 'increase',
+ adjustment_magnitude: shiftDecimalPoint(negative ? percentage.slice(1) : percentage, 0),
}
}
diff --git a/packages/dashboard/src/schemas/tax-rate.ts b/packages/dashboard/src/schemas/tax-rate.ts
index d8a3466da4..dd42dd09b3 100644
--- a/packages/dashboard/src/schemas/tax-rate.ts
+++ b/packages/dashboard/src/schemas/tax-rate.ts
@@ -1,12 +1,17 @@
-import type { TaxRateParams } from '@spree/admin-sdk'
+import { compareMoney, type TaxRateParams } from '@spree/admin-sdk'
import { blankToNull } from '@spree/dashboard-core'
import { requiredMessage } from '@spree/dashboard-ui'
import { z } from 'zod/v4'
export const taxRateFormSchema = z.object({
name: z.string().min(1, { error: requiredMessage('name') }),
- // The merchant types a percentage (20), the API stores a fraction (0.2).
- amount_percentage: z.coerce.number().min(0).max(100),
+ // The merchant types a percentage (20); the API converts it to the fraction it stores.
+ rate_percent: z
+ .string()
+ .regex(/^\d+(\.\d+)?$/, { error: requiredMessage('tax_rate.amount') })
+ .refine((value) => compareMoney(value, '100') <= 0, {
+ error: requiredMessage('tax_rate.amount'),
+ }),
// Required: a rate always taxes exactly one category.
tax_category_id: z.string().min(1, { error: requiredMessage('tax_rate.tax_category_id') }),
// Empty means the rate applies everywhere, so neither field is required.
@@ -20,7 +25,7 @@ export type TaxRateFormValues = z.infer<typeof taxRateFormSchema>
export const TAX_RATE_DEFAULTS: TaxRateFormValues = {
name: '',
- amount_percentage: 0,
+ rate_percent: '0',
tax_category_id: '',
country_code: '',
state_code: '',
@@ -36,7 +41,7 @@ export const TAX_RATE_DEFAULTS: TaxRateFormValues = {
export function taxRateValuesToParams(values: TaxRateFormValues): TaxRateParams {
return {
name: values.name,
- amount: values.amount_percentage / 100,
+ rate_percent: values.rate_percent,
tax_category_id: values.tax_category_id,
country_code: blankToNull(values.country_code),
state_code: blankToNull(values.state_code),
diff --git a/packages/dashboard/src/tables/tax-rates.tsx b/packages/dashboard/src/tables/tax-rates.tsx
index 79e89768c1..aead6b989d 100644
--- a/packages/dashboard/src/tables/tax-rates.tsx
+++ b/packages/dashboard/src/tables/tax-rates.tsx
@@ -30,8 +30,7 @@ defineTable<TaxRate>('tax-rates', {
label: i18n.t('admin.fields.tax_rate.amount.label'),
sortable: true,
default: true,
- render: (taxRate) =>
- taxRate.amount_percentage === null ? '—' : `${taxRate.amount_percentage}%`,
+ render: (taxRate) => (taxRate.rate_percent == null ? '—' : `${taxRate.rate_percent}%`),
},
{
key: 'country_code',
diff --git a/packages/sdk-core/src/currency-exponents.ts b/packages/sdk-core/src/currency-exponents.ts
new file mode 100644
index 0000000000..d49a28e524
--- /dev/null
+++ b/packages/sdk-core/src/currency-exponents.ts
@@ -0,0 +1,182 @@
+// Generated from spree/core/config/currency_exponents.json (ISO 4217 minor
+// units). Spree reads the same table; a test fails if the two drift apart.
+export const CURRENCY_EXPONENTS: Readonly<Record<string, number>> = {
+ AED: 2,
+ AFN: 2,
+ ALL: 2,
+ AMD: 2,
+ ANG: 2,
+ AOA: 2,
+ ARS: 2,
+ AUD: 2,
+ AWG: 2,
+ AZN: 2,
+ BAM: 2,
+ BBD: 2,
+ BDT: 2,
+ BGN: 2,
+ BHD: 3,
+ BIF: 0,
+ BMD: 2,
+ BND: 2,
+ BOB: 2,
+ BRL: 2,
+ BSD: 2,
+ BTN: 2,
+ BWP: 2,
+ BYN: 2,
+ BYR: 0,
+ BZD: 2,
+ CAD: 2,
+ CDF: 2,
+ CHF: 2,
+ CLF: 4,
+ CLP: 0,
+ CNY: 2,
+ COP: 2,
+ CRC: 2,
+ CUC: 2,
+ CUP: 2,
+ CVE: 2,
+ CZK: 2,
+ DJF: 0,
+ DKK: 2,
+ DOP: 2,
+ DZD: 2,
+ EEK: 2,
+ EGP: 2,
+ ERN: 2,
+ ETB: 2,
+ EUR: 2,
+ FJD: 2,
+ FKP: 2,
+ GBP: 2,
+ GEL: 2,
+ GHS: 2,
+ GIP: 2,
+ GMD: 2,
+ GNF: 0,
+ GTQ: 2,
+ GYD: 2,
+ HKD: 2,
+ HNL: 2,
+ HRK: 2,
+ HTG: 2,
+ HUF: 2,
+ IDR: 2,
+ ILS: 2,
+ INR: 2,
+ IQD: 3,
+ IRR: 2,
+ ISK: 0,
+ JMD: 2,
+ JOD: 3,
+ JPY: 0,
+ KES: 2,
+ KGS: 2,
+ KHR: 2,
+ KMF: 0,
+ KPW: 2,
+ KRW: 0,
+ KWD: 3,
+ KYD: 2,
+ KZT: 2,
+ LAK: 2,
+ LBP: 2,
+ LKR: 2,
+ LRD: 2,
+ LSL: 2,
+ LTL: 2,
+ LVL: 2,
+ LYD: 3,
+ MAD: 2,
+ MDL: 2,
+ MGA: 2,
+ MKD: 2,
+ MMK: 2,
+ MNT: 2,
+ MOP: 2,
+ MRO: 2,
+ MRU: 2,
+ MTL: 2,
+ MUR: 2,
+ MVR: 2,
+ MWK: 2,
+ MXN: 2,
+ MYR: 2,
+ MZN: 2,
+ NAD: 2,
+ NGN: 2,
+ NIO: 2,
+ NOK: 2,
+ NPR: 2,
+ NZD: 2,
+ OMR: 3,
+ PAB: 2,
+ PEN: 2,
+ PGK: 2,
+ PHP: 2,
+ PKR: 2,
+ PLN: 2,
+ PYG: 0,
+ QAR: 2,
+ RON: 2,
+ RSD: 2,
+ RUB: 2,
+ RWF: 0,
+ SAR: 2,
+ SBD: 2,
+ SCR: 2,
+ SDG: 2,
+ SEK: 2,
+ SGD: 2,
+ SHP: 2,
+ SKK: 2,
+ SLE: 2,
+ SLL: 2,
+ SOS: 2,
+ SRD: 2,
+ SSP: 2,
+ STD: 2,
+ STN: 2,
+ SVC: 2,
+ SYP: 2,
+ SZL: 2,
+ THB: 2,
+ TJS: 2,
+ TMM: 2,
+ TMT: 2,
+ TND: 3,
+ TOP: 2,
+ TRY: 2,
+ TTD: 2,
+ TWD: 2,
+ TZS: 2,
+ UAH: 2,
+ UGX: 0,
+ USD: 2,
+ UYI: 0,
+ UYU: 2,
+ UYW: 4,
+ UZS: 2,
+ VED: 2,
+ VEF: 2,
+ VES: 2,
+ VND: 0,
+ VUV: 0,
+ WST: 2,
+ XAF: 0,
+ XCD: 2,
+ XCG: 2,
+ XOF: 0,
+ XPF: 0,
+ YER: 2,
+ ZAR: 2,
+ ZMK: 2,
+ ZMW: 2,
+ ZWD: 2,
+ ZWG: 2,
+ ZWL: 2,
+ ZWN: 2,
+ ZWR: 2,
+}
diff --git a/packages/sdk-core/src/index.ts b/packages/sdk-core/src/index.ts
index 63d81a1fad..c0479cdb66 100644
--- a/packages/sdk-core/src/index.ts
+++ b/packages/sdk-core/src/index.ts
@@ -3,6 +3,17 @@
export type { ResolvedRetryConfig } from './helpers'
// Helpers
export { getParams, resolveRetryConfig } from './helpers'
+// Money
+export {
+ compareMoney,
+ decimalPlaces,
+ isDecimalString,
+ isZeroMoney,
+ multiplyMoney,
+ negateMoney,
+ subtractMoney,
+ sumMoney,
+} from './money'
// Params
export { transformListParams } from './params'
export type {
diff --git a/packages/sdk-core/src/money.ts b/packages/sdk-core/src/money.ts
new file mode 100644
index 0000000000..dd20a5bd3b
--- /dev/null
+++ b/packages/sdk-core/src/money.ts
@@ -0,0 +1,99 @@
+import { CURRENCY_EXPONENTS } from './currency-exponents'
+
+// Money arrives from the API as canonical decimal strings ("1234.56"). These
+// helpers work on those strings through scaled bigints, so no amount passes
+// through a JS number on the way to a comparison or a sum.
+
+const CANONICAL = /^-?\d+(\.\d+)?$/
+
+interface Scaled {
+ units: bigint
+ scale: number
+}
+
+function parse(value: string): Scaled {
+ if (!CANONICAL.test(value)) throw new Error(`Not a decimal string: ${JSON.stringify(value)}`)
+
+ const negative = value.startsWith('-')
+ const [whole, fraction = ''] = (negative ? value.slice(1) : value).split('.')
+ const units = BigInt(whole + fraction)
+ return { units: negative ? -units : units, scale: fraction.length }
+}
+
+function rescale(scaled: Scaled, scale: number): bigint {
+ return scaled.units * 10n ** BigInt(scale - scaled.scale)
+}
+
+function write(units: bigint, scale: number, places = 0): string {
+ const negative = units < 0n
+ const digits = (negative ? -units : units).toString().padStart(scale + 1, '0')
+ const whole = scale > 0 ? digits.slice(0, -scale) : digits
+ let fraction = scale > 0 ? digits.slice(-scale) : ''
+ fraction = fraction.replace(/0+$/, '').padEnd(places, '0')
+ const text = fraction ? `${whole}.${fraction}` : whole
+ return negative && /[1-9]/.test(text) ? `-${text}` : text
+}
+
+/**
+ * The decimals amounts in a currency are written with (ISO 4217): 2 for USD,
+ * 0 for JPY, 3 for KWD. An unknown code answers 2.
+ */
+export function decimalPlaces(currency: string): number {
+ return CURRENCY_EXPONENTS[currency.toUpperCase()] ?? 2
+}
+
+/** Whether a value is a canonical decimal string such as "19.99". */
+export function isDecimalString(value: unknown): value is string {
+ return typeof value === 'string' && CANONICAL.test(value)
+}
+
+/** -1, 0 or 1, comparing two decimal strings exactly. */
+export function compareMoney(a: string, b: string): -1 | 0 | 1 {
+ const left = parse(a)
+ const right = parse(b)
+ const scale = Math.max(left.scale, right.scale)
+ const difference = rescale(left, scale) - rescale(right, scale)
+ return difference === 0n ? 0 : difference > 0n ? 1 : -1
+}
+
+/** Whether a decimal string is zero ("0", "0.00", "-0.0"). Blank counts as zero. */
+export function isZeroMoney(value: string | null | undefined): boolean {
+ if (value == null || value === '') return true
+ return parse(value).units === 0n
+}
+
+/**
+ * Adds decimal strings exactly. Blank values count as zero. With a currency,
+ * the result is written with that currency's decimals ("10.00").
+ */
+export function sumMoney(values: Array<string | null | undefined>, currency?: string): string {
+ const present = values
+ .filter((value): value is string => value != null && value !== '')
+ .map(parse)
+ const scale = Math.max(
+ 0,
+ currency ? decimalPlaces(currency) : 0,
+ ...present.map((value) => value.scale),
+ )
+ const total = present.reduce((sum, value) => sum + rescale(value, scale), 0n)
+ return write(total, scale, currency ? decimalPlaces(currency) : 0)
+}
+
+/** a minus b, exactly. */
+export function subtractMoney(a: string, b: string, currency?: string): string {
+ return sumMoney([a, negateMoney(b)], currency)
+}
+
+/** The decimal string with its sign flipped. */
+export function negateMoney(value: string): string {
+ const { units, scale } = parse(value)
+ return write(-units, scale, scale)
+}
+
+/** A decimal string times a whole quantity, exactly. */
+export function multiplyMoney(value: string, quantity: number, currency?: string): string {
+ if (!Number.isInteger(quantity)) throw new Error(`Quantity must be a whole number: ${quantity}`)
+
+ const { units, scale } = parse(value)
+ return write(units * BigInt(quantity), scale, currency ? decimalPlaces(currency) : scale)
+}
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index b8a9815499..b8659d8b20 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -2,7 +2,17 @@
export type { RequestFn, RequestOptions, RetryConfig } from '@spree/sdk-core'
// Request infrastructure (re-export from sdk-core)
-export { SpreeError } from '@spree/sdk-core'
+export {
+ compareMoney,
+ decimalPlaces,
+ isDecimalString,
+ isZeroMoney,
+ multiplyMoney,
+ negateMoney,
+ SpreeError,
+ subtractMoney,
+ sumMoney,
+} from '@spree/sdk-core'
export type { Client, ClientConfig } from './client'
export { createClient } from './client'
export { isOrderGroup } from './order-group'
diff --git a/packages/sdk/src/types/generated/Cart.ts b/packages/sdk/src/types/generated/Cart.ts
index b8c5ac03be..6136faf85b 100644
--- a/packages/sdk/src/types/generated/Cart.ts
+++ b/packages/sdk/src/types/generated/Cart.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 03ae46084646eeb8994cb245a69a5846
+// Typelizer digest f720d8e3149a958aa0cede08e8c4f9eb
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {FreightSummary, AppliedPromotion, Fee, LineItem, Fulfillment, Payment, Address, PaymentMethod, GiftCard, Market} from '@/types'
@@ -51,8 +51,8 @@ interface Cart {
current_step: string;
completed_steps: Array<string>;
requirements: Array<{step: string, field: string, code: string, message: string}>;
- order_minimum: number | null;
- order_minimum_shortfall: number | null;
+ order_minimum: string | null;
+ order_minimum_shortfall: string | null;
below_order_minimum: boolean | null;
freight_summary: FreightSummary | null;
shipping_eq_billing_address: boolean;
diff --git a/packages/sdk/src/types/generated/Claim.ts b/packages/sdk/src/types/generated/Claim.ts
index cf88f85d13..9d9fbecd25 100644
--- a/packages/sdk/src/types/generated/Claim.ts
+++ b/packages/sdk/src/types/generated/Claim.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 4493963aa63a176ee17920416f1c3692
+// Typelizer digest 758cba4d74ea400f8baa68702380a774
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {ClaimReason, ClaimLineItem, ClaimStatus} from '@/types'
@@ -10,8 +10,8 @@ interface Claim {
resolution: string | null;
order_id: string | null;
reason_id: string | null;
- refund_total: string;
- display_refund_total: string;
+ refund_total: string | null;
+ display_refund_total: string | null;
approved_at: string | null;
resolved_at: string | null;
denied_at: string | null;
diff --git a/packages/sdk/src/types/generated/ClaimLineItem.ts b/packages/sdk/src/types/generated/ClaimLineItem.ts
index a937c2fc46..7c1ca0a33b 100644
--- a/packages/sdk/src/types/generated/ClaimLineItem.ts
+++ b/packages/sdk/src/types/generated/ClaimLineItem.ts
@@ -1,4 +1,4 @@
-// Typelizer digest e24c9db5294c44cf9f5907e3fa9d5615
+// Typelizer digest 080a40c6b7549a5f37cc3f2b8ea18974
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Variant} from '@/types'
@@ -8,13 +8,13 @@ interface ClaimLineItem {
quantity: number;
send_replacement: boolean;
description: string | null;
- refund_amount: string;
- paid_amount: string;
- pre_tax_amount: string;
- included_tax_total: string;
- additional_tax_total: string;
- tax_total: string;
- display_refund_amount: string;
+ refund_amount: string | null;
+ paid_amount: string | null;
+ pre_tax_amount: string | null;
+ included_tax_total: string | null;
+ additional_tax_total: string | null;
+ tax_total: string | null;
+ display_refund_amount: string | null;
variant_id: string | null;
replacement_variant_id: string | null;
line_item_id: string | null;
diff --git a/packages/sdk/src/types/generated/Currency.ts b/packages/sdk/src/types/generated/Currency.ts
index 5abf2583a7..0f41222630 100644
--- a/packages/sdk/src/types/generated/Currency.ts
+++ b/packages/sdk/src/types/generated/Currency.ts
@@ -1,4 +1,4 @@
-// Typelizer digest eb653be88376e1ccf9516573b558cf65
+// Typelizer digest 192978bfebb834035dc1d1035c54fb18
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -6,6 +6,7 @@ interface Currency {
iso_code: string;
name: string;
symbol: string;
+ decimal_places: number;
}
export default Currency;
diff --git a/packages/sdk/src/types/generated/DeliveryRate.ts b/packages/sdk/src/types/generated/DeliveryRate.ts
index 917a1e052e..a913a46975 100644
--- a/packages/sdk/src/types/generated/DeliveryRate.ts
+++ b/packages/sdk/src/types/generated/DeliveryRate.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 59fe4790052c2eac795e39be500d4d4d
+// Typelizer digest 18b6a19b4956210ad3039ed8f4d99f34
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {FreightSummary, DeliveryMethod} from '@/types'
@@ -8,21 +8,21 @@ interface DeliveryRate {
delivery_method_id: string;
name: string;
selected: boolean;
- cost: string;
- total: string;
- additional_tax_total: string;
- included_tax_total: string;
- tax_total: string;
+ cost: string | null;
+ total: string | null;
+ additional_tax_total: string | null;
+ included_tax_total: string | null;
+ tax_total: string | null;
carrier: string | null;
service_level: string | null;
estimated_delivery_date: string | null;
unpriced: boolean;
freight_summary: FreightSummary | null;
- display_cost: string;
- display_total: string;
- display_additional_tax_total: string;
- display_included_tax_total: string;
- display_tax_total: string;
+ display_cost: string | null;
+ display_total: string | null;
+ display_additional_tax_total: string | null;
+ display_included_tax_total: string | null;
+ display_tax_total: string | null;
delivery_method: DeliveryMethod;
}
diff --git a/packages/sdk/src/types/generated/Exchange.ts b/packages/sdk/src/types/generated/Exchange.ts
index a5445bea4f..0e60475b17 100644
--- a/packages/sdk/src/types/generated/Exchange.ts
+++ b/packages/sdk/src/types/generated/Exchange.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 375a5878644597b35562d8e169371142
+// Typelizer digest 9f5051c2c8bd138a33c82a1b1e1fbad3
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {ReturnReason, ExchangeLineItem, ExchangeStatus} from '@/types'
@@ -9,8 +9,8 @@ interface Exchange {
status: ExchangeStatus;
order_id: string | null;
reason_id: string | null;
- price_difference: string;
- display_price_difference: string;
+ price_difference: string | null;
+ display_price_difference: string | null;
approved_at: string | null;
received_at: string | null;
fulfilled_at: string | null;
diff --git a/packages/sdk/src/types/generated/ExchangeLineItem.ts b/packages/sdk/src/types/generated/ExchangeLineItem.ts
index 0ced5f3bd0..a02812268e 100644
--- a/packages/sdk/src/types/generated/ExchangeLineItem.ts
+++ b/packages/sdk/src/types/generated/ExchangeLineItem.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 5f8ecd026f5f45a9d8ce54629d8fc11f
+// Typelizer digest 10b88d317ca3f8c3738633b1893360c1
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Variant} from '@/types'
@@ -8,11 +8,11 @@ interface ExchangeLineItem {
quantity: number;
received_quantity: number;
resellable: boolean;
- original_price: string;
- new_variant_price: string;
- price_difference: string;
- original_tax_total: string;
- new_tax_total: string;
+ original_price: string | null;
+ new_variant_price: string | null;
+ price_difference: string | null;
+ original_tax_total: string | null;
+ new_tax_total: string | null;
original_variant_id: string | null;
new_variant_id: string | null;
line_item_id: string | null;
diff --git a/packages/sdk/src/types/generated/PaymentSession.ts b/packages/sdk/src/types/generated/PaymentSession.ts
index 1bd58331e9..71470ea5ae 100644
--- a/packages/sdk/src/types/generated/PaymentSession.ts
+++ b/packages/sdk/src/types/generated/PaymentSession.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 90a0440006f62206a9a83da10563f227
+// Typelizer digest f37382488804941aef29390f19d3e21a
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {PaymentMethod, Payment, PaymentSessionStatus} from '@/types'
@@ -11,7 +11,7 @@ interface PaymentSession {
external_data: Record<string, unknown>;
customer_external_id: string | null;
expires_at: string | null;
- amount: string;
+ amount: string | null;
payment_method_id: string;
order_id: string | null;
cart_id: string | null;
diff --git a/packages/sdk/src/types/generated/Price.ts b/packages/sdk/src/types/generated/Price.ts
index 2ce2516faa..b8aca6d779 100644
--- a/packages/sdk/src/types/generated/Price.ts
+++ b/packages/sdk/src/types/generated/Price.ts
@@ -1,14 +1,12 @@
-// Typelizer digest 7a116315f0ab746b716e9f89137a67f0
+// Typelizer digest 486832c830acf82a1754edef271452b9
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface Price {
id: string;
+ currency: string | null;
amount: string | null;
- amount_in_cents: number | null;
compare_at_amount: string | null;
- compare_at_amount_in_cents: number | null;
- currency: string | null;
display_amount: string | null;
display_compare_at_amount: string | null;
price_list_id: string | null;
diff --git a/packages/sdk/src/types/generated/PriceHistory.ts b/packages/sdk/src/types/generated/PriceHistory.ts
index 08a9bc551a..52873033bb 100644
--- a/packages/sdk/src/types/generated/PriceHistory.ts
+++ b/packages/sdk/src/types/generated/PriceHistory.ts
@@ -1,12 +1,11 @@
-// Typelizer digest 82799fb1cdb9d1035174afc6b1613ca8
+// Typelizer digest 5e2279c98b06b1d7edd6179b2023e704
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface PriceHistory {
id: string;
- amount: string;
- amount_in_cents: number;
currency: string;
+ amount: string | null;
display_amount: string;
recorded_at: string;
}
diff --git a/packages/sdk/src/types/generated/ProductFilterPriceRange.ts b/packages/sdk/src/types/generated/ProductFilterPriceRange.ts
index 9399874a7f..d1dde424ec 100644
--- a/packages/sdk/src/types/generated/ProductFilterPriceRange.ts
+++ b/packages/sdk/src/types/generated/ProductFilterPriceRange.ts
@@ -1,12 +1,12 @@
-// Typelizer digest 20a24a200790cfa21c817870c92a59b0
+// Typelizer digest b6efe85fb4f4d2cd1e49361ac4fceca7
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface ProductFilterPriceRange {
id: string;
type: 'price_range';
- min: number;
- max: number;
+ min: string;
+ max: string;
currency: string;
}
diff --git a/packages/sdk/src/types/generated/Return.ts b/packages/sdk/src/types/generated/Return.ts
index 025c9aca7a..ee12d8fb9c 100644
--- a/packages/sdk/src/types/generated/Return.ts
+++ b/packages/sdk/src/types/generated/Return.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 1dde8e686110e363a5f066038b496180
+// Typelizer digest 629e0b8ed448a349cd291939e5a51b69
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {ReturnReason, ReturnLineItem, ReturnStatus} from '@/types'
@@ -9,10 +9,10 @@ interface Return {
status: ReturnStatus;
order_id: string | null;
reason_id: string | null;
- refund_total: string;
- display_refund_total: string;
- refund_tax_total: string;
- display_refund_tax_total: string;
+ refund_total: string | null;
+ display_refund_total: string | null;
+ refund_tax_total: string | null;
+ display_refund_tax_total: string | null;
approved_at: string | null;
received_at: string | null;
refunded_at: string | null;
diff --git a/packages/sdk/src/types/generated/ReturnLineItem.ts b/packages/sdk/src/types/generated/ReturnLineItem.ts
index e89f0f3c63..45c0c82570 100644
--- a/packages/sdk/src/types/generated/ReturnLineItem.ts
+++ b/packages/sdk/src/types/generated/ReturnLineItem.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 52618021396b2aa98ecac943cc724a39
+// Typelizer digest 714e4f5c56fafb4983c96cdfc04aa471
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Variant} from '@/types'
@@ -8,14 +8,14 @@ interface ReturnLineItem {
quantity: number;
received_quantity: number;
resellable: boolean;
- pre_tax_amount: string;
- display_pre_tax_amount: string;
- included_tax_total: string;
- additional_tax_total: string;
- tax_total: string;
- display_tax_total: string;
- refund_amount: string;
- display_refund_amount: string;
+ pre_tax_amount: string | null;
+ display_pre_tax_amount: string | null;
+ included_tax_total: string | null;
+ additional_tax_total: string | null;
+ tax_total: string | null;
+ display_tax_total: string | null;
+ refund_amount: string | null;
+ display_refund_amount: string | null;
variant_id: string | null;
line_item_id: string | null;
fulfillment_item_id: string | null;
diff --git a/packages/sdk/src/types/generated/StoreCredit.ts b/packages/sdk/src/types/generated/StoreCredit.ts
index 5b5fbabb23..e90a01675f 100644
--- a/packages/sdk/src/types/generated/StoreCredit.ts
+++ b/packages/sdk/src/types/generated/StoreCredit.ts
@@ -1,15 +1,15 @@
-// Typelizer digest c55751f6541b1ddc58f1cbbd26b7aadf
+// Typelizer digest 250523f4e58d2c266aecc3c7d388d257
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface StoreCredit {
id: string;
- amount: string;
- amount_used: string;
- amount_remaining: string;
- display_amount: string;
- display_amount_used: string;
- display_amount_remaining: string;
+ amount: string | null;
+ amount_used: string | null;
+ amount_remaining: string | null;
+ display_amount: string | null;
+ display_amount_used: string | null;
+ display_amount_remaining: string | null;
currency: string;
}
diff --git a/packages/sdk/src/types/generated/StoreCreditEvent.ts b/packages/sdk/src/types/generated/StoreCreditEvent.ts
index 3cebb62646..baa4f262ec 100644
--- a/packages/sdk/src/types/generated/StoreCreditEvent.ts
+++ b/packages/sdk/src/types/generated/StoreCreditEvent.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 5673dc2c7d22616c9352d8335ab20c2c
+// Typelizer digest b78f2e36d2c39d8870c913dbba1c7f60
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -7,8 +7,8 @@ interface StoreCreditEvent {
action: string;
authorization_code: string | null;
display_action: string | null;
- amount: string;
- display_amount: string;
+ amount: string | null;
+ display_amount: string | null;
created_at: string;
}
diff --git a/packages/sdk/src/types/generated/TaxLine.ts b/packages/sdk/src/types/generated/TaxLine.ts
index f2bd5e4d73..0e8d8e381a 100644
--- a/packages/sdk/src/types/generated/TaxLine.ts
+++ b/packages/sdk/src/types/generated/TaxLine.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 8b56687adf279133bd7edbbf4edd6c6c
+// Typelizer digest e62f5f22e0ed73c0ae9ad1087303d82b
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -7,7 +7,7 @@ interface TaxLine {
label: string;
included: boolean;
credit: boolean;
- rate: string;
+ rate: string | null;
tax_rate_id: string | null;
line_item_id: string | null;
fulfillment_id: string | null;
diff --git a/packages/sdk/src/zod/generated/Cart.ts b/packages/sdk/src/zod/generated/Cart.ts
index 32ebb3d47b..362d5f0bb4 100644
--- a/packages/sdk/src/zod/generated/Cart.ts
+++ b/packages/sdk/src/zod/generated/Cart.ts
@@ -59,8 +59,8 @@ export const CartSchema = z.object({
current_step: z.string(),
completed_steps: z.array(z.string()),
requirements: z.array(z.object({ step: z.string(), field: z.string(), code: z.string(), message: z.string() })),
- order_minimum: z.number().nullable(),
- order_minimum_shortfall: z.number().nullable(),
+ order_minimum: z.string().nullable(),
+ order_minimum_shortfall: z.string().nullable(),
below_order_minimum: z.boolean().nullable(),
freight_summary: FreightSummarySchema.nullable(),
shipping_eq_billing_address: z.boolean(),
diff --git a/packages/sdk/src/zod/generated/Claim.ts b/packages/sdk/src/zod/generated/Claim.ts
index dde7be9c25..27787ae426 100644
--- a/packages/sdk/src/zod/generated/Claim.ts
+++ b/packages/sdk/src/zod/generated/Claim.ts
@@ -10,8 +10,8 @@ export const ClaimSchema = z.object({
resolution: z.string().nullable(),
order_id: z.string().nullable(),
reason_id: z.string().nullable(),
- refund_total: z.string(),
- display_refund_total: z.string(),
+ refund_total: z.string().nullable(),
+ display_refund_total: z.string().nullable(),
approved_at: z.string().nullable(),
resolved_at: z.string().nullable(),
denied_at: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/ClaimLineItem.ts b/packages/sdk/src/zod/generated/ClaimLineItem.ts
index 1c80fbd1de..819e84a485 100644
--- a/packages/sdk/src/zod/generated/ClaimLineItem.ts
+++ b/packages/sdk/src/zod/generated/ClaimLineItem.ts
@@ -7,13 +7,13 @@ export const ClaimLineItemSchema = z.object({
quantity: z.number(),
send_replacement: z.boolean(),
description: z.string().nullable(),
- refund_amount: z.string(),
- paid_amount: z.string(),
- pre_tax_amount: z.string(),
- included_tax_total: z.string(),
- additional_tax_total: z.string(),
- tax_total: z.string(),
- display_refund_amount: z.string(),
+ refund_amount: z.string().nullable(),
+ paid_amount: z.string().nullable(),
+ pre_tax_amount: z.string().nullable(),
+ included_tax_total: z.string().nullable(),
+ additional_tax_total: z.string().nullable(),
+ tax_total: z.string().nullable(),
+ display_refund_amount: z.string().nullable(),
variant_id: z.string().nullable(),
replacement_variant_id: z.string().nullable(),
line_item_id: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/Currency.ts b/packages/sdk/src/zod/generated/Currency.ts
index b5349b2f3a..9e393208e3 100644
--- a/packages/sdk/src/zod/generated/Currency.ts
+++ b/packages/sdk/src/zod/generated/Currency.ts
@@ -5,6 +5,7 @@ export const CurrencySchema = z.object({
iso_code: z.string(),
name: z.string(),
symbol: z.string(),
+ decimal_places: z.number(),
});
export type Currency = z.infer<typeof CurrencySchema>;
diff --git a/packages/sdk/src/zod/generated/DeliveryRate.ts b/packages/sdk/src/zod/generated/DeliveryRate.ts
index c7ccf27f61..f0d00514df 100644
--- a/packages/sdk/src/zod/generated/DeliveryRate.ts
+++ b/packages/sdk/src/zod/generated/DeliveryRate.ts
@@ -8,21 +8,21 @@ export const DeliveryRateSchema = z.object({
delivery_method_id: z.string(),
name: z.string(),
selected: z.boolean(),
- cost: z.string(),
- total: z.string(),
- additional_tax_total: z.string(),
- included_tax_total: z.string(),
- tax_total: z.string(),
+ cost: z.string().nullable(),
+ total: z.string().nullable(),
+ additional_tax_total: z.string().nullable(),
+ included_tax_total: z.string().nullable(),
+ tax_total: z.string().nullable(),
carrier: z.string().nullable(),
service_level: z.string().nullable(),
estimated_delivery_date: z.string().nullable(),
unpriced: z.boolean(),
freight_summary: FreightSummarySchema.nullable(),
- display_cost: z.string(),
- display_total: z.string(),
- display_additional_tax_total: z.string(),
- display_included_tax_total: z.string(),
- display_tax_total: z.string(),
+ display_cost: z.string().nullable(),
+ display_total: z.string().nullable(),
+ display_additional_tax_total: z.string().nullable(),
+ display_included_tax_total: z.string().nullable(),
+ display_tax_total: z.string().nullable(),
delivery_method: DeliveryMethodSchema,
});
diff --git a/packages/sdk/src/zod/generated/Exchange.ts b/packages/sdk/src/zod/generated/Exchange.ts
index df0b577777..8f6fb87e7d 100644
--- a/packages/sdk/src/zod/generated/Exchange.ts
+++ b/packages/sdk/src/zod/generated/Exchange.ts
@@ -9,8 +9,8 @@ export const ExchangeSchema = z.object({
status: z.string(),
order_id: z.string().nullable(),
reason_id: z.string().nullable(),
- price_difference: z.string(),
- display_price_difference: z.string(),
+ price_difference: z.string().nullable(),
+ display_price_difference: z.string().nullable(),
approved_at: z.string().nullable(),
received_at: z.string().nullable(),
fulfilled_at: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/ExchangeLineItem.ts b/packages/sdk/src/zod/generated/ExchangeLineItem.ts
index 57c800737c..c2359d7425 100644
--- a/packages/sdk/src/zod/generated/ExchangeLineItem.ts
+++ b/packages/sdk/src/zod/generated/ExchangeLineItem.ts
@@ -7,11 +7,11 @@ export const ExchangeLineItemSchema = z.object({
quantity: z.number(),
received_quantity: z.number(),
resellable: z.boolean(),
- original_price: z.string(),
- new_variant_price: z.string(),
- price_difference: z.string(),
- original_tax_total: z.string(),
- new_tax_total: z.string(),
+ original_price: z.string().nullable(),
+ new_variant_price: z.string().nullable(),
+ price_difference: z.string().nullable(),
+ original_tax_total: z.string().nullable(),
+ new_tax_total: z.string().nullable(),
original_variant_id: z.string().nullable(),
new_variant_id: z.string().nullable(),
line_item_id: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/PaymentSession.ts b/packages/sdk/src/zod/generated/PaymentSession.ts
index c4e93f7e85..4a5cf3ca5b 100644
--- a/packages/sdk/src/zod/generated/PaymentSession.ts
+++ b/packages/sdk/src/zod/generated/PaymentSession.ts
@@ -11,7 +11,7 @@ export const PaymentSessionSchema = z.object({
external_data: z.record(z.string(), z.unknown()),
customer_external_id: z.string().nullable(),
expires_at: z.string().nullable(),
- amount: z.string(),
+ amount: z.string().nullable(),
payment_method_id: z.string(),
order_id: z.string().nullable(),
cart_id: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/Price.ts b/packages/sdk/src/zod/generated/Price.ts
index 75f9cfa745..834e31fb10 100644
--- a/packages/sdk/src/zod/generated/Price.ts
+++ b/packages/sdk/src/zod/generated/Price.ts
@@ -3,11 +3,9 @@ import { z } from 'zod';
export const PriceSchema = z.object({
id: z.string(),
+ currency: z.string().nullable(),
amount: z.string().nullable(),
- amount_in_cents: z.number().nullable(),
compare_at_amount: z.string().nullable(),
- compare_at_amount_in_cents: z.number().nullable(),
- currency: z.string().nullable(),
display_amount: z.string().nullable(),
display_compare_at_amount: z.string().nullable(),
price_list_id: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/PriceHistory.ts b/packages/sdk/src/zod/generated/PriceHistory.ts
index 91ce6f0d19..48f3be55e0 100644
--- a/packages/sdk/src/zod/generated/PriceHistory.ts
+++ b/packages/sdk/src/zod/generated/PriceHistory.ts
@@ -3,9 +3,8 @@ import { z } from 'zod';
export const PriceHistorySchema = z.object({
id: z.string(),
- amount: z.string(),
- amount_in_cents: z.number(),
currency: z.string(),
+ amount: z.string().nullable(),
display_amount: z.string(),
recorded_at: z.string(),
});
diff --git a/packages/sdk/src/zod/generated/ProductFilterPriceRange.ts b/packages/sdk/src/zod/generated/ProductFilterPriceRange.ts
index 24e2376299..2b859ae962 100644
--- a/packages/sdk/src/zod/generated/ProductFilterPriceRange.ts
+++ b/packages/sdk/src/zod/generated/ProductFilterPriceRange.ts
@@ -4,8 +4,8 @@ import { z } from 'zod';
export const ProductFilterPriceRangeSchema = z.object({
id: z.string(),
type: z.literal('price_range'),
- min: z.number(),
- max: z.number(),
+ min: z.string(),
+ max: z.string(),
currency: z.string(),
});
diff --git a/packages/sdk/src/zod/generated/Return.ts b/packages/sdk/src/zod/generated/Return.ts
index d40ecd8ba5..86eac303fb 100644
--- a/packages/sdk/src/zod/generated/Return.ts
+++ b/packages/sdk/src/zod/generated/Return.ts
@@ -9,10 +9,10 @@ export const ReturnSchema = z.object({
status: z.string(),
order_id: z.string().nullable(),
reason_id: z.string().nullable(),
- refund_total: z.string(),
- display_refund_total: z.string(),
- refund_tax_total: z.string(),
- display_refund_tax_total: z.string(),
+ refund_total: z.string().nullable(),
+ display_refund_total: z.string().nullable(),
+ refund_tax_total: z.string().nullable(),
+ display_refund_tax_total: z.string().nullable(),
approved_at: z.string().nullable(),
received_at: z.string().nullable(),
refunded_at: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/ReturnLineItem.ts b/packages/sdk/src/zod/generated/ReturnLineItem.ts
index 72091a2151..da764c5e9e 100644
--- a/packages/sdk/src/zod/generated/ReturnLineItem.ts
+++ b/packages/sdk/src/zod/generated/ReturnLineItem.ts
@@ -7,14 +7,14 @@ export const ReturnLineItemSchema = z.object({
quantity: z.number(),
received_quantity: z.number(),
resellable: z.boolean(),
- pre_tax_amount: z.string(),
- display_pre_tax_amount: z.string(),
- included_tax_total: z.string(),
- additional_tax_total: z.string(),
- tax_total: z.string(),
- display_tax_total: z.string(),
- refund_amount: z.string(),
- display_refund_amount: z.string(),
+ pre_tax_amount: z.string().nullable(),
+ display_pre_tax_amount: z.string().nullable(),
+ included_tax_total: z.string().nullable(),
+ additional_tax_total: z.string().nullable(),
+ tax_total: z.string().nullable(),
+ display_tax_total: z.string().nullable(),
+ refund_amount: z.string().nullable(),
+ display_refund_amount: z.string().nullable(),
variant_id: z.string().nullable(),
line_item_id: z.string().nullable(),
fulfillment_item_id: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/StoreCredit.ts b/packages/sdk/src/zod/generated/StoreCredit.ts
index f9f35b39e7..84c755d84a 100644
--- a/packages/sdk/src/zod/generated/StoreCredit.ts
+++ b/packages/sdk/src/zod/generated/StoreCredit.ts
@@ -3,12 +3,12 @@ import { z } from 'zod';
export const StoreCreditSchema = z.object({
id: z.string(),
- amount: z.string(),
- amount_used: z.string(),
- amount_remaining: z.string(),
- display_amount: z.string(),
- display_amount_used: z.string(),
- display_amount_remaining: z.string(),
+ amount: z.string().nullable(),
+ amount_used: z.string().nullable(),
+ amount_remaining: z.string().nullable(),
+ display_amount: z.string().nullable(),
+ display_amount_used: z.string().nullable(),
+ display_amount_remaining: z.string().nullable(),
currency: z.string(),
});
diff --git a/packages/sdk/src/zod/generated/StoreCreditEvent.ts b/packages/sdk/src/zod/generated/StoreCreditEvent.ts
index c2782e43b9..b76049a568 100644
--- a/packages/sdk/src/zod/generated/StoreCreditEvent.ts
+++ b/packages/sdk/src/zod/generated/StoreCreditEvent.ts
@@ -6,8 +6,8 @@ export const StoreCreditEventSchema = z.object({
action: z.string(),
authorization_code: z.string().nullable(),
display_action: z.string().nullable(),
- amount: z.string(),
- display_amount: z.string(),
+ amount: z.string().nullable(),
+ display_amount: z.string().nullable(),
created_at: z.string(),
});
diff --git a/packages/sdk/src/zod/generated/TaxLine.ts b/packages/sdk/src/zod/generated/TaxLine.ts
index 1829aa9097..38bfdfada9 100644
--- a/packages/sdk/src/zod/generated/TaxLine.ts
+++ b/packages/sdk/src/zod/generated/TaxLine.ts
@@ -6,7 +6,7 @@ export const TaxLineSchema = z.object({
label: z.string(),
included: z.boolean(),
credit: z.boolean(),
- rate: z.string(),
+ rate: z.string().nullable(),
tax_rate_id: z.string().nullable(),
line_item_id: z.string().nullable(),
fulfillment_id: z.string().nullable(),
diff --git a/packages/seller-dashboard/src/components/orders/fulfillment-edit-dialog.tsx b/packages/seller-dashboard/src/components/orders/fulfillment-edit-dialog.tsx
index 304e6b43cb..cae65dacf0 100644
--- a/packages/seller-dashboard/src/components/orders/fulfillment-edit-dialog.tsx
+++ b/packages/seller-dashboard/src/components/orders/fulfillment-edit-dialog.tsx
@@ -1,5 +1,5 @@
import { FulfillmentEditDialog as SharedFulfillmentEditDialog } from '@spree/dashboard-ui'
-import { type Fulfillment, SpreeError } from '@spree/seller-sdk'
+import { type Fulfillment, isZeroMoney, SpreeError } from '@spree/seller-sdk'
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import { useFulfillmentActions } from '../../hooks/use-fulfillments'
@@ -38,7 +38,7 @@ export function FulfillmentEditDialog({
const rateOptions = (fulfillment.delivery_rates ?? []).map((rate) => ({
value: rate.id,
label: `${rate.name} — ${
- Number.parseFloat(rate.cost) === 0 ? t('orders.fulfillments.free') : rate.display_cost
+ isZeroMoney(rate.cost) ? t('orders.fulfillments.free') : rate.display_cost
}`,
}))
diff --git a/packages/seller-dashboard/src/components/orders/order-cards.tsx b/packages/seller-dashboard/src/components/orders/order-cards.tsx
index 5f998cef94..b4e4538a12 100644
--- a/packages/seller-dashboard/src/components/orders/order-cards.tsx
+++ b/packages/seller-dashboard/src/components/orders/order-cards.tsx
@@ -1,4 +1,4 @@
-import { AddressFormDialog, formatStoreDateTime } from '@spree/dashboard-core'
+import { AddressFormDialog, formatStoreDateTime, isPositiveMoney } from '@spree/dashboard-core'
import {
AddressBlock,
Button,
@@ -15,6 +15,7 @@ import {
} from '@spree/dashboard-ui'
import { EllipsisVerticalIcon, PencilIcon } from '@spree/dashboard-ui/icons'
import type { Order, OrderAddressParams } from '@spree/seller-sdk'
+import { isZeroMoney } from '@spree/seller-sdk'
import { type ReactNode, useState } from 'react'
import { useTranslation } from 'react-i18next'
import { sellerClient } from '../../api-client'
@@ -71,8 +72,7 @@ export function OrderSummaryCard({ order }: { order: Order }) {
const { t } = useTranslation()
const timezone = useStoreTimezone()
- const amount = (value: string | null | undefined) => Number.parseFloat(value ?? '0')
- const outstanding = amount(order.amount_due)
+ const outstanding = isPositiveMoney(order.amount_due)
const placed = Boolean(order.completed_at)
return (
@@ -120,22 +120,22 @@ export function OrderSummaryCard({ order }: { order: Order }) {
<SummaryRow label={t('orders.summary.subtotal')} value={order.display_item_total} />
- {amount(order.delivery_total) > 0 && (
+ {isPositiveMoney(order.delivery_total) && (
<SummaryRow label={t('orders.summary.shipping')} value={order.display_delivery_total} />
)}
- {amount(order.discount_total) !== 0 && (
+ {!isZeroMoney(order.discount_total) && (
<SummaryRow label={t('orders.summary.promotions')} value={order.display_discount_total} />
)}
- {amount(order.adjustment_total) !== 0 && (
+ {!isZeroMoney(order.adjustment_total) && (
<SummaryRow
label={t('orders.summary.adjustments')}
value={order.display_adjustment_total}
/>
)}
- {amount(order.included_tax_total) > 0 && (
+ {isPositiveMoney(order.included_tax_total) && (
<SummaryRow
label={t('orders.summary.tax_included')}
value={order.display_included_tax_total}
@@ -144,8 +144,8 @@ export function OrderSummaryCard({ order }: { order: Order }) {
{/* Shown on a placed order even at zero, so "no tax was charged" reads
as an answer rather than a missing row. */}
- {(amount(order.additional_tax_total) > 0 ||
- (placed && amount(order.included_tax_total) === 0)) && (
+ {(isPositiveMoney(order.additional_tax_total) ||
+ (placed && isZeroMoney(order.included_tax_total))) && (
<SummaryRow
label={t('orders.summary.tax_additional')}
value={order.display_additional_tax_total}
@@ -181,7 +181,7 @@ export function OrderSummaryCard({ order }: { order: Order }) {
value={order.display_commission_amount_total}
/>
- {amount(order.commission_tax_total) > 0 && (
+ {isPositiveMoney(order.commission_tax_total) && (
<SummaryRow
label={t('orders.summary.commission_tax')}
value={order.display_commission_tax_total}
@@ -207,7 +207,7 @@ export function OrderSummaryCard({ order }: { order: Order }) {
label={t('orders.summary.outstanding_balance')}
value={order.display_amount_due}
highlight
- danger={outstanding > 0}
+ danger={outstanding}
/>
</div>
</Card>
diff --git a/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx b/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx
index a8b3af2a00..7407e8676c 100644
--- a/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx
+++ b/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx
@@ -1,4 +1,4 @@
-import { currencyParts } from '@spree/dashboard-core'
+import { currencyParts, isPositiveMoney } from '@spree/dashboard-core'
import {
Button,
Card,
@@ -23,6 +23,7 @@ import {
ShieldAlertIcon,
} from '@spree/dashboard-ui/icons'
import type { Claim, Order } from '@spree/seller-sdk'
+import { sumMoney } from '@spree/seller-sdk'
import i18n from 'i18next'
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
@@ -113,7 +114,7 @@ export function ExchangesCard({ order }: { order: Order }) {
// A dearer replacement leaves the customer owing the
// difference, which fulfilling puts on the order.
if (
- Number(exchange.price_difference) > 0 &&
+ isPositiveMoney(exchange.price_difference) &&
!(await confirm({
message: t('orders.post_sale.exchanges.balance_due_confirm'),
confirmLabel: t('orders.post_sale.exchanges.fulfill'),
@@ -322,14 +323,9 @@ function ResolveClaimDialog({
// A claim opened without per-item amounts has a refund_total of zero, and
// the workflow refuses to refund nothing — offer what the customer paid for
// the claimed items instead, which is also the ceiling it enforces.
- const recorded = Number(claim.refund_total)
- const paid = lines.reduce((sum, line) => sum + Number(line.paid_amount ?? 0), 0)
+ const paid = sumMoney(lines.map((line) => line.paid_amount))
const defaultAmount =
- Number.isFinite(recorded) && recorded > 0
- ? claim.refund_total
- : paid > 0
- ? paid.toFixed(2)
- : claim.refund_total
+ isPositiveMoney(claim.refund_total) || !isPositiveMoney(paid) ? claim.refund_total : paid
return (
<ClaimResolveDialog
diff --git a/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx b/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx
index 1a1627bc7f..2fb842748d 100644
--- a/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx
+++ b/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx
@@ -1,4 +1,4 @@
-import { currencyParts } from '@spree/dashboard-core'
+import { currencyParts, paidForUnits } from '@spree/dashboard-core'
import {
Field,
FieldLabel,
@@ -137,8 +137,7 @@ export function CreateClaimDialog({
id: item.id,
label: unitLabel(item),
quantity: item.quantity,
- discountedAmount: item.discounted_amount,
- additionalTaxTotal: item.additional_tax_total,
+ paidFor: (quantity: number) => paidForUnits(item, quantity, order.currency),
}))}
currencySymbol={currencySymbol}
reasonField={<ClaimReasonField value={reasonId} onChange={setReasonId} />}
diff --git a/packages/seller-dashboard/src/components/orders/returns-card.tsx b/packages/seller-dashboard/src/components/orders/returns-card.tsx
index bcaf26b303..8d8594fcb3 100644
--- a/packages/seller-dashboard/src/components/orders/returns-card.tsx
+++ b/packages/seller-dashboard/src/components/orders/returns-card.tsx
@@ -1,4 +1,9 @@
-import { currencyParts } from '@spree/dashboard-core'
+import {
+ currencyParts,
+ isPositiveMoney,
+ returnOwesNothing,
+ returnRefundSummary,
+} from '@spree/dashboard-core'
import {
Badge,
Button,
@@ -14,8 +19,6 @@ import {
DropdownMenuTrigger,
ReturnReceiveDialog,
ReturnRefundDialog,
- returnOwesNothing,
- returnRefundSummary,
StatusBadge,
useConfirm,
} from '@spree/dashboard-ui'
@@ -260,8 +263,9 @@ function RefundDialog({
return (
<ReturnRefundDialog
refundableTotal={returnRecord.refundable_total}
+ owesNothing={returnOwesNothing(returnRecord.refundable_total)}
refundTaxTotal={
- Number(returnRecord.refund_tax_total) > 0
+ isPositiveMoney(returnRecord.refund_tax_total)
? returnRecord.display_refund_tax_total
: undefined
}
diff --git a/packages/seller-sdk/src/index.ts b/packages/seller-sdk/src/index.ts
index 3914bd0c6c..88fc51c5e6 100644
--- a/packages/seller-sdk/src/index.ts
+++ b/packages/seller-sdk/src/index.ts
@@ -1,6 +1,16 @@
export type { RequestOptions, RetryConfig } from '@spree/sdk-core'
// Request infrastructure (re-exported from sdk-core)
-export { SpreeError } from '@spree/sdk-core'
+export {
+ compareMoney,
+ decimalPlaces,
+ isDecimalString,
+ isZeroMoney,
+ multiplyMoney,
+ negateMoney,
+ SpreeError,
+ subtractMoney,
+ sumMoney,
+} from '@spree/sdk-core'
// `Client` is the whole configured client (auth + resources + token/seller
// setters); `SellerClient` below is just the resource group. Exported under
// both names so hosts can say what they mean.
diff --git a/packages/seller-sdk/src/types/generated/Price.ts b/packages/seller-sdk/src/types/generated/Price.ts
index 5e9bf42a18..9baca522ee 100644
--- a/packages/seller-sdk/src/types/generated/Price.ts
+++ b/packages/seller-sdk/src/types/generated/Price.ts
@@ -1,14 +1,12 @@
-// Typelizer digest 7a116315f0ab746b716e9f89137a67f0
+// Typelizer digest 486832c830acf82a1754edef271452b9
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
type Price = {
id: string;
+ currency: string | null;
amount: string | null;
- amount_in_cents: number | null;
compare_at_amount: string | null;
- compare_at_amount_in_cents: number | null;
- currency: string | null;
display_amount: string | null;
display_compare_at_amount: string | null;
price_list_id: string | null;
diff --git a/packages/seller-sdk/src/types/generated/PriceHistory.ts b/packages/seller-sdk/src/types/generated/PriceHistory.ts
index b1e1a526af..966d4cf7f5 100644
--- a/packages/seller-sdk/src/types/generated/PriceHistory.ts
+++ b/packages/seller-sdk/src/types/generated/PriceHistory.ts
@@ -1,12 +1,11 @@
-// Typelizer digest 82799fb1cdb9d1035174afc6b1613ca8
+// Typelizer digest 5e2279c98b06b1d7edd6179b2023e704
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
type PriceHistory = {
id: string;
- amount: string;
- amount_in_cents: number;
currency: string;
+ amount: string | null;
display_amount: string;
recorded_at: string;
}
diff --git a/packages/seller-sdk/src/types/generated/ShippingLabel.ts b/packages/seller-sdk/src/types/generated/ShippingLabel.ts
index 2d9e4ae457..891f4f3e12 100644
--- a/packages/seller-sdk/src/types/generated/ShippingLabel.ts
+++ b/packages/seller-sdk/src/types/generated/ShippingLabel.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 63bf00d90369522947569216d8408672
+// Typelizer digest e20560b951b504e8062d2f13adf06216
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {ShippingLabelStatus} from '@/types'
@@ -21,7 +21,7 @@ type ShippingLabel = {
owner_id: string;
owner_type: 'fulfillment' | 'return';
cost: string;
- display_cost: string;
+ display_cost: string | null;
integration_id: string | null;
file_pending: boolean;
download_url: string | null;
diff --git a/packages/seller-sdk/src/types/generated/Variant.ts b/packages/seller-sdk/src/types/generated/Variant.ts
index 40b21ec516..25344af14f 100644
--- a/packages/seller-sdk/src/types/generated/Variant.ts
+++ b/packages/seller-sdk/src/types/generated/Variant.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 1cdab11d653fcdb97b03570eb6e0ff48
+// Typelizer digest 35bcd9f5f5fe62db10662174ca954800
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Price, PriceHistory, Seller, Media, OptionValue, CustomField, StockLevel} from '@/types'
@@ -37,7 +37,6 @@ type Variant = {
prior_price?: PriceHistory | null;
metadata: Record<string, unknown>;
position: number;
- cost_price: string | null;
cost_currency: string | null;
barcode: string | null;
backorder_limit: number | null;
@@ -46,6 +45,7 @@ type Variant = {
customs_description: string | null;
created_at: string;
updated_at: string;
+ cost_price: string | null;
preorderable: boolean;
available_stock: number | null;
total_on_hand: number | null;
diff --git a/packages/seller-sdk/src/zod/generated/Price.ts b/packages/seller-sdk/src/zod/generated/Price.ts
index 75f9cfa745..834e31fb10 100644
--- a/packages/seller-sdk/src/zod/generated/Price.ts
+++ b/packages/seller-sdk/src/zod/generated/Price.ts
@@ -3,11 +3,9 @@ import { z } from 'zod';
export const PriceSchema = z.object({
id: z.string(),
+ currency: z.string().nullable(),
amount: z.string().nullable(),
- amount_in_cents: z.number().nullable(),
compare_at_amount: z.string().nullable(),
- compare_at_amount_in_cents: z.number().nullable(),
- currency: z.string().nullable(),
display_amount: z.string().nullable(),
display_compare_at_amount: z.string().nullable(),
price_list_id: z.string().nullable(),
diff --git a/packages/seller-sdk/src/zod/generated/PriceHistory.ts b/packages/seller-sdk/src/zod/generated/PriceHistory.ts
index 91ce6f0d19..48f3be55e0 100644
--- a/packages/seller-sdk/src/zod/generated/PriceHistory.ts
+++ b/packages/seller-sdk/src/zod/generated/PriceHistory.ts
@@ -3,9 +3,8 @@ import { z } from 'zod';
export const PriceHistorySchema = z.object({
id: z.string(),
- amount: z.string(),
- amount_in_cents: z.number(),
currency: z.string(),
+ amount: z.string().nullable(),
display_amount: z.string(),
recorded_at: z.string(),
});
diff --git a/packages/seller-sdk/src/zod/generated/ShippingLabel.ts b/packages/seller-sdk/src/zod/generated/ShippingLabel.ts
index 8e58b4b740..21b5890ccb 100644
--- a/packages/seller-sdk/src/zod/generated/ShippingLabel.ts
+++ b/packages/seller-sdk/src/zod/generated/ShippingLabel.ts
@@ -19,7 +19,7 @@ export const ShippingLabelSchema = z.object({
owner_id: z.string(),
owner_type: z.string(),
cost: z.string(),
- display_cost: z.string(),
+ display_cost: z.string().nullable(),
integration_id: z.string().nullable(),
file_pending: z.boolean(),
download_url: z.string().nullable(),
diff --git a/packages/seller-sdk/src/zod/generated/Variant.ts b/packages/seller-sdk/src/zod/generated/Variant.ts
index 820cd47c37..6546c0ae20 100644
--- a/packages/seller-sdk/src/zod/generated/Variant.ts
+++ b/packages/seller-sdk/src/zod/generated/Variant.ts
@@ -42,7 +42,6 @@ export const VariantSchema = z.object({
prior_price: PriceHistorySchema.nullable().optional(),
metadata: z.record(z.string(), z.unknown()),
position: z.number(),
- cost_price: z.string().nullable(),
cost_currency: z.string().nullable(),
barcode: z.string().nullable(),
backorder_limit: z.number().nullable(),
@@ -51,6 +50,7 @@ export const VariantSchema = z.object({
customs_description: z.string().nullable(),
created_at: z.string(),
updated_at: z.string(),
+ cost_price: z.string().nullable(),
preorderable: z.boolean(),
available_stock: z.number().nullable(),
total_on_hand: z.number().nullable(),
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/money_params.rb b/spree/api/app/controllers/concerns/spree/api/v3/money_params.rb
index 58ed123448..2aecb3887c 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/money_params.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/money_params.rb
@@ -19,10 +19,7 @@ module Spree
# @return [BigDecimal, nil] nil when the parameter is absent
# @raise [Spree::Money::InvalidFormat]
def money_param(name, currency, unit_price: false)
- value = params[name]
- # JSON numbers stay accepted until the 6.0 wire contract (money plan, PR B).
- value = value.to_s if value.is_a?(Integer) || value.is_a?(Float)
- Spree::Money::Rounding.parse_canonical(value, currency, unit_price: unit_price)
+ Spree::Money::Rounding.parse_canonical(params[name], currency, unit_price: unit_price)
rescue Spree::Money::InvalidFormat => error
raise Spree::Money::InvalidFormat.new(error.message, field: name)
end
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/strict_money_params.rb b/spree/api/app/controllers/concerns/spree/api/v3/strict_money_params.rb
new file mode 100644
index 0000000000..f84b685c1f
--- /dev/null
+++ b/spree/api/app/controllers/concerns/spree/api/v3/strict_money_params.rb
@@ -0,0 +1,87 @@
+module Spree
+ module Api
+ module V3
+ # Admin and Seller writes take money and rates as canonical decimal
+ # strings only ("19.99", "0.23"): a JSON number, localized text or more
+ # decimals than the field holds is answered with `invalid_money_format`
+ # before anything is written. A money field checks its currency's decimals
+ # when the payload names the currency beside it, and four otherwise; unit
+ # prices always allow four. Store API writes carry no amounts and are not
+ # checked here.
+ module StrictMoneyParams
+ extend ActiveSupport::Concern
+
+ MONEY_KEYS = %w[
+ amount compare_at_amount cost cost_price price unit_cost refund_amount settled_amount
+ minimum_payout_amount min_amount max_amount markup_flat
+ amount_min amount_max first_item additional_item minimal_amount normal_amount discount_amount
+ base_amount minimum_item_total maximum_item_total preferred_default_minimum_payout_amount
+ ].freeze
+
+ UNIT_PRICE_KEYS = %w[price compare_at_amount cost_price unit_cost].freeze
+
+ RATE_KEYS = %w[
+ rate rate_percent percent flat_percent base_percent markup_percent percentage
+ price_adjustment_percentage commission_tax_rate preferred_default_commission_tax_rate
+ ].freeze
+
+ # Values the merchant or a provider owns, stored as sent.
+ OPAQUE_KEYS = %w[metadata custom_fields external_data].freeze
+
+ included do
+ before_action :refuse_noncanonical_decimals, if: -> { request.post? || request.patch? || request.put? }
+ end
+
+ private
+
+ def refuse_noncanonical_decimals
+ check_decimals(request.request_parameters, parent: nil, currency: nil)
+ end
+
+ def check_decimals(node, parent:, currency:)
+ case node
+ when Hash
+ currency = node['currency'].presence || currency
+ node.each do |key, value|
+ next if OPAQUE_KEYS.include?(key)
+
+ if scalar?(value) && MONEY_KEYS.include?(key)
+ check_money(key, value, currency, UNIT_PRICE_KEYS.include?(key) || (key == 'amount' && parent == 'prices'))
+ elsif scalar?(value) && RATE_KEYS.include?(key)
+ check_rate(key, value)
+ else
+ check_decimals(value, parent: key, currency: currency)
+ end
+ end
+ when Array
+ node.each { |item| check_decimals(item, parent: parent, currency: currency) }
+ end
+ end
+
+ def check_money(key, value, currency, unit_price)
+ return if blank_value?(value)
+
+ Spree::Money::Rounding.parse_canonical(value, currency.presence, unit_price: unit_price)
+ rescue Spree::Money::InvalidFormat => error
+ raise Spree::Money::InvalidFormat.new(error.message, field: key.to_sym)
+ end
+
+ def check_rate(key, value)
+ return if blank_value?(value)
+
+ Spree::Money::Rounding.parse_canonical_decimal(value)
+ rescue Spree::Money::InvalidFormat => error
+ raise Spree::Money::InvalidFormat.new(error.message, field: key.to_sym)
+ end
+
+ def scalar?(value)
+ !value.is_a?(Hash) && !value.is_a?(Array)
+ end
+
+ def blank_value?(value)
+ value.nil? || (value.is_a?(String) && value.strip.empty?)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/base_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/base_controller.rb
index 4e2ff1fa37..c5176635d2 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/base_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/base_controller.rb
@@ -12,6 +12,7 @@ module Spree
before_action :authenticate_admin!
include Spree::Api::V3::ScopedAuthorization
+ include Spree::Api::V3::StrictMoneyParams
include Spree::Api::V3::Admin::ValidationDetails
include Spree::Api::V3::Admin::EmbedPermissions
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/resource_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/resource_controller.rb
index d8cbb957e7..b8d89904bc 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/resource_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/resource_controller.rb
@@ -9,6 +9,7 @@ module Spree
include Spree::Api::V3::Admin::StoreContext
include Spree::Api::V3::AdminAuthentication
include Spree::Api::V3::ScopedAuthorization
+ include Spree::Api::V3::StrictMoneyParams
# External-identity addressing for every admin resource whose model
# opts in via Spree::HasExternalReferences — the concern's guards
# no-op for everything else. Sitting here rather than per controller
diff --git a/spree/api/app/controllers/spree/api/v3/admin/tax_rates_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/tax_rates_controller.rb
index 81343535eb..8fb111c7b3 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/tax_rates_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/tax_rates_controller.rb
@@ -22,7 +22,7 @@ module Spree
end
def permitted_params
- params.permit(*model_additional_permitted_attributes, :name, :amount, :amount_percentage, :included_in_price,
+ params.permit(*model_additional_permitted_attributes, :name, :rate, :rate_percent, :included_in_price,
:show_rate_in_label, :tax_category_id,
:country_code, :state_code, metadata: {})
end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/base_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/base_controller.rb
index 7d61132ae4..39bdb0934a 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/base_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/base_controller.rb
@@ -18,6 +18,7 @@ module Spree
before_action :authenticate_seller!
include Spree::Api::V3::ScopedAuthorization
+ include Spree::Api::V3::StrictMoneyParams
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/resource_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/resource_controller.rb
index 16721a9542..9a86066874 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/resource_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/resource_controller.rb
@@ -11,6 +11,7 @@ module Spree
include Spree::Api::V3::Seller::SellerContext
include Spree::Api::V3::SellerAuthentication
include Spree::Api::V3::ScopedAuthorization
+ include Spree::Api::V3::StrictMoneyParams
protected
diff --git a/spree/api/app/serializers/spree/api/v3/admin/catalog_order_minimum_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/catalog_order_minimum_serializer.rb
index 9f97281746..3fea3a3b01 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/catalog_order_minimum_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/catalog_order_minimum_serializer.rb
@@ -5,11 +5,12 @@ module Spree
# The least a whole order must come to under a catalog's agreement,
# in one currency.
class CatalogOrderMinimumSerializer < V3::BaseSerializer
- typelize currency: :string, amount: :string, display_amount: :string
+ typelize currency: :string
attributes :currency, created_at: :iso8601, updated_at: :iso8601
- attributes amount: :string, display_amount: :string
+ money_attributes :amount, :display_amount
+ typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false]
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/catalog_price_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/catalog_price_serializer.rb
index 2898853e74..0ba7200140 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/catalog_price_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/catalog_price_serializer.rb
@@ -17,7 +17,7 @@ module Spree
_attributes.delete(:id)
typelize id: 'string | null', label: 'string | null', sku: 'string | null',
- amount: :string, display_amount: :string,
+ display_amount: :string,
currency: :string, source: [:string, enum: Spree::CatalogPrice::SOURCES], break_count: :number
# The variant this prices, so a row can name what it is showing —
@@ -33,7 +33,8 @@ module Spree
# though it were the only one.
attributes :currency, :source, :break_count
- attribute :amount, &:display_value
+ money_attributes :amount, unit_price: true
+ typelize amount: [:string, nullable: false]
attributes :display_amount
diff --git a/spree/api/app/serializers/spree/api/v3/admin/catalog_price_tier_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/catalog_price_tier_serializer.rb
index b41720d776..5fed6983bd 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/catalog_price_tier_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/catalog_price_tier_serializer.rb
@@ -11,11 +11,12 @@ module Spree
class CatalogPriceTierSerializer < V3::BaseSerializer
_attributes.delete(:id)
- typelize min_quantity: :number, amount: :string, display_amount: :string
+ typelize min_quantity: :number, display_amount: :string
attributes :min_quantity, :display_amount
- attribute :amount, &:display_value
+ money_attributes :amount, unit_price: true
+ typelize amount: [:string, nullable: false]
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb
index 1142282443..130c2feac2 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb
@@ -5,6 +5,12 @@ module Spree
module V3
module Admin
class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize refund_amount: [:string, nullable: false], paid_amount: [:string, nullable: false],
+ pre_tax_amount: [:string, nullable: false], included_tax_total: [:string, nullable: false],
+ additional_tax_total: [:string, nullable: false], tax_total: [:string, nullable: false],
+ display_refund_amount: [:string, nullable: false]
+
attributes created_at: :iso8601, updated_at: :iso8601
one :variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb
index 661bb563c6..c1d1a3457a 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb
@@ -5,6 +5,9 @@ module Spree
module V3
module Admin
class ClaimSerializer < V3::ClaimSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize refund_total: [:string, nullable: false], display_refund_total: [:string, nullable: false]
+
typelize memo: [:string, nullable: true],
metadata: 'Record<string, unknown>',
created_by_id: [:string, nullable: true],
diff --git a/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb
index 4d77454ab4..854bcbd414 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb
@@ -20,14 +20,9 @@ module Spree
fulfillment_id: 'string | null',
commission_rate_id: 'string | null',
kind: [:string, enum: Spree::CommissionRate::KINDS],
- rate: :string,
- tax_rate: :string,
taxability_reason: 'string | null',
country_code: 'string | null',
state_code: 'string | null',
- amount: :string,
- tax_amount: :string,
- total: :string,
currency: :string,
display_amount: :string,
display_tax_amount: :string,
@@ -39,10 +34,11 @@ module Spree
attributes :kind, :currency, :taxability_reason, :country_code, :state_code,
created_at: :iso8601, updated_at: :iso8601
- # Strings, so the figures a seller is invoiced round-trip exactly.
- %i[rate tax_rate amount tax_amount total].each do |decimal|
- attribute(decimal) { |line| line.public_send(decimal)&.to_s }
- end
+ rate_attributes :rate, :tax_rate
+ money_attributes :amount, :tax_amount, :total
+ typelize rate: [:string, nullable: false], tax_rate: [:string, nullable: false],
+ amount: [:string, nullable: false], tax_amount: [:string, nullable: false],
+ total: [:string, nullable: false]
%i[display_amount display_tax_amount display_total].each do |formatted|
attribute(formatted) { |line| line.public_send(formatted).to_s }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb
index 2529aff16a..56745a8f19 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb
@@ -10,21 +10,16 @@ module Spree
# were actually charged (Spree::CommissionLine) on their own branch,
# never the rules that produced it.
class CommissionRateSerializer < V3::BaseSerializer
- # Decimals serialize as strings, like every other money-ish field on
- # the admin API: a rate has to round-trip exactly, and a float does
- # not promise that.
typelize name: :string,
code: 'string | null',
enabled: :boolean,
position: :number,
global: :boolean,
kind: [:string, enum: Spree::CommissionRate::KINDS],
- value: :string,
amounts: 'Record<string, string>',
bounds: 'Record<string, { min_amount: string | null; max_amount: string | null }>',
tax_inclusive: :boolean,
include_shipping: :boolean,
- commission_tax_rate: 'string | null',
metadata: 'Record<string, unknown> | null',
deleted_at: 'string | null'
@@ -32,22 +27,23 @@ module Spree
:tax_inclusive, :include_shipping, :metadata,
deleted_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
- %i[value commission_tax_rate].each do |decimal|
- attribute(decimal) { |rate| rate.public_send(decimal)&.to_s }
- end
+ # +value+ is the percentage a percentage rate charges; a flat fee's
+ # money lives in +amounts+, per currency.
+ rate_attributes :value, :commission_tax_rate
+ typelize value: [:string, nullable: false]
# What a flat fee charges, per currency. Empty on a percentage rate,
# which needs no amount of its own.
attribute :amounts do |rate|
- rate.amounts.transform_values(&:to_s)
+ rate.amounts.to_h { |currency, amount| [currency, Spree::Money::Rounding.format(amount, currency)] }
end
# The floor and cap a percentage charges within, per currency. Each
# holds only in its own currency, so a rate may bound some and leave
# others unbounded.
attribute :bounds do |rate|
- rate.bounds.transform_values do |bound|
- bound.transform_values { |amount| amount&.to_s }
+ rate.bounds.to_h do |currency, bound|
+ [currency, bound.transform_values { |amount| Spree::Money::Rounding.format(amount, currency) }]
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
index 19defb49ad..c83fea2f09 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
@@ -53,7 +53,8 @@ module Spree
end
attribute :total_spent do |user|
- (user.attributes['total_spent'] || user.orders.complete.sum(:total)).to_s
+ amount = user.attributes['total_spent'] || user.orders.complete.sum(:total)
+ Spree::Money::Rounding.format(amount, (current_store || Spree::Current.store)&.default_currency)
end
attribute :display_total_spent do |user|
diff --git a/spree/api/app/serializers/spree/api/v3/admin/delivery_method_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/delivery_method_serializer.rb
index d961376994..49f68d7433 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/delivery_method_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/delivery_method_serializer.rb
@@ -21,10 +21,17 @@ module Spree
seller_id: [:string, nullable: true],
seller_name: [:string, nullable: true]
- attributes :admin_name, :storefront_visible, :tracking_url,
- :markup_flat, :markup_percent, :available_to_sellers,
+ attributes :admin_name, :storefront_visible, :tracking_url, :available_to_sellers,
created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
+ # The flat markup is charged in whatever currency the rate is quoted
+ # in, so it is written to the store's default currency.
+ attribute :markup_flat do |record|
+ Spree::Money::Rounding.format(record.markup_flat, (current_store || Spree::Current.store)&.default_currency)
+ end
+
+ rate_attributes :markup_percent
+
# Which seller runs this method, so the operator's list can say
# whose it is. Null is the marketplace's own
# (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
diff --git a/spree/api/app/serializers/spree/api/v3/admin/delivery_method_service_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/delivery_method_service_serializer.rb
index 8348463b1e..fae0077250 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/delivery_method_service_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/delivery_method_service_serializer.rb
@@ -7,7 +7,15 @@ module Spree
markup_flat: [:string, nullable: true], markup_percent: [:string, nullable: true],
position: :number
- attributes :carrier, :service, :label, :markup_flat, :markup_percent, :position
+ attributes :carrier, :service, :label
+
+ attribute :markup_flat do |record|
+ Spree::Money::Rounding.format(record.markup_flat, (current_store || Spree::Current.store)&.default_currency)
+ end
+
+ rate_attributes :markup_percent
+
+ attributes :position
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/delivery_rate_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/delivery_rate_serializer.rb
index 3575c31da3..e396c6dfda 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/delivery_rate_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/delivery_rate_serializer.rb
@@ -3,6 +3,15 @@ module Spree
module V3
module Admin
class DeliveryRateSerializer < V3::DeliveryRateSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize cost: [:string, nullable: false], display_cost: [:string, nullable: false],
+ total: [:string, nullable: false], display_total: [:string, nullable: false],
+ additional_tax_total: [:string, nullable: false],
+ display_additional_tax_total: [:string, nullable: false],
+ included_tax_total: [:string, nullable: false],
+ display_included_tax_total: [:string, nullable: false], tax_total: [:string, nullable: false],
+ display_tax_total: [:string, nullable: false]
+
typelize metadata: ['Record<string, unknown>', nullable: true]
# Raw carrier payload (quote ids, service codes) — operational
diff --git a/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb
index 20295621de..8156471e31 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb
@@ -5,6 +5,11 @@ module Spree
module V3
module Admin
class ExchangeLineItemSerializer < V3::ExchangeLineItemSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize original_price: [:string, nullable: false], new_variant_price: [:string, nullable: false],
+ price_difference: [:string, nullable: false], original_tax_total: [:string, nullable: false],
+ new_tax_total: [:string, nullable: false]
+
attributes created_at: :iso8601, updated_at: :iso8601
one :original_variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('original_variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb
index 19ea087a55..f6fded6e0e 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb
@@ -5,6 +5,9 @@ module Spree
module V3
module Admin
class ExchangeSerializer < V3::ExchangeSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize price_difference: [:string, nullable: false], display_price_difference: [:string, nullable: false]
+
typelize memo: [:string, nullable: true],
metadata: 'Record<string, unknown>',
stock_location_id: [:string, nullable: true],
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 8f9b5ed84b..09fb6f8de6 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
@@ -16,12 +16,12 @@ module Spree
documents: "Array<{ kind: string; url: string }>",
provider_generates_labels: :boolean,
order_id: [:string, nullable: true],
- stock_location_id: [:string, nullable: true],
- adjustment_total: :string,
- pre_tax_amount: :string
+ stock_location_id: [:string, nullable: true]
- attributes :metadata, :adjustment_total, :pre_tax_amount,
- created_at: :iso8601, updated_at: :iso8601
+ attributes :metadata, created_at: :iso8601, updated_at: :iso8601
+
+ money_attributes :adjustment_total, :pre_tax_amount
+ typelize adjustment_total: [:string, nullable: false], pre_tax_amount: [:string, nullable: false]
prefixed_id_attributes :order, :stock_location
diff --git a/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb
index 6e7cf86180..44c5029116 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb
@@ -34,7 +34,7 @@ module Spree
# Base price, not resolved: resolving would call the pricing provider
# once per line on a read path that must stay provider-free.
attribute :catalog_price do |line_item|
- line_item.variant&.amount_in(line_item.currency)&.to_s
+ Spree::Money::Rounding.format(line_item.variant&.amount_in(line_item.currency), line_item.currency, unit_price: true)
end
# Which agreement priced this line. The list id is stamped on the
@@ -58,9 +58,7 @@ module Spree
line_item.price_list&.catalog&.name
end
- attribute :cost_price do |line_item|
- line_item.cost_price&.to_s
- end
+ money_attributes :cost_price, unit_price: true
prefixed_id_attributes :tax_category
diff --git a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
index 352f9ac153..be7d041a91 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
@@ -29,20 +29,6 @@ module Spree
total: [:string, nullable: false], display_total: [:string, nullable: false],
amount_due: [:string, nullable: false], display_amount_due: [:string, nullable: false]
- # Back-office only: what the marketplace earned on this sale — the fee,
- # the tax charged on it, and the two together. Never on the store
- # serializer: a commission settles between the platform and the
- # seller, and the shopper does not pay it.
- #
- # The tax stands on its own because it is separately reportable —
- # the platform files it as output tax on a B2B supply to the seller.
- typelize commission_amount_total: [:string, nullable: false],
- display_commission_amount_total: [:string, nullable: false],
- commission_tax_total: [:string, nullable: false],
- display_commission_tax_total: [:string, nullable: false],
- commission_total: [:string, nullable: false],
- display_commission_total: [:string, nullable: false]
-
typelize status: [:string, enum: Spree::Order::STATUSES],
last_ip_address: [:string, nullable: true],
considered_risky: :boolean, confirmation_delivered: :boolean,
@@ -59,21 +45,36 @@ module Spree
cancel_reason_id: [:string, nullable: true],
cancel_reason_name: [:string, nullable: true],
cancel_note: [:string, nullable: true],
- payment_total: :string, display_payment_total: :string,
tags: [:string, multi: true],
metadata: 'Record<string, unknown>'
# Admin-only attributes
attributes :status, :last_ip_address, :considered_risky,
:confirmation_delivered, :store_owner_notification_delivered,
- :payment_total, :display_payment_total, :metadata,
- :cancel_note,
- :commission_amount_total, :display_commission_amount_total,
- :commission_tax_total, :display_commission_tax_total,
- :commission_total, :display_commission_total,
+ :metadata, :cancel_note,
canceled_at: :iso8601, approved_at: :iso8601,
created_at: :iso8601, updated_at: :iso8601
+ money_attributes :payment_total, :display_payment_total
+ typelize payment_total: [:string, nullable: false], display_payment_total: [:string, nullable: false]
+
+ # Back-office only: what the marketplace earned on this sale — the fee,
+ # the tax charged on it, and the two together. Never on the store
+ # serializer: a commission settles between the platform and the
+ # seller, and the shopper does not pay it.
+ #
+ # The tax stands on its own because it is separately reportable —
+ # the platform files it as output tax on a B2B supply to the seller.
+ money_attributes :commission_amount_total, :display_commission_amount_total,
+ :commission_tax_total, :display_commission_tax_total,
+ :commission_total, :display_commission_total
+ typelize commission_amount_total: [:string, nullable: false],
+ display_commission_amount_total: [:string, nullable: false],
+ commission_tax_total: [:string, nullable: false],
+ display_commission_tax_total: [:string, nullable: false],
+ commission_total: [:string, nullable: false],
+ display_commission_total: [:string, nullable: false]
+
prefixed_id_attributes :preferred_stock_location
# Our own endpoint rather than a pre-signed storage URL: the
diff --git a/spree/api/app/serializers/spree/api/v3/admin/payment_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/payment_serializer.rb
index bd5dfa1c15..300205fb3c 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/payment_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/payment_serializer.rb
@@ -8,7 +8,6 @@ module Spree
typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false]
typelize metadata: 'Record<string, unknown>',
- captured_amount: :string,
order_id: [:string, nullable: true],
avs_response: [:string, nullable: true],
cvv_response_code: [:string, nullable: true],
@@ -17,7 +16,9 @@ module Spree
attributes :metadata, :avs_response, :cvv_response_code, :cvv_response_message,
created_at: :iso8601, updated_at: :iso8601
- attributes captured_amount: :string
+ money_attributes :captured_amount
+ typelize captured_amount: [:string, nullable: false]
+
prefixed_id_attributes :order
# Override inherited associations to use admin serializers
diff --git a/spree/api/app/serializers/spree/api/v3/admin/payment_split_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/payment_split_serializer.rb
index d6433e6f0c..4300851177 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/payment_split_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/payment_split_serializer.rb
@@ -26,7 +26,7 @@ module Spree
attributes :currency, created_at: :iso8601, updated_at: :iso8601
AMOUNTS.each do |amount|
- attribute(amount) { |split| split.public_send(amount).to_s }
+ attribute(amount) { |split| Spree::Money::Rounding.format(split.public_send(amount), split.currency) }
attribute(:"display_#{amount}") { |split| split.public_send(:"display_#{amount}").to_s }
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/price_adjustment_tier_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/price_adjustment_tier_serializer.rb
index 45baf9657a..ba179857fb 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/price_adjustment_tier_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/price_adjustment_tier_serializer.rb
@@ -6,15 +6,12 @@ module Spree
# the list itself — the storefront sees resolved prices, never the
# arithmetic behind them.
class PriceAdjustmentTierSerializer < V3::BaseSerializer
- typelize min_quantity: :number, percentage: :string
+ typelize min_quantity: :number
attributes :min_quantity
- # A decimal as a string, like every other money-shaped value on the
- # wire — a float would round the merchant's own figure.
- attribute :percentage do |tier|
- tier.percentage&.to_s
- end
+ rate_attributes :percentage
+ typelize percentage: [:string, nullable: false]
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/price_history_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/price_history_serializer.rb
index 87efd6f63a..2489ed2141 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/price_history_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/price_history_serializer.rb
@@ -7,7 +7,6 @@ module Spree
class PriceHistorySerializer < V3::PriceHistorySerializer
typelize variant_id: :string,
price_id: :string,
- compare_at_amount: [:string, nullable: true],
created_at: :string
attribute :variant_id do |price_history|
@@ -18,7 +17,9 @@ module Spree
price_history.price.prefixed_id
end
- attributes :compare_at_amount, created_at: :iso8601
+ money_attributes :compare_at_amount, unit_price: true
+
+ attributes created_at: :iso8601
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/price_list_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/price_list_serializer.rb
index 734c873a8e..81e1b51911 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/price_list_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/price_list_serializer.rb
@@ -27,11 +27,7 @@ module Spree
starts_at: :iso8601, ends_at: :iso8601, deleted_at: :iso8601,
created_at: :iso8601, updated_at: :iso8601
- # A decimal as a string, like every other money-shaped value on the
- # wire — a float would round the merchant's own figure.
- attribute :price_adjustment_percentage do |price_list|
- price_list.price_adjustment_percentage&.to_s
- end
+ rate_attributes :price_adjustment_percentage
attribute :automatic_pricing, &:automatic_pricing?
diff --git a/spree/api/app/serializers/spree/api/v3/admin/purchase_order_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/purchase_order_item_serializer.rb
index 8297564313..62b0ddd33d 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/purchase_order_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/purchase_order_item_serializer.rb
@@ -9,10 +9,6 @@ module Spree
quantity_rejected: :number,
quantity_over: :number,
outstanding: :number,
- unit_cost: :string,
- display_unit_cost: :string,
- total_cost: :string,
- display_total_cost: :string,
currency: 'string | null',
purchase_order_id: 'string | null',
thumbnail_url: 'string | null',
@@ -26,13 +22,11 @@ module Spree
:outstanding, :currency,
created_at: :iso8601, updated_at: :iso8601
- # Money on the wire is a decimal string: a float would round the
- # merchant's own figure.
- attribute :unit_cost do |item|
- item.unit_cost&.to_s
- end
+ money_attributes :unit_cost, :display_unit_cost, unit_price: true
+ money_attributes :total_cost, :display_total_cost
+ typelize unit_cost: [:string, nullable: false], display_unit_cost: [:string, nullable: false],
+ total_cost: [:string, nullable: false], display_total_cost: [:string, nullable: false]
- attributes total_cost: :string, display_unit_cost: :string, display_total_cost: :string
attribute :purchase_order_id do |item|
Spree::PurchaseOrder.prefixed_id_for(item.purchase_order_id)
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb
index ba3f649c1e..4835bfd706 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb
@@ -21,8 +21,6 @@ module Spree
quantity_rejected_total: :number,
quantity_ordered_total: :number,
quantity_received_total: :number,
- subtotal: :string,
- display_subtotal: :string,
editable: :boolean,
ordered_at: 'string | null',
received_at: 'string | null',
@@ -56,7 +54,9 @@ module Spree
attribute :editable, &:editable?
- attributes subtotal: :string, display_subtotal: :string
+ money_attributes :subtotal, :display_subtotal
+ typelize subtotal: [:string, nullable: false], display_subtotal: [:string, nullable: false]
+
prefixed_id_attributes :supplier, :destination_location
many :items,
diff --git a/spree/api/app/serializers/spree/api/v3/admin/refund_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/refund_serializer.rb
index 623cd74fad..dfc751a868 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/refund_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/refund_serializer.rb
@@ -7,14 +7,15 @@ module Spree
refund_reason_id: [:string, nullable: true],
refunder_id: [:string, nullable: true],
refunder_type: [:string, nullable: true, enum: Spree::Actor::BUILT_IN_KINDS, enum_type_name: 'ActorKind'],
- metadata: 'Record<string, unknown>',
- tax_amount: :string
+ metadata: 'Record<string, unknown>'
attributes :metadata,
created_at: :iso8601, updated_at: :iso8601
# The tax inside the amount, when what was refunded carried tax.
- attributes tax_amount: :string
+ money_attributes :tax_amount
+ typelize tax_amount: [:string, nullable: false]
+
# Who issued it — an admin user, or the API key an integration
# refunded through.
actor_attributes :refunder
diff --git a/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
index e31068ca72..6c44d4344e 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
@@ -2,8 +2,9 @@ module Spree
module Api
module V3
module Admin
- # Decorates a Spree::Reporting::Result for the wire: money display
- # strings, ISO ranges, and dimension hydration (raw group keys become
+ # Decorates a Spree::Reporting::Result for the wire: money as decimal
+ # strings in the result's currency, ratios and growth as plain decimal
+ # strings, counts as integers, money display strings, ISO ranges, and dimension hydration (raw group keys become
# { id, label, meta } display payloads — see Spree::Reporting::Hydration).
class ReportingResultSerializer
attr_reader :result, :store, :params
@@ -39,7 +40,13 @@ module Spree
end
def metric_payload(name, payload)
+ metric = Spree.reporting.metrics[name]
output = payload.dup
+ if metric
+ output[:value] = metric.format_value(payload[:value], result.meta[:currency])
+ output[:previous] = metric.format_value(payload[:previous], result.meta[:currency]) if payload.key?(:previous)
+ end
+ output[:growth] = Spree::Money::Rounding.format_decimal(payload[:growth]) if payload.key?(:growth)
output[:display] = money(payload[:value]) if money_metrics.include?(name)
output
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/return_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/return_line_item_serializer.rb
index 479661b7c1..b5c73dd675 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/return_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/return_line_item_serializer.rb
@@ -5,6 +5,12 @@ module Spree
module V3
module Admin
class ReturnLineItemSerializer < V3::ReturnLineItemSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize pre_tax_amount: [:string, nullable: false], display_pre_tax_amount: [:string, nullable: false],
+ included_tax_total: [:string, nullable: false], additional_tax_total: [:string, nullable: false],
+ tax_total: [:string, nullable: false], display_tax_total: [:string, nullable: false],
+ refund_amount: [:string, nullable: false], display_refund_amount: [:string, nullable: false]
+
attributes created_at: :iso8601, updated_at: :iso8601
one :variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb
index aa57d92b1b..593e79439e 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb
@@ -11,9 +11,8 @@ module Spree
stock_location_id: [:string, nullable: true],
created_by_id: [:string, nullable: true],
created_by_type: [:string, nullable: true, enum: Spree::Actor::BUILT_IN_KINDS, enum_type_name: 'ActorKind'],
- refunded_total: :string,
- display_refunded_total: :string,
- refundable_total: :string
+ refund_total: [:string, nullable: false], display_refund_total: [:string, nullable: false],
+ refund_tax_total: [:string, nullable: false], display_refund_tax_total: [:string, nullable: false]
attributes :memo, :metadata, created_at: :iso8601, updated_at: :iso8601
@@ -21,7 +20,10 @@ module Spree
actor_attributes :created_by
- attributes refunded_total: :string, display_refunded_total: :string, refundable_total: :string
+ money_attributes :refunded_total, :display_refunded_total, :refundable_total
+ typelize refunded_total: [:string, nullable: false], display_refunded_total: [:string, nullable: false],
+ refundable_total: [:string, nullable: false]
+
many :return_line_items,
resource: proc { Spree.api.admin_return_line_item_serializer },
if: proc { expand?('return_line_items') }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/seller_balance_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/seller_balance_serializer.rb
index 4834309d65..ea2f6a08f0 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/seller_balance_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/seller_balance_serializer.rb
@@ -27,7 +27,7 @@ module Spree
attribute(:seller_id) { |balance| balance.seller&.prefixed_id }
%i[earned payable paid balance pending].each do |figure|
- attribute(figure) { |balance| balance.public_send(figure).to_s }
+ attribute(figure) { |balance| Spree::Money::Rounding.format(balance.public_send(figure), balance.settlement_currency) }
attribute(:"display_#{figure}") { |balance| balance.public_send(:"display_#{figure}").to_s }
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/seller_payout_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/seller_payout_serializer.rb
index b47aa517e6..3ae101a687 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/seller_payout_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/seller_payout_serializer.rb
@@ -24,7 +24,7 @@ module Spree
period_start: :iso8601, period_end: :iso8601,
created_at: :iso8601, updated_at: :iso8601
- attribute(:amount) { |payout| payout.amount&.to_s }
+ attribute(:amount) { |payout| Spree::Money::Rounding.format(payout.amount, payout.currency) }
attribute(:display_amount) { |payout| payout.display_amount.to_s }
attribute(:seller_id) { |payout| payout.seller&.prefixed_id }
attribute(:seller_name) { |payout| payout.seller&.name }
diff --git a/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb
index 7bafb73367..ceb4ffe64b 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb
@@ -38,7 +38,7 @@ module Spree
_attributes.delete(:policies)
attribute :minimum_payout_amount do |seller|
- seller.minimum_payout_amount&.to_s
+ Spree::Money::Rounding.format(seller.minimum_payout_amount, (current_store || Spree::Current.store)&.default_currency)
end
# Approved but away still cannot sell, and the list has to say so
diff --git a/spree/api/app/serializers/spree/api/v3/admin/seller_transfer_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/seller_transfer_serializer.rb
index 88a170cd14..6cd00db560 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/seller_transfer_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/seller_transfer_serializer.rb
@@ -28,13 +28,14 @@ module Spree
attributes :kind, :status, :currency, :reference, :metadata,
created_at: :iso8601, updated_at: :iso8601
- # A string, so the figure a seller is paid round-trips exactly.
- attribute(:amount) { |transfer| transfer.amount&.to_s }
+ attribute(:amount) { |transfer| Spree::Money::Rounding.format(transfer.amount, transfer.currency) }
attribute(:display_amount) { |transfer| transfer.display_amount.to_s }
# What the seller's account received, when the provider converted on
# the way in. Null when it settled in the currency of the sale.
- attribute(:settled_amount) { |transfer| transfer.settled_amount&.to_s }
+ attribute(:settled_amount) do |transfer|
+ Spree::Money::Rounding.format(transfer.settled_amount, transfer.settled_currency || transfer.currency)
+ end
attribute(:settled_currency) { |transfer| transfer.settled_currency }
attribute(:converted) { |transfer| transfer.converted? }
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
index 41b64cbe6e..4a81c3fde7 100644
--- 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
@@ -14,7 +14,6 @@ module Spree
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],
@@ -34,7 +33,9 @@ module Spree
Spree::Base.polymorphic_api_type(shipping_label.owner_type)
end
- attributes cost: :string, display_cost: :string
+ money_attributes :cost, :display_cost, currency: ->(label) { label.currency.presence || label.store.default_currency }
+ typelize cost: [:string, nullable: false]
+
prefixed_id_attributes :integration
# Whether the file is still being fetched from the carrier; the
diff --git a/spree/api/app/serializers/spree/api/v3/admin/stock_movement_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/stock_movement_serializer.rb
index 19281b29eb..13b834dc59 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/stock_movement_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/stock_movement_serializer.rb
@@ -101,7 +101,8 @@ module Spree
# purchase. Null on a transfer or a return — moving stock the
# merchant already owns is not buying it.
attribute :unit_cost do |movement|
- movement.unit_cost&.to_s
+ currency = movement.purchase_order&.currency || (current_store || Spree::Current.store)&.default_currency
+ Spree::Money::Rounding.format(movement.unit_cost, currency, unit_price: true)
end
attribute :display_unit_cost do |movement|
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_credit_event_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_credit_event_serializer.rb
index b1d083a210..943fd2387c 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/store_credit_event_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/store_credit_event_serializer.rb
@@ -5,6 +5,9 @@ module Spree
# One line of a store credit's ledger: how the balance moved and what
# moved it. Read-only — events are written by the credit itself.
class StoreCreditEventSerializer < V3::StoreCreditEventSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false]
+
typelize originator_type: [:string, nullable: true],
originator_id: [:string, nullable: true],
store_credit_id: :string
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_credit_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_credit_serializer.rb
index 6a0f8a34c6..c0f258e2fe 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/store_credit_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/store_credit_serializer.rb
@@ -6,8 +6,11 @@ module Spree
typelize customer_id: [:string, nullable: true],
created_by_id: [:string, nullable: true],
memo: [:string, nullable: true],
- amount_authorized: :string,
- display_amount_authorized: :string,
+ amount: [:string, nullable: false], amount_used: [:string, nullable: false],
+ amount_remaining: [:string, nullable: false], display_amount: [:string, nullable: false],
+ display_amount_used: [:string, nullable: false], display_amount_remaining: [:string, nullable: false],
+ amount_authorized: [:string, nullable: false],
+ display_amount_authorized: [:string, nullable: false],
outstanding: :boolean,
originator_type: [:string, nullable: true],
originator_id: [:string, nullable: true],
@@ -16,12 +19,15 @@ module Spree
attributes :memo, :metadata,
created_at: :iso8601, updated_at: :iso8601
- attributes amount_authorized: :string
+ money_attributes :amount_authorized
# Answers the same question as the `outstanding` filter, so the row
# and the filter cannot disagree.
attribute :outstanding, &:outstanding?
- attributes display_amount_authorized: :string
+ money_attributes :display_amount_authorized
+ # money_attributes types its fields nullable for gated guests; the
+ # Admin API never gates prices.
+ typelize amount_authorized: [:string, nullable: false], display_amount_authorized: [:string, nullable: false]
prefixed_id_attributes :customer, :created_by
# Why the credit exists: the return, exchange, claim or gift card
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
index e3001234d3..02df4613b9 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
@@ -47,11 +47,11 @@ module Spree
preferred_inventory_provider_failure_policy: :string,
preferred_payout_provider: [:string, nullable: true, comment: 'Payout provider; null uses the installation default. Built-in: system. Provider gems register more (e.g. stripe).'],
preferred_default_payouts_schedule_interval: :string,
- preferred_default_minimum_payout_amount: :number,
+ preferred_default_minimum_payout_amount: [:string, nullable: true],
preferred_auto_approve_sellers: :boolean,
preferred_auto_approve_seller_products: :boolean,
preferred_send_seller_transactional_emails: :boolean,
- preferred_default_commission_tax_rate: :number,
+ preferred_default_commission_tax_rate: [:string, nullable: true],
preferred_document_number_format: :string,
preferred_order_number_prefix: :string,
preferred_order_number_suffix: :string,
@@ -126,12 +126,10 @@ module Spree
end
attribute :preferred_default_minimum_payout_amount do |store|
- store.preferred_default_minimum_payout_amount&.to_f
+ Spree::Money::Rounding.format(store.preferred_default_minimum_payout_amount, store.default_currency)
end
- attribute :preferred_default_commission_tax_rate do |store|
- store.preferred_default_commission_tax_rate&.to_f
- end
+ rate_attributes :preferred_default_commission_tax_rate
attribute :url, &:storefront_url
diff --git a/spree/api/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb
index a0d668efd5..37ebc4bb7e 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb
@@ -6,8 +6,6 @@ module Spree
# customer-facing. What the customer sees is the label on a tax line.
class TaxRateSerializer < V3::BaseSerializer
typelize name: :string,
- amount: :string,
- amount_percentage: [:number, nullable: true],
included_in_price: :boolean,
show_rate_in_label: :boolean,
tax_category_id: [:string, nullable: true],
@@ -20,15 +18,7 @@ module Spree
attributes :name, :included_in_price, :show_rate_in_label, :metadata,
created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
- attribute :amount do |tax_rate|
- tax_rate.amount&.to_s
- end
-
- # A real number, unlike the money-style `amount` string — this is a
- # percentage for display, not an amount to round-trip exactly.
- attribute :amount_percentage do |tax_rate|
- tax_rate.amount_percentage&.to_f
- end
+ rate_attributes :rate, :rate_percent
prefixed_id_attributes :tax_category, :store
diff --git a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
index daa9231105..75452db5ee 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
@@ -32,7 +32,7 @@ module Spree
# The last three override the store serializer's buyer-resolved
# values with the variant's OWN: a merchant edits what is stored on
# the row, not what some catalog resolves to for a buyer they are not.
- attributes :metadata, :position, :cost_price, :cost_currency,
+ attributes :metadata, :position, :cost_currency,
:barcode, :backorder_limit,
:hs_code, :country_of_origin, :customs_description,
:minimum_order_quantity, :order_multiple, :purchase_unit,
@@ -40,6 +40,8 @@ module Spree
preorder_ships_at: :iso8601, deleted_at: :iso8601,
created_at: :iso8601, updated_at: :iso8601
+ money_attributes :cost_price, currency: :cost_currency, unit_price: true
+
attribute :preorderable, &:preorderable?
# Stored on the row only — nil means inherit from the product. The
diff --git a/spree/api/app/serializers/spree/api/v3/base_serializer.rb b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
index 37422c1be9..6031b0a97d 100644
--- a/spree/api/app/serializers/spree/api/v3/base_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
@@ -16,16 +16,41 @@ module Spree
object.prefixed_id
end
- # Declares money/display attributes that render +null+ for gated
- # (prices_hidden) guests, keyed off the same +hide_prices+ flag the
- # +price_for+/+price_in+ helpers use — so the whole price surface
- # (product prices AND cart/order/line-item totals) is gated from one
- # place instead of per-attribute opt-in.
- def self.money_attributes(*names)
+ # Declares money attributes, written as decimal strings with exactly
+ # the currency's decimal places ("10.00", "1.500", "100"), or up to
+ # four for unit prices ("0.0125"). +display_*+ names pass through as
+ # formatted. All render +null+ for gated (prices_hidden) guests, keyed
+ # off the same +hide_prices+ flag the +price_for+/+price_in+ helpers
+ # use, so the whole price surface is gated from one place.
+ #
+ # @param currency [Symbol, Proc] the record's reader for its currency,
+ # or a block taking the record
+ # @param unit_price [Boolean]
+ def self.money_attributes(*names, currency: :currency, unit_price: false)
+ typelize(**names.index_with { [:string, nullable: true] })
+
+ names.each do |name|
+ attribute(name) do |object|
+ next if params[:hide_prices]
+
+ value = object.public_send(name)
+ next value if name.to_s.start_with?('display_') || value.nil?
+
+ code = currency.is_a?(Proc) ? currency.call(object) : object.public_send(currency)
+ Spree::Money::Rounding.format(value, code, unit_price: unit_price)
+ end
+ end
+ end
+
+ # Declares rates and percentages, written as decimal strings without
+ # trailing zeros ("0.23", "7.25", "10"). A name ending +_percent+ or
+ # +_percentage+ holds 0-100; +rate+ or a name ending +_rate+ holds a
+ # fraction.
+ def self.rate_attributes(*names)
typelize(**names.index_with { [:string, nullable: true] })
names.each do |name|
- attribute(name) { |object| object.public_send(name) unless params[:hide_prices] }
+ attribute(name) { |object| Spree::Money::Rounding.format_decimal(object.public_send(name)) }
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb b/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
index 225a448776..0984c4ec2d 100644
--- a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
@@ -11,8 +11,8 @@ module Spree
preferred_stock_location_id: [:string, nullable: true], company_id: [:string, nullable: true],
company_name: [:string, nullable: true], po_number: [:string, nullable: true],
po_number_required: :boolean, po_document_filename: [:string, nullable: true],
- po_document_byte_size: ['number | null'], order_minimum: ['number | null'],
- order_minimum_shortfall: ['number | null'], below_order_minimum: ['boolean | null'],
+ po_document_byte_size: ['number | null'], order_minimum: [:string, nullable: true],
+ order_minimum_shortfall: [:string, nullable: true], below_order_minimum: ['boolean | null'],
freight_summary: [:FreightSummary, nullable: true],
requirements: 'Array<{step: string, field: string, code: string, message: string}>',
store_credit_total: [:string, nullable: true], display_store_credit_total: [:string, nullable: true],
@@ -70,7 +70,7 @@ module Spree
:fee_total, :display_fee_total
attribute :store_credit_total do |order|
- order.total_applied_store_credit.to_s unless params[:hide_prices]
+ Spree::Money::Rounding.format(order.total_applied_store_credit, order.currency) unless params[:hide_prices]
end
attribute :display_store_credit_total do |order|
@@ -106,11 +106,11 @@ module Spree
# shortfall are amounts, and a storefront that hides prices from
# guests must not hand them "$180 short of $500" instead.
attribute :order_minimum do |order|
- order.order_minimum_amount&.to_f unless params[:hide_prices]
+ Spree::Money::Rounding.format(order.order_minimum_amount, order.currency) unless params[:hide_prices]
end
attribute :order_minimum_shortfall do |order|
- order.order_minimum_shortfall&.to_f unless params[:hide_prices]
+ Spree::Money::Rounding.format(order.order_minimum_shortfall, order.currency) unless params[:hide_prices]
end
attribute :below_order_minimum do |order|
diff --git a/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb
index 1af3954c09..101f9bb4b3 100644
--- a/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb
@@ -6,13 +6,6 @@ module Spree
class ClaimLineItemSerializer < BaseSerializer
typelize quantity: :number,
send_replacement: :boolean,
- refund_amount: :string,
- display_refund_amount: :string,
- paid_amount: :string,
- pre_tax_amount: :string,
- included_tax_total: :string,
- additional_tax_total: :string,
- tax_total: :string,
description: [:string, nullable: true],
variant_id: [:string, nullable: true],
replacement_variant_id: [:string, nullable: true],
@@ -20,12 +13,11 @@ module Spree
attributes :quantity, :send_replacement, :description
- attributes refund_amount: :string
- # What the customer actually paid for these units, tax included — the
- # ceiling the resolve workflow enforces, and what the dashboard offers
- # when the claim carries no explicit amount.
- attributes paid_amount: :string, pre_tax_amount: :string, included_tax_total: :string,
- additional_tax_total: :string, tax_total: :string, display_refund_amount: :string
+ # paid_amount is what the customer actually paid for these units, tax
+ # included — the ceiling the resolve workflow enforces, and what the
+ # dashboard offers when the claim carries no explicit amount.
+ money_attributes :refund_amount, :paid_amount, :pre_tax_amount, :included_tax_total,
+ :additional_tax_total, :tax_total, :display_refund_amount
prefixed_id_attributes :variant, :replacement_variant, :line_item
one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/claim_serializer.rb b/spree/api/app/serializers/spree/api/v3/claim_serializer.rb
index c918db6d12..b9484d0ecf 100644
--- a/spree/api/app/serializers/spree/api/v3/claim_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/claim_serializer.rb
@@ -10,8 +10,6 @@ module Spree
resolution: [:string, nullable: true],
order_id: [:string, nullable: true],
reason_id: [:string, nullable: true],
- refund_total: :string,
- display_refund_total: :string,
approved_at: [:string, nullable: true],
resolved_at: [:string, nullable: true],
denied_at: [:string, nullable: true],
@@ -21,7 +19,8 @@ module Spree
prefixed_id_attributes :order, :reason
- attributes refund_total: :string, display_refund_total: :string
+ money_attributes :refund_total, :display_refund_total
+
attribute :approved_at do |claim|
claim.approved_at&.iso8601
end
diff --git a/spree/api/app/serializers/spree/api/v3/currency_serializer.rb b/spree/api/app/serializers/spree/api/v3/currency_serializer.rb
index 822a69703c..6324ff34ae 100644
--- a/spree/api/app/serializers/spree/api/v3/currency_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/currency_serializer.rb
@@ -5,9 +5,15 @@ module Spree
include Alba::Resource
include Typelizer::DSL
- typelize iso_code: :string, name: :string, symbol: :string
+ typelize iso_code: :string, name: :string, symbol: :string, decimal_places: :number
attributes :iso_code, :name, :symbol
+
+ # ISO 4217 minor units: the decimals every amount in this currency is
+ # written with (2 for USD, 0 for JPY, 3 for KWD).
+ attribute :decimal_places do |currency|
+ Spree::Money::Rounding.precision(currency)
+ end
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/customer_serializer.rb b/spree/api/app/serializers/spree/api/v3/customer_serializer.rb
index a26c24992f..f2738da03f 100644
--- a/spree/api/app/serializers/spree/api/v3/customer_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/customer_serializer.rb
@@ -28,7 +28,7 @@ module Spree
attribute :available_store_credit_total do |user, params|
store = params&.dig(:store) || Spree::Current.store
currency = params&.dig(:currency) || Spree::Current.currency || store&.default_currency
- user.total_available_store_credit(currency, store).to_s
+ Spree::Money::Rounding.format(user.total_available_store_credit(currency, store), currency)
end
attribute :display_available_store_credit_total do |user, params|
diff --git a/spree/api/app/serializers/spree/api/v3/delivery_rate_serializer.rb b/spree/api/app/serializers/spree/api/v3/delivery_rate_serializer.rb
index d8c3438a5c..8ab4b8d08b 100644
--- a/spree/api/app/serializers/spree/api/v3/delivery_rate_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/delivery_rate_serializer.rb
@@ -3,11 +3,6 @@ module Spree
module V3
class DeliveryRateSerializer < BaseSerializer
typelize name: :string, selected: :boolean, delivery_method_id: :string,
- cost: :string, display_cost: :string,
- total: :string, display_total: :string,
- additional_tax_total: :string, display_additional_tax_total: :string,
- included_tax_total: :string, display_included_tax_total: :string,
- tax_total: :string, display_tax_total: :string,
carrier: [:string, nullable: true],
service_level: [:string, nullable: true],
estimated_delivery_date: [:string, nullable: true],
@@ -19,11 +14,11 @@ module Spree
# Carrier, service level and delivery date come from the rate provider
# and are what the customer chooses between; nil on calculator-priced
# methods. Provider metadata stays admin-only.
- attributes :name, :selected,
- :cost, :total,
- :additional_tax_total, :included_tax_total,
- :tax_total,
- :carrier, :service_level, :estimated_delivery_date,
+ attributes :name, :selected
+
+ money_attributes :cost, :total, :additional_tax_total, :included_tax_total, :tax_total
+
+ attributes :carrier, :service_level, :estimated_delivery_date,
:unpriced
# What the shipment looks like to a freight forwarder — cartons,
@@ -33,8 +28,9 @@ module Spree
# froze it here when it quoted.
one :freight_summary, resource: proc { Spree.api.freight_summary_serializer }
- attributes display_cost: :string, display_total: :string, display_additional_tax_total: :string,
- display_included_tax_total: :string, display_tax_total: :string
+ money_attributes :display_cost, :display_total, :display_additional_tax_total,
+ :display_included_tax_total, :display_tax_total
+
one :delivery_method, resource: proc { Spree.api.delivery_method_serializer }
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/discount_serializer.rb b/spree/api/app/serializers/spree/api/v3/discount_serializer.rb
index ec063b7d03..747469d276 100644
--- a/spree/api/app/serializers/spree/api/v3/discount_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/discount_serializer.rb
@@ -12,8 +12,11 @@ module Spree
attributes :label, :kind, :code, :value_type
+ # A percent discount carries a rate; a flat one an amount.
attribute :value do |record|
- record.value&.to_s
+ next Spree::Money::Rounding.format_decimal(record.value) if record.value_type == 'percent'
+
+ Spree::Money::Rounding.format(record.value, record.currency) unless params[:hide_prices]
end
prefixed_id_attributes :promotion, :line_item, :fulfillment
diff --git a/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb
index 3306b31d4d..593f92ce35 100644
--- a/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb
@@ -7,11 +7,6 @@ module Spree
typelize quantity: :number,
received_quantity: :number,
resellable: :boolean,
- original_price: :string,
- new_variant_price: :string,
- price_difference: :string,
- original_tax_total: :string,
- new_tax_total: :string,
original_variant_id: [:string, nullable: true],
new_variant_id: [:string, nullable: true],
line_item_id: [:string, nullable: true],
@@ -21,10 +16,9 @@ module Spree
# What the customer paid for the units coming back, after discounts
# and with their tax.
- attributes original_price: :string
+ money_attributes :original_price
# The replacement at the same discount, with its own tax.
- attributes new_variant_price: :string, price_difference: :string, original_tax_total: :string,
- new_tax_total: :string
+ money_attributes :new_variant_price, :price_difference, :original_tax_total, :new_tax_total
prefixed_id_attributes :original_variant, :new_variant, :line_item, :fulfillment_item
one :original_variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('original_variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb b/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb
index 1244863b7e..4d0f9cbf88 100644
--- a/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb
@@ -9,8 +9,6 @@ module Spree
status: [:string, enum: Spree::Exchange.statuses, enum_type_name: 'ExchangeStatus'],
order_id: [:string, nullable: true],
reason_id: [:string, nullable: true],
- price_difference: :string,
- display_price_difference: :string,
approved_at: [:string, nullable: true],
received_at: [:string, nullable: true],
fulfilled_at: [:string, nullable: true],
@@ -20,7 +18,8 @@ module Spree
prefixed_id_attributes :order, :reason
- attributes price_difference: :string, display_price_difference: :string
+ money_attributes :price_difference, :display_price_difference
+
attribute :approved_at do |exchange|
exchange.approved_at&.iso8601
end
diff --git a/spree/api/app/serializers/spree/api/v3/gift_card_batch_serializer.rb b/spree/api/app/serializers/spree/api/v3/gift_card_batch_serializer.rb
index 2bc8338723..94cc7b7721 100644
--- a/spree/api/app/serializers/spree/api/v3/gift_card_batch_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/gift_card_batch_serializer.rb
@@ -4,16 +4,14 @@ module Spree
module Api
module V3
class GiftCardBatchSerializer < BaseSerializer
- typelize codes_count: :number, amount: [:string, nullable: true], currency: [:string, nullable: true],
+ typelize codes_count: :number, currency: [:string, nullable: true],
prefix: [:string, nullable: true], expires_at: [:string, nullable: true],
created_by_id: [:string, nullable: true]
attributes :codes_count, :currency, :prefix,
created_at: :iso8601, updated_at: :iso8601
- attribute :amount do |batch|
- batch.amount&.to_s
- end
+ money_attributes :amount
attribute :expires_at do |batch|
batch.expires_at&.iso8601
diff --git a/spree/api/app/serializers/spree/api/v3/line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/line_item_serializer.rb
index dec753b2ae..d966ac4ca8 100644
--- a/spree/api/app/serializers/spree/api/v3/line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/line_item_serializer.rb
@@ -30,7 +30,8 @@ module Spree
# Nulled for gated (prices_hidden) guests so the cart's line items can't
# leak the prices that product/variant serializers already withhold.
- money_attributes :price, :display_price, :total, :display_total,
+ money_attributes :price, :display_price, unit_price: true
+ money_attributes :total, :display_total,
:adjustment_total, :display_adjustment_total,
:additional_tax_total, :display_additional_tax_total,
:included_tax_total, :display_included_tax_total,
@@ -44,7 +45,7 @@ module Spree
next nil if params[:hide_prices]
amount = line_item.compare_at_amount
- amount.present? && amount.positive? ? amount.to_s : nil
+ amount.present? && amount.positive? ? Spree::Money::Rounding.format(amount, line_item.currency, unit_price: true) : nil
end
# Thumbnail URL for line item (variant thumbnail or product thumbnail)
diff --git a/spree/api/app/serializers/spree/api/v3/order_group_serializer.rb b/spree/api/app/serializers/spree/api/v3/order_group_serializer.rb
index 63baaf3a07..d923470b51 100644
--- a/spree/api/app/serializers/spree/api/v3/order_group_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/order_group_serializer.rb
@@ -9,8 +9,6 @@ module Spree
# inside it, each carrying its own items, delivery and tracking.
class OrderGroupSerializer < BaseSerializer
typelize number: :string, email: [:string, nullable: true], currency: :string,
- total: [:string, nullable: true], display_total: [:string, nullable: true],
- item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],
fulfillment_status: [:string, nullable: true, enum: Spree::Order::FULFILLMENT_STATUSES],
payment_status: [:string, nullable: true, enum: Spree::Order::PAYMENT_STATUSES],
completed_at: [:string, nullable: true],
@@ -18,7 +16,8 @@ module Spree
attributes :number, :email, :currency
- attributes total: :string, display_total: :string, item_total: :string, display_item_total: :string
+ money_attributes :total, :display_total, :item_total, :display_item_total
+
# Rolled up across the children rather than stored, so it can never
# disagree with the orders it describes.
attributes :fulfillment_status, :payment_status
diff --git a/spree/api/app/serializers/spree/api/v3/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/order_serializer.rb
index 11f055f290..db79b7e385 100644
--- a/spree/api/app/serializers/spree/api/v3/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/order_serializer.rb
@@ -75,7 +75,7 @@ module Spree
:fee_total, :display_fee_total
attribute :store_credit_total do |order|
- order.total_applied_store_credit.to_s unless params[:hide_prices]
+ Spree::Money::Rounding.format(order.total_applied_store_credit, order.currency) unless params[:hide_prices]
end
attribute :display_store_credit_total do |order|
diff --git a/spree/api/app/serializers/spree/api/v3/payment_session_serializer.rb b/spree/api/app/serializers/spree/api/v3/payment_session_serializer.rb
index 67eef86aee..6846478dad 100644
--- a/spree/api/app/serializers/spree/api/v3/payment_session_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/payment_session_serializer.rb
@@ -2,7 +2,7 @@ module Spree
module Api
module V3
class PaymentSessionSerializer < BaseSerializer
- typelize status: [:string, enum: Spree::PaymentSession.statuses, enum_type_name: 'PaymentSessionStatus'], amount: :string, currency: :string,
+ typelize status: [:string, enum: Spree::PaymentSession.statuses, enum_type_name: 'PaymentSessionStatus'], currency: :string,
external_id: :string, external_data: 'Record<string, unknown>',
expires_at: [:string, nullable: true], customer_external_id: [:string, nullable: true],
payment_method_id: :string, order_id: [:string, nullable: true],
@@ -12,9 +12,7 @@ module Spree
:customer_external_id,
expires_at: :iso8601
- attribute :amount do |session|
- session.amount&.to_s
- end
+ money_attributes :amount
prefixed_id_attributes :payment_method
diff --git a/spree/api/app/serializers/spree/api/v3/price_history_serializer.rb b/spree/api/app/serializers/spree/api/v3/price_history_serializer.rb
index 4085d3c722..d0cb2d5a9c 100644
--- a/spree/api/app/serializers/spree/api/v3/price_history_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/price_history_serializer.rb
@@ -4,13 +4,13 @@ module Spree
module Api
module V3
class PriceHistorySerializer < BaseSerializer
- typelize amount: :string,
- amount_in_cents: :number,
- display_amount: :string,
+ typelize display_amount: :string,
currency: :string,
recorded_at: :string
- attributes :amount, :amount_in_cents, :currency
+ attributes :currency
+
+ money_attributes :amount, unit_price: true
attributes :display_amount
diff --git a/spree/api/app/serializers/spree/api/v3/price_serializer.rb b/spree/api/app/serializers/spree/api/v3/price_serializer.rb
index 0477a1e626..89f73b000e 100644
--- a/spree/api/app/serializers/spree/api/v3/price_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/price_serializer.rb
@@ -5,17 +5,14 @@ module Spree
# Represents a resolved/calculated price for storefront display
# Can represent either a calculated price (with price list resolution) or a base price
class PriceSerializer < BaseSerializer
- typelize amount: [:string, nullable: true],
- amount_in_cents: [:number, nullable: true],
- display_amount: [:string, nullable: true],
- compare_at_amount: [:string, nullable: true],
- compare_at_amount_in_cents: [:number, nullable: true],
+ typelize display_amount: [:string, nullable: true],
display_compare_at_amount: [:string, nullable: true],
currency: [:string, nullable: true],
price_list_id: [:string, nullable: true]
- attributes :amount, :amount_in_cents, :compare_at_amount,
- :compare_at_amount_in_cents, :currency
+ attributes :currency
+
+ money_attributes :amount, :compare_at_amount, unit_price: true
attribute :display_amount do |price|
price.display_amount&.to_s
diff --git a/spree/api/app/serializers/spree/api/v3/product_filter_price_range_serializer.rb b/spree/api/app/serializers/spree/api/v3/product_filter_price_range_serializer.rb
index 59d1974bdd..5e18f0a6bc 100644
--- a/spree/api/app/serializers/spree/api/v3/product_filter_price_range_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/product_filter_price_range_serializer.rb
@@ -4,11 +4,17 @@ module Spree
class ProductFilterPriceRangeSerializer < BaseSerializer
typelize id: :string,
type: "'price_range'",
- min: :number,
- max: :number,
+ min: :string,
+ max: :string,
currency: :string
- attributes :id, :type, :min, :max, :currency
+ attributes :id, :type
+
+ # Search providers hand the bounds over as numbers.
+ attribute(:min) { |range| Spree::Money::Rounding.format(range[:min], range[:currency], unit_price: true) }
+ attribute(:max) { |range| Spree::Money::Rounding.format(range[:max], range[:currency], unit_price: true) }
+
+ attributes :currency
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/refund_serializer.rb b/spree/api/app/serializers/spree/api/v3/refund_serializer.rb
index 8ff3b62295..96c3470e2a 100644
--- a/spree/api/app/serializers/spree/api/v3/refund_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/refund_serializer.rb
@@ -4,15 +4,13 @@ module Spree
module Api
module V3
class RefundSerializer < BaseSerializer
- typelize amount: [:string, nullable: true], transaction_id: [:string, nullable: true],
+ typelize transaction_id: [:string, nullable: true],
payment_id: [:string, nullable: true], refund_reason_id: [:string, nullable: true],
originator_id: [:string, nullable: true], originator_type: [:string, nullable: true]
attributes :transaction_id
- attribute :amount do |refund|
- refund.amount&.to_s
- end
+ money_attributes :amount
prefixed_id_attributes :payment, refund_reason_id: :reason
diff --git a/spree/api/app/serializers/spree/api/v3/return_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/return_line_item_serializer.rb
index 98bf354e2d..53666c6f99 100644
--- a/spree/api/app/serializers/spree/api/v3/return_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/return_line_item_serializer.rb
@@ -7,25 +7,17 @@ module Spree
typelize quantity: :number,
received_quantity: :number,
resellable: :boolean,
- pre_tax_amount: :string,
- display_pre_tax_amount: :string,
- included_tax_total: :string,
- additional_tax_total: :string,
- tax_total: :string,
- display_tax_total: :string,
- refund_amount: :string,
- display_refund_amount: :string,
variant_id: [:string, nullable: true],
line_item_id: [:string, nullable: true],
fulfillment_item_id: [:string, nullable: true]
attributes :quantity, :received_quantity, :resellable
- attributes pre_tax_amount: :string, display_pre_tax_amount: :string, included_tax_total: :string,
- additional_tax_total: :string, tax_total: :string, display_tax_total: :string
+ money_attributes :pre_tax_amount, :display_pre_tax_amount, :included_tax_total,
+ :additional_tax_total, :tax_total, :display_tax_total
# What the line refunds, tax included — for the units that arrived
# once the warehouse has counted.
- attributes refund_amount: :string, display_refund_amount: :string
+ money_attributes :refund_amount, :display_refund_amount
prefixed_id_attributes :variant, :line_item, :fulfillment_item
one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
diff --git a/spree/api/app/serializers/spree/api/v3/return_serializer.rb b/spree/api/app/serializers/spree/api/v3/return_serializer.rb
index dc274374c2..3dd335df1f 100644
--- a/spree/api/app/serializers/spree/api/v3/return_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/return_serializer.rb
@@ -10,10 +10,6 @@ module Spree
status: [:string, enum: Spree::Return.statuses, enum_type_name: 'ReturnStatus'],
order_id: [:string, nullable: true],
reason_id: [:string, nullable: true],
- refund_total: :string,
- display_refund_total: :string,
- refund_tax_total: :string,
- display_refund_tax_total: :string,
approved_at: [:string, nullable: true],
received_at: [:string, nullable: true],
refunded_at: [:string, nullable: true],
@@ -23,9 +19,10 @@ module Spree
prefixed_id_attributes :order, :reason
- attributes refund_total: :string, display_refund_total: :string
+ money_attributes :refund_total, :display_refund_total
# The tax inside refund_total.
- attributes refund_tax_total: :string, display_refund_tax_total: :string
+ money_attributes :refund_tax_total, :display_refund_tax_total
+
attribute :approved_at do |return_record|
return_record.approved_at&.iso8601
end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/balance_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/balance_serializer.rb
index ed57bac6e3..b16d6b0bc4 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/balance_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/balance_serializer.rb
@@ -25,7 +25,7 @@ module Spree
attribute(:converted) { |balance| balance.converted? }
%i[earned payable paid balance pending].each do |figure|
- attribute(figure) { |balance| balance.public_send(figure).to_s }
+ attribute(figure) { |balance| Spree::Money::Rounding.format(balance.public_send(figure), balance.settlement_currency) }
attribute(:"display_#{figure}") { |balance| balance.public_send(:"display_#{figure}").to_s }
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb
index 67a062ebcd..8ff0ea9642 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb
@@ -7,6 +7,12 @@ module Spree
# One line of a claim — what went wrong, and what is being sent or
# refunded to put it right.
class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize refund_amount: [:string, nullable: false], paid_amount: [:string, nullable: false],
+ pre_tax_amount: [:string, nullable: false], included_tax_total: [:string, nullable: false],
+ additional_tax_total: [:string, nullable: false], tax_total: [:string, nullable: false],
+ display_refund_amount: [:string, nullable: false]
+
typelize name: [:string, nullable: true]
attribute :name do |line|
diff --git a/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb
index 80df34d85c..15957d973b 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb
@@ -9,6 +9,9 @@ module Spree
# Built on the shared V3 serializer rather than the admin one, which
# expands the order and the customer behind it.
class ClaimSerializer < V3::ClaimSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize refund_total: [:string, nullable: false], display_refund_total: [:string, nullable: false]
+
typelize memo: [:string, nullable: true]
attributes :memo
diff --git a/spree/api/app/serializers/spree/api/v3/seller/delivery_rate_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/delivery_rate_serializer.rb
index ec93334600..36132dc0c9 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/delivery_rate_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/delivery_rate_serializer.rb
@@ -10,18 +10,19 @@ module Spree
class DeliveryRateSerializer < V3::BaseSerializer
typelize name: :string,
selected: :boolean,
- cost: :string,
- display_cost: :string,
- total: :string,
- display_total: :string,
carrier: [:string, nullable: true],
service_level: [:string, nullable: true],
estimated_delivery_date: [:string, nullable: true]
- attributes :name, :selected, :cost, :total,
- :carrier, :service_level, :estimated_delivery_date
+ attributes :name, :selected
- attributes display_cost: :string, display_total: :string
+ money_attributes :cost, :total
+
+ attributes :carrier, :service_level, :estimated_delivery_date
+
+ money_attributes :display_cost, :display_total
+ typelize cost: [:string, nullable: false], display_cost: [:string, nullable: false],
+ total: [:string, nullable: false], display_total: [:string, nullable: false]
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb
index 5539256b8e..6b80090961 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb
@@ -7,6 +7,11 @@ module Spree
# One line of an exchange — what came back and what goes out in its
# place. Both variants expand through the seller's own serializer.
class ExchangeLineItemSerializer < V3::ExchangeLineItemSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize original_price: [:string, nullable: false], new_variant_price: [:string, nullable: false],
+ price_difference: [:string, nullable: false], original_tax_total: [:string, nullable: false],
+ new_tax_total: [:string, nullable: false]
+
typelize name: [:string, nullable: true],
new_variant_name: [:string, nullable: true]
diff --git a/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb
index a20ffa87e7..0030925be2 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb
@@ -9,6 +9,9 @@ module Spree
# Built on the shared V3 serializer rather than the admin one, which
# expands the order and the customer behind it.
class ExchangeSerializer < V3::ExchangeSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize price_difference: [:string, nullable: false], display_price_difference: [:string, nullable: false]
+
typelize memo: [:string, nullable: true],
stock_location_id: [:string, nullable: true]
diff --git a/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb
index a2408bfab9..9d12eb1378 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb
@@ -18,7 +18,8 @@ module Spree
attributes :name, :options_text, :quantity, :currency
# The tax charged on top is what a claim refunds beside the goods.
- money_attributes :price, :display_price, :discounted_amount, :display_discounted_amount,
+ money_attributes :price, :display_price, unit_price: true
+ money_attributes :discounted_amount, :display_discounted_amount,
:additional_tax_total, :total, :display_total
prefixed_id_attributes :variant
diff --git a/spree/api/app/serializers/spree/api/v3/seller/payment_split_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/payment_split_serializer.rb
index 787cd4428b..7c81a3d8d5 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/payment_split_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/payment_split_serializer.rb
@@ -24,7 +24,7 @@ module Spree
attributes :currency, created_at: :iso8601
AMOUNTS.each do |amount|
- attribute(amount) { |split| split.public_send(amount).to_s }
+ attribute(amount) { |split| Spree::Money::Rounding.format(split.public_send(amount), split.currency) }
attribute(:"display_#{amount}") { |split| split.public_send(:"display_#{amount}").to_s }
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/payout_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/payout_serializer.rb
index 4e676899d8..3cffb1d933 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/payout_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/payout_serializer.rb
@@ -18,7 +18,7 @@ module Spree
period_start: :iso8601, period_end: :iso8601,
created_at: :iso8601, updated_at: :iso8601
- attribute(:amount) { |payout| payout.amount&.to_s }
+ attribute(:amount) { |payout| Spree::Money::Rounding.format(payout.amount, payout.currency) }
attribute(:display_amount) { |payout| payout.display_amount.to_s }
# How many earnings this settlement covers. Read from a count the
diff --git a/spree/api/app/serializers/spree/api/v3/seller/profile_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/profile_serializer.rb
index 24e0f4a2f5..01bd8797b3 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/profile_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/profile_serializer.rb
@@ -28,7 +28,7 @@ module Spree
created_at: :iso8601
attribute :minimum_payout_amount do |seller|
- seller.minimum_payout_amount&.to_s
+ Spree::Money::Rounding.format(seller.minimum_payout_amount, seller.store&.default_currency)
end
# Rebound from the inherited store declaration to this branch's own
diff --git a/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb
index 2a173edb3c..6dacde440d 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb
@@ -10,6 +10,12 @@ module Spree
# its option values but no product name, so a card built from the
# variant alone would show a bare id for anything unSKU'd.
class ReturnLineItemSerializer < V3::ReturnLineItemSerializer
+ # No guest price gating here, so the inherited money fields are always present.
+ typelize pre_tax_amount: [:string, nullable: false], display_pre_tax_amount: [:string, nullable: false],
+ included_tax_total: [:string, nullable: false], additional_tax_total: [:string, nullable: false],
+ tax_total: [:string, nullable: false], display_tax_total: [:string, nullable: false],
+ refund_amount: [:string, nullable: false], display_refund_amount: [:string, nullable: false]
+
typelize name: [:string, nullable: true]
attribute :name do |line|
diff --git a/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb
index f0ef298805..ffda075c10 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb
@@ -15,18 +15,20 @@ module Spree
class ReturnSerializer < V3::ReturnSerializer
typelize memo: [:string, nullable: true],
stock_location_id: [:string, nullable: true],
- refunded_total: :string,
- refundable_total: :string,
- display_refunded_total: :string
+ refund_total: [:string, nullable: false], display_refund_total: [:string, nullable: false],
+ refund_tax_total: [:string, nullable: false], display_refund_tax_total: [:string, nullable: false]
attributes :memo
prefixed_id_attributes :stock_location
- attributes refunded_total: :string
+ money_attributes :refunded_total
# What the refund dialog opens on — never more than this may be
# given back, whatever amount is typed.
- attributes refundable_total: :string, display_refunded_total: :string
+ money_attributes :refundable_total, :display_refunded_total
+ typelize refunded_total: [:string, nullable: false], refundable_total: [:string, nullable: false],
+ display_refunded_total: [:string, nullable: false]
+
many :return_line_items,
resource: proc { Spree.api.seller_return_line_item_serializer },
if: proc { expand?('return_line_items') }
diff --git a/spree/api/app/serializers/spree/api/v3/seller/transfer_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/transfer_serializer.rb
index ac1466a7da..3828093070 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/transfer_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/transfer_serializer.rb
@@ -27,13 +27,14 @@ module Spree
attributes :kind, :status, :currency, :reference,
created_at: :iso8601, updated_at: :iso8601
- # A string, so the figure a seller is paid round-trips exactly.
- attribute(:amount) { |transfer| transfer.amount&.to_s }
+ attribute(:amount) { |transfer| Spree::Money::Rounding.format(transfer.amount, transfer.currency) }
attribute(:display_amount) { |transfer| transfer.display_amount.to_s }
# What this seller's account received, when the provider converted
# on the way in. Null when it settled in the currency of the sale.
- attribute(:settled_amount) { |transfer| transfer.settled_amount&.to_s }
+ attribute(:settled_amount) do |transfer|
+ Spree::Money::Rounding.format(transfer.settled_amount, transfer.settled_currency || transfer.currency)
+ end
attribute(:settled_currency) { |transfer| transfer.settled_currency }
attribute(:converted) { |transfer| transfer.converted? }
diff --git a/spree/api/app/serializers/spree/api/v3/seller/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/variant_serializer.rb
index 6be48ca80b..2009617951 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/variant_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/variant_serializer.rb
@@ -26,12 +26,14 @@ module Spree
purchase_unit: [:string, nullable: true, enum: Spree::Variant::PURCHASE_UNITS],
metadata: 'Record<string, unknown>'
- attributes :metadata, :position, :cost_price, :cost_currency,
+ attributes :metadata, :position, :cost_currency,
:barcode, :backorder_limit,
:hs_code, :country_of_origin, :customs_description,
preorder_ships_at: :iso8601,
created_at: :iso8601, updated_at: :iso8601
+ money_attributes :cost_price, currency: :cost_currency, unit_price: true
+
# The variant's own stored rules, not a buyer's resolved ones — a
# seller edits the row.
attribute :minimum_order_quantity, &:minimum_order_quantity
diff --git a/spree/api/app/serializers/spree/api/v3/store_credit_event_serializer.rb b/spree/api/app/serializers/spree/api/v3/store_credit_event_serializer.rb
index e824f5e292..4cb2b16875 100644
--- a/spree/api/app/serializers/spree/api/v3/store_credit_event_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/store_credit_event_serializer.rb
@@ -4,15 +4,13 @@ module Spree
class StoreCreditEventSerializer < BaseSerializer
typelize action: :string,
display_action: [:string, nullable: true],
- amount: :string,
- display_amount: :string,
authorization_code: [:string, nullable: true]
attributes :action, :authorization_code
attributes :display_action
- attributes amount: :string, display_amount: :string
+ money_attributes :amount, :display_amount
attributes created_at: :iso8601
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/store_credit_serializer.rb b/spree/api/app/serializers/spree/api/v3/store_credit_serializer.rb
index ff8965f49b..d1212efe17 100644
--- a/spree/api/app/serializers/spree/api/v3/store_credit_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/store_credit_serializer.rb
@@ -2,12 +2,10 @@ module Spree
module Api
module V3
class StoreCreditSerializer < BaseSerializer
- typelize amount: :string, amount_used: :string, amount_remaining: :string,
- display_amount: :string, display_amount_used: :string, display_amount_remaining: :string,
- currency: :string
+ typelize currency: :string
- attributes amount: :string, amount_used: :string, amount_remaining: :string, display_amount: :string,
- display_amount_used: :string, display_amount_remaining: :string
+ money_attributes :amount, :amount_used, :amount_remaining, :display_amount,
+ :display_amount_used, :display_amount_remaining
attributes :currency
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/tax_line_serializer.rb b/spree/api/app/serializers/spree/api/v3/tax_line_serializer.rb
index 1af987c4f5..0939891090 100644
--- a/spree/api/app/serializers/spree/api/v3/tax_line_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/tax_line_serializer.rb
@@ -5,7 +5,7 @@ module Spree
# or, after the sale, the tax a return, claim or exchange line gives
# back (`credit`) or charges on an exchange's replacement.
class TaxLineSerializer < BaseSerializer
- typelize label: :string, rate: :string, included: :boolean, credit: :boolean,
+ typelize label: :string, included: :boolean, credit: :boolean,
tax_rate_id: [:string, nullable: true], line_item_id: [:string, nullable: true],
fulfillment_id: [:string, nullable: true], fee_id: [:string, nullable: true],
return_line_item_id: [:string, nullable: true], claim_line_item_id: [:string, nullable: true],
@@ -13,9 +13,7 @@ module Spree
attributes :label, :included, :credit
- attribute :rate do |record|
- record.rate&.to_s
- end
+ rate_attributes :rate
prefixed_id_attributes :tax_rate, :line_item, :fulfillment, :fee, :return_line_item, :claim_line_item,
:exchange_line_item
diff --git a/spree/api/app/services/spree/api/v3/filters_aggregator.rb b/spree/api/app/services/spree/api/v3/filters_aggregator.rb
index 3237f2cfd6..4a3e92e13d 100644
--- a/spree/api/app/services/spree/api/v3/filters_aggregator.rb
+++ b/spree/api/app/services/spree/api/v3/filters_aggregator.rb
@@ -63,8 +63,8 @@ module Spree
{
id: 'price',
type: 'price_range',
- min: min.to_f,
- max: max.to_f,
+ min: min,
+ max: max,
currency: @currency
}
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/catalogs/order_minimums_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/catalogs/order_minimums_controller_spec.rb
index 8c9f5853f2..f3accd187a 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/catalogs/order_minimums_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/catalogs/order_minimums_controller_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe Spree::Api::V3::Admin::Catalogs::OrderMinimumsController, type: :
expect(response).to have_http_status(:ok)
row = json_response['data'].first
expect(row['currency']).to eq('USD')
- expect(row['amount']).to eq('500.0')
+ expect(row['amount']).to eq('500.00')
expect(row['display_amount']).to include('500')
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/catalogs/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/catalogs/products_controller_spec.rb
index d932f00454..6872c08b21 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/catalogs/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/catalogs/products_controller_spec.rb
@@ -120,7 +120,7 @@ RSpec.describe Spree::Api::V3::Admin::Catalogs::ProductsController, type: :contr
get :index, params: { catalog_id: catalog.prefixed_id, expand: 'catalog_price' }, as: :json
price = json_response['data'].first['catalog_variants'].first
- expect(price['amount']).to eq('85.0')
+ expect(price['amount']).to eq('85.00')
expect(price['source']).to eq('automatic')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb
index f3bb9ec62e..304369f3c6 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb
@@ -178,7 +178,7 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller do
get :show, params: { id: created.prefixed_id, expand: 'price_list' }, as: :json
- expect(json_response['price_list']['price_adjustment_percentage']).to eq('-10.0')
+ expect(json_response['price_list']['price_adjustment_percentage']).to eq('-10')
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb
index d45a19c6a5..7cc34444da 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb
@@ -34,9 +34,9 @@ RSpec.describe Spree::Api::V3::Admin::CommissionLinesController, type: :controll
expect(response).to have_http_status(:ok)
row = json_response['data'].first
expect(row['commission_rate']['name']).to eq('Standard commission')
- expect(row['amount']).to eq('10.0')
- expect(row['tax_amount']).to eq('2.1')
- expect(row['total']).to eq('12.1')
+ expect(row['amount']).to eq('10.00')
+ expect(row['tax_amount']).to eq('2.10')
+ expect(row['total']).to eq('12.10')
expect(row['display_total']).to eq('$12.10')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb
index ccf25997f2..12b0f9a0d2 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb
@@ -114,8 +114,8 @@ RSpec.describe Spree::Api::V3::Admin::CommissionRatesController, type: :controll
expect(response).to have_http_status(:created)
expect(json_response['bounds']).to eq(
- 'USD' => { 'min_amount' => '2.0', 'max_amount' => '20.0' },
- 'PLN' => { 'min_amount' => nil, 'max_amount' => '80.0' }
+ 'USD' => { 'min_amount' => '2.00', 'max_amount' => '20.00' },
+ 'PLN' => { 'min_amount' => nil, 'max_amount' => '80.00' }
)
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/customers/store_credits_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/customers/store_credits_controller_spec.rb
index 013841cc78..074b61edd2 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/customers/store_credits_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/customers/store_credits_controller_spec.rb
@@ -69,7 +69,7 @@ RSpec.describe Spree::Api::V3::Admin::Customers::StoreCreditsController, type: :
let(:headers) { { 'x-spree-api-key' => secret_api_key.plaintext_token } }
let(:create_params) do
- { customer_id: customer.prefixed_id, amount: 10.0, currency: 'USD' }
+ { customer_id: customer.prefixed_id, amount: '10.00', currency: 'USD' }
end
context 'with a key granting only read_store_credits' do
@@ -109,7 +109,7 @@ RSpec.describe Spree::Api::V3::Admin::Customers::StoreCreditsController, type: :
expect {
post :create, params: {
customer_id: customer.prefixed_id,
- amount: 25.00,
+ amount: '25.00',
currency: 'USD',
memo: 'Goodwill'
}, as: :json
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/delivery_methods_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/delivery_methods_controller_spec.rb
index 61dacaa778..8cc53f32d4 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/delivery_methods_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/delivery_methods_controller_spec.rb
@@ -96,7 +96,7 @@ RSpec.describe Spree::Api::V3::Admin::DeliveryMethodsController, type: :controll
it 'creates service rows with markup and label from a flat payload' do
patch :update, params: {
id: delivery_method.prefixed_id,
- markup_percent: 5,
+ markup_percent: '5',
services: [
{ carrier: 'UPS', service: 'Ground', label: 'UPS standard' },
{ carrier: 'USPS', service: 'Priority', markup_flat: '2.5' }
@@ -104,7 +104,7 @@ RSpec.describe Spree::Api::V3::Admin::DeliveryMethodsController, type: :controll
}, as: :json
expect(response).to have_http_status(:ok)
- expect(json_response['markup_percent']).to eq('5.0')
+ expect(json_response['markup_percent']).to eq('5')
services = json_response['services']
expect(services.size).to eq(2)
ups = services.find { |row| row['carrier'] == 'UPS' }
@@ -157,7 +157,7 @@ RSpec.describe Spree::Api::V3::Admin::DeliveryMethodsController, type: :controll
name: 'Express',
storefront_visible: true,
calculator_type: 'flat_rate',
- calculator_preferences: { amount: 12.5 },
+ calculator_preferences: { amount: '12.5' },
delivery_zone_id: zone.prefixed_id
}, as: :json
@@ -177,7 +177,7 @@ RSpec.describe Spree::Api::V3::Admin::DeliveryMethodsController, type: :controll
it 'keeps the amount when no calculator is named' do
post :create, params: {
name: 'Priced by default',
- calculator_preferences: { amount: 7.25 }
+ calculator_preferences: { amount: '7.25' }
}, as: :json
expect(response).to have_http_status(:created)
@@ -227,7 +227,7 @@ RSpec.describe Spree::Api::V3::Admin::DeliveryMethodsController, type: :controll
patch :update, params: {
id: delivery_method.prefixed_id,
name: 'UPS Ground v2',
- calculator_preferences: { amount: 99 }
+ calculator_preferences: { amount: '99' }
}, as: :json
expect(response).to have_http_status(:ok)
@@ -239,7 +239,7 @@ RSpec.describe Spree::Api::V3::Admin::DeliveryMethodsController, type: :controll
patch :update, params: {
id: delivery_method.prefixed_id,
calculator_type: 'flat_rate',
- calculator_preferences: { amount: 20, currency: 'USD', amounts: { 'EUR' => '15.0' } }
+ calculator_preferences: { amount: '20', currency: 'USD', amounts: { 'EUR' => '15.0' } }
}, as: :json
expect(response).to have_http_status(:ok)
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/discounts_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/discounts_controller_spec.rb
index b3bcffda8e..041a5bd013 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/discounts_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/discounts_controller_spec.rb
@@ -40,7 +40,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::DiscountsController, type: :contro
expect(response).to have_http_status(:created)
expect(json_response['data'].length).to eq(1)
- expect(json_response['data'].first['amount']).to eq('-3.0')
+ expect(json_response['data'].first['amount']).to eq('-3.00')
expect(order.reload.total).to eq(original_total - 3)
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/fees_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/fees_controller_spec.rb
index 21ae104c87..fdb74edec3 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/fees_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/fees_controller_spec.rb
@@ -19,7 +19,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FeesController, type: :controller
expect(response).to have_http_status(:ok)
expect(json_response['data'].length).to eq(1)
expect(json_response['data'].first['label']).to eq('Handling')
- expect(json_response['data'].first['amount']).to eq('5.0')
+ expect(json_response['data'].first['amount']).to eq('5.00')
end
end
@@ -27,7 +27,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FeesController, type: :controller
it 'creates an order-level fee and re-sums totals' do
original_total = order.total
- post :create, params: { order_id: order.prefixed_id, label: 'Gift wrap', amount: 4, kind: 'gift_wrap' }, as: :json
+ post :create, params: { order_id: order.prefixed_id, label: 'Gift wrap', amount: '4.00', kind: 'gift_wrap' }, as: :json
expect(response).to have_http_status(:created)
expect(json_response['label']).to eq('Gift wrap')
@@ -38,7 +38,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FeesController, type: :controller
it 'creates a line-item fee' do
post :create, params: {
- order_id: order.prefixed_id, line_item_id: line_item.prefixed_id, label: 'Restocking', amount: 2
+ order_id: order.prefixed_id, line_item_id: line_item.prefixed_id, label: 'Restocking', amount: '2.00'
}, as: :json
expect(response).to have_http_status(:created)
@@ -47,13 +47,13 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FeesController, type: :controller
end
it 'rejects a negative amount' do
- post :create, params: { order_id: order.prefixed_id, label: 'Credit', amount: -3 }, as: :json
+ post :create, params: { order_id: order.prefixed_id, label: 'Credit', amount: '-3.00' }, as: :json
expect(response).to have_http_status(:unprocessable_content)
end
it 'rejects an unknown kind' do
- post :create, params: { order_id: order.prefixed_id, label: 'Mystery', amount: 3, kind: 'nonsense' }, as: :json
+ post :create, params: { order_id: order.prefixed_id, label: 'Mystery', amount: '3.00', kind: 'nonsense' }, as: :json
expect(response).to have_http_status(:unprocessable_content)
end
@@ -66,7 +66,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FeesController, type: :controller
order.recalculate_totals!
with_fee_total = order.reload.total
- patch :update, params: { order_id: order.prefixed_id, id: fee.prefixed_id, amount: 8 }, as: :json
+ patch :update, params: { order_id: order.prefixed_id, id: fee.prefixed_id, amount: '8.00' }, as: :json
expect(response).to have_http_status(:ok)
expect(fee.reload.amount).to eq(8)
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb
index 93fd4c9879..dd9d4c2771 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb
@@ -100,7 +100,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ItemsController, type: :controller
context 'with an unusable price' do
subject do
- post :create, params: { order_id: order.prefixed_id, variant_id: variant.prefixed_id, quantity: 1, price: 'NaN' }, as: :json
+ post :create, params: { order_id: order.prefixed_id, variant_id: variant.prefixed_id, quantity: 1, price: '-1' }, as: :json
end
it 'refuses with the invalid_price code' do
@@ -125,9 +125,9 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ItemsController, type: :controller
expect(json_response['error']['code']).to eq('price_override_not_allowed')
end
- context 'with a non-numeric price' do
+ context 'with an unusable price' do
subject do
- post :create, params: { order_id: order.prefixed_id, variant_id: variant.prefixed_id, quantity: 1, price: 'NaN' }, as: :json
+ post :create, params: { order_id: order.prefixed_id, variant_id: variant.prefixed_id, quantity: 1, price: '-1' }, as: :json
end
it 'still refuses with price_override_not_allowed' do
@@ -205,8 +205,8 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ItemsController, type: :controller
expect(line_item.reload.price_source).to be_nil
end
- context 'with a non-numeric price' do
- subject { patch :update, params: { order_id: order.prefixed_id, id: line_item.prefixed_id, price: 'NaN' }, as: :json }
+ context 'with an unusable price' do
+ subject { patch :update, params: { order_id: order.prefixed_id, id: line_item.prefixed_id, price: '-1' }, as: :json }
it 'still refuses with price_override_not_allowed' do
subject
@@ -217,15 +217,15 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ItemsController, type: :controller
end
end
- context 'with an unusable price' do
+ context 'with a non-numeric price' do
subject { patch :update, params: { order_id: order.prefixed_id, id: line_item.prefixed_id, price: 'NaN' }, as: :json }
it 'refuses with 422 and an actionable message' do
subject
expect(response).to have_http_status(:unprocessable_entity)
- expect(json_response['error']['code']).to eq('invalid_price')
- expect(response.body).to include('non-negative number')
+ expect(json_response['error']['code']).to eq('invalid_money_format')
+ expect(json_response['error']['details']).to eq('price' => ['must be a decimal string like "19.99"'])
expect(line_item.reload.price_source).to be_nil
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
index 1a15a6839e..79370184f2 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
@@ -176,12 +176,6 @@ RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :control
end
context 'with a partial amount' do
- it 'still accepts a JSON number' do
- expect(Spree.payment_capture_workflow).to receive(:call).with(payment: payment, amount: BigDecimal('1.15')).and_call_original
-
- patch :capture, params: { order_id: order_with_payment.prefixed_id, id: payment.prefixed_id, amount: 1.15 }, as: :json
- end
-
it 'hands the workflow the exact amount' do
expect(Spree.payment_capture_workflow).to receive(:call).with(payment: payment, amount: BigDecimal('1.15')).and_call_original
@@ -192,7 +186,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :control
}, as: :json
end
- ['1,15', '1.155', '-5.00', '0', 'abc'].each do |amount|
+ [1.15, '1,15', '1.155', '-5.00', '0', 'abc'].each do |amount|
it "refuses #{amount.inspect} with invalid_money_format" do
expect(Spree.payment_capture_workflow).not_to receive(:call)
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb
index 6df8e36847..52ce5ea3c8 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb
@@ -32,12 +32,12 @@ RSpec.describe Spree::Api::V3::Admin::Orders::RefundsController, type: :controll
order_id: order.prefixed_id,
payment_id: payment.prefixed_id,
refund_reason_id: refund_reason.prefixed_id,
- amount: 5.00
+ amount: '5.00'
}, as: :json
}.to change(Spree::Refund, :count).by(1)
expect(response).to have_http_status(:created)
- expect(json_response['amount']).to eq('5.0')
+ expect(json_response['amount']).to eq('5.00')
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb
index 4cdad48ac5..8f9804d4d6 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb
@@ -39,11 +39,12 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ReturnsController, type: :controll
}, as: :json
line = json_response['return_line_items'].sole
- expect(json_response['refund_total']).to eq((line_item.price + 1).to_s)
- expect(json_response['refund_tax_total']).to eq('1.0')
- expect(line).to include('pre_tax_amount' => line_item.price.to_s, 'additional_tax_total' => '1.0',
- 'refund_amount' => (line_item.price + 1).to_s)
- expect(line['tax_lines'].sole).to include('credit' => true, 'amount' => '1.0', 'return_line_item_id' => line['id'])
+ expect(json_response['refund_total']).to eq(Spree::Money::Rounding.format(line_item.price + 1, 'USD'))
+ expect(json_response['refund_tax_total']).to eq('1.00')
+ expect(line).to include('pre_tax_amount' => Spree::Money::Rounding.format(line_item.price, 'USD'),
+ 'additional_tax_total' => '1.00',
+ 'refund_amount' => Spree::Money::Rounding.format(line_item.price + 1, 'USD'))
+ expect(line['tax_lines'].sole).to include('credit' => true, 'amount' => '1.00', 'return_line_item_id' => line['id'])
end
it 'rejects returning more than was fulfilled' do
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb
index 00d1f9466e..bb3e9a8a09 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/store_credits_controller_spec.rb
@@ -22,7 +22,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::StoreCreditsController, type: :con
context 'with explicit amount' do
it 'applies up to the requested amount' do
- post :create, params: { order_id: order.prefixed_id, amount: 5.00 }, as: :json
+ post :create, params: { order_id: order.prefixed_id, amount: '5.00' }, as: :json
expect(response).to have_http_status(:created)
applied = order.reload.payments.store_credits.sum(:amount)
@@ -32,7 +32,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::StoreCreditsController, type: :con
context 'when explicit amount exceeds available balance' do
it 'caps at the available store credit balance' do
- post :create, params: { order_id: order.prefixed_id, amount: 9999.99 }, as: :json
+ post :create, params: { order_id: order.prefixed_id, amount: '9999.99' }, as: :json
expect(response).to have_http_status(:created)
applied = order.reload.payments.store_credits.sum(:amount)
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb
index 8e883af5a5..3efc8f8c29 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb
@@ -64,7 +64,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::TaxLinesController, type: :control
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(tax_line.prefixed_id)
- expect(json_response['amount']).to eq('1.5')
+ expect(json_response['amount']).to eq('1.50')
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb
index d1a516d8aa..eb0f042469 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders_controller_spec.rb
@@ -218,7 +218,7 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
row = json_response['payment_splits'].first
expect(row['id']).to eq(split.prefixed_id)
expect(row).to include('payment_id' => payment.prefixed_id, 'payment_number' => payment.number,
- 'order_id' => child.prefixed_id, 'captured_amount' => '100.0')
+ 'order_id' => child.prefixed_id, 'captured_amount' => '100.00')
end
subject { get :show, params: { id: order.prefixed_id }, as: :json }
@@ -400,7 +400,7 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
let(:create_params) do
{
- items: [{ variant_id: variant.prefixed_id, quantity: 1, price: '12,50' }]
+ items: [{ variant_id: variant.prefixed_id, quantity: 1, price: '-1' }]
}
end
@@ -453,8 +453,8 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
expect(created.delivery_total).to eq(5)
expect(created.total).to eq(created.item_total + created.delivery_total + created.adjustment_total)
- expect(json_response['delivery_total']).to eq('5.0')
- expect(json_response['total']).to eq(created.total.to_s)
+ expect(json_response['delivery_total']).to eq('5.00')
+ expect(json_response['total']).to eq(Spree::Money::Rounding.format(created.total, created.currency))
end
end
@@ -811,7 +811,7 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
it 'refuses with an actionable message' do
patch :update, params: {
id: order.prefixed_id,
- items: [{ variant_id: variant.prefixed_id, quantity: 1, price: '12,50' }]
+ items: [{ variant_id: variant.prefixed_id, quantity: 1, price: '-1' }]
}, as: :json
expect(response).to have_http_status(:unprocessable_entity)
@@ -852,8 +852,8 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
expect(order.fulfillments.first.selected_shipping_rate).to be_present
expect(order.delivery_total).to eq(5)
- expect(json_response['delivery_total']).to eq('5.0')
- expect(json_response['total']).to eq(order.total.to_s)
+ expect(json_response['delivery_total']).to eq('5.00')
+ expect(json_response['total']).to eq(Spree::Money::Rounding.format(order.total, order.currency))
end
context 'when the order already has shipments' do
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb
index 86eaa2443c..2d09cd5c3b 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb
@@ -31,7 +31,7 @@ RSpec.describe Spree::Api::V3::Admin::PriceListsController, type: :controller do
get :show, params: { id: owned.prefixed_id }, as: :json
- expect(json_response['price_adjustment_percentage']).to eq('-15.0')
+ expect(json_response['price_adjustment_percentage']).to eq('-15')
expect(json_response['automatic_pricing']).to be true
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb
index eecb727151..6099766ec7 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/products/variants_controller_spec.rb
@@ -74,7 +74,7 @@ RSpec.describe Spree::Api::V3::Admin::Products::VariantsController, type: :contr
post :create, params: {
product_id: product.prefixed_id,
sku: 'NEW-SKU-001',
- prices: [{ currency: 'USD', amount: 29.99 }],
+ prices: [{ currency: 'USD', amount: '29.99' }],
options: [{ name: option_type.name, value: option_value.name }]
}, as: :json
}.to change(product.variants, :count).by(1)
@@ -94,8 +94,8 @@ RSpec.describe Spree::Api::V3::Admin::Products::VariantsController, type: :contr
sku: 'MULTI-001',
options: [{ name: option_type.name, value: 'New Value' }],
prices: [
- { currency: 'USD', amount: 19.99, compare_at_amount: 24.99 },
- { currency: 'EUR', amount: 17.99 }
+ { currency: 'USD', amount: '19.99', compare_at_amount: '24.99' },
+ { currency: 'EUR', amount: '17.99' }
],
stock_levels: [
{ stock_location_id: stock_location_1.prefixed_id, count_on_hand: 50, backorderable: false },
@@ -154,7 +154,7 @@ RSpec.describe Spree::Api::V3::Admin::Products::VariantsController, type: :contr
product_id: product.prefixed_id,
id: variant.prefixed_id,
prices: [
- { currency: 'GBP', amount: 15.99 }
+ { currency: 'GBP', amount: '15.99' }
]
}, as: :json
@@ -173,7 +173,7 @@ RSpec.describe Spree::Api::V3::Admin::Products::VariantsController, type: :contr
product_id: product.prefixed_id,
id: variant.prefixed_id,
prices: [
- { currency: existing_currency, amount: 42.50 }
+ { currency: existing_currency, amount: '42.50' }
]
}, as: :json
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
index f80f8a3a4b..b428f9e470 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
@@ -366,7 +366,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
it 'creates a minimal product' do
expect {
- post :create, params: { name: 'Simple Product', price: 19.99 }, as: :json
+ post :create, params: { name: 'Simple Product', price: '19.99' }, as: :json
}.to change(Spree::Product, :count).by(1)
expect(response).to have_http_status(:created)
@@ -389,7 +389,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
{
sku: 'PREM-TEE-S',
options: [{ name: 'size', value: 'Small' }],
- cost_price: 8.50,
+ cost_price: '8.50',
weight: 0.2,
width: 30,
height: 40,
@@ -398,9 +398,9 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
dimensions_unit: 'cm',
track_inventory: true,
prices: [
- { currency: 'USD', amount: 29.99, compare_at_amount: 39.99 },
- { currency: 'EUR', amount: 27.99 },
- { currency: 'GBP', amount: 24.99 }
+ { currency: 'USD', amount: '29.99', compare_at_amount: '39.99' },
+ { currency: 'EUR', amount: '27.99' },
+ { currency: 'GBP', amount: '24.99' }
]
},
{
@@ -409,9 +409,9 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
weight: 0.22,
track_inventory: true,
prices: [
- { currency: 'USD', amount: 29.99 },
- { currency: 'EUR', amount: 27.99 },
- { currency: 'GBP', amount: 24.99 }
+ { currency: 'USD', amount: '29.99' },
+ { currency: 'EUR', amount: '27.99' },
+ { currency: 'GBP', amount: '24.99' }
]
},
{
@@ -420,9 +420,9 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
weight: 0.25,
track_inventory: true,
prices: [
- { currency: 'USD', amount: 31.99 },
- { currency: 'EUR', amount: 29.99 },
- { currency: 'GBP', amount: 26.99 }
+ { currency: 'USD', amount: '31.99' },
+ { currency: 'EUR', amount: '29.99' },
+ { currency: 'GBP', amount: '26.99' }
]
}
]
@@ -713,8 +713,8 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
post :create, params: {
name: 'Simple Product',
prices: [
- { currency: 'USD', amount: 12.50 },
- { currency: 'EUR', amount: 11.00, compare_at_amount: 13.99 }
+ { currency: 'USD', amount: '12.50' },
+ { currency: 'EUR', amount: '11.00', compare_at_amount: '13.99' }
]
}, as: :json
@@ -917,9 +917,9 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
country_of_origin: 'bd',
customs_description: 'Cotton t-shirt',
prices: [
- { currency: 'USD', amount: 34.99, compare_at_amount: 49.99 },
- { currency: 'EUR', amount: 31.99 },
- { currency: 'GBP', amount: 28.99 }
+ { currency: 'USD', amount: '34.99', compare_at_amount: '49.99' },
+ { currency: 'EUR', amount: '31.99' },
+ { currency: 'GBP', amount: '28.99' }
]
},
{
@@ -928,9 +928,9 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
weight: 0.4,
track_inventory: true,
prices: [
- { currency: 'USD', amount: 36.99 },
- { currency: 'EUR', amount: 33.99 },
- { currency: 'GBP', amount: 30.99 }
+ { currency: 'USD', amount: '36.99' },
+ { currency: 'EUR', amount: '33.99' },
+ { currency: 'GBP', amount: '30.99' }
]
}
]
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/purchase_orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/purchase_orders_controller_spec.rb
index 81beb396a0..404b95c26d 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/purchase_orders_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/purchase_orders_controller_spec.rb
@@ -33,7 +33,7 @@ RSpec.describe Spree::Api::V3::Admin::PurchaseOrdersController, type: :controlle
row = json_response['data'].find { |po| po['id'] == purchase_order.prefixed_id }
expect(row).to include(
'status' => 'draft', 'items_count' => 1, 'quantity_ordered_total' => 100,
- 'quantity_received_total' => 0, 'subtotal' => '1250.0', 'editable' => true
+ 'quantity_received_total' => 0, 'subtotal' => '1250.00', 'editable' => true
)
expect(row['supplier_id']).to eq(supplier.prefixed_id)
end
@@ -237,7 +237,7 @@ RSpec.describe Spree::Api::V3::Admin::PurchaseOrdersController, type: :controlle
expect(response).to have_http_status(:ok)
line = json_response['items'].sole
- expect(line).to include('quantity_ordered' => 100, 'unit_cost' => '12.5',
+ expect(line).to include('quantity_ordered' => 100, 'unit_cost' => '12.50',
'display_unit_cost' => '$12.50', 'outstanding' => 100)
expect(json_response['supplier']['name']).to eq('Acme Wholesale')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb
index 5e63ed2129..1442a0cd6f 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb
@@ -42,13 +42,13 @@ RSpec.describe Spree::Api::V3::Admin::ReportingController, type: :controller do
it 'computes totals with money display strings and nil growth without baseline' do
subject
totals = json_response['totals']
- expected_gross = (order1.total + order2.total).to_f.round(2)
+ expected_gross = order1.total + order2.total
- expect(totals['total_sales']['value']).to eq(expected_gross)
+ expect(totals['total_sales']['value']).to eq(Spree::Money::Rounding.format(expected_gross, 'USD'))
expect(totals['total_sales']['display']).to include('$')
expect(totals['total_sales']['growth']).to be_nil
expect(totals['orders']['value']).to eq(2)
- expect(totals['average_order_value']['value']).to eq((expected_gross / 2).round(2))
+ expect(totals['average_order_value']['value']).to eq(Spree::Money::Rounding.format(expected_gross / 2, 'USD'))
end
it 'hydrates product rows with prefixed ids, labels and meta' do
@@ -63,7 +63,7 @@ RSpec.describe Spree::Api::V3::Admin::ReportingController, type: :controller do
expect(row['dimensions']['product']['id']).to start_with('prod_')
expect(row['dimensions']['product']['label']).to be_present
expect(row['dimensions']['product']['meta']).to include('slug', 'thumbnail_url')
- expect(row['metrics']['net_sales']['value']).to be > 0
+ expect(row['metrics']['net_sales']['value'].to_d).to be > 0
end
it 'hydrates customer rows and ranks by revenue' do
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/seller_payouts_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/seller_payouts_controller_spec.rb
index c2fad69cc4..d1fd87fc5e 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/seller_payouts_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/seller_payouts_controller_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe Spree::Api::V3::Admin::SellerPayoutsController, type: :controller
row = json_response['data'].first
expect(row['id']).to start_with('vpo_')
expect(row['seller_name']).to eq('Sparks Audio')
- expect(row['amount']).to eq('120.0')
+ expect(row['amount']).to eq('120.00')
expect(row['display_amount']).to eq('$120.00')
expect(row['status']).to eq('pending')
expect(row['provider']).to eq('system')
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/seller_transfers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/seller_transfers_controller_spec.rb
index a7f9f18ea7..dda7305df7 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/seller_transfers_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/seller_transfers_controller_spec.rb
@@ -22,7 +22,7 @@ RSpec.describe Spree::Api::V3::Admin::SellerTransfersController, type: :controll
expect(row['id']).to start_with('vtr_')
expect(row['seller_name']).to eq('Sparks Audio')
expect(row['order_number']).to eq(order.number)
- expect(row['amount']).to eq('42.5')
+ expect(row['amount']).to eq('42.50')
expect(row['display_amount']).to eq('$42.50')
expect(row['kind']).to eq('earning')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/sellers/balances_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/sellers/balances_controller_spec.rb
index ea346dd9c5..445d0c5778 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/sellers/balances_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/sellers/balances_controller_spec.rb
@@ -24,7 +24,7 @@ RSpec.describe Spree::Api::V3::Admin::Sellers::BalancesController, type: :contro
expect(response).to have_http_status(:ok)
row = json_response['data'].first
expect(row).to include('seller_id' => seller.prefixed_id, 'currency' => 'USD',
- 'balance' => '25.0', 'display_balance' => '$25.00')
+ 'balance' => '25.00', 'display_balance' => '$25.00')
end
it "404s on another marketplace's seller" do
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb
index f5b2d3c091..0e36df34bd 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb
@@ -84,7 +84,7 @@ RSpec.describe Spree::Api::V3::Admin::StockMovementsController, type: :controlle
row = json_response['data'].find { |m| m['purchase_order_id'] == purchase_order.prefixed_id }
expect(row['purchase_order_number']).to eq(purchase_order.number)
- expect(row['unit_cost']).to eq('9.5')
+ expect(row['unit_cost']).to eq('9.50')
expect(row['display_unit_cost']).to eq('$9.50')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
index 7a37a291dc..0fa969fa74 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
@@ -379,7 +379,7 @@ RSpec.describe Spree::Api::V3::Admin::StoreController, type: :controller do
preferred_auto_approve_sellers: true,
preferred_auto_approve_seller_products: true,
preferred_send_seller_transactional_emails: false,
- preferred_default_commission_tax_rate: 0.23
+ preferred_default_commission_tax_rate: '0.23'
}
end
@@ -397,7 +397,7 @@ RSpec.describe Spree::Api::V3::Admin::StoreController, type: :controller do
# The rate is a fraction, so a percentage typed straight in would bill
# more tax than fee.
context 'with a commission tax rate above 1' do
- let(:params) { { preferred_default_commission_tax_rate: 23 } }
+ let(:params) { { preferred_default_commission_tax_rate: '23' } }
it 'returns a validation error' do
subject
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/store_credits/events_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/store_credits/events_controller_spec.rb
index 40440e7b56..1173ea2e62 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/store_credits/events_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/store_credits/events_controller_spec.rb
@@ -25,7 +25,7 @@ RSpec.describe Spree::Api::V3::Admin::StoreCredits::EventsController, type: :con
subject
entry = json_response['data'].first
- expect(entry['amount']).to eq('50.0')
+ expect(entry['amount']).to eq('50.00')
expect(entry['display_amount']).to match(/\$50\.00/)
expect(entry['store_credit_id']).to eq(store_credit.prefixed_id)
expect(entry['created_at']).to match(/\A\d{4}-\d{2}-\d{2}T/)
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/store_credits_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/store_credits_controller_spec.rb
index 3f746c6418..906f7f0410 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/store_credits_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/store_credits_controller_spec.rb
@@ -31,7 +31,7 @@ RSpec.describe Spree::Api::V3::Admin::StoreCreditsController, type: :controller
subject
entry = json_response['data'].find { |c| c['id'] == store_credit.prefixed_id }
- expect(entry['amount_authorized']).to eq('10.0')
+ expect(entry['amount_authorized']).to eq('10.00')
expect(entry['display_amount_authorized']).to match(/\$10\.00/)
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/tax_rates_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/tax_rates_controller_spec.rb
index 865ddf58b4..b9a8e62204 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/tax_rates_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/tax_rates_controller_spec.rb
@@ -30,8 +30,9 @@ RSpec.describe Spree::Api::V3::Admin::TaxRatesController, type: :controller do
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(tax_rate.prefixed_id)
- expect(json_response['amount']).to eq('0.19')
- expect(json_response['amount_percentage']).to eq(19.0)
+ expect(json_response['rate']).to eq('0.19')
+ expect(json_response['rate_percent']).to eq('19')
+ expect(json_response).not_to have_key('amount')
expect(json_response['included_in_price']).to be(true)
expect(json_response['tax_category_id']).to eq(tax_category.prefixed_id)
expect(json_response['country_code']).to eq('DE')
@@ -43,7 +44,7 @@ RSpec.describe Spree::Api::V3::Admin::TaxRatesController, type: :controller do
describe 'POST #create' do
let(:create_params) do
- { name: 'German VAT', amount: 0.19, included_in_price: true,
+ { name: 'German VAT', rate: '0.19', included_in_price: true,
tax_category_id: tax_category.prefixed_id, country_code: 'DE' }
end
@@ -56,7 +57,7 @@ RSpec.describe Spree::Api::V3::Admin::TaxRatesController, type: :controller do
end
it 'accepts a percentage instead of a decimal' do
- post :create, params: create_params.merge(amount: nil, amount_percentage: 7), as: :json
+ post :create, params: create_params.except(:rate).merge(rate_percent: '7'), as: :json
expect(response).to have_http_status(:created)
expect(Spree::TaxRate.last.amount).to eq(0.07)
@@ -87,7 +88,7 @@ RSpec.describe Spree::Api::V3::Admin::TaxRatesController, type: :controller do
describe 'PATCH #update' do
it 'updates the rate' do
- patch :update, params: { id: tax_rate.prefixed_id, amount: 0 }, as: :json
+ patch :update, params: { id: tax_rate.prefixed_id, rate: '0' }, as: :json
expect(response).to have_http_status(:ok)
expect(tax_rate.reload.amount).to eq(0)
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/balances_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/balances_controller_spec.rb
index 2808687c79..b0f5f648f1 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/balances_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/balances_controller_spec.rb
@@ -41,7 +41,7 @@ RSpec.describe Spree::Api::V3::Seller::BalancesController, type: :controller do
expect(response).to have_http_status(:ok)
usd = json_response['data'].find { |row| row['currency'] == 'USD' }
expect(json_response['data'].map { |row| row['currency'] }).to eq(%w[EUR USD])
- expect(usd).to include('earned' => '40.0', 'paid' => '15.0', 'balance' => '25.0', 'pending' => '10.0',
+ expect(usd).to include('earned' => '40.00', 'paid' => '15.00', 'balance' => '25.00', 'pending' => '10.00',
'display_balance' => '$25.00')
expect(usd).not_to have_key('id')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb
index c6035ea1ca..fabc339344 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb
@@ -97,7 +97,7 @@ RSpec.describe Spree::Api::V3::Seller::Orders::ClaimsController, type: :controll
patch :resolve, params: {
order_id: order.prefixed_id, id: claim.prefixed_id,
- resolution: 'refund', refund_method: 'store_credit', amount: 5
+ resolution: 'refund', refund_method: 'store_credit', amount: '5.00'
}, as: :json
expect(response).to have_http_status(:ok)
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb
index 629054225f..7f8a209028 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb
@@ -237,8 +237,8 @@ RSpec.describe Spree::Api::V3::Seller::OrdersController, type: :controller do
row = json_response['payment_splits'].first
expect(row['id']).to eq(split.prefixed_id)
- expect(row).to include('captured_amount' => '100.0', 'refunded_amount' => '20.0',
- 'net_captured_amount' => '80.0', 'display_captured_amount' => '$100.00')
+ expect(row).to include('captured_amount' => '100.00', 'refunded_amount' => '20.00',
+ 'net_captured_amount' => '80.00', 'display_captured_amount' => '$100.00')
expect(row.keys).not_to include('payment_id', 'payment_number', 'payment_method')
end
@@ -251,7 +251,7 @@ RSpec.describe Spree::Api::V3::Seller::OrdersController, type: :controller do
get :show, params: { id: mine.prefixed_id }, as: :json
item = json_response['items'].find { |row| row['id'] == line_item.prefixed_id }
- expect(item).to include('discounted_amount' => '8.0', 'display_discounted_amount' => '$8.00')
+ expect(item).to include('discounted_amount' => '8.00', 'display_discounted_amount' => '$8.00')
end
it 'leaves the shares out unless asked' do
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/transfers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/transfers_controller_spec.rb
index 16889fa04d..86ed7542be 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/transfers_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/transfers_controller_spec.rb
@@ -37,7 +37,7 @@ RSpec.describe Spree::Api::V3::Seller::TransfersController, type: :controller do
expect(response).to have_http_status(:ok)
row = json_response['data'].first
expect(json_response['data'].map { |transfer| transfer['id'] }).to contain_exactly(mine.prefixed_id)
- expect(row['amount']).to eq('42.0')
+ expect(row['amount']).to eq('42.00')
expect(row['display_amount']).to eq('$42.00')
expect(row['order_number']).to eq(order.number)
expect(row['order_id']).to eq(order.prefixed_id)
diff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
index 83cc92fbb2..80a5439d9d 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
@@ -100,7 +100,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::GiftCardsController, type: :control
post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
expect(response).to have_http_status(:created)
- expect(json_response['amount_due']).to eq('0.0')
+ expect(json_response['amount_due']).to eq('0.00')
expect(json_response['current_step']).to eq('payment')
expect(json_response['requirements']).to be_empty
end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/payment_sessions_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/payment_sessions_controller_spec.rb
index 872dae47c7..348655b9eb 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/carts/payment_sessions_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/payment_sessions_controller_spec.rb
@@ -104,7 +104,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PaymentSessionsController, type: :c
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(payment_session.prefixed_id)
expect(json_response['status']).to eq('pending')
- expect(json_response['amount']).to eq(payment_session.amount.to_s)
+ expect(json_response['amount']).to eq(Spree::Money::Rounding.format(payment_session.amount, payment_session.currency))
expect(json_response['external_data']).to eq({ 'client_secret' => 'secret_123' })
end
@@ -154,7 +154,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PaymentSessionsController, type: :c
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(payment_session.prefixed_id)
- expect(json_response['amount']).to eq('50.0')
+ expect(json_response['amount']).to eq('50.00')
end
context 'when the cart is already completed' do
diff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb
index df8193d3f9..c0fbe92ee2 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb
@@ -28,7 +28,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PaymentsController, type: :controll
post :create, params: { cart_id: order.prefixed_id, payment_method_id: check_payment_method.prefixed_id, amount: '5.00' }
expect(response).to have_http_status(:created)
- expect(json_response['amount']).to eq('5.0')
+ expect(json_response['amount']).to eq('5.00')
end
it 'creates a payment with metadata' do
diff --git a/spree/api/spec/controllers/spree/api/v3/store/customer/gift_cards_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/customer/gift_cards_controller_spec.rb
index 673e9530c5..75151ae7cf 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/customer/gift_cards_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/customer/gift_cards_controller_spec.rb
@@ -45,9 +45,9 @@ RSpec.describe Spree::Api::V3::Store::Customer::GiftCardsController, type: :cont
get :index
card_data = json_response['data'].first
- expect(card_data['amount']).to eq('100.0')
- expect(card_data['amount_used']).to eq('25.0')
- expect(card_data['amount_remaining']).to eq('75.0')
+ expect(card_data['amount']).to eq('100.00')
+ expect(card_data['amount_used']).to eq('25.00')
+ expect(card_data['amount_remaining']).to eq('75.00')
end
it 'only returns gift cards belonging to the current user' do
@@ -111,7 +111,7 @@ RSpec.describe Spree::Api::V3::Store::Customer::GiftCardsController, type: :cont
partial_data = json_response['data'].find { |c| c['id'] == partial_card.prefixed_id }
expect(partial_data['status']).to eq('partially_redeemed')
- expect(partial_data['amount_remaining']).to eq('30.0')
+ expect(partial_data['amount_remaining']).to eq('30.00')
end
end
@@ -138,9 +138,9 @@ RSpec.describe Spree::Api::V3::Store::Customer::GiftCardsController, type: :cont
get :show, params: { id: gift_card.prefixed_id }
expect(json_response['code']).to eq(gift_card.display_code)
- expect(json_response['amount']).to eq('100.0')
- expect(json_response['amount_used']).to eq('25.0')
- expect(json_response['amount_remaining']).to eq('75.0')
+ expect(json_response['amount']).to eq('100.00')
+ expect(json_response['amount_used']).to eq('25.00')
+ expect(json_response['amount_remaining']).to eq('75.00')
expect(json_response['currency']).to eq(gift_card.currency)
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/catalogs_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/catalogs_spec.rb
index c3be9743ea..2dd50c15de 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/catalogs_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/catalogs_spec.rb
@@ -165,7 +165,7 @@ RSpec.describe 'Admin Catalogs API', type: :request, swagger_doc: 'api-reference
run_test! do |response|
price = JSON.parse(response.body)['data'].first['catalog_variants'].first
expect(price['source']).to eq('automatic')
- expect(price['amount']).to eq('80.0')
+ expect(price['amount']).to eq('80.00')
end
end
end
@@ -320,7 +320,7 @@ RSpec.describe 'Admin Catalogs API', type: :request, swagger_doc: 'api-reference
let(:body) { { amount: '750.00' } }
run_test! do |response|
- expect(JSON.parse(response.body)['amount']).to eq('750.0')
+ expect(JSON.parse(response.body)['amount']).to eq('750.00')
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb
index b32fcd7f81..7a34b83bc6 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb
@@ -93,7 +93,7 @@ RSpec.describe 'Admin Commission Lines API', type: :request, swagger_doc: 'api-r
schema '$ref' => '#/components/schemas/CommissionLine'
run_test! do |response|
- expect(JSON.parse(response.body)['total']).to eq('12.1')
+ expect(JSON.parse(response.body)['total']).to eq('12.10')
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb
index e1398b3a12..8bbcd8ab29 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb
@@ -303,7 +303,7 @@ RSpec.describe 'Admin Commission Rates API', type: :request, swagger_doc: 'api-r
schema '$ref' => '#/components/schemas/CommissionRate'
run_test! do |response|
- expect(JSON.parse(response.body)['value']).to eq('15.0')
+ expect(JSON.parse(response.body)['value']).to eq('15')
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
index f02c796701..f69a1d4d87 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
@@ -57,7 +57,7 @@ RSpec.describe 'Admin Delivery Settings API', type: :request, swagger_doc: 'api-
estimated_transit_business_days_max: { type: :integer, nullable: true },
tax_category_id: { type: :string, nullable: true },
calculator_type: { type: :string, example: 'flat_rate' },
- calculator_preferences: { type: :object, example: { amount: 12.5 } },
+ calculator_preferences: { type: :object, example: { amount: '12.50' } },
delivery_zone_id: { type: :string, nullable: true }
},
required: %w[name]
@@ -69,7 +69,7 @@ RSpec.describe 'Admin Delivery Settings API', type: :request, swagger_doc: 'api-
name: 'Express',
storefront_visible: true,
calculator_type: 'flat_rate',
- calculator_preferences: { amount: 12.5 }
+ calculator_preferences: { amount: '12.50' }
}
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb
index d6fb1da8d1..c79b1eb0c2 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb
@@ -89,7 +89,7 @@ RSpec.describe 'Admin Order Adjustment Lines API', type: :request, swagger_doc:
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['data'].first['amount']).to eq('-3.0')
+ expect(data['data'].first['amount']).to eq('-3.00')
end
end
@@ -119,7 +119,7 @@ RSpec.describe 'Admin Order Adjustment Lines API', type: :request, swagger_doc:
type: :object,
properties: {
label: { type: :string, example: 'Gift wrap' },
- amount: { type: :number, example: 4 },
+ amount: { type: :string, example: '4.00' },
kind: { type: :string, enum: Spree::Fee::KINDS, example: 'gift_wrap', description: "Defaults to 'surcharge'" },
line_item_id: { type: :string, nullable: true },
fulfillment_id: { type: :string, nullable: true }
@@ -128,17 +128,17 @@ RSpec.describe 'Admin Order Adjustment Lines API', type: :request, swagger_doc:
}
response '201', 'fee created' do
- let(:body) { { label: 'Gift wrap', amount: 4, kind: 'gift_wrap' } }
+ let(:body) { { label: 'Gift wrap', amount: '4.00', kind: 'gift_wrap' } }
run_test! do |response|
data = JSON.parse(response.body)
expect(data['label']).to eq('Gift wrap')
- expect(data['amount']).to eq('4.0')
+ expect(data['amount']).to eq('4.00')
end
end
response '422', 'invalid fee' do
- let(:body) { { label: 'Mystery', amount: 4, kind: 'nonsense' } }
+ let(:body) { { label: 'Mystery', amount: '4.00', kind: 'nonsense' } }
run_test!
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb
index bb5b50799c..5a25083ccf 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb
@@ -73,7 +73,7 @@ RSpec.describe 'Admin Order Refunds API', type: :request, swagger_doc: 'api-refe
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['amount']).to eq('5.0')
+ expect(data['amount']).to eq('5.00')
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/promotions_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/promotions_spec.rb
index 14c21f5244..7750f2adb7 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/promotions_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/promotions_spec.rb
@@ -127,7 +127,7 @@ RSpec.describe 'Admin Promotions API', type: :request, swagger_doc: 'api-referen
{ type: 'currency', preferences: { currency: 'USD' } },
{
type: 'item_total',
- preferences: { amount_min: 100, operator_min: 'gte' }
+ preferences: { amount_min: '100', operator_min: 'gte' }
},
{
type: 'product',
@@ -140,7 +140,7 @@ RSpec.describe 'Admin Promotions API', type: :request, swagger_doc: 'api-referen
type: 'create_item_adjustments',
calculator: {
type: 'percent_on_line_item',
- preferences: { percent: 25 }
+ preferences: { percent: '25' }
}
},
{ type: 'free_shipping' }
@@ -305,7 +305,7 @@ RSpec.describe 'Admin Promotions API', type: :request, swagger_doc: 'api-referen
# Add a new rule
{
type: 'item_total',
- preferences: { amount_min: 50, operator_min: 'gte' }
+ preferences: { amount_min: '50', operator_min: 'gte' }
}
# `dropped_rule` (FirstOrder) omitted — should be destroyed
],
@@ -316,7 +316,7 @@ RSpec.describe 'Admin Promotions API', type: :request, swagger_doc: 'api-referen
type: 'create_item_adjustments',
calculator: {
type: 'percent_on_line_item',
- preferences: { percent: 15 }
+ preferences: { percent: '15' }
}
}
]
diff --git a/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb
index a6994d3167..bd8b084000 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb
@@ -63,7 +63,7 @@ RSpec.describe 'Admin Purchase Orders API', type: :request, swagger_doc: 'api-re
row = data['data'].find { |po| po['id'] == order_record.prefixed_id }
expect(row['status']).to eq('draft')
expect(row['quantity_ordered_total']).to eq(100)
- expect(row['subtotal']).to eq('1250.0')
+ expect(row['subtotal']).to eq('1250.00')
end
end
@@ -186,7 +186,7 @@ RSpec.describe 'Admin Purchase Orders API', type: :request, swagger_doc: 'api-re
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['items'].first['unit_cost']).to eq('12.5')
+ expect(data['items'].first['unit_cost']).to eq('12.50')
expect(data['supplier']['name']).to eq('Acme Wholesale')
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb
index aa71862ae4..891dfb6e59 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb
@@ -506,7 +506,7 @@ RSpec.describe 'Admin Sellers API', type: :request, swagger_doc: 'api-reference/
run_test! do |response|
data = JSON.parse(response.body)['data']
- expect(data.first).to include('seller_id' => seller.prefixed_id, 'currency' => 'USD', 'balance' => '40.0')
+ expect(data.first).to include('seller_id' => seller.prefixed_id, 'currency' => 'USD', 'balance' => '40.00')
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/tax_rates_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/tax_rates_spec.rb
index b71b57576d..01d81de9c0 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/tax_rates_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/tax_rates_spec.rb
@@ -66,8 +66,8 @@ RSpec.describe 'Admin Tax Rates API', type: :request, swagger_doc: 'api-referenc
produces 'application/json'
security [api_key: [], bearer_auth: []]
description <<~DESC
- Creates a tax rate for the current store. Give either `amount` as a
- decimal (`0.19`) or `amount_percentage` as a percentage (`19`).
+ Creates a tax rate for the current store. Give either `rate` as a
+ decimal string (`"0.19"`) or `rate_percent` as a percentage string (`"19"`).
Name the jurisdiction with `country_code` (and `state_code` for a
state-level rate). Omitting the country makes the rate apply everywhere.
@@ -84,8 +84,8 @@ RSpec.describe 'Admin Tax Rates API', type: :request, swagger_doc: 'api-referenc
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' },
+ rate: { type: :string, description: 'Rate as a decimal string, e.g. "0.19"' },
+ rate_percent: { type: :string, description: 'Rate as a percentage string, e.g. "19"' },
included_in_price: { type: :boolean },
show_rate_in_label: { type: :boolean },
tax_category_id: { type: :string },
@@ -98,7 +98,7 @@ RSpec.describe 'Admin Tax Rates API', type: :request, swagger_doc: 'api-referenc
response '201', 'tax rate created' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
let(:body) do
- { name: 'VAT', amount_percentage: 19, included_in_price: true,
+ { name: 'VAT', rate_percent: '19', included_in_price: true,
tax_category_id: tax_category.prefixed_id, country_code: 'DE' }
end
@@ -106,14 +106,14 @@ RSpec.describe 'Admin Tax Rates API', type: :request, swagger_doc: 'api-referenc
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['amount']).to eq('0.19')
- expect(data['amount_percentage']).to eq(19.0)
+ expect(data['rate']).to eq('0.19')
+ expect(data['rate_percent']).to eq('19')
end
end
response '422', 'validation failed' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
- let(:body) { { amount_percentage: 19 } }
+ let(:body) { { rate_percent: '19' } }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -160,8 +160,8 @@ RSpec.describe 'Admin Tax Rates API', type: :request, swagger_doc: 'api-referenc
type: :object,
properties: {
name: { type: :string },
- amount: { type: :string },
- amount_percentage: { type: :number },
+ rate: { type: :string },
+ rate_percent: { type: :string },
included_in_price: { type: :boolean },
show_rate_in_label: { type: :boolean },
tax_category_id: { type: :string },
@@ -172,12 +172,12 @@ RSpec.describe 'Admin Tax Rates API', type: :request, swagger_doc: 'api-referenc
response '200', 'tax rate updated' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
- let(:body) { { amount_percentage: 7 } }
+ let(:body) { { rate_percent: '7' } }
schema '$ref' => '#/components/schemas/TaxRate'
run_test! do |response|
- expect(JSON.parse(response.body)['amount']).to eq('0.07')
+ expect(JSON.parse(response.body)['rate']).to eq('0.07')
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/seller/balances_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/balances_spec.rb
index c4ef056b5b..23590f3ffe 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/balances_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/balances_spec.rb
@@ -49,7 +49,7 @@ RSpec.describe 'Seller Balances API', type: :request, swagger_doc: 'api-referenc
run_test! do |response|
data = JSON.parse(response.body)['data']
- expect(data.first).to include('currency' => 'USD', 'balance' => '25.0')
+ expect(data.first).to include('currency' => 'USD', 'balance' => '25.00')
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb b/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb
index 299b43f46c..2dd58bdb12 100644
--- a/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb
@@ -152,7 +152,7 @@ RSpec.describe 'Carts API', type: :request, swagger_doc: 'api-reference/store.ya
expect(data['number']).to eq(cart.number)
expect(data['warnings']).to eq([])
expect(data['fees'].map { |fee| fee['kind'] }).to contain_exactly('gift_wrap', 'duty')
- expect(data['fee_total']).to eq('17.0')
+ expect(data['fee_total']).to eq('17.00')
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb b/spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb
index 0d84c459f3..fc1bd495b3 100644
--- a/spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb
@@ -81,7 +81,7 @@ RSpec.describe 'Cart Discount Codes API', type: :request, swagger_doc: 'api-refe
run_test! do |response|
data = JSON.parse(response.body)
expect(data['coupon_code']).to eq('big50')
- expect(data['discount_total']).to eq('0.0')
+ expect(data['discount_total']).to eq('0.00')
warning = data['warnings'].sole
expect(warning['code']).to eq('coupon_code_not_eligible')
expect(warning['message']).to be_present
diff --git a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
index 2a8e1d9ffa..1327e71458 100644
--- a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
@@ -46,7 +46,7 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.y
expect(data['id']).to start_with('or_')
expect(data['number']).to eq(completed_order.number)
expect(data['fees'].map { |fee| fee['kind'] }).to eq(['duty'])
- expect(data['fee_total']).to eq('12.0')
+ expect(data['fee_total']).to eq('12.00')
expect(data['completed_at']).to be_present
expect(data).not_to have_key('token')
expect(data).not_to have_key('checkout_steps')
diff --git a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb b/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
index 1394d9385d..7c9b06f8cf 100644
--- a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
@@ -184,7 +184,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
expect(lowest['amount']).to eq('9.99')
expect(lowest['currency']).to eq('USD')
expect(lowest['display_amount']).to be_present
- expect(lowest['amount_in_cents']).to eq(999)
+ expect(lowest).not_to have_key('amount_in_cents')
expect(lowest['recorded_at']).to be_present
end
end
diff --git a/spree/api/spec/requests/spree/api/v3/admin/tax_configuration_spec.rb b/spree/api/spec/requests/spree/api/v3/admin/tax_configuration_spec.rb
index 9515349c3e..9e74fad37f 100644
--- a/spree/api/spec/requests/spree/api/v3/admin/tax_configuration_spec.rb
+++ b/spree/api/spec/requests/spree/api/v3/admin/tax_configuration_spec.rb
@@ -25,7 +25,7 @@ RSpec.describe 'Admin tax configuration', type: :request do
it 'configures a rate and produces the tax it describes' do
post '/api/v3/admin/tax_rates',
- params: { name: 'German VAT', amount_percentage: 19, included_in_price: true,
+ params: { name: 'German VAT', rate_percent: '19', included_in_price: true,
tax_category_id: tax_category.prefixed_id, country_code: 'DE' },
headers: headers, as: :json
@@ -42,14 +42,14 @@ RSpec.describe 'Admin tax configuration', type: :request do
it 'still records a treatment when the rate is zero' do
post '/api/v3/admin/tax_rates',
- params: { name: 'German VAT', amount_percentage: 19, included_in_price: true,
+ params: { name: 'German VAT', rate_percent: '19', included_in_price: true,
tax_category_id: tax_category.prefixed_id, country_code: 'DE' },
headers: headers, as: :json
rate_id = JSON.parse(response.body)['id']
Spree::Carts::RecalculateTotals.call(cart: cart)
- patch "/api/v3/admin/tax_rates/#{rate_id}", params: { amount: 0 }, headers: headers, as: :json
+ patch "/api/v3/admin/tax_rates/#{rate_id}", params: { rate: '0' }, headers: headers, as: :json
expect(response).to have_http_status(:ok)
Spree::Carts::RecalculateTotals.call(cart: cart.reload)
@@ -61,7 +61,7 @@ RSpec.describe 'Admin tax configuration', type: :request do
it 'shows the storefront the tax on a line, without the admin treatment fields' do
post '/api/v3/admin/tax_rates',
- params: { name: 'German VAT', amount_percentage: 19, included_in_price: true,
+ params: { name: 'German VAT', rate_percent: '19', included_in_price: true,
tax_category_id: tax_category.prefixed_id, country_code: 'DE' },
headers: headers, as: :json
diff --git a/spree/api/spec/serializers/spree/api/v3/delivery_rate_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/delivery_rate_serializer_spec.rb
index 9be936ec34..df135e4e02 100644
--- a/spree/api/spec/serializers/spree/api/v3/delivery_rate_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/delivery_rate_serializer_spec.rb
@@ -45,8 +45,8 @@ RSpec.describe Spree::Api::V3::DeliveryRateSerializer do
end
it 'returns cost and total' do
- expect(subject['cost']).to eq(shipping_rate.cost)
- expect(subject['total']).to eq(shipping_rate.total)
+ expect(subject['cost']).to eq(Spree::Money::Rounding.format(shipping_rate.cost, 'USD'))
+ expect(subject['total']).to eq(Spree::Money::Rounding.format(shipping_rate.total, 'USD'))
end
it 'returns display_cost and display_total' do
@@ -55,9 +55,9 @@ RSpec.describe Spree::Api::V3::DeliveryRateSerializer do
end
it 'returns tax totals as zero when no tax rate' do
- expect(subject['tax_total']).to eq(0)
- expect(subject['additional_tax_total']).to eq(0)
- expect(subject['included_tax_total']).to eq(0)
+ expect(subject['tax_total']).to eq('0.00')
+ expect(subject['additional_tax_total']).to eq('0.00')
+ expect(subject['included_tax_total']).to eq('0.00')
end
it 'returns prefixed delivery_method_id' do
@@ -71,9 +71,9 @@ RSpec.describe Spree::Api::V3::DeliveryRateSerializer do
before { shipping_rate.update!(tax_rate: tax_rate) }
it 'returns the tax in additional_tax_total' do
- expect(subject['tax_total']).to be > 0
- expect(subject['additional_tax_total']).to be > 0
- expect(subject['included_tax_total']).to eq(0)
+ expect(subject['tax_total'].to_d).to be > 0
+ expect(subject['additional_tax_total'].to_d).to be > 0
+ expect(subject['included_tax_total']).to eq('0.00')
end
end
@@ -83,9 +83,9 @@ RSpec.describe Spree::Api::V3::DeliveryRateSerializer do
before { shipping_rate.update!(tax_rate: tax_rate) }
it 'returns the tax in included_tax_total' do
- expect(subject['tax_total']).to be > 0
- expect(subject['additional_tax_total']).to eq(0)
- expect(subject['included_tax_total']).to be > 0
+ expect(subject['tax_total'].to_d).to be > 0
+ expect(subject['additional_tax_total']).to eq('0.00')
+ expect(subject['included_tax_total'].to_d).to be > 0
end
end
@@ -100,15 +100,15 @@ RSpec.describe Spree::Api::V3::DeliveryRateSerializer do
end
it 'returns total as 0' do
- expect(subject['total']).to eq(0)
+ expect(subject['total']).to eq('0.00')
end
it 'returns display_total as $0.00' do
- expect(subject['display_total']).to eq('$0.00')
+ expect(subject['display_total'].to_s).to eq('$0.00')
end
it 'preserves original cost' do
- expect(subject['cost']).to be > 0
+ expect(subject['cost'].to_d).to be > 0
end
end
end
diff --git a/spree/api/spec/serializers/spree/api/v3/gift_card_batch_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/gift_card_batch_serializer_spec.rb
index 6023d49157..8fb58c10e7 100644
--- a/spree/api/spec/serializers/spree/api/v3/gift_card_batch_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/gift_card_batch_serializer_spec.rb
@@ -20,6 +20,6 @@ RSpec.describe Spree::Api::V3::GiftCardBatchSerializer do
end
it 'returns amount as string' do
- expect(subject['amount']).to eq('25.0')
+ expect(subject['amount']).to eq('25.00')
end
end
diff --git a/spree/api/spec/serializers/spree/api/v3/money_contract_spec.rb b/spree/api/spec/serializers/spree/api/v3/money_contract_spec.rb
new file mode 100644
index 0000000000..1c042e2f1e
--- /dev/null
+++ b/spree/api/spec/serializers/spree/api/v3/money_contract_spec.rb
@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# The money contract (docs/plans/6.0-money-correctness.md): every money amount
+# is a decimal string with exactly its currency's decimals, unit prices keep up
+# to four, rates are decimal strings, and nothing money-shaped is a JSON number.
+RSpec.describe 'API v3 money contract' do
+ let(:store) { @default_store }
+
+ def money_name = /(\A|_)(amount|price|total|cost|fee|payout|discount|tax|revenue|balance|refund|credit|minimum|earned|payable|paid|pending|subtotal)(\z|_)/
+ def rate_name = /(\A|_)(rate|percent|percentage)\z/
+ def not_money = /(\A|_)(id|ids|count|quantity|status|kind|type|code|label|name|at|unit|method|methods|provider|currency)\z|\Adisplay_|\Atotal_(quantity|units|cartons|on_hand)\z|delivery_count/
+ def unit_price_keys = %w[price compare_at_amount cost_price unit_cost catalog_price original_price new_variant_price]
+
+ # Walks a payload and yields every money- or rate-named scalar with the
+ # currency of the hash it sits in.
+ def each_decimal(node, currency = nil, path = [], &block)
+ case node
+ when Hash
+ currency = node['currency'] if node['currency'].is_a?(String)
+ node.each do |key, value|
+ next if key.match?(not_money)
+
+ if value.is_a?(Hash) || value.is_a?(Array)
+ each_decimal(value, currency, path + [key], &block)
+ elsif value && (key.match?(money_name) || key.match?(rate_name))
+ yield(key, value, currency, path + [key])
+ end
+ end
+ when Array
+ node.each_with_index { |item, index| each_decimal(item, currency, path + [index], &block) }
+ end
+ end
+
+ def expect_contract(payload, prices: false)
+ checked = 0
+ each_decimal(payload) do |key, value, currency, path|
+ checked += 1
+ expect(value).to be_a(String), "#{path.join('.')} is #{value.inspect}, not a decimal string"
+ expect(value).to match(/\A-?\d+(\.\d+)?\z/), "#{path.join('.')} is #{value.inspect}"
+ next if key.match?(rate_name) || currency.nil?
+
+ places = value.include?('.') ? value.split('.').last.length : 0
+ exponent = Spree::Money::Rounding.precision(currency)
+ if unit_price_keys.include?(key) || (key == 'amount' && (prices || path.include?('price')))
+ expect(places).to be_between(exponent, [exponent, 4].max), "#{path.join('.')} #{value} (#{currency})"
+ else
+ expect(places).to eq(exponent), "#{path.join('.')} #{value} has #{places} decimals, #{currency} has #{exponent}"
+ end
+ end
+ expect(checked).to be_positive
+ end
+
+ def serialize(serializer, record, **params)
+ JSON.parse(serializer.new(record, params: { store: store, currency: record.try(:currency) || 'USD', **params }).to_json)
+ end
+
+ %w[USD KWD JPY].each do |currency|
+ context "in #{currency}" do
+ let(:order) do
+ create(:completed_order_with_totals, store: store).tap do |order|
+ order.update_columns(currency: currency)
+ order.line_items.update_all(currency: currency)
+ end.reload
+ end
+
+ it 'writes order totals and line items to the currency' do
+ expect_contract(serialize(Spree::Api::V3::OrderSerializer, order))
+ expect_contract(serialize(Spree::Api::V3::Admin::OrderSerializer, order))
+ end
+
+ it 'writes payments and refunds to the currency' do
+ payment = create(:payment, order: order, amount: order.total, status: 'completed')
+ refund = create(:refund, payment: payment, amount: 1)
+
+ expect_contract(serialize(Spree::Api::V3::Admin::PaymentSerializer, payment))
+ expect_contract(serialize(Spree::Api::V3::Admin::RefundSerializer, refund))
+ end
+
+ it 'writes prices as unit prices in the currency' do
+ variant = create(:variant)
+ variant.set_price(currency, BigDecimal('19.5'), BigDecimal('25'))
+ price = variant.prices.find_by!(currency: currency, price_list_id: nil)
+
+ expect_contract(serialize(Spree::Api::V3::PriceSerializer, price), prices: true)
+ expect_contract(serialize(Spree::Api::V3::Admin::VariantSerializer, variant))
+ end
+
+ it 'writes store credit to the currency' do
+ credit = create(:store_credit, store: store, currency: currency, amount: BigDecimal('15'))
+
+ expect_contract(serialize(Spree::Api::V3::Admin::StoreCreditSerializer, credit))
+ end
+ end
+ end
+
+ it 'writes rates as decimal strings without trailing zeros' do
+ rate = create(:tax_rate, amount: BigDecimal('0.23'))
+ payload = serialize(Spree::Api::V3::Admin::TaxRateSerializer, rate)
+
+ expect(payload['rate']).to eq('0.23')
+ expect(payload['rate_percent']).to eq('23')
+ end
+
+ it 'gives every currency its decimal places' do
+ payload = Spree::Api::V3::CurrencySerializer.new(Money::Currency.find('KWD')).serializable_hash
+
+ expect(payload['decimal_places']).to eq(3)
+ end
+end
diff --git a/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb b/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb
index fce7f5f658..97419b6012 100644
--- a/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/price_gating_spec.rb
@@ -62,9 +62,9 @@ RSpec.describe 'v3 Store serializer price gating' do
it 'states the threshold and shortfall when not gated' do
hash = serialize(described_class, cart.reload, hide: false)
- expect(hash['order_minimum']).to eq(500.0)
+ expect(hash['order_minimum']).to eq('500.00')
# What is left to add, so the cart's own items count against it.
- expect(hash['order_minimum_shortfall']).to eq(500.0 - cart.item_total.to_f)
+ expect(hash['order_minimum_shortfall']).to eq(Spree::Money::Rounding.format(500 - cart.item_total, 'USD'))
expect(hash['below_order_minimum']).to be(true)
expect(hash['requirements'].map { |r| r['code'] }).to include('order_minimum_not_met')
end
@@ -182,8 +182,9 @@ RSpec.describe 'v3 Store serializer price gating' do
# The record is a lightweight applied-promotion presenter responding to
# the money methods; a struct keeps the gating assertion factory-free.
let(:applied_promotion) do
- Struct.new(:name, :description, :code, :amount, :display_amount, :promotion, keyword_init: true).new(
- name: 'Promo', description: nil, code: 'SAVE10', amount: '5.0', display_amount: '$5.00', promotion: nil
+ Struct.new(:name, :description, :code, :amount, :display_amount, :promotion, :currency, keyword_init: true).new(
+ name: 'Promo', description: nil, code: 'SAVE10', amount: '5.0', display_amount: '$5.00', promotion: nil,
+ currency: 'USD'
)
end
@@ -202,9 +203,9 @@ RSpec.describe 'v3 Store serializer price gating' do
describe Spree::Api::V3::DiscountSerializer do
let(:discount) do
Struct.new(:label, :kind, :code, :value, :value_type, :amount, :display_amount,
- :promotion, :line_item, :fulfillment, keyword_init: true).new(
+ :promotion, :line_item, :fulfillment, :currency, keyword_init: true).new(
label: 'Promo', kind: 'promotion', code: 'SAVE10', value: '10.0', value_type: 'flat',
- amount: '-5.0', display_amount: '-$5.00', promotion: nil, line_item: nil, fulfillment: nil
+ amount: '-5.0', display_amount: '-$5.00', promotion: nil, line_item: nil, fulfillment: nil, currency: 'USD'
)
end
diff --git a/spree/api/spec/serializers/spree/api/v3/price_history_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/price_history_serializer_spec.rb
index d34a65ba4e..d95f546539 100644
--- a/spree/api/spec/serializers/spree/api/v3/price_history_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/price_history_serializer_spec.rb
@@ -14,8 +14,7 @@ RSpec.describe Spree::Api::V3::PriceHistorySerializer do
it 'includes amount fields' do
expect(subject).to include(
- 'amount' => '9.99'.to_d,
- 'amount_in_cents' => 999,
+ 'amount' => '9.99',
'currency' => 'USD'
)
end
@@ -35,7 +34,7 @@ RSpec.describe Spree::Api::V3::PriceHistorySerializer do
it 'uses the correct currency for display' do
expect(subject['currency']).to eq('EUR')
- expect(subject['amount']).to eq('19.99'.to_d)
+ expect(subject['amount']).to eq('19.99')
end
end
end
@@ -54,8 +53,7 @@ RSpec.describe Spree::Api::V3::Admin::PriceHistorySerializer do
it 'includes store serializer fields' do
expect(subject).to include(
- 'amount' => '9.99'.to_d,
- 'amount_in_cents' => 999,
+ 'amount' => '9.99',
'currency' => 'USD',
'display_amount' => '$9.99'
)
@@ -64,7 +62,7 @@ RSpec.describe Spree::Api::V3::Admin::PriceHistorySerializer do
it 'includes admin-only fields' do
expect(subject['variant_id']).to eq(variant.prefixed_id)
expect(subject['price_id']).to eq(price.prefixed_id)
- expect(subject['compare_at_amount']).to eq('14.99'.to_d)
+ expect(subject['compare_at_amount']).to eq('14.99')
expect(subject['created_at']).to be_present
end
end
diff --git a/spree/api/spec/serializers/spree/api/v3/price_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/price_serializer_spec.rb
index cf958a14e1..207f1e130b 100644
--- a/spree/api/spec/serializers/spree/api/v3/price_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/price_serializer_spec.rb
@@ -12,22 +12,21 @@ RSpec.describe Spree::Api::V3::PriceSerializer do
it 'includes amount fields' do
expect(subject).to include(
- 'amount' => '19.99'.to_d,
- 'amount_in_cents' => 1999,
+ 'amount' => '19.99',
'display_amount' => '$19.99',
'currency' => 'USD'
)
end
it 'includes nil compare_at fields when not set' do
- expect(subject.values_at('compare_at_amount', 'compare_at_amount_in_cents', 'display_compare_at_amount')).to all(be_nil)
+ expect(subject.values_at('compare_at_amount', 'display_compare_at_amount')).to all(be_nil)
+ expect(subject).not_to include('amount_in_cents', 'compare_at_amount_in_cents')
end
it 'includes compare_at fields when set' do
price.update!(compare_at_amount: 29.99)
expect(subject).to include(
- 'compare_at_amount' => '29.99'.to_d,
- 'compare_at_amount_in_cents' => 2999,
+ 'compare_at_amount' => '29.99',
'display_compare_at_amount' => '$29.99'
)
end
diff --git a/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb
index a8d207e8fb..c3e3aed841 100644
--- a/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb
@@ -58,7 +58,7 @@ RSpec.describe Spree::Api::V3::ProductFiltersSerializer do
it 'serializes filter metadata' do
expect(subject).to eq(
'filters' => [
- { 'id' => 'price', 'type' => 'price_range', 'min' => 10.0, 'max' => 100.0, 'currency' => 'USD' },
+ { 'id' => 'price', 'type' => 'price_range', 'min' => '10.00', 'max' => '100.00', 'currency' => 'USD' },
{
'id' => 'availability',
'type' => 'availability',
diff --git a/spree/api/spec/serializers/spree/api/v3/refund_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/refund_serializer_spec.rb
index 027cad68a5..b52cb535d6 100644
--- a/spree/api/spec/serializers/spree/api/v3/refund_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/refund_serializer_spec.rb
@@ -31,7 +31,7 @@ RSpec.describe Spree::Api::V3::RefundSerializer do
end
it 'returns amount as string' do
- expect(subject['amount']).to eq('10.0')
+ expect(subject['amount']).to eq('10.00')
end
it 'returns prefixed payment_id' do
diff --git a/spree/api/spec/serializers/spree/api/v3/store_credit_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/store_credit_serializer_spec.rb
index 8795e8b439..d0920bdebf 100644
--- a/spree/api/spec/serializers/spree/api/v3/store_credit_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/store_credit_serializer_spec.rb
@@ -20,9 +20,9 @@ RSpec.describe Spree::Api::V3::StoreCreditSerializer do
end
it 'returns correct attribute values' do
- expect(subject['amount']).to eq('100.0')
- expect(subject['amount_used']).to eq('0.0')
- expect(subject['amount_remaining']).to eq('100.0')
+ expect(subject['amount']).to eq('100.00')
+ expect(subject['amount_used']).to eq('0.00')
+ expect(subject['amount_remaining']).to eq('100.00')
expect(subject['display_amount']).to be_present
expect(subject['display_amount_used']).to be_present
expect(subject['display_amount_remaining']).to be_present
@@ -35,9 +35,9 @@ RSpec.describe Spree::Api::V3::StoreCreditSerializer do
end
it 'returns correct amounts' do
- expect(subject['amount']).to eq('100.0')
- expect(subject['amount_used']).to eq('40.0')
- expect(subject['amount_remaining']).to eq('60.0')
+ expect(subject['amount']).to eq('100.00')
+ expect(subject['amount_used']).to eq('40.00')
+ expect(subject['amount_remaining']).to eq('60.00')
end
end
end
diff --git a/spree/core/app/models/spree/catalog_price.rb b/spree/core/app/models/spree/catalog_price.rb
index cb1cccbd81..003a052ef3 100644
--- a/spree/core/app/models/spree/catalog_price.rb
+++ b/spree/core/app/models/spree/catalog_price.rb
@@ -80,13 +80,6 @@ module Spree
break_count.to_i.positive?
end
- # The amount as the wire carries it — see CatalogPriceTier#display_value.
- #
- # @return [String]
- def display_value
- amount.to_s
- end
-
# @return [Spree::Money]
def money
Spree::Money.new(amount, currency: currency)
diff --git a/spree/core/app/models/spree/catalog_price_tier.rb b/spree/core/app/models/spree/catalog_price_tier.rb
index 3b0d1c9ef2..a22eca8c8d 100644
--- a/spree/core/app/models/spree/catalog_price_tier.rb
+++ b/spree/core/app/models/spree/catalog_price_tier.rb
@@ -15,14 +15,6 @@ module Spree
validates :min_quantity, numericality: { greater_than: 1 }
- # The amount as the wire carries it — a string, like every other
- # money-shaped value, since a float would round the merchant's figure.
- #
- # @return [String]
- def display_value
- amount.to_s
- end
-
# @return [Spree::Money]
def money
Spree::Money.new(amount, currency: currency)
diff --git a/spree/core/app/models/spree/exports/report.rb b/spree/core/app/models/spree/exports/report.rb
index ef42419f72..ecc1567125 100644
--- a/spree/core/app/models/spree/exports/report.rb
+++ b/spree/core/app/models/spree/exports/report.rb
@@ -46,10 +46,10 @@ module Spree
result.rows.each do |row|
csv << Spree::CSV::FormulaSanitizer.row(
row[:dimensions].map { |name, raw| hydration.label(name, raw) } +
- query.metrics.map { |m| row[:metrics][m.name][:value] }
+ query.metrics.map { |m| m.format_value(row[:metrics][m.name][:value], result.meta[:currency]) }
)
end
- totals = query.metrics.map { |m| result.totals[m.name][:value] }
+ totals = query.metrics.map { |m| m.format_value(result.totals[m.name][:value], result.meta[:currency]) }
# With a breakdown the totals close the file under a "Total" label in
# the first dimension column; without one the totals are the only row.
label = query.dimensions.empty? ? [] : [I18n.t('spree.reporting.export.total')] + Array.new(query.dimensions.size - 1, '')
diff --git a/spree/core/app/models/spree/tax_rate.rb b/spree/core/app/models/spree/tax_rate.rb
index a8154e50d1..3ee28a8410 100644
--- a/spree/core/app/models/spree/tax_rate.rb
+++ b/spree/core/app/models/spree/tax_rate.rb
@@ -56,17 +56,35 @@ module Spree
->(category) { where(tax_category_id: category.try(:id)) }
scope :included_in_price, -> { where(included_in_price: true) }
- self.whitelisted_ransackable_attributes = %w[amount country_code state_code tax_category_id included_in_price name]
+ self.whitelisted_ransackable_attributes = %w[amount rate country_code state_code tax_category_id included_in_price name]
+ ransack_alias :rate, :amount
- # Virtual attribute for percentage display in admin forms
- def amount_percentage
- return nil if amount.nil?
+ # The rate as a fraction (0.23); the column is +amount+.
+ alias_attribute :rate, :amount
+
+ # The rate as a percentage (23), what a merchant types.
+ #
+ # @return [BigDecimal, nil]
+ def rate_percent
+ amount && amount * 100
+ end
- (amount * 100).round(2)
+ # @param value [String, Numeric, nil]
+ def rate_percent=(value)
+ parsed = Spree::Money::Rounding.parse_decimal(value)
+ self.amount = parsed && parsed / 100
+ end
+
+ # @deprecated Use {#rate_percent}; removed in 6.1.
+ def amount_percentage
+ Spree::Deprecation.warn('Spree::TaxRate#amount_percentage is deprecated and will be removed in Spree 6.1. Use #rate_percent instead.')
+ rate_percent
end
+ # @deprecated Use {#rate_percent=}; removed in 6.1.
def amount_percentage=(value)
- self.amount = value.present? ? BigDecimal(value.to_s) / 100 : nil
+ Spree::Deprecation.warn('Spree::TaxRate#amount_percentage= is deprecated and will be removed in Spree 6.1. Use #rate_percent= instead.')
+ self.rate_percent = value
end
# The included-in-price rate to back out of a gross price.
diff --git a/spree/core/db/migrate/20261009000001_change_money_columns_to_decimal_19_4.rb b/spree/core/db/migrate/20261009000001_change_money_columns_to_decimal_19_4.rb
index d28ce44394..fc6c984784 100644
--- a/spree/core/db/migrate/20261009000001_change_money_columns_to_decimal_19_4.rb
+++ b/spree/core/db/migrate/20261009000001_change_money_columns_to_decimal_19_4.rb
@@ -70,30 +70,47 @@ class ChangeMoneyColumnsToDecimal194 < ActiveRecord::Migration[8.1]
}.freeze
def up
- each_column { |table, column| widen(table, column, 19, 4) }
+ deliberately_rewriting { COLUMNS.each_key { |table| retype(table) { [19, 4] } } }
end
def down
- each_column do |table, column|
- precision, scale = ORIGINAL.fetch("#{table}.#{column}", [10, 2])
- widen(table, column, precision, scale)
+ deliberately_rewriting do
+ COLUMNS.each_key { |table| retype(table) { |column| ORIGINAL.fetch("#{table}.#{column}", [10, 2]) } }
end
end
private
- def each_column
- COLUMNS.each do |table, columns|
- next unless table_exists?(table)
-
- columns.each { |column| yield(table, column) if column_exists?(table, column) }
- end
+ # The rewrite is the point of this migration and the upgrade guide documents
+ # it, so an app running strong_migrations is not stopped by it.
+ def deliberately_rewriting(&block)
+ respond_to?(:safety_assured) ? safety_assured(&block) : yield
end
- def widen(table, name, precision, scale)
- column = connection.columns(table).find { |candidate| candidate.name == name.to_s }
- return if column.precision == precision && column.scale == scale
+ # One ALTER TABLE per table, so each is rewritten once rather than once per
+ # column. PostgreSQL keeps NOT NULL and the default through a type change,
+ # and Rails' MySQL adapter carries them over itself; passing them would add a
+ # SET NOT NULL that scans every row. SQLite rebuilds the table from the new
+ # definition, so it is told both.
+ def retype(table)
+ return unless table_exists?(table)
+
+ existing = connection.columns(table).index_by(&:name)
+ changes = COLUMNS[table].filter_map do |name|
+ column = existing[name.to_s]
+ next if column.nil?
- change_column table, name, :decimal, precision: precision, scale: scale, null: column.null, default: column.default
+ precision, scale = yield(name)
+ [column, precision, scale] unless column.precision == precision && column.scale == scale
+ end
+ return if changes.empty?
+
+ change_table(table, bulk: true) do |definition|
+ changes.each do |column, precision, scale|
+ options = { precision: precision, scale: scale }
+ options.merge!(null: column.null, default: column.default) if connection.adapter_name.match?(/sqlite/i)
+ definition.change column.name, :decimal, **options
+ end
+ end
end
end
diff --git a/spree/core/lib/spree/money.rb b/spree/core/lib/spree/money.rb
index 7125633368..20fffa1348 100644
--- a/spree/core/lib/spree/money.rb
+++ b/spree/core/lib/spree/money.rb
@@ -83,7 +83,8 @@ module Spree
# precision as a float, and never more decimals than the field holds.
#
# @param value [String, nil]
- # @param currency [String, ::Money::Currency, nil]
+ # @param currency [String, ::Money::Currency, nil] nil when unknown,
+ # which allows up to {UNIT_PRICE_DECIMALS} decimals
# @param unit_price [Boolean] allows up to {UNIT_PRICE_DECIMALS} decimals
# @return [BigDecimal, nil]
# @raise [Spree::Money::InvalidFormat]
@@ -91,7 +92,11 @@ module Spree
amount = parse_canonical_decimal(value)
return if amount.nil?
- allowed = unit_price ? [precision(currency), UNIT_PRICE_DECIMALS].max : precision(currency)
+ allowed = if currency.nil? || unit_price
+ [precision(currency), UNIT_PRICE_DECIMALS].max
+ else
+ precision(currency)
+ end
raise InvalidFormat, "has more than #{allowed} decimal places" if decimal_places(value) > allowed
amount
diff --git a/spree/core/lib/spree/reporting/adapters/base.rb b/spree/core/lib/spree/reporting/adapters/base.rb
index c3048321d1..cbfd277bed 100644
--- a/spree/core/lib/spree/reporting/adapters/base.rb
+++ b/spree/core/lib/spree/reporting/adapters/base.rb
@@ -22,24 +22,25 @@ module Spree
def cast_value(metric, raw)
case metric.format
- when :money, :decimal, :percent then raw.to_f.round(2)
+ when :money then BigDecimal((raw || 0).to_s)
+ when :decimal, :percent then BigDecimal((raw || 0).to_s).round(2)
else raw.to_i
end
end
def zero_for(metric)
- metric.format == :integer ? 0 : 0.0
+ metric.format == :integer ? 0 : BigDecimal(0)
end
# Computes requested ratio metrics from their aggregated components.
def apply_derived(metrics)
query.metrics.select(&:derived?).each do |metric|
numerator, denominator = metric.ratio.map { |name| metrics[name] || 0 }
- ratio = denominator.to_f.zero? ? 0.0 : numerator / denominator.to_f
+ ratio = denominator.zero? ? BigDecimal(0) : BigDecimal(numerator.to_s) / BigDecimal(denominator.to_s)
# A percent metric carries the number a merchant reads (42.5), not
# the fraction, so clients never have to know to multiply.
ratio *= 100 if metric.format == :percent
- metrics[metric.name] = ratio.round(2)
+ metrics[metric.name] = metric.money? ? ratio : ratio.round(2)
end
end
@@ -58,12 +59,12 @@ module Spree
def growth_rate(current, previous)
return nil if previous.nil?
if previous.zero?
- return 0.0 if current.zero?
+ return BigDecimal(0) if current.zero?
return nil
end
- (((current - previous) / previous.to_f) * 100).round(1)
+ ((BigDecimal(current.to_s) - BigDecimal(previous.to_s)) / BigDecimal(previous.to_s) * 100).round(1)
end
end
end
diff --git a/spree/core/lib/spree/reporting/registry.rb b/spree/core/lib/spree/reporting/registry.rb
index 171a909455..660a500126 100644
--- a/spree/core/lib/spree/reporting/registry.rb
+++ b/spree/core/lib/spree/reporting/registry.rb
@@ -45,6 +45,19 @@ module Spree
# total is suppressed rather than rendered as a headline.
def per_group? = requires_grouping.present?
def money? = format == :money
+
+ # A value as the API and exports write it: money to the currency's
+ # decimal places, other decimals without trailing zeros, counts as
+ # integers.
+ #
+ # @param value [Numeric, nil]
+ # @param currency [String, nil]
+ # @return [String, Integer, nil]
+ def format_value(value, currency)
+ return value if value.nil? || format == :integer
+
+ money? ? Spree::Money::Rounding.format(value, currency) : Spree::Money::Rounding.format_decimal(value)
+ end
end
# A dimension groups rows. The definition owns every behavior keyed off
diff --git a/spree/core/lib/tasks/money.rake b/spree/core/lib/tasks/money.rake
index 6d844b0c5a..0f73ef80b0 100644
--- a/spree/core/lib/tasks/money.rake
+++ b/spree/core/lib/tasks/money.rake
@@ -14,9 +14,11 @@ namespace :spree do
DESC
task audit_capture_events: :environment do
listed = 0
- # The wrong records were written with the Money gem's exponent, which
- # differs from ISO 4217 for a few currencies (forint, ariary).
- codes = ::Money::Currency.all.reject { |currency| currency.exponent == 2 }.map(&:iso_code)
+ # The wrong records were written with the Money gem's exponents as they
+ # were before 6.0, which differ from ISO 4217 for a few currencies.
+ legacy_exponents = { 'HUF' => 0, 'MGA' => 1, 'MRO' => 1, 'MRU' => 1 }
+ exponent_for = ->(code) { legacy_exponents.fetch(code) { Spree::Money::Rounding.precision(code) } }
+ codes = (Spree::Money::Rounding::EXPONENTS.keys | legacy_exponents.keys).reject { |code| exponent_for.(code) == 2 }
in_codes = [Spree::Order, Spree::Cart, Spree::OrderGroup].map { |owner| owner.arel_table[:currency].in(codes) }.reduce(:or)
Spree::PaymentCaptureEvent.left_joins(payment: [:order, :cart, :order_group]).where(in_codes)
@@ -24,7 +26,7 @@ namespace :spree do
payment = event.payment
next if payment.nil?
- exponent = ::Money::Currency.find(payment.currency).exponent
+ exponent = exponent_for.(payment.currency.to_s.upcase)
corrected = event.amount * (10**exponent) / 100
puts [
diff --git a/spree/core/spec/models/spree/tax_rate_spec.rb b/spree/core/spec/models/spree/tax_rate_spec.rb
index 6660f5c4e4..dd2d1ebf41 100644
--- a/spree/core/spec/models/spree/tax_rate_spec.rb
+++ b/spree/core/spec/models/spree/tax_rate_spec.rb
@@ -294,56 +294,61 @@ describe Spree::TaxRate, type: :model do
end
describe 'percentage conversion' do
- describe '#amount_percentage' do
+ it 'still answers the deprecated #amount_percentage, with a warning' do
+ expect(Spree::Deprecation).to receive(:warn).with(/amount_percentage is deprecated/)
+ expect(build(:tax_rate, amount: 0.0825).amount_percentage).to eq(BigDecimal('8.25'))
+ end
+
+ describe '#rate_percent' do
it 'converts decimal amount to percentage' do
tax_rate = build(:tax_rate, amount: 0.0825)
- expect(tax_rate.amount_percentage).to eq(8.25)
+ expect(tax_rate.rate_percent).to eq(8.25)
end
it 'returns nil when amount is nil' do
tax_rate = build(:tax_rate, amount: nil)
- expect(tax_rate.amount_percentage).to be_nil
+ expect(tax_rate.rate_percent).to be_nil
end
it 'handles zero amount' do
tax_rate = build(:tax_rate, amount: 0.0)
- expect(tax_rate.amount_percentage).to eq(0.0)
+ expect(tax_rate.rate_percent).to eq(0.0)
end
- it 'rounds to 2 decimal places' do
+ it 'keeps every decimal the rate has' do
tax_rate = build(:tax_rate, amount: 0.12345)
- expect(tax_rate.amount_percentage).to eq(12.35)
+ expect(tax_rate.rate_percent).to eq(BigDecimal('12.345'))
end
end
- describe '#amount_percentage=' do
+ describe '#rate_percent=' do
it 'converts percentage to decimal amount' do
tax_rate = build(:tax_rate)
- tax_rate.amount_percentage = 8.25
+ tax_rate.rate_percent = 8.25
expect(tax_rate.amount).to eq(0.0825)
end
it 'sets amount to nil when percentage is nil' do
tax_rate = build(:tax_rate)
- tax_rate.amount_percentage = nil
+ tax_rate.rate_percent = nil
expect(tax_rate.amount).to be_nil
end
it 'sets amount to nil when percentage is empty string' do
tax_rate = build(:tax_rate)
- tax_rate.amount_percentage = ''
+ tax_rate.rate_percent = ''
expect(tax_rate.amount).to be_nil
end
it 'handles zero percentage' do
tax_rate = build(:tax_rate)
- tax_rate.amount_percentage = 0
+ tax_rate.rate_percent = 0
expect(tax_rate.amount).to eq(0.0)
end
it 'handles string percentage values' do
tax_rate = build(:tax_rate)
- tax_rate.amount_percentage = '5.5'
+ tax_rate.rate_percent = '5.5'
expect(tax_rate.amount).to eq(0.055)
end
end
diff --git a/spree/emails/app/serializers/spree/emails/amount_line_serializer.rb b/spree/emails/app/serializers/spree/emails/amount_line_serializer.rb
index 743a5507f7..34c54f3492 100644
--- a/spree/emails/app/serializers/spree/emails/amount_line_serializer.rb
+++ b/spree/emails/app/serializers/spree/emails/amount_line_serializer.rb
@@ -10,7 +10,7 @@ module Spree
end
attribute :amount do |line|
- line.amount.to_s
+ Spree::Money::Rounding.format(line.amount, line.currency)
end
end
end
diff --git a/spree/emails/app/serializers/spree/emails/order_group_serializer.rb b/spree/emails/app/serializers/spree/emails/order_group_serializer.rb
index c99fe0d6d0..34c8407406 100644
--- a/spree/emails/app/serializers/spree/emails/order_group_serializer.rb
+++ b/spree/emails/app/serializers/spree/emails/order_group_serializer.rb
@@ -21,11 +21,11 @@ module Spree
end
attribute :delivery_total do |group|
- group.delivery_total.to_s
+ Spree::Money::Rounding.format(group.delivery_total, group.currency)
end
attribute :additional_tax_total do |group|
- group.additional_tax_total.to_s
+ Spree::Money::Rounding.format(group.additional_tax_total, group.currency)
end
attribute :display_additional_tax_total do |group|
@@ -33,7 +33,7 @@ module Spree
end
attribute :gift_card_total do |group|
- group.gift_card_total.to_s
+ Spree::Money::Rounding.format(group.gift_card_total, group.currency)
end
attribute :display_gift_card_total do |group|