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.

API/SDK: Split discount codes and gift cards into separate cart endpoints. Rename `couponCodes` to `discountCodes` and add dedicated `giftCards` resource

Damian Legawiecbe59a63de881
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 8d554334d8..1b9fb997af 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -590,17 +590,17 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImUyMzFkMjU4LTcyZDQtNDJlZS04OGYyLTI1NjFmMGIxNDFhNiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzUzOTE1fQ.ITqNPF04ehqvkdhalyYCwWR5j1tadRAOaEVomin0rpU
- refresh_token: gijniFRnfEMpic9UtcidKCgE
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImJhOTk5NzU0LWFiYTItNGE1Zi05OWZiLWE3Nzg5YzNlY2Y3OCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzYzNDAxfQ.1QWQiaszbr8DME0BdTZb7CjR-uoYtmxouP3Xze9uQvc
+ refresh_token: fWFkfMiEN8mqxqS9MVFrrgx3
user:
id: cus_UkLWZg9DAJ
- first_name: Kitty
- last_name: Bergnaum
+ first_name: Erich
+ last_name: Zboncak
phone:
accepts_email_marketing: false
- created_at: '2026-03-24T11:05:14.866Z'
- updated_at: '2026-03-24T11:05:14.866Z'
+ created_at: '2026-03-24T13:43:21.029Z'
+ updated_at: '2026-03-24T13:43:21.029Z'
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -673,17 +673,17 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijc1YTA4Mzk4LWM2N2ItNGYzMS05NDE3LWM2ZDI5NzIxYjc5MCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzUzOTE2fQ.3vk-woF89efUSXH4ACetfIwTAnv7gH6OxWm4t0gj-4w
- refresh_token: 5zhggqsZmsjg2fsSSCiGpGhc
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY5YjRmZWY0LTI4MDMtNDhmNS1iM2FmLTkzNWJkZjE0NDlhNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzYzNDAyfQ.UAdUpxDuFGvG_R4aRki64fSMg5j2PcjtsQBCzxfj518
+ refresh_token: MQiya6Xf96yK1KMEVs21MsGS
user:
id: cus_UkLWZg9DAJ
- first_name: Marna
- last_name: Roob
+ first_name: Lanie
+ last_name: Waters
phone:
accepts_email_marketing: false
- created_at: '2026-03-24T11:05:16.295Z'
- updated_at: '2026-03-24T11:05:16.295Z'
+ created_at: '2026-03-24T13:43:22.474Z'
+ updated_at: '2026-03-24T13:43:22.474Z'
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -800,9 +800,9 @@ paths:
example:
data:
- id: cart_gbHJdmfrXB
- number: R006942926
- token: 6qQ6pdQFbUJ9VtEJYxZzWtiWEWSfNNqMpfk
+ number: R392640759
+ token: S76sXt5Xjb4dhdSJMWQzAiBEy6WWoP43KaK
customer_note:
currency: USD
locale: en
@@ -821,14 +821,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:18.437Z'
- updated_at: '2026-03-24T11:05:18.490Z'
+ created_at: '2026-03-24T13:43:25.104Z'
+ updated_at: '2026-03-24T13:43:25.159Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -843,8 +845,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 25091
- slug: product-25091
+ name: Product 26589
+ slug: product-26589
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -863,21 +865,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:18.469Z'
- updated_at: '2026-03-24T11:05:18.469Z'
+ created_at: '2026-03-24T13:43:25.137Z'
+ updated_at: '2026-03-24T13:43:25.137Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H77648156123
+ number: H60952316909
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:18.477Z'
- updated_at: '2026-03-24T11:05:18.488Z'
+ created_at: '2026-03-24T13:43:25.146Z'
+ updated_at: '2026-03-24T13:43:25.157Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -892,7 +894,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_32
- name: Georgianna Hintz
+ name: Shawna Stanton
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -952,9 +954,9 @@ paths:
payment_methods: []
gift_card:
- id: cart_UkLWZg9DAJ
- number: R446234317
- token: 7pYs3jswX8ch9VNeqqxEUwjVVjx7JpmFs6t
+ number: R111540662
+ token: kP2huZHWqV7iu8xLjUQFgHov7EFoxStZvdg
customer_note:
currency: USD
locale: en
@@ -973,14 +975,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:18.273Z'
- updated_at: '2026-03-24T11:05:18.430Z'
+ created_at: '2026-03-24T13:43:24.939Z'
+ updated_at: '2026-03-24T13:43:25.097Z'
store_credit_total: '0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -995,8 +999,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 11693
- slug: product-11693
+ name: Product 18622
+ slug: product-18622
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1015,21 +1019,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:18.353Z'
- updated_at: '2026-03-24T11:05:18.353Z'
+ created_at: '2026-03-24T13:43:25.020Z'
+ updated_at: '2026-03-24T13:43:25.020Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H65792432005
+ number: H08887615299
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:18.366Z'
- updated_at: '2026-03-24T11:05:18.424Z'
+ created_at: '2026-03-24T13:43:25.034Z'
+ updated_at: '2026-03-24T13:43:25.092Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -1044,7 +1048,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_32
- name: Georgianna Hintz
+ name: Shawna Stanton
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1177,8 +1181,8 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R811755379
- token: 6FCZTsMTYxQaTmqJH8rf2sxnNTnGDMe4nKM
+ number: R508168639
+ token: 2gG7dY3FtZLS5aKFuJnae9Bu2VAJiJzRYjN
email:
customer_note:
currency: USD
@@ -1198,14 +1202,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '0.0'
display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
- created_at: '2026-03-24T11:05:18.982Z'
- updated_at: '2026-03-24T11:05:18.982Z'
+ created_at: '2026-03-24T13:43:25.655Z'
+ updated_at: '2026-03-24T13:43:25.655Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -1315,9 +1321,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R142439546
- token: FC6u77rCTbiLxUfVfBfp4Yk4AEJCDT1nJxY
+ number: R356803276
+ token: 74NazyZ9QDgpa1vsj7r5c5ma3qeVQyhtd5a
customer_note:
currency: USD
locale: en
@@ -1336,14 +1342,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:19.265Z'
- updated_at: '2026-03-24T11:05:19.326Z'
+ created_at: '2026-03-24T13:43:25.935Z'
+ updated_at: '2026-03-24T13:43:25.997Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -1358,8 +1366,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 57580
- slug: product-57580
+ name: Product 59735
+ slug: product-59735
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1378,21 +1386,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:19.302Z'
- updated_at: '2026-03-24T11:05:19.302Z'
+ created_at: '2026-03-24T13:43:25.971Z'
+ updated_at: '2026-03-24T13:43:25.971Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H62242796409
+ number: H82190452254
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:19.308Z'
- updated_at: '2026-03-24T11:05:19.324Z'
+ created_at: '2026-03-24T13:43:25.977Z'
+ updated_at: '2026-03-24T13:43:25.995Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -1407,7 +1415,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_42
- name: Simona Grady
+ name: Lyle Sanford
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1546,9 +1554,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R596219891
- token: 5jQ5ojyeJzdaQDXNhDBKegTRZrWJ84jzBYg
+ number: R081940704
+ token: BwLpjFbf9uBn4VroHvc8HgecqGxQNtAK4LF
customer_note: Leave at door
currency: USD
locale: en
@@ -1567,14 +1575,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '29.99'
display_total: "$29.99"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '29.99'
+ display_amount_due: "$29.99"
delivery_total: '10.0'
display_delivery_total: "$10.00"
- created_at: '2026-03-24T11:05:19.912Z'
- updated_at: '2026-03-24T11:05:20.074Z'
+ created_at: '2026-03-24T13:43:26.655Z'
+ updated_at: '2026-03-24T13:43:26.861Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: payment
completed_steps:
@@ -1591,8 +1601,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 62880
- slug: product-62880
+ name: Product 63106
+ slug: product-63106
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -1611,21 +1621,21 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:19.957Z'
- updated_at: '2026-03-24T11:05:20.029Z'
+ created_at: '2026-03-24T13:43:26.729Z'
+ updated_at: '2026-03-24T13:43:26.811Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H58405017329
+ number: H06651379215
tracking:
tracking_url:
cost: '10.0'
display_cost: "$10.00"
- created_at: '2026-03-24T11:05:20.046Z'
- updated_at: '2026-03-24T11:05:20.059Z'
+ created_at: '2026-03-24T13:43:26.829Z'
+ updated_at: '2026-03-24T13:43:26.845Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -1640,7 +1650,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_44
- name: Miguel Gerhold
+ name: Yvette Braun
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1867,9 +1877,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R847028704
- token: gMTHheRSZqXPxnKUT1sCV3J9hAXmcqGruCn
+ number: R988679261
+ token: AJeBLgpYusAQWWvDtXqZqrHdJ6HgPzLMu33
customer_note:
currency: USD
locale: en
@@ -1888,14 +1898,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:20.752Z'
- updated_at: '2026-03-24T11:05:20.804Z'
+ created_at: '2026-03-24T13:43:27.559Z'
+ updated_at: '2026-03-24T13:43:27.612Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -1910,8 +1922,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 84404
- slug: product-84404
+ name: Product 86801
+ slug: product-86801
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1930,21 +1942,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:20.785Z'
- updated_at: '2026-03-24T11:05:20.785Z'
+ created_at: '2026-03-24T13:43:27.590Z'
+ updated_at: '2026-03-24T13:43:27.590Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H72246124757
+ number: H95333744955
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:20.790Z'
- updated_at: '2026-03-24T11:05:20.802Z'
+ created_at: '2026-03-24T13:43:27.595Z'
+ updated_at: '2026-03-24T13:43:27.609Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -1959,7 +1971,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_52
- name: Gaston Morissette
+ name: Shaquana VonRueden
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2083,8 +2095,8 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R478053417
+ number: R507140724
customer_note:
currency: USD
locale: en
@@ -2103,17 +2115,19 @@ paths:
display_additional_tax_total: "$0.00"
total: '29.99'
display_total: "$29.99"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '29.99'
+ display_amount_due: "$29.99"
delivery_total: '10.0'
display_delivery_total: "$10.00"
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-03-24T11:05:22.264Z'
- created_at: '2026-03-24T11:05:22.027Z'
- updated_at: '2026-03-24T11:05:22.264Z'
+ completed_at: '2026-03-24T13:43:29.126Z'
+ created_at: '2026-03-24T13:43:28.880Z'
+ updated_at: '2026-03-24T13:43:29.126Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
discounts: []
items:
@@ -2121,8 +2135,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 108977
- slug: product-108977
+ name: Product 107998
+ slug: product-107998
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2141,21 +2155,21 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:22.063Z'
- updated_at: '2026-03-24T11:05:22.268Z'
+ created_at: '2026-03-24T13:43:28.923Z'
+ updated_at: '2026-03-24T13:43:29.130Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H05796288500
+ number: H47558220148
tracking:
tracking_url:
cost: '10.0'
display_cost: "$10.00"
- created_at: '2026-03-24T11:05:22.132Z'
- updated_at: '2026-03-24T11:05:22.256Z'
+ created_at: '2026-03-24T13:43:28.992Z'
+ updated_at: '2026-03-24T13:43:29.119Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -2170,7 +2184,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_58
- name: Barb Stracke
+ name: Fredia Nader
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2192,11 +2206,11 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code: '12345'
- number: PW4ZHL30
+ number: PT6JP8Y5
amount: '29.99'
display_amount: "$29.99"
- created_at: '2026-03-24T11:05:22.202Z'
- updated_at: '2026-03-24T11:05:22.235Z'
+ created_at: '2026-03-24T13:43:29.064Z'
+ updated_at: '2026-03-24T13:43:29.097Z'
status: completed
source_type: credit_card
source_id: card_UkLWZg9DAJ
@@ -2334,8 +2348,8 @@ paths:
meta_description:
meta_keywords:
children_count: 1
- created_at: '2026-03-24T11:05:22.972Z'
- updated_at: '2026-03-24T11:05:23.046Z'
+ created_at: '2026-03-24T13:43:29.867Z'
+ updated_at: '2026-03-24T13:43:29.943Z'
parent_id:
description: ''
description_html: ''
@@ -2353,8 +2367,8 @@ paths:
meta_description:
meta_keywords:
children_count: 1
- created_at: '2026-03-24T11:05:22.992Z'
- updated_at: '2026-03-24T11:05:23.045Z'
+ created_at: '2026-03-24T13:43:29.877Z'
+ updated_at: '2026-03-24T13:43:29.943Z'
parent_id: ctg_UkLWZg9DAJ
description: ''
description_html: ''
@@ -2372,8 +2386,8 @@ paths:
meta_description:
meta_keywords:
children_count: 0
- created_at: '2026-03-24T11:05:23.009Z'
- updated_at: '2026-03-24T11:05:23.016Z'
+ created_at: '2026-03-24T13:43:29.889Z'
+ updated_at: '2026-03-24T13:43:29.897Z'
parent_id: ctg_gbHJdmfrXB
description: ''
description_html: ''
@@ -2474,8 +2488,8 @@ paths:
meta_description:
meta_keywords:
children_count: 1
- created_at: '2026-03-24T11:05:23.366Z'
- updated_at: '2026-03-24T11:05:23.402Z'
+ created_at: '2026-03-24T13:43:30.365Z'
+ updated_at: '2026-03-24T13:43:30.409Z'
parent_id: ctg_UkLWZg9DAJ
description: ''
description_html: ''
@@ -2602,28 +2616,33 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 194047
- slug: product-194047
+ name: Product 19997
+ slug: product-19997
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-03-24T11:05:23.867Z'
- created_at: '2026-03-24T11:05:23.890Z'
- updated_at: '2026-03-24T11:05:23.907Z'
+ available_on: '2025-03-24T13:43:30.974Z'
+ created_at: '2026-03-24T13:43:30.994Z'
+ updated_at: '2026-03-24T13:43:31.016Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Voluptates repudiandae laboriosam expedita corrupti
- recusandae nostrum. Beatae voluptates ex consequatur dolorum voluptate
- mollitia. Deserunt ad pariatur quod nulla veniam aut beatae repudiandae.
- Iusto at deleniti fugiat a. Necessitatibus tenetur error facere
- mollitia nesciunt ea.
- description_html: Voluptates repudiandae laboriosam expedita corrupti
- recusandae nostrum. Beatae voluptates ex consequatur dolorum voluptate
- mollitia. Deserunt ad pariatur quod nulla veniam aut beatae repudiandae.
- Iusto at deleniti fugiat a. Necessitatibus tenetur error facere
- mollitia nesciunt ea.
+ description: Quibusdam repellat laborum optio officiis. Quasi totam
+ quaerat occaecati odio architecto dignissimos cumque incidunt.
+ Expedita voluptates voluptatum illo placeat et. Quod sit minima
+ molestiae modi iusto maiores excepturi atque. Soluta error alias
+ occaecati ex qui eos repudiandae. Adipisci dolorum repudiandae
+ quo omnis animi quidem libero. Praesentium numquam magnam temporibus
+ qui odit minima id doloribus. Veritatis perferendis quo omnis
+ illo atque at possimus. Reiciendis repellendus quia aliquid quas
+ a quo. Amet corrupti odio delectus qui sit ex. Repellat illo autem
+ consectetur labore. Et tempore autem ut explicabo rem. Doloribus
+ aperiam accusamus et sapiente facilis quaerat necessitatibus voluptas.
+ description_html: |-
+ Quibusdam repellat laborum optio officiis. Quasi totam quaerat occaecati odio architecto dignissimos cumque incidunt. Expedita voluptates voluptatum illo placeat et. Quod sit minima molestiae modi iusto maiores excepturi atque.
+ Soluta error alias occaecati ex qui eos repudiandae. Adipisci dolorum repudiandae quo omnis animi quidem libero. Praesentium numquam magnam temporibus qui odit minima id doloribus. Veritatis perferendis quo omnis illo atque at possimus. Reiciendis repellendus quia aliquid quas a quo.
+ Amet corrupti odio delectus qui sit ex. Repellat illo autem consectetur labore. Et tempore autem ut explicabo rem. Doloribus aperiam accusamus et sapiente facilis quaerat necessitatibus voluptas.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -2827,17 +2846,15 @@ paths:
message: Country not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/coupon_codes":
- post:
- summary: Apply coupon code
+ "/api/v3/store/customers/me/credit_cards":
+ get:
+ summary: List saved credit cards
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: |
- Applies a coupon code to the cart. Supports both promotion coupon codes and gift card codes.
- The code is matched case-insensitively.
+ description: Returns all saved credit cards for the authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2849,7 +2866,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.couponCodes.apply('cart_abc123', 'SAVE10', {
+ const cards = await client.customer.creditCards.list({}, {
bearerToken: '<token>',
})
parameters:
@@ -2860,265 +2877,651 @@ paths:
type: string
- name: Authorization
in: header
+ required: true
+ schema:
+ type: string
+ - name: page
+ in: query
required: false
- description: Bearer token for authenticated customers
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
- - name: x-spree-token
+ responses:
+ '200':
+ description: credit cards found
+ content:
+ application/json:
+ example:
+ data:
+ - id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/CreditCard"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customers/me/credit_cards/{id}":
+ get:
+ summary: Get a credit card
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns a saved credit card by its ID
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const card = await client.customer.creditCards.get('cc_abc123', {
+ bearerToken: '<token>',
+ })
+ 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: fields
+ in: query
required: false
- description: Order token for guest access
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
- - name: cart_id
+ responses:
+ '200':
+ description: credit card found
+ content:
+ application/json:
+ example:
+ id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ schema:
+ "$ref": "#/components/schemas/CreditCard"
+ '404':
+ description: credit card not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Credit card not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ delete:
+ summary: Delete a credit card
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Removes a saved credit card from the customer account
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ await client.customer.creditCards.delete('cc_abc123', {
+ bearerToken: '<token>',
+ })
+ 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: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: Idempotency-Key
+ responses:
+ '204':
+ description: credit card deleted
+ '404':
+ description: credit card not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Credit card not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/currencies":
+ get:
+ summary: List supported currencies
+ tags:
+ - Markets
+ security:
+ - api_key: []
+ description: Returns currencies supported by the store (derived from markets)
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const currencies = await client.currencies.list()
+ parameters:
+ - name: x-spree-api-key
in: header
+ required: true
+ schema:
+ type: string
+ - name: fields
+ in: query
required: false
- description: Unique key for request idempotency.
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '201':
- description: coupon code applied (gift card)
+ '200':
+ description: currencies found
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- number: R281157330
- token: 4YysmU2TzicFAg9rgQEtETLkeWgGGETQW94
- customer_note:
- currency: USD
- locale: en
- total_quantity: 1
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:25.759Z'
- updated_at: '2026-03-24T11:05:25.894Z'
- store_credit_total: '50.0'
- display_store_credit_total: "-$50.00"
- gift_card_total: '50.0'
- display_gift_card_total: "$50.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements: []
- shipping_eq_billing_address: false
- discounts: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
+ data:
+ - iso_code: USD
+ name: United States Dollar
+ symbol: "$"
+ - iso_code: EUR
+ name: Euro
+ symbol: "€"
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Currency"
+ required:
+ - data
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customers/me/password_resets":
+ post:
+ summary: Request a password reset
+ tags:
+ - Authentication
+ security:
+ - api_key: []
+ description: Sends a password reset email if an account exists for the given
+ email address. Always returns 202 Accepted to prevent email enumeration.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ await client.customer.passwordResets.create({
+ email: '[email protected]',
+ redirect_url: 'https://myshop.com/reset-password',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '202':
+ description: email not found (same response to prevent enumeration)
+ content:
+ application/json:
+ example:
+ message: If an account exists for that email, password reset instructions
+ have been sent.
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ '401':
+ description: missing API key
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ description: Email address of the account to reset
+ redirect_url:
+ type: string
+ format: uri
+ example: https://myshop.com/reset-password
+ description: URL to redirect the user to after clicking the reset
+ link. Validated against the store's allowed origins.
+ required:
+ - email
+ "/api/v3/store/customers/me/password_resets/{token}":
+ patch:
+ summary: Reset password with token
+ tags:
+ - Authentication
+ security:
+ - api_key: []
+ description: Resets the password using a token received via email. Returns a
+ JWT token on success (auto-login).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const auth = await client.customer.passwordResets.update(
+ 'reset-token-from-email',
+ {
+ password: 'newsecurepassword',
+ password_confirmation: 'newsecurepassword',
+ }
+ )
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: token
+ in: path
+ required: true
+ description: Password reset token from the email
+ schema:
+ type: string
+ responses:
+ '200':
+ description: password reset successful
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImYwYjY3YjExLWEwYzEtNDRlZC05MTIxLWM5MGZmMWJiMDJmYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzYzNDE2fQ.TiQF0NdI_KkgYO1hm7IN25Uwd9rxpkw2KLju9t6VJ_s
+ refresh_token: CJHbM3Y5pzxrtuHVht3v7JFx
+ user:
+ id: cus_UkLWZg9DAJ
+ first_name: Celena
+ last_name: Feil
+ phone:
+ accepts_email_marketing: false
+ created_at: '2026-03-24T13:43:35.921Z'
+ updated_at: '2026-03-24T13:43:36.199Z'
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
+ schema:
+ "$ref": "#/components/schemas/AuthResponse"
+ '422':
+ description: password confirmation mismatch
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Password confirmation doesn't match Password
+ details:
+ password_confirmation:
+ - doesn't match Password
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '401':
+ description: missing API key
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ password:
+ type: string
+ minLength: 6
+ example: newsecurepassword
+ password_confirmation:
+ type: string
+ example: newsecurepassword
+ required:
+ - password
+ - password_confirmation
+ "/api/v3/store/customers/me/orders":
+ get:
+ summary: List orders
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns a paginated list of completed orders for the authenticated
+ customer.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const orders = await client.customer.orders.list({
+ bearerToken: '<token>',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: orders listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: or_UkLWZg9DAJ
+ number: R755887989
+ customer_note:
currency: USD
- name: Product 235269
- slug: product-235269
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
+ locale: en
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
discount_total: '0.0'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:25.808Z'
- updated_at: '2026-03-24T11:05:25.808Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: H89141703013
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- created_at: '2026-03-24T11:05:25.816Z'
- updated_at: '2026-03-24T11:05:25.835Z'
- status: pending
- fulfillment_type: shipping
- fulfilled_at:
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-03-24T13:43:37.105Z'
+ created_at: '2026-03-24T13:43:37.050Z'
+ updated_at: '2026-03-24T13:43:37.105Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ discounts: []
items:
- - item_id: li_UkLWZg9DAJ
+ - id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_80
- name: Erlene Mueller
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_80
- delivery_rates:
- - id: dr_UkLWZg9DAJ
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
+ currency: USD
+ name: Product 227172
+ slug: product-227172
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-24T13:43:37.083Z'
+ updated_at: '2026-03-24T13:43:37.083Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: H23322808966
+ tracking: U10000
+ tracking_url:
cost: '100.0'
display_cost: "$100.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260324110525886496
- number: PIF9V7HO
- amount: '50.0'
- display_amount: "$50.00"
- created_at: '2026-03-24T11:05:25.888Z'
- updated_at: '2026-03-24T11:05:25.888Z'
- status: checkout
- source_type: store_credit
- source_id: credit_UkLWZg9DAJ
- source:
- id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
- display_amount: "$50.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$50.00"
- currency: USD
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: Spree::PaymentMethod::StoreCredit
- session_required: false
- billing_address:
- id: addr_EfhxLZ9ck8
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 72 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_82
- state_abbr: STATE_ABBR_82
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_82
- shipping_address:
- id: addr_VqXmZF31wY
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 73 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_83
- state_abbr: STATE_ABBR_83
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_83
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: Spree::PaymentMethod::StoreCredit
- session_required: false
- gift_card:
- id: gc_UkLWZg9DAJ
- code: GIFTCODE1
- status: active
- currency: USD
- amount: '50.0'
- amount_used: '50.0'
- amount_authorized: '0.0'
- amount_remaining: '0.0'
- display_amount: "$50.00"
- display_amount_used: "$50.00"
- display_amount_remaining: "$0.00"
- expires_at:
- redeemed_at:
- expired: false
- active: true
- created_at: '2026-03-24T11:05:25.842Z'
- updated_at: '2026-03-24T11:05:25.882Z'
- schema:
- "$ref": "#/components/schemas/Cart"
- '422':
- description: invalid coupon code
+ created_at: '2026-03-24T13:43:37.088Z'
+ updated_at: '2026-03-24T13:43:37.103Z'
+ status: pending
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_88
+ name: Vince Spinka
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_88
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ display_cost: "$10.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 80 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_90
+ state_abbr: STATE_ABBR_90
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_90
+ shipping_address:
+ id: addr_VqXmZF31wY
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 81 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_91
+ state_abbr: STATE_ABBR_91
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_91
+ gift_card:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: processing_error
- message: The coupon code you entered doesn't exist. Please try again.
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- code:
- type: string
- example: SAVE10
- description: Coupon code or gift card code to apply
- required:
- - code
- "/api/v3/store/carts/{cart_id}/coupon_codes/{id}":
- delete:
- summary: Remove coupon code
+ "/api/v3/store/customers/me/orders/{id}":
+ get:
+ summary: Get an order
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Removes a previously applied coupon code from the cart. The ID
- is the coupon code string itself.
+ description: Returns a single completed order for the authenticated customer.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3130,7 +3533,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.couponCodes.remove('cart_abc123', 'SAVE10', {
+ const order = await client.customer.orders.get('or_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -3141,38 +3544,24 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: cart_id
- in: path
required: true
- description: Cart prefixed ID
schema:
type: string
- name: id
in: path
required: true
- description: The coupon code string to remove (e.g., SAVE10)
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
+ description: Order prefixed ID
schema:
type: string
responses:
'200':
- description: coupon code removed
+ description: order found
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- number: R560441265
- token: scZZXJHR2VsMLkQ5WkxeutNhzefxDBXqTuK
+ id: or_UkLWZg9DAJ
+ number: R094131006
customer_note:
currency: USD
locale: en
@@ -3191,30 +3580,28 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:27.158Z'
- updated_at: '2026-03-24T11:05:27.271Z'
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-03-24T13:43:37.806Z'
+ created_at: '2026-03-24T13:43:37.751Z'
+ updated_at: '2026-03-24T13:43:37.806Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - step: payment
- field: payment
- message: Add a payment method
- shipping_eq_billing_address: false
discounts: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 25605
- slug: product-25605
+ name: Product 243756
+ slug: product-243756
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3233,21 +3620,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:27.189Z'
- updated_at: '2026-03-24T11:05:27.266Z'
+ created_at: '2026-03-24T13:43:37.784Z'
+ updated_at: '2026-03-24T13:43:37.784Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H53091341637
+ number: H91666274996
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:27.194Z'
- updated_at: '2026-03-24T11:05:27.211Z'
+ created_at: '2026-03-24T13:43:37.789Z'
+ updated_at: '2026-03-24T13:43:37.804Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -3261,182 +3648,85 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_88
- name: Micki Dach
+ state_abbr: STATE_ABBR_94
+ name: Arminda Rath
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_88
- delivery_rates:
- - id: dr_UkLWZg9DAJ
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- billing_address:
- id: addr_EfhxLZ9ck8
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 80 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_90
- state_abbr: STATE_ABBR_90
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_90
- shipping_address:
- id: addr_VqXmZF31wY
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 81 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_91
- state_abbr: STATE_ABBR_91
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_91
- payment_methods: []
- gift_card:
- schema:
- "$ref": "#/components/schemas/Cart"
- '422':
- description: coupon code not found on cart
- content:
- application/json:
- example:
- error:
- code: processing_error
- message: The coupon code you entered doesn't exist. Please try again.
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/credit_cards":
- get:
- summary: List saved credit cards
- tags:
- - Customers
- security:
- - api_key: []
- bearer_auth: []
- description: Returns all saved credit cards for the authenticated customer
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const cards = await client.customer.creditCards.list({}, {
- bearerToken: '<token>',
- })
- 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: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: credit cards found
- content:
- application/json:
- example:
- data:
- - id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_94
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ display_cost: "$10.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 86 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_96
+ state_abbr: STATE_ABBR_96
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_96
+ shipping_address:
+ id: addr_VqXmZF31wY
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 87 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_97
+ state_abbr: STATE_ABBR_97
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_97
+ gift_card:
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/CreditCard"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/Order"
+ '404':
+ description: order belongs to another user
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: order_not_found
+ message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/credit_cards/{id}":
- get:
- summary: Get a credit card
+ "/api/v3/store/customers":
+ post:
+ summary: Register a new customer
tags:
- Customers
security:
- api_key: []
- bearer_auth: []
- description: Returns a saved credit card by its ID
+ description: Creates a new customer account and returns a JWT token
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3448,8 +3738,15 @@ paths:
publishableKey: '<api-key>',
})
- const card = await client.customer.creditCards.get('cc_abc123', {
- bearerToken: '<token>',
+ const auth = await client.customers.create({
+ email: '[email protected]',
+ password: 'password123',
+ password_confirmation: 'password123',
+ first_name: 'John',
+ last_name: 'Doe',
+ phone: '+1234567890',
+ accepts_email_marketing: true,
+ metadata: { source: 'storefront' },
})
parameters:
- name: x-spree-api-key
@@ -3457,57 +3754,88 @@ paths:
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
responses:
- '200':
- description: credit card found
+ '201':
+ description: registration successful
content:
application/json:
example:
- id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjAwZDZkZTQwLTJlZjctNGUxNS1iMzJlLTlmMjE1Mjc4YjMxZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzYzNDE5fQ.MXSa-h9cyuPAk-5gHlaJru5O_cFt_Tz3BwZnmViiryc
+ refresh_token: q7c56cxMaYt3VRjXA2fY3ZR2
+ user:
+ id: cus_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ phone: "+1234567890"
+ accepts_email_marketing: true
+ created_at: '2026-03-24T13:43:39.090Z'
+ updated_at: '2026-03-24T13:43:39.090Z'
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
schema:
- "$ref": "#/components/schemas/CreditCard"
- '404':
- description: credit card not found
+ "$ref": "#/components/schemas/AuthResponse"
+ '422':
+ description: email already taken
content:
application/json:
example:
error:
- code: record_not_found
- message: Credit card not found
+ code: validation_error
+ message: Email has already been taken
+ details:
+ email:
+ - has already been taken
schema:
"$ref": "#/components/schemas/ErrorResponse"
- delete:
- summary: Delete a credit card
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ password:
+ type: string
+ minLength: 6
+ example: password123
+ password_confirmation:
+ type: string
+ example: password123
+ first_name:
+ type: string
+ example: John
+ last_name:
+ type: string
+ example: Doe
+ phone:
+ type: string
+ example: "+1234567890"
+ accepts_email_marketing:
+ type: boolean
+ example: true
+ metadata:
+ type: object
+ example:
+ source: storefront
+ required:
+ - email
+ - password
+ "/api/v3/store/customers/me":
+ get:
+ summary: Get current customer profile
tags:
- Customers
security:
- api_key: []
bearer_auth: []
- description: Removes a saved credit card from the customer account
+ description: Returns the profile of the currently authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3519,7 +3847,7 @@ paths:
publishableKey: '<api-key>',
})
- await client.customer.creditCards.delete('cc_abc123', {
+ const customer = await client.customer.get({
bearerToken: '<token>',
})
parameters:
@@ -3531,34 +3859,127 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer JWT token
schema:
type: string
- - name: id
- in: path
- required: true
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '204':
- description: credit card deleted
- '404':
- description: credit card not found
+ '200':
+ description: profile found
+ content:
+ application/json:
+ example:
+ id: cus_UkLWZg9DAJ
+ first_name: Josefa
+ last_name: Corkery
+ phone: 555-555-0199
+ accepts_email_marketing: false
+ created_at: '2026-03-24T13:43:39.649Z'
+ updated_at: '2026-03-24T13:43:39.929Z'
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses:
+ - id: addr_gbHJdmfrXB
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 93 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_103
+ state_abbr: STATE_ABBR_103
+ quick_checkout: false
+ is_default_billing: true
+ is_default_shipping: false
+ state_name: STATE_NAME_103
+ - id: addr_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 92 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_102
+ state_abbr: STATE_ABBR_102
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: true
+ state_name: STATE_NAME_102
+ default_billing_address:
+ id: addr_gbHJdmfrXB
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 93 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_103
+ state_abbr: STATE_ABBR_103
+ quick_checkout: false
+ is_default_billing: true
+ is_default_shipping: false
+ state_name: STATE_NAME_103
+ default_shipping_address:
+ id: addr_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 92 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_102
+ state_abbr: STATE_ABBR_102
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: true
+ state_name: STATE_NAME_102
+ schema:
+ "$ref": "#/components/schemas/Customer"
+ '401':
+ description: unauthorized - invalid token
content:
application/json:
example:
error:
- code: record_not_found
- message: Credit card not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/currencies":
- get:
- summary: List supported currencies
+ patch:
+ summary: Update current customer profile
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Returns currencies supported by the store (derived from markets)
+ bearer_auth: []
+ description: Updates the profile of the currently authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3570,133 +3991,224 @@ paths:
publishableKey: '<api-key>',
})
- const currencies = await client.currencies.list()
+ const customer = await client.customer.update({
+ first_name: 'John',
+ last_name: 'Doe',
+ metadata: { preferred_contact: 'email' },
+ }, {
+ bearerToken: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: currencies found
+ description: profile updated
content:
application/json:
example:
- data:
- - iso_code: USD
- name: United States Dollar
- symbol: "$"
- - iso_code: EUR
- name: Euro
- symbol: "€"
+ id: cus_UkLWZg9DAJ
+ first_name: Updated
+ last_name: Name
+ phone: 555-555-0199
+ accepts_email_marketing: false
+ created_at: '2026-03-24T13:43:40.226Z'
+ updated_at: '2026-03-24T13:43:40.506Z'
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses:
+ - id: addr_gbHJdmfrXB
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 95 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_105
+ state_abbr: STATE_ABBR_105
+ quick_checkout: false
+ is_default_billing: true
+ is_default_shipping: false
+ state_name: STATE_NAME_105
+ - id: addr_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 94 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_104
+ state_abbr: STATE_ABBR_104
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: true
+ state_name: STATE_NAME_104
+ default_billing_address:
+ id: addr_gbHJdmfrXB
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 95 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_105
+ state_abbr: STATE_ABBR_105
+ quick_checkout: false
+ is_default_billing: true
+ is_default_shipping: false
+ state_name: STATE_NAME_105
+ default_shipping_address:
+ id: addr_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 94 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_104
+ state_abbr: STATE_ABBR_104
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: true
+ state_name: STATE_NAME_104
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Currency"
- required:
- - data
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/Customer"
+ '422':
+ description: validation error
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: validation_error
+ message: Email can't be blank
+ details:
+ email:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/password_resets":
- post:
- summary: Request a password reset
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ first_name:
+ type: string
+ example: John
+ last_name:
+ type: string
+ example: Doe
+ email:
+ type: string
+ format: email
+ password:
+ type: string
+ example: newpassword123
+ password_confirmation:
+ type: string
+ example: newpassword123
+ accepts_email_marketing:
+ type: boolean
+ example: true
+ phone:
+ type: string
+ example: "+1 555 123 4567"
+ metadata:
+ type: object
+ example:
+ preferred_contact: email
+ "/api/v3/store/digitals/{token}":
+ get:
+ summary: Download a digital product
tags:
- - Authentication
- security:
- - api_key: []
- description: Sends a password reset email if an account exists for the given
- email address. Always returns 202 Accepted to prevent email enumeration.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- await client.customer.passwordResets.create({
- email: '[email protected]',
- redirect_url: 'https://myshop.com/reset-password',
- })
+ - Digitals
+ description: |
+ Downloads a digital product file using the digital link token.
+ The token is provided via the `download_url` field on digital links
+ returned with order line items. No API key or authentication required —
+ the token itself grants access.
+ Each download increments the access counter. Downloads may be limited by
+ store settings (number of downloads and/or time-based expiration).
parameters:
- - name: x-spree-api-key
- in: header
+ - name: token
+ in: path
required: true
+ description: Digital link token
schema:
type: string
responses:
- '202':
- description: email not found (same response to prevent enumeration)
+ '200':
+ description: file downloaded
content:
- application/json:
- example:
- message: If an account exists for that email, password reset instructions
- have been sent.
- schema:
- type: object
- properties:
- message:
- type: string
- '401':
- description: missing API key
+ application/json: {}
+ '403':
+ description: download link expired or limit exceeded
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: digital_link_expired
+ message: Download link expired or invalid
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- description: Email address of the account to reset
- redirect_url:
- type: string
- format: uri
- example: https://myshop.com/reset-password
- description: URL to redirect the user to after clicking the reset
- link. Validated against the store's allowed origins.
- required:
- - email
- "/api/v3/store/customers/me/password_resets/{token}":
- patch:
- summary: Reset password with token
+ application/octet-stream:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '404':
+ description: digital link not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Digital link not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ application/octet-stream:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/carts/{cart_id}/discount_codes":
+ post:
+ summary: Apply discount code
tags:
- - Authentication
+ - Carts
security:
- api_key: []
- description: Resets the password using a token received via email. Returns a
- JWT token on success (auto-login).
+ bearer_auth: []
+ description: |
+ Applies a promotion discount code to the cart. The code is matched case-insensitively.
+
+ For gift cards, use the dedicated `POST /carts/{cart_id}/gift_cards` endpoint instead.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3708,70 +4220,216 @@ paths:
publishableKey: '<api-key>',
})
- const auth = await client.customer.passwordResets.update(
- 'reset-token-from-email',
- {
- password: 'newsecurepassword',
- password_confirmation: 'newsecurepassword',
- }
- )
+ const cart = await client.carts.discountCodes.apply('cart_abc123', 'SAVE10', {
+ bearerToken: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: token
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: cart_id
in: path
required: true
- description: Password reset token from the email
+ description: Cart prefixed ID (e.g., cart_abc123)
+ schema:
+ type: string
+ - name: Idempotency-Key
+ in: header
+ required: false
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '200':
- description: password reset successful
+ '201':
+ description: discount code applied
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjU5NDk1MmFmLTI5OTgtNDA4OC1hMTIzLWI2NGM1YzNjNjcxOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzUzOTMyfQ.NTCYCGiMW-npPp797iVA_WdTFTiNKSdxRyskm1h6xSg
- refresh_token: JmDfeJjU1rWK2uoYLdYooT5f
- user:
- id: cus_UkLWZg9DAJ
- first_name: Elnora
- last_name: Kirlin
- phone:
- accepts_email_marketing: false
- created_at: '2026-03-24T11:05:32.150Z'
- updated_at: '2026-03-24T11:05:32.424Z'
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses: []
- default_billing_address:
- default_shipping_address:
+ id: cart_UkLWZg9DAJ
+ number: R824036882
+ token: dhFDBcGzzhp3rswZX1Mpv4qcSwGCESvZiEi
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: "-10.0"
+ display_adjustment_total: "-$10.00"
+ discount_total: "-10.0"
+ display_discount_total: "-$10.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '100.0'
+ display_total: "$100.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '100.0'
+ display_amount_due: "$100.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ created_at: '2026-03-24T13:43:43.653Z'
+ updated_at: '2026-03-24T13:43:43.774Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - step: payment
+ field: payment
+ message: Add a payment method
+ shipping_eq_billing_address: false
+ discounts:
+ - id: discount_UkLWZg9DAJ
+ promotion_id: promo_UkLWZg9DAJ
+ name: Promo
+ description:
+ code: save10
+ amount: "-10.0"
+ display_amount: "-$10.00"
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 321468
+ slug: product-321468
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '0.0'
+ display_total: "$0.00"
+ adjustment_total: "-10.0"
+ display_adjustment_total: "-$10.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: "-10.0"
+ display_discount_total: "-$10.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '0.0'
+ display_discounted_amount: "$0.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-24T13:43:43.686Z'
+ updated_at: '2026-03-24T13:43:43.759Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: H25170147529
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ created_at: '2026-03-24T13:43:43.692Z'
+ updated_at: '2026-03-24T13:43:43.707Z'
+ status: pending
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_120
+ name: Tabitha Rowe
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_120
+ delivery_rates:
+ - id: dr_UkLWZg9DAJ
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 112 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_122
+ state_abbr: STATE_ABBR_122
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_122
+ shipping_address:
+ id: addr_VqXmZF31wY
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 113 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_123
+ state_abbr: STATE_ABBR_123
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_123
+ payment_methods: []
+ gift_card:
schema:
- "$ref": "#/components/schemas/AuthResponse"
+ "$ref": "#/components/schemas/Cart"
'422':
- description: password confirmation mismatch
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Password confirmation doesn't match Password
- details:
- password_confirmation:
- - doesn't match Password
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: missing API key
+ description: invalid discount code
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: processing_error
+ message: The coupon code you entered doesn't exist. Please try again.
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -3780,26 +4438,22 @@ paths:
schema:
type: object
properties:
- password:
- type: string
- minLength: 6
- example: newsecurepassword
- password_confirmation:
+ code:
type: string
- example: newsecurepassword
+ example: SAVE10
+ description: Promotion discount code to apply
required:
- - password
- - password_confirmation
- "/api/v3/store/customers/me/orders":
- get:
- summary: List orders
+ - code
+ "/api/v3/store/carts/{cart_id}/discount_codes/{id}":
+ delete:
+ summary: Remove discount code
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Returns a paginated list of completed orders for the authenticated
- customer.
+ description: Removes a previously applied discount code from the cart. The ID
+ is the discount code string itself.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3811,7 +4465,7 @@ paths:
publishableKey: '<api-key>',
})
- const orders = await client.customer.orders.list({
+ const cart = await client.carts.discountCodes.remove('cart_abc123', 'SAVE10', {
bearerToken: '<token>',
})
parameters:
@@ -3822,191 +4476,210 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: cart_id
+ in: path
required: true
+ description: Cart prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: The discount code string to remove (e.g., SAVE10)
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
schema:
type: string
responses:
'200':
- description: orders listed
+ description: discount code removed
content:
application/json:
example:
- data:
- - id: or_UkLWZg9DAJ
- number: R016692819
- customer_note:
+ id: cart_UkLWZg9DAJ
+ number: R901040932
+ token: auzdwKF5eukgt4bnFweaL5fo9YaXZrN1icM
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ created_at: '2026-03-24T13:43:44.985Z'
+ updated_at: '2026-03-24T13:43:45.086Z'
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - step: payment
+ field: payment
+ message: Add a payment method
+ shipping_eq_billing_address: false
+ discounts: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
currency: USD
- locale: en
- total_quantity: 1
- item_total: '10.0'
- display_item_total: "$10.00"
+ name: Product 34709
+ slug: product-34709
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fulfillment_status:
- payment_status:
- completed_at: '2026-03-24T11:05:33.423Z'
- created_at: '2026-03-24T11:05:33.366Z'
- updated_at: '2026-03-24T11:05:33.423Z'
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- covered_by_store_credit: false
- discounts: []
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-24T13:43:45.013Z'
+ updated_at: '2026-03-24T13:43:45.081Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: H61630651780
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ created_at: '2026-03-24T13:43:45.018Z'
+ updated_at: '2026-03-24T13:43:45.030Z'
+ status: pending
+ fulfillment_type: shipping
+ fulfilled_at:
items:
- - id: li_UkLWZg9DAJ
+ - item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
- currency: USD
- name: Product 274985
- slug: product-274985
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:33.401Z'
- updated_at: '2026-03-24T11:05:33.401Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: H08038928226
- tracking: U10000
- tracking_url:
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_128
+ name: Norberto Zieme
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_128
+ delivery_rates:
+ - id: dr_UkLWZg9DAJ
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:33.407Z'
- updated_at: '2026-03-24T11:05:33.421Z'
- status: pending
- fulfillment_type: shipping
- fulfilled_at:
- items:
- - item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
delivery_method:
id: dm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_108
- name: Thi Kuphal
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_108
- delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- billing_address:
- id: addr_EfhxLZ9ck8
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 100 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_110
- state_abbr: STATE_ABBR_110
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_110
- shipping_address:
- id: addr_VqXmZF31wY
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 101 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_111
- state_abbr: STATE_ABBR_111
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_111
- gift_card:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- '401':
- description: unauthorized
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 120 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_130
+ state_abbr: STATE_ABBR_130
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_130
+ shipping_address:
+ id: addr_VqXmZF31wY
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 121 Lovely Street
+ address2: Northwest
+ postal_code: '35005'
+ city: Herndon
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_131
+ state_abbr: STATE_ABBR_131
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_name: STATE_NAME_131
+ payment_methods: []
+ gift_card:
+ schema:
+ "$ref": "#/components/schemas/Cart"
+ '422':
+ description: discount code not found on cart
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: processing_error
+ message: The coupon code you entered doesn't exist. Please try again.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/orders/{id}":
- get:
- summary: Get an order
+ "/api/v3/store/carts/{cart_id}/fulfillments/{id}":
+ patch:
+ summary: Select delivery rate for fulfillment
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Returns a single completed order for the authenticated customer.
+ description: Selects a delivery rate for a specific fulfillment and auto-advances
+ checkout.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4018,7 +4691,9 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.customer.orders.get('or_abc123', {
+ const cart = await client.carts.fulfillments.update('cart_abc123', 'ful_abc123', {
+ selected_delivery_rate_id: 'dr_abc123',
+ }, {
bearerToken: '<token>',
})
parameters:
@@ -4029,24 +4704,37 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ schema:
+ type: string
+ - name: cart_id
+ in: path
required: true
+ description: Cart prefixed ID
schema:
type: string
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
schema:
type: string
responses:
'200':
- description: order found
+ description: delivery rate selected, returns updated cart
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R697251079
+ id: cart_UkLWZg9DAJ
+ number: R821725026
+ token: o6HpEFqmeu1jzQqE2DBW1meqh3btfmHZb4o
customer_note:
currency: USD
locale: en
@@ -4065,26 +4753,34 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- fulfillment_status:
- payment_status:
- completed_at: '2026-03-24T11:05:34.122Z'
- created_at: '2026-03-24T11:05:34.066Z'
- updated_at: '2026-03-24T11:05:34.122Z'
+ created_at: '2026-03-24T13:43:46.276Z'
+ updated_at: '2026-03-24T13:43:46.390Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
+ current_step: payment
+ completed_steps:
+ - address
+ - delivery
+ requirements:
+ - step: payment
+ field: payment
+ message: Add a payment method
+ shipping_eq_billing_address: false
discounts: []
items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 295564
- slug: product-295564
+ name: Product 364685
+ slug: product-364685
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4103,21 +4799,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:34.099Z'
- updated_at: '2026-03-24T11:05:34.099Z'
+ created_at: '2026-03-24T13:43:46.306Z'
+ updated_at: '2026-03-24T13:43:46.306Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H09978577301
+ number: H19736965107
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:34.104Z'
- updated_at: '2026-03-24T11:05:34.119Z'
+ created_at: '2026-03-24T13:43:46.311Z'
+ updated_at: '2026-03-24T13:43:46.366Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -4131,267 +4827,32 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_114
- name: Joane Lakin
+ state_abbr: STATE_ABBR_136
+ name: Alberto Bauch
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_114
+ state_text: STATE_ABBR_136
delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- billing_address:
- id: addr_EfhxLZ9ck8
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 106 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_116
- state_abbr: STATE_ABBR_116
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_116
- shipping_address:
- id: addr_VqXmZF31wY
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 107 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_117
- state_abbr: STATE_ABBR_117
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_name: STATE_NAME_117
- gift_card:
- schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: order belongs to another user
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers":
- post:
- summary: Register a new customer
- tags:
- - Customers
- security:
- - api_key: []
- description: Creates a new customer account and returns a JWT token
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const auth = await client.customers.create({
- email: '[email protected]',
- password: 'password123',
- password_confirmation: 'password123',
- first_name: 'John',
- last_name: 'Doe',
- phone: '+1234567890',
- accepts_email_marketing: true,
- metadata: { source: 'storefront' },
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: registration successful
- content:
- application/json:
- example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImJiYjY2NmY3LWU4OTYtNDFmYi04ZjA5LTdlYjQ5YzAxM2M4NCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc0MzUzOTM1fQ.L4lU7hiteKNR8CNkCt9lmn_ozJCwuyWniR_8vGUB7mI
- refresh_token: UJeZ1JvJabaJMcDQmGES6Thy
- user:
- id: cus_UkLWZg9DAJ
- first_name: John
- last_name: Doe
- phone: "+1234567890"
- accepts_email_marketing: true
- created_at: '2026-03-24T11:05:35.309Z'
- updated_at: '2026-03-24T11:05:35.309Z'
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses: []
- default_billing_address:
- default_shipping_address:
- schema:
- "$ref": "#/components/schemas/AuthResponse"
- '422':
- description: email already taken
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Email has already been taken
- details:
- email:
- - has already been taken
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- password:
- type: string
- minLength: 6
- example: password123
- password_confirmation:
- type: string
- example: password123
- first_name:
- type: string
- example: John
- last_name:
- type: string
- example: Doe
- phone:
- type: string
- example: "+1234567890"
- accepts_email_marketing:
- type: boolean
- example: true
- metadata:
- type: object
- example:
- source: storefront
- required:
- - email
- - password
- "/api/v3/store/customers/me":
- get:
- summary: Get current customer profile
- tags:
- - Customers
- security:
- - api_key: []
- bearer_auth: []
- description: Returns the profile of the currently authenticated customer
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const customer = await client.customer.get({
- bearerToken: '<token>',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer JWT token
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: profile found
- content:
- application/json:
- example:
- id: cus_UkLWZg9DAJ
- first_name: Iris
- last_name: Wolf
- phone: 555-555-0199
- accepts_email_marketing: false
- created_at: '2026-03-24T11:05:35.869Z'
- updated_at: '2026-03-24T11:05:36.138Z'
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses:
- - id: addr_gbHJdmfrXB
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 113 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_123
- state_abbr: STATE_ABBR_123
- quick_checkout: false
- is_default_billing: true
- is_default_shipping: false
- state_name: STATE_NAME_123
- - id: addr_UkLWZg9DAJ
+ - id: dr_UkLWZg9DAJ
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
first_name: John
last_name: Doe
full_name: John Doe
- address1: 112 Lovely Street
+ address1: 128 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4399,37 +4860,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_122
- state_abbr: STATE_ABBR_122
+ state_text: STATE_ABBR_138
+ state_abbr: STATE_ABBR_138
quick_checkout: false
is_default_billing: false
- is_default_shipping: true
- state_name: STATE_NAME_122
- default_billing_address:
- id: addr_gbHJdmfrXB
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 113 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_123
- state_abbr: STATE_ABBR_123
- quick_checkout: false
- is_default_billing: true
is_default_shipping: false
- state_name: STATE_NAME_123
- default_shipping_address:
- id: addr_UkLWZg9DAJ
+ state_name: STATE_NAME_138
+ shipping_address:
+ id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 112 Lovely Street
+ address1: 129 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4437,32 +4879,51 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_122
- state_abbr: STATE_ABBR_122
+ state_text: STATE_ABBR_139
+ state_abbr: STATE_ABBR_139
quick_checkout: false
is_default_billing: false
- is_default_shipping: true
- state_name: STATE_NAME_122
+ is_default_shipping: false
+ state_name: STATE_NAME_139
+ payment_methods: []
+ gift_card:
schema:
- "$ref": "#/components/schemas/Customer"
- '401':
- description: unauthorized - invalid token
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: delivery rate not found
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: record_not_found
+ message: Shipping rate not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update current customer profile
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ selected_delivery_rate_id:
+ type: string
+ example: dr_abc123
+ description: Delivery rate ID to select
+ required:
+ - selected_delivery_rate_id
+ "/api/v3/store/carts/{cart_id}/gift_cards":
+ post:
+ summary: Apply gift card
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Updates the profile of the currently authenticated customer
+ description: |
+ Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount —
+ the cart `total` remains unchanged while `amount_due` is reduced.
+
+ For promotion discount codes, use the `POST /carts/{cart_id}/discount_codes` endpoint instead.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4474,11 +4935,7 @@ paths:
publishableKey: '<api-key>',
})
- const customer = await client.customer.update({
- first_name: 'John',
- last_name: 'Doe',
- metadata: { preferred_contact: 'email' },
- }, {
+ const cart = await client.carts.giftCards.apply('cart_abc123', 'GC-ABCD-1234', {
bearerToken: '<token>',
})
parameters:
@@ -4489,68 +4946,177 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: cart_id
+ in: path
required: true
+ description: Cart prefixed ID (e.g., cart_abc123)
+ schema:
+ type: string
+ - name: Idempotency-Key
+ in: header
+ required: false
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '200':
- description: profile updated
+ '201':
+ description: gift card applied
content:
application/json:
example:
- id: cus_UkLWZg9DAJ
- first_name: Updated
- last_name: Name
- phone: 555-555-0199
- accepts_email_marketing: false
- created_at: '2026-03-24T11:05:36.432Z'
- updated_at: '2026-03-24T11:05:36.716Z'
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses:
- - id: addr_gbHJdmfrXB
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 115 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_125
- state_abbr: STATE_ABBR_125
- quick_checkout: false
- is_default_billing: true
- is_default_shipping: false
- state_name: STATE_NAME_125
- - id: addr_UkLWZg9DAJ
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 114 Lovely Street
- address2: Northwest
- postal_code: '35005'
- city: Herndon
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_124
- state_abbr: STATE_ABBR_124
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: true
- state_name: STATE_NAME_124
- default_billing_address:
- id: addr_gbHJdmfrXB
+ id: cart_UkLWZg9DAJ
+ number: R624445187
+ token: efvkAevYGjWN86FbFeXbGui9x1v2CZFf6Tm
+ customer_note:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '50.0'
+ display_gift_card_total: "$50.00"
+ amount_due: '60.0'
+ display_amount_due: "$60.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ created_at: '2026-03-24T13:43:47.592Z'
+ updated_at: '2026-03-24T13:43:47.699Z'
+ store_credit_total: '50.0'
+ display_store_credit_total: "-$50.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements: []
+ shipping_eq_billing_address: false
+ discounts: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 388590
+ slug: product-388590
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-24T13:43:47.625Z'
+ updated_at: '2026-03-24T13:43:47.625Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: H35447129866
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ created_at: '2026-03-24T13:43:47.630Z'
+ updated_at: '2026-03-24T13:43:47.645Z'
+ status: pending
+ fulfillment_type: shipping
+ fulfilled_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_144
+ name: Anh Stoltenberg
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_144
+ delivery_rates:
+ - id: dr_UkLWZg9DAJ
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: 1-SC-20260324134347692676
+ number: PDE3YFV8
+ amount: '50.0'
+ display_amount: "$50.00"
+ created_at: '2026-03-24T13:43:47.694Z'
+ updated_at: '2026-03-24T13:43:47.694Z'
+ status: checkout
+ source_type: store_credit
+ source_id: credit_UkLWZg9DAJ
+ source:
+ id: credit_UkLWZg9DAJ
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.00"
+ currency: USD
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: Spree::PaymentMethod::StoreCredit
+ session_required: false
+ billing_address:
+ id: addr_EfhxLZ9ck8
first_name: John
last_name: Doe
full_name: John Doe
- address1: 115 Lovely Street
+ address1: 136 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4558,18 +5124,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_125
- state_abbr: STATE_ABBR_125
+ state_text: STATE_ABBR_146
+ state_abbr: STATE_ABBR_146
quick_checkout: false
- is_default_billing: true
+ is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_125
- default_shipping_address:
- id: addr_UkLWZg9DAJ
+ state_name: STATE_NAME_146
+ shipping_address:
+ id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 114 Lovely Street
+ address1: 137 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4577,25 +5143,56 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_124
- state_abbr: STATE_ABBR_124
+ state_text: STATE_ABBR_147
+ state_abbr: STATE_ABBR_147
quick_checkout: false
is_default_billing: false
- is_default_shipping: true
- state_name: STATE_NAME_124
+ is_default_shipping: false
+ state_name: STATE_NAME_147
+ payment_methods:
+ - id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: Spree::PaymentMethod::StoreCredit
+ session_required: false
+ gift_card:
+ id: gc_UkLWZg9DAJ
+ code: GIFTCODE1
+ status: active
+ currency: USD
+ amount: '50.0'
+ amount_used: '50.0'
+ amount_authorized: '0.0'
+ amount_remaining: '0.0'
+ display_amount: "$50.00"
+ display_amount_used: "$50.00"
+ display_amount_remaining: "$0.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
+ created_at: '2026-03-24T13:43:47.651Z'
+ updated_at: '2026-03-24T13:43:47.689Z'
schema:
- "$ref": "#/components/schemas/Customer"
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: gift card not found
+ content:
+ application/json:
+ example:
+ error:
+ code: gift_card_not_found
+ message: The Gift Card was not found.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
'422':
- description: validation error
+ description: gift card already redeemed
content:
application/json:
example:
error:
- code: validation_error
- message: Email can't be blank
- details:
- email:
- - can't be blank
+ code: gift_card_already_redeemed
+ message: The Gift Card has already been redeemed.
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -4604,92 +5201,21 @@ paths:
schema:
type: object
properties:
- first_name:
- type: string
- example: John
- last_name:
- type: string
- example: Doe
- email:
- type: string
- format: email
- password:
- type: string
- example: newpassword123
- password_confirmation:
- type: string
- example: newpassword123
- accepts_email_marketing:
- type: boolean
- example: true
- phone:
+ code:
type: string
- example: "+1 555 123 4567"
- metadata:
- type: object
- example:
- preferred_contact: email
- "/api/v3/store/digitals/{token}":
- get:
- summary: Download a digital product
- tags:
- - Digitals
- description: |
- Downloads a digital product file using the digital link token.
- The token is provided via the `download_url` field on digital links
- returned with order line items. No API key or authentication required —
- the token itself grants access.
- Each download increments the access counter. Downloads may be limited by
- store settings (number of downloads and/or time-based expiration).
- parameters:
- - name: token
- in: path
- required: true
- description: Digital link token
- schema:
- type: string
- responses:
- '200':
- description: file downloaded
- content:
- application/json: {}
- '403':
- description: download link expired or limit exceeded
- content:
- application/json:
- example:
- error:
- code: digital_link_expired
- message: Download link expired or invalid
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- application/octet-stream:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: digital link not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Digital link not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- application/octet-stream:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/fulfillments/{id}":
- patch:
- summary: Select delivery rate for fulfillment
+ example: GC-ABCD-1234
+ description: Gift card code to apply
+ required:
+ - code
+ "/api/v3/store/carts/{cart_id}/gift_cards/{id}":
+ delete:
+ summary: Remove gift card
tags:
- Carts
security:
- api_key: []
bearer_auth: []
- description: Selects a delivery rate for a specific fulfillment and auto-advances
- checkout.
+ description: Removes a previously applied gift card from the cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4701,9 +5227,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.fulfillments.update('cart_abc123', 'ful_abc123', {
- selected_delivery_rate_id: 'dr_abc123',
- }, {
+ const cart = await client.carts.giftCards.remove('cart_abc123', 'gc_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -4715,6 +5239,7 @@ paths:
- name: Authorization
in: header
required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- name: cart_id
@@ -4726,7 +5251,7 @@ paths:
- name: id
in: path
required: true
- description: Fulfillment ID
+ description: Gift card prefixed ID (e.g., gc_abc123)
schema:
type: string
- name: x-spree-token
@@ -4737,14 +5262,14 @@ paths:
type: string
responses:
'200':
- description: delivery rate selected, returns updated cart
+ description: gift card removed
content:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R047761878
- token: fajNJ8dpN5cfSfio6mVpxVy9hp4GGxrKBUW
+ number: R743209821
+ token: ozYKaJra1mH6aQceeXPm5Pp7p6WcGZojxLW
customer_note:
currency: USD
locale: en
@@ -4763,19 +5288,19 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:05:39.811Z'
- updated_at: '2026-03-24T11:05:39.904Z'
+ created_at: '2026-03-24T13:43:50.161Z'
+ updated_at: '2026-03-24T13:43:50.272Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
- current_step: payment
- completed_steps:
- - address
- - delivery
+ current_step: address
+ completed_steps: []
requirements:
- step: payment
field: payment
@@ -4787,8 +5312,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 375290
- slug: product-375290
+ name: Product 425390
+ slug: product-425390
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4807,21 +5332,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:39.840Z'
- updated_at: '2026-03-24T11:05:39.840Z'
+ created_at: '2026-03-24T13:43:50.197Z'
+ updated_at: '2026-03-24T13:43:50.197Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H84190806434
+ number: H59829977634
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:39.846Z'
- updated_at: '2026-03-24T11:05:39.888Z'
+ created_at: '2026-03-24T13:43:50.202Z'
+ updated_at: '2026-03-24T13:43:50.217Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -4835,14 +5360,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_140
- name: Bettyann Ritchie
+ state_abbr: STATE_ABBR_160
+ name: Shad Dickens
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_140
+ state_text: STATE_ABBR_160
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -4854,13 +5379,39 @@ paths:
id: dm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
- payments: []
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: 1-SC-20260324134350239268
+ number: PTNN0H7E
+ amount: '50.0'
+ display_amount: "$50.00"
+ created_at: '2026-03-24T13:43:50.241Z'
+ updated_at: '2026-03-24T13:43:50.264Z'
+ status: invalid
+ source_type: store_credit
+ source_id: credit_UkLWZg9DAJ
+ source:
+ id: credit_UkLWZg9DAJ
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.00"
+ currency: USD
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: Spree::PaymentMethod::StoreCredit
+ session_required: false
billing_address:
id: addr_EfhxLZ9ck8
first_name: John
last_name: Doe
full_name: John Doe
- address1: 132 Lovely Street
+ address1: 152 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4868,18 +5419,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_142
- state_abbr: STATE_ABBR_142
+ state_text: STATE_ABBR_162
+ state_abbr: STATE_ABBR_162
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_142
+ state_name: STATE_NAME_162
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 133 Lovely Street
+ address1: 153 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -4887,38 +5438,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_143
- state_abbr: STATE_ABBR_143
+ state_text: STATE_ABBR_163
+ state_abbr: STATE_ABBR_163
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_143
+ state_name: STATE_NAME_163
payment_methods: []
gift_card:
schema:
"$ref": "#/components/schemas/Cart"
- '404':
- description: delivery rate not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Shipping rate not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- selected_delivery_rate_id:
- type: string
- example: dr_abc123
- description: Delivery rate ID to select
- required:
- - selected_delivery_rate_id
"/api/v3/store/customers/me/gift_cards":
get:
summary: List gift cards
@@ -4978,7 +5507,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 326E3E272A33064C
+ code: 1964BE3C6E206219
status: active
currency: USD
amount: '10.0'
@@ -4992,8 +5521,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-03-24T11:05:41.112Z'
- updated_at: '2026-03-24T11:05:41.112Z'
+ created_at: '2026-03-24T13:43:50.879Z'
+ updated_at: '2026-03-24T13:43:50.879Z'
meta:
page: 1
limit: 25
@@ -5076,7 +5605,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: '0902CC79EBEB527E'
+ code: F63108E827B9E980
status: active
currency: USD
amount: '10.0'
@@ -5090,8 +5619,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-03-24T11:05:42.365Z'
- updated_at: '2026-03-24T11:05:42.365Z'
+ created_at: '2026-03-24T13:43:52.010Z'
+ updated_at: '2026-03-24T13:43:52.010Z'
schema:
"$ref": "#/components/schemas/GiftCard"
'404':
@@ -5168,9 +5697,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R326124229
- token: UXe2dok7BoQuw4VYCE4BseTALv6sZ5QHN2y
+ number: R639367901
+ token: YhoFUL5UBcu3JjDMCH2Nsgrerr9EviUtJg1
customer_note:
currency: USD
locale: en
@@ -5189,14 +5718,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '29.99'
display_total: "$29.99"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '29.99'
+ display_amount_due: "$29.99"
delivery_total: '0.0'
display_delivery_total: "$0.00"
- created_at: '2026-03-24T11:05:44.130Z'
- updated_at: '2026-03-24T11:05:44.270Z'
+ created_at: '2026-03-24T13:43:53.798Z'
+ updated_at: '2026-03-24T13:43:53.952Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -5217,8 +5748,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 41958
- slug: product-41958
+ name: Product 452345
+ slug: product-452345
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5237,8 +5768,8 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:44.163Z'
- updated_at: '2026-03-24T11:05:44.163Z'
+ created_at: '2026-03-24T13:43:53.833Z'
+ updated_at: '2026-03-24T13:43:53.833Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -5247,8 +5778,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 427386
- slug: product-427386
+ name: Product 464916
+ slug: product-464916
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -5267,8 +5798,8 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:44.226Z'
- updated_at: '2026-03-24T11:05:44.226Z'
+ created_at: '2026-03-24T13:43:53.908Z'
+ updated_at: '2026-03-24T13:43:53.908Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -5280,7 +5811,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 151 Lovely Street
+ address1: 167 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5288,12 +5819,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_161
- state_abbr: STATE_ABBR_161
+ state_text: STATE_ABBR_177
+ state_abbr: STATE_ABBR_177
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_161
+ state_name: STATE_NAME_177
shipping_address:
payment_methods: []
gift_card:
@@ -5391,9 +5922,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R535839457
- token: BsfybRDzVD69NciUBAmffg9P2v4bxpbPNup
+ number: R178379916
+ token: Etv68g4qXVFetBydZ3n41k6GngtQNjESRW4
customer_note:
currency: USD
locale: en
@@ -5412,14 +5943,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '0.0'
display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
- created_at: '2026-03-24T11:05:46.075Z'
- updated_at: '2026-03-24T11:05:46.106Z'
+ created_at: '2026-03-24T13:43:55.792Z'
+ updated_at: '2026-03-24T13:43:55.826Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -5437,8 +5970,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 454984
- slug: product-454984
+ name: Product 495363
+ slug: product-495363
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5457,8 +5990,8 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:46.106Z'
- updated_at: '2026-03-24T11:05:46.121Z'
+ created_at: '2026-03-24T13:43:55.826Z'
+ updated_at: '2026-03-24T13:43:55.845Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -5470,7 +6003,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 160 Lovely Street
+ address1: 176 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5478,12 +6011,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_170
- state_abbr: STATE_ABBR_170
+ state_text: STATE_ABBR_186
+ state_abbr: STATE_ABBR_186
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_170
+ state_name: STATE_NAME_186
shipping_address:
payment_methods: []
gift_card:
@@ -5561,9 +6094,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R756386841
- token: JysS9GAKxVk6hMPVuhsRCGJxrV7GLFQ7HjD
+ number: R673080908
+ token: cSBdUNyBAQsodyJ3Se6twJ5X9a2RB61pCxk
customer_note:
currency: USD
locale: en
@@ -5582,14 +6115,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '0.0'
display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
delivery_total: '0.0'
display_delivery_total: "$0.00"
- created_at: '2026-03-24T11:05:46.665Z'
- updated_at: '2026-03-24T11:05:46.720Z'
+ created_at: '2026-03-24T13:43:56.407Z'
+ updated_at: '2026-03-24T13:43:56.463Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -5613,7 +6148,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 163 Lovely Street
+ address1: 179 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -5621,12 +6156,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_173
- state_abbr: STATE_ABBR_173
+ state_text: STATE_ABBR_189
+ state_abbr: STATE_ABBR_189
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_173
+ state_name: STATE_NAME_189
shipping_address:
payment_methods: []
gift_card:
@@ -5773,12 +6308,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS41
+ iso3: IS45
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS42
+ iso3: IS46
name: France
states_required: false
zipcode_required: true
@@ -5857,12 +6392,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS45
+ iso3: IS49
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS46
+ iso3: IS50
name: France
states_required: false
zipcode_required: true
@@ -5937,12 +6472,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS49
+ iso3: IS53
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS50
+ iso3: IS54
name: France
states_required: false
zipcode_required: true
@@ -6006,12 +6541,12 @@ paths:
example:
data:
- iso: FR
- iso3: IS54
+ iso3: IS58
name: France
states_required: false
zipcode_required: true
- iso: DE
- iso3: IS53
+ iso3: IS57
name: Germany
states_required: false
zipcode_required: true
@@ -6146,7 +6681,7 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R128727515
+ number: R234840902
customer_note:
currency: USD
@@ -6166,17 +6701,19 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-03-24T11:05:48.460Z'
- created_at: '2026-03-24T11:05:48.405Z'
- updated_at: '2026-03-24T11:05:48.460Z'
+ completed_at: '2026-03-24T13:43:58.490Z'
+ created_at: '2026-03-24T13:43:58.430Z'
+ updated_at: '2026-03-24T13:43:58.490Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
discounts: []
items:
@@ -6184,8 +6721,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 493300
- slug: product-493300
+ name: Product 539528
+ slug: product-539528
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6204,21 +6741,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:05:48.438Z'
- updated_at: '2026-03-24T11:05:48.438Z'
+ created_at: '2026-03-24T13:43:58.467Z'
+ updated_at: '2026-03-24T13:43:58.467Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H32448688287
+ number: H44354070148
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:05:48.443Z'
- updated_at: '2026-03-24T11:05:48.458Z'
+ created_at: '2026-03-24T13:43:58.472Z'
+ updated_at: '2026-03-24T13:43:58.487Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -6232,14 +6769,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_181
- name: Gemma Kirlin
+ state_abbr: STATE_ABBR_197
+ name: Stacee VonRueden
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_181
+ state_text: STATE_ABBR_197
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
@@ -6257,7 +6794,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 171 Lovely Street
+ address1: 187 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -6265,18 +6802,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_181
- state_abbr: STATE_ABBR_181
+ state_text: STATE_ABBR_197
+ state_abbr: STATE_ABBR_197
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_181
+ state_name: STATE_NAME_197
shipping_address:
id: addr_gbHJdmfrXB
first_name: John
last_name: Doe
full_name: John Doe
- address1: 172 Lovely Street
+ address1: 188 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -6284,12 +6821,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_182
- state_abbr: STATE_ABBR_182
+ state_text: STATE_ABBR_198
+ state_abbr: STATE_ABBR_198
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_182
+ state_name: STATE_NAME_198
gift_card:
schema:
"$ref": "#/components/schemas/Order"
@@ -6369,13 +6906,13 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_067bd59e2cd318af3d19669e
+ external_id: bogus_7eb95ecdd4c1e07fd0d84619
external_data:
- client_secret: bogus_secret_53dcbe8ec43304c5
+ client_secret: bogus_secret_3e0e3f3ee1eda7c3
customer_external_id:
expires_at:
- created_at: '2026-03-24T11:05:50.302Z'
- updated_at: '2026-03-24T11:05:50.302Z'
+ created_at: '2026-03-24T13:44:00.392Z'
+ updated_at: '2026-03-24T13:44:00.392Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6470,13 +7007,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_87a78956dcdbba5ff78940be
+ external_id: bogus_6551038a555bfef7d7bb357f
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-24T11:05:50.916Z'
- updated_at: '2026-03-24T11:05:50.916Z'
+ created_at: '2026-03-24T13:44:01.004Z'
+ updated_at: '2026-03-24T13:44:01.004Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6533,13 +7070,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_a8bf0622b05c10f35154438a
+ external_id: bogus_bfce70f9c92c7ce05e73eba1
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-24T11:05:52.145Z'
- updated_at: '2026-03-24T11:05:52.157Z'
+ created_at: '2026-03-24T13:44:02.311Z'
+ updated_at: '2026-03-24T13:44:02.324Z'
amount: '50.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6636,13 +7173,13 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_ad4f57c22e579bdd5f4836db
+ external_id: bogus_d173f2f6544ba3f23054589c
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-24T11:05:52.789Z'
- updated_at: '2026-03-24T11:05:52.813Z'
+ created_at: '2026-03-24T13:44:02.931Z'
+ updated_at: '2026-03-24T13:44:02.944Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6722,11 +7259,11 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_6d01a0cb5e3d1e9e64a51691
- external_client_secret: bogus_seti_secret_c4688e8684e7a485
+ external_id: bogus_seti_9678ff4904f3adae29042ed9
+ external_client_secret: bogus_seti_secret_82747f8d7a396287
external_data: {}
- created_at: '2026-03-24T11:05:54.041Z'
- updated_at: '2026-03-24T11:05:54.041Z'
+ created_at: '2026-03-24T13:44:04.140Z'
+ updated_at: '2026-03-24T13:44:04.140Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6823,12 +7360,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_405964e605f0f7cad98f7023
- external_client_secret: seti_secret_8d391a059642300a37c5bedf
+ external_id: seti_test_1a9b42833860e3d7fc485de2
+ external_client_secret: seti_secret_f7bb935cbf333165f8dfc4d7
external_data:
client_secret: secret_123
- created_at: '2026-03-24T11:05:55.679Z'
- updated_at: '2026-03-24T11:05:55.679Z'
+ created_at: '2026-03-24T13:44:05.861Z'
+ updated_at: '2026-03-24T13:44:05.861Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6901,12 +7438,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_125f77851299a5f4612b564c
- external_client_secret: seti_secret_b85bb39905f17d5a3c95f461
+ external_id: seti_test_2f12a5f22d3dda4ba3535bb6
+ external_client_secret: seti_secret_f2a9f57a4867d5d1b4475cae
external_data:
client_secret: secret_123
- created_at: '2026-03-24T11:05:56.781Z'
- updated_at: '2026-03-24T11:05:56.793Z'
+ created_at: '2026-03-24T13:44:07.038Z'
+ updated_at: '2026-03-24T13:44:07.053Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id: card_UkLWZg9DAJ
payment_source_type: Spree::CreditCard
@@ -6997,11 +7534,11 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: P3DUDCFZ
+ number: P7HB1SA5
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-24T11:05:58.054Z'
- updated_at: '2026-03-24T11:05:58.054Z'
+ created_at: '2026-03-24T13:44:08.247Z'
+ updated_at: '2026-03-24T13:44:08.247Z'
status: checkout
source_type:
source_id:
@@ -7159,14 +7696,14 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 59391
- slug: product-59391
+ name: Product 638731
+ slug: product-638731
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-24T11:05:58.728Z'
- created_at: '2026-03-24T11:05:58.743Z'
- updated_at: '2026-03-24T11:05:58.790Z'
+ available_on: '2025-03-24T13:44:08.936Z'
+ created_at: '2026-03-24T13:44:08.954Z'
+ updated_at: '2026-03-24T13:44:09.006Z'
purchasable: true
in_stock: false
backorderable: true
@@ -7188,36 +7725,29 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 602924
- slug: product-602924
+ name: Product 643383
+ slug: product-643383
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-03-24T11:05:58.795Z'
- created_at: '2026-03-24T11:05:58.805Z'
- updated_at: '2026-03-24T11:05:58.819Z'
+ available_on: '2025-03-24T13:44:09.011Z'
+ created_at: '2026-03-24T13:44:09.022Z'
+ updated_at: '2026-03-24T13:44:09.036Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Quisquam repudiandae aut natus recusandae laudantium
- impedit dolore veniam. Reprehenderit vero cumque voluptate laboriosam.
- Dolorum a labore sunt temporibus in. Adipisci minus illo aperiam
- minima alias. Inventore iste accusamus repellendus velit a aliquid
- nisi. Excepturi suscipit voluptates quaerat ullam nisi exercitationem.
- Minus magni velit temporibus ullam. Possimus quam dolorem adipisci
- voluptatum. Laudantium placeat perspiciatis error id cumque. Expedita
- magni illum architecto numquam esse. Et voluptates blanditiis
- illo cupiditate similique omnis neque facere. Corrupti rerum aut
- alias exercitationem fugit illo possimus perspiciatis. Earum temporibus
- soluta ducimus repellendus velit ipsam aspernatur. Facere totam
- numquam vitae tenetur suscipit nisi. Optio quam incidunt praesentium
- voluptatum libero commodi iusto eum.
+ description: Similique dignissimos quam accusantium facilis perferendis
+ fugiat repellendus. Itaque odio veritatis corrupti unde. Ipsa
+ commodi deserunt ab nostrum dolores asperiores a fugiat. Deleniti
+ itaque laudantium asperiores ipsum ab. Corporis consequuntur quasi
+ nisi earum illo est eaque porro. Eaque natus consectetur facilis
+ voluptatum quod. Reprehenderit exercitationem impedit natus ea
+ deleniti molestias voluptatum. Accusamus nostrum aliquam sequi
+ laudantium id architecto voluptatibus.
description_html: |-
- Quisquam repudiandae aut natus recusandae laudantium impedit dolore veniam. Reprehenderit vero cumque voluptate laboriosam. Dolorum a labore sunt temporibus in.
- Adipisci minus illo aperiam minima alias. Inventore iste accusamus repellendus velit a aliquid nisi. Excepturi suscipit voluptates quaerat ullam nisi exercitationem. Minus magni velit temporibus ullam.
- Possimus quam dolorem adipisci voluptatum. Laudantium placeat perspiciatis error id cumque. Expedita magni illum architecto numquam esse. Et voluptates blanditiis illo cupiditate similique omnis neque facere.
- Corrupti rerum aut alias exercitationem fugit illo possimus perspiciatis. Earum temporibus soluta ducimus repellendus velit ipsam aspernatur. Facere totam numquam vitae tenetur suscipit nisi. Optio quam incidunt praesentium voluptatum libero commodi iusto eum.
+ Similique dignissimos quam accusantium facilis perferendis fugiat repellendus. Itaque odio veritatis corrupti unde. Ipsa commodi deserunt ab nostrum dolores asperiores a fugiat. Deleniti itaque laudantium asperiores ipsum ab.
+ Corporis consequuntur quasi nisi earum illo est eaque porro. Eaque natus consectetur facilis voluptatum quod. Reprehenderit exercitationem impedit natus ea deleniti molestias voluptatum. Accusamus nostrum aliquam sequi laudantium id architecto voluptatibus.
default_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -7319,14 +7849,14 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 873511
- slug: product-873511
+ name: Product 919764
+ slug: product-919764
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-24T11:06:00.369Z'
- created_at: '2026-03-24T11:06:00.384Z'
- updated_at: '2026-03-24T11:06:00.420Z'
+ available_on: '2025-03-24T13:44:10.771Z'
+ created_at: '2026-03-24T13:44:10.787Z'
+ updated_at: '2026-03-24T13:44:10.830Z'
purchasable: true
in_stock: false
backorderable: true
@@ -7353,7 +7883,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-03-09T11:06:00Z'
+ recorded_at: '2026-03-09T13:44:10Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -7724,9 +8254,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R943357454
- token: jmNR2nMZZZSXi9xHbhvHtGn6r6XKFyq6Z6t
+ number: R321738279
+ token: HcmhhmRGX2isSSAjBmDn6qfFUth9aVipEPe
customer_note:
currency: USD
locale: en
@@ -7745,14 +8275,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '100.0'
+ display_amount_due: "$100.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:06:05.291Z'
- updated_at: '2026-03-24T11:06:05.337Z'
+ created_at: '2026-03-24T13:44:16.012Z'
+ updated_at: '2026-03-24T13:44:16.073Z'
store_credit_total: '10.0'
display_store_credit_total: "-$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -7764,8 +8296,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1072461
- slug: product-1072461
+ name: Product 1113814
+ slug: product-1113814
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7784,21 +8316,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:06:05.318Z'
- updated_at: '2026-03-24T11:06:05.318Z'
+ created_at: '2026-03-24T13:44:16.045Z'
+ updated_at: '2026-03-24T13:44:16.045Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H46724419728
+ number: H31282705837
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:06:05.323Z'
- updated_at: '2026-03-24T11:06:05.335Z'
+ created_at: '2026-03-24T13:44:16.053Z'
+ updated_at: '2026-03-24T13:44:16.071Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -7812,14 +8344,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_255
- name: Rene Lynch
+ state_abbr: STATE_ABBR_271
+ name: Carley Schoen
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_255
+ state_text: STATE_ABBR_271
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -7834,12 +8366,12 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260324110605630576
- number: P1BUJWVD
+ response_code: 1-SC-20260324134416366672
+ number: P98QSLQC
amount: '10.0'
display_amount: "$10.00"
- created_at: '2026-03-24T11:06:05.633Z'
- updated_at: '2026-03-24T11:06:05.633Z'
+ created_at: '2026-03-24T13:44:16.370Z'
+ updated_at: '2026-03-24T13:44:16.370Z'
status: checkout
source_type: store_credit
source_id: credit_UkLWZg9DAJ
@@ -7863,7 +8395,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 235 Lovely Street
+ address1: 251 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -7871,18 +8403,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_257
- state_abbr: STATE_ABBR_257
+ state_text: STATE_ABBR_273
+ state_abbr: STATE_ABBR_273
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_257
+ state_name: STATE_NAME_273
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 236 Lovely Street
+ address1: 252 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -7890,12 +8422,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_258
- state_abbr: STATE_ABBR_258
+ state_text: STATE_ABBR_274
+ state_abbr: STATE_ABBR_274
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_258
+ state_name: STATE_NAME_274
payment_methods:
- id: pm_UkLWZg9DAJ
name: Store Credit
@@ -7976,9 +8508,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R223600924
- token: KiRS8iuhHyuqQwXUsTbnVa2F1mH3VL74NXW
+ number: R430425294
+ token: XHLzoGM9zg51PiHH6ugoBdPenfM7Q2DzEfo
customer_note:
currency: USD
locale: en
@@ -7997,14 +8529,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
delivery_total: '100.0'
display_delivery_total: "$100.00"
- created_at: '2026-03-24T11:06:06.816Z'
- updated_at: '2026-03-24T11:06:06.864Z'
+ created_at: '2026-03-24T13:44:17.539Z'
+ updated_at: '2026-03-24T13:44:17.600Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
covered_by_store_credit: false
current_step: address
completed_steps: []
@@ -8019,8 +8553,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1092250
- slug: product-1092250
+ name: Product 1137865
+ slug: product-1137865
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8039,21 +8573,21 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-24T11:06:06.845Z'
- updated_at: '2026-03-24T11:06:06.845Z'
+ created_at: '2026-03-24T13:44:17.577Z'
+ updated_at: '2026-03-24T13:44:17.577Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H39852890219
+ number: H61704690913
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
- created_at: '2026-03-24T11:06:06.849Z'
- updated_at: '2026-03-24T11:06:06.862Z'
+ created_at: '2026-03-24T13:44:17.582Z'
+ updated_at: '2026-03-24T13:44:17.597Z'
status: pending
fulfillment_type: shipping
fulfilled_at:
@@ -8067,14 +8601,14 @@ paths:
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_263
- name: Yuk Gibson
+ state_abbr: STATE_ABBR_279
+ name: Leo Stanton
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_263
+ state_text: STATE_ABBR_279
delivery_rates:
- id: dr_UkLWZg9DAJ
delivery_method_id: dm_UkLWZg9DAJ
@@ -8092,7 +8626,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 243 Lovely Street
+ address1: 259 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -8100,18 +8634,18 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_265
- state_abbr: STATE_ABBR_265
+ state_text: STATE_ABBR_281
+ state_abbr: STATE_ABBR_281
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_265
+ state_name: STATE_NAME_281
shipping_address:
id: addr_VqXmZF31wY
first_name: John
last_name: Doe
full_name: John Doe
- address1: 244 Lovely Street
+ address1: 260 Lovely Street
address2: Northwest
postal_code: '35005'
city: Herndon
@@ -8119,12 +8653,12 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_266
- state_abbr: STATE_ABBR_266
+ state_text: STATE_ABBR_282
+ state_abbr: STATE_ABBR_282
quick_checkout: false
is_default_billing: false
is_default_shipping: false
- state_name: STATE_NAME_266
+ state_name: STATE_NAME_282
payment_methods: []
gift_card:
schema:
@@ -8189,9 +8723,9 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: cAWj8qUcWi2shxzhec4Usn3i
- created_at: '2026-03-24T11:06:07.446Z'
- updated_at: '2026-03-24T11:06:07.446Z'
+ token: 3AuZRknquh5bG4Eb8wnQdtjU
+ created_at: '2026-03-24T13:44:18.179Z'
+ updated_at: '2026-03-24T13:44:18.179Z'
is_default: false
is_private: true
meta:
@@ -8267,9 +8801,9 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: f3YJ8WfGKobeaEiwoSLfsRFJ
- created_at: '2026-03-24T11:06:08.645Z'
- updated_at: '2026-03-24T11:06:08.645Z'
+ token: 1gaeTiNsP1XhXz6AHMh2CgUW
+ created_at: '2026-03-24T13:44:19.371Z'
+ updated_at: '2026-03-24T13:44:19.371Z'
is_default: false
is_private: true
schema:
@@ -8365,9 +8899,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: ZtcVF65692MDpfJjiJ6uCDQo
- created_at: '2026-03-24T11:06:09.759Z'
- updated_at: '2026-03-24T11:06:09.759Z'
+ token: nvtnd6BzjYUWx2qQghbV7RiD
+ created_at: '2026-03-24T13:44:20.486Z'
+ updated_at: '2026-03-24T13:44:20.486Z'
is_default: false
is_private: true
schema:
@@ -8429,9 +8963,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: 3UejRiQSyCDQPYwbWUWAh5rF
- created_at: '2026-03-24T11:06:10.902Z'
- updated_at: '2026-03-24T11:06:10.954Z'
+ token: 7jAzL9K8yvySDHLWsHN2bzgb
+ created_at: '2026-03-24T13:44:21.649Z'
+ updated_at: '2026-03-24T13:44:21.690Z'
is_default: false
is_private: true
schema:
@@ -8543,17 +9077,17 @@ paths:
variant_id: variant_gbHJdmfrXB
wishlist_id: wl_UkLWZg9DAJ
quantity: 1
- created_at: '2026-03-24T11:06:12.139Z'
- updated_at: '2026-03-24T11:06:12.139Z'
+ created_at: '2026-03-24T13:44:22.866Z'
+ updated_at: '2026-03-24T13:44:22.866Z'
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-131
+ sku: SKU-135
options_text: ''
track_inventory: true
media_count: 0
- created_at: '2026-03-24T11:06:12.113Z'
- updated_at: '2026-03-24T11:06:12.123Z'
+ created_at: '2026-03-24T13:44:22.842Z'
+ updated_at: '2026-03-24T13:44:22.852Z'
thumbnail_url:
purchasable: true
in_stock: false
@@ -8970,6 +9504,14 @@ components:
type: string
display_total:
type: string
+ gift_card_total:
+ type: string
+ display_gift_card_total:
+ type: string
+ amount_due:
+ type: string
+ display_amount_due:
+ type: string
delivery_total:
type: string
display_delivery_total:
@@ -8982,10 +9524,6 @@ components:
type: string
display_store_credit_total:
type: string
- gift_card_total:
- type: string
- display_gift_card_total:
- type: string
covered_by_store_credit:
type: boolean
current_step:
@@ -9055,14 +9593,16 @@ components:
- display_additional_tax_total
- total
- display_total
+ - gift_card_total
+ - display_gift_card_total
+ - amount_due
+ - display_amount_due
- delivery_total
- display_delivery_total
- created_at
- updated_at
- store_credit_total
- display_store_credit_total
- - gift_card_total
- - display_gift_card_total
- covered_by_store_credit
- current_step
- completed_steps
@@ -9971,6 +10511,14 @@ components:
type: string
display_total:
type: string
+ gift_card_total:
+ type: string
+ display_gift_card_total:
+ type: string
+ amount_due:
+ type: string
+ display_amount_due:
+ type: string
delivery_total:
type: string
display_delivery_total:
@@ -9992,10 +10540,6 @@ components:
type: string
display_store_credit_total:
type: string
- gift_card_total:
- type: string
- display_gift_card_total:
- type: string
covered_by_store_credit:
type: boolean
discounts:
@@ -10048,6 +10592,10 @@ components:
- display_additional_tax_total
- total
- display_total
+ - gift_card_total
+ - display_gift_card_total
+ - amount_due
+ - display_amount_due
- delivery_total
- display_delivery_total
- fulfillment_status
@@ -10057,8 +10605,6 @@ components:
- updated_at
- store_credit_total
- display_store_credit_total
- - gift_card_total
- - display_gift_card_total
- covered_by_store_credit
- discounts
- items
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index e7d3fd9084..ca9857939e 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 a7e33dabfb090e2a86fed6b6aa3c0621
+// Typelizer digest 7cfd29f58b2f8b0f45cf89897f24a319
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Discount, LineItem, Fulfillment, Payment, Address, GiftCard, PaymentMethod, Customer, Adjustment, ReturnAuthorization, Reimbursement} from '@/types'
@@ -25,6 +25,10 @@ interface Order {
display_additional_tax_total: string;
total: string;
display_total: string;
+ gift_card_total: string;
+ display_gift_card_total: string;
+ amount_due: string;
+ display_amount_due: string;
delivery_total: string;
display_delivery_total: string;
fulfillment_status: string | null;
@@ -34,8 +38,6 @@ interface Order {
updated_at: string;
store_credit_total: string;
display_store_credit_total: string;
- gift_card_total: string;
- display_gift_card_total: string;
covered_by_store_credit: boolean;
discounts?: Array<Discount>;
items?: Array<LineItem>;
diff --git a/packages/next/.changeset/gift-card-discount-code-actions.md b/packages/next/.changeset/gift-card-discount-code-actions.md
new file mode 100644
index 0000000000..1782adca29
--- /dev/null
+++ b/packages/next/.changeset/gift-card-discount-code-actions.md
@@ -0,0 +1,10 @@
+---
+"@spree/next": minor
+---
+
+Split discount codes and gift cards into separate server actions. Rename coupon actions and add dedicated gift card actions.
+
+- `applyDiscountCode(code)` — apply promotion discount code (replaces `applyCoupon`)
+- `removeDiscountCode(code)` — remove discount code (replaces `removeCoupon`)
+- `applyGiftCard(code)` — apply gift card to cart (new)
+- `removeGiftCard(giftCardId)` — remove gift card by prefixed ID (new)
diff --git a/packages/next/src/actions/cart.ts b/packages/next/src/actions/cart.ts
index 6b74c77148..7ce17dd05e 100644
--- a/packages/next/src/actions/cart.ts
+++ b/packages/next/src/actions/cart.ts
@@ -189,28 +189,57 @@ export async function selectDeliveryRate(
}
/**
- * Apply a coupon code to the cart.
+ * Apply a discount code to the cart.
*/
-export async function applyCoupon(
+export async function applyDiscountCode(
code: string
): Promise<Cart> {
const options = await getCartOptions();
const cartId = await requireCartId();
- const result = await getClient().carts.couponCodes.apply(cartId, code, options);
+ const result = await getClient().carts.discountCodes.apply(cartId, code, options);
revalidateTag('checkout');
revalidateTag('cart');
return result;
}
/**
- * Remove a coupon code from the cart.
+ * Remove a discount code from the cart.
*/
-export async function removeCoupon(
+export async function removeDiscountCode(
code: string
): Promise<Cart> {
const options = await getCartOptions();
const cartId = await requireCartId();
- const result = await getClient().carts.couponCodes.remove(cartId, code, options);
+ const result = await getClient().carts.discountCodes.remove(cartId, code, options);
+ revalidateTag('checkout');
+ revalidateTag('cart');
+ return result;
+}
+
+/**
+ * Apply a gift card to the cart.
+ * Gift cards are treated as a payment method — the cart total stays the same
+ * while `amount_due` is reduced.
+ */
+export async function applyGiftCard(
+ code: string
+): Promise<Cart> {
+ const options = await getCartOptions();
+ const cartId = await requireCartId();
+ const result = await getClient().carts.giftCards.apply(cartId, code, options);
+ revalidateTag('checkout');
+ revalidateTag('cart');
+ return result;
+}
+
+/**
+ * Remove the applied gift card from the cart.
+ * @param giftCardId - Gift card prefixed ID (e.g., 'gc_abc123') from cart.gift_card.id
+ */
+export async function removeGiftCard(giftCardId: string): Promise<Cart> {
+ const options = await getCartOptions();
+ const cartId = await requireCartId();
+ const result = await getClient().carts.giftCards.remove(cartId, giftCardId, options);
revalidateTag('checkout');
revalidateTag('cart');
return result;
diff --git a/packages/next/src/index.ts b/packages/next/src/index.ts
index ee3987d8e5..03655f01e7 100644
--- a/packages/next/src/index.ts
+++ b/packages/next/src/index.ts
@@ -21,8 +21,10 @@ export {
associateCart,
updateCart,
selectDeliveryRate,
- applyCoupon,
- removeCoupon,
+ applyDiscountCode,
+ removeDiscountCode,
+ applyGiftCard,
+ removeGiftCard,
complete,
} from './actions/cart';
diff --git a/packages/next/tests/actions/cart.test.ts b/packages/next/tests/actions/cart.test.ts
index f310a6170f..a55f6b4b1b 100644
--- a/packages/next/tests/actions/cart.test.ts
+++ b/packages/next/tests/actions/cart.test.ts
@@ -19,7 +19,11 @@ const mockClient = {
fulfillments: {
update: vi.fn(),
},
- couponCodes: {
+ discountCodes: {
+ apply: vi.fn(),
+ remove: vi.fn(),
+ },
+ giftCards: {
apply: vi.fn(),
remove: vi.fn(),
},
@@ -32,7 +36,7 @@ vi.mock('@spree/sdk', () => ({
import {
getCart, getOrCreateCart, addItem, updateItem, removeItem, clearCart, associateCart,
- updateCart, selectDeliveryRate, applyCoupon, removeCoupon, complete,
+ updateCart, selectDeliveryRate, applyDiscountCode, removeDiscountCode, applyGiftCard, removeGiftCard, complete,
} from '../../src/actions/cart';
import { revalidateTag } from 'next/cache';
@@ -274,19 +278,19 @@ describe('cart actions', () => {
});
});
- describe('applyCoupon', () => {
- it('applies coupon and revalidates checkout and cart', async () => {
+ describe('applyDiscountCode', () => {
+ it('applies discount code and revalidates checkout and cart', async () => {
const updatedCart = { id: 'cart_1', discount_total: -10 };
mockCookies({
'_spree_cart_token': 'order_token',
'_spree_cart_token_id': 'cart_1',
'_spree_jwt': 'jwt_token',
});
- mockClient.carts.couponCodes.apply.mockResolvedValue(updatedCart);
+ mockClient.carts.discountCodes.apply.mockResolvedValue(updatedCart);
- const result = await applyCoupon('SAVE10');
+ const result = await applyDiscountCode('SAVE10');
expect(result).toEqual(updatedCart);
- expect(mockClient.carts.couponCodes.apply).toHaveBeenCalledWith(
+ expect(mockClient.carts.discountCodes.apply).toHaveBeenCalledWith(
'cart_1',
'SAVE10',
{ spreeToken: 'order_token', token: 'jwt_token' }
@@ -296,19 +300,19 @@ describe('cart actions', () => {
});
});
- describe('removeCoupon', () => {
- it('removes coupon and revalidates checkout and cart', async () => {
+ describe('removeDiscountCode', () => {
+ it('removes discount code and revalidates checkout and cart', async () => {
const updatedCart = { id: 'cart_1', discount_total: 0 };
mockCookies({
'_spree_cart_token': 'order_token',
'_spree_cart_token_id': 'cart_1',
'_spree_jwt': 'jwt_token',
});
- mockClient.carts.couponCodes.remove.mockResolvedValue(updatedCart);
+ mockClient.carts.discountCodes.remove.mockResolvedValue(updatedCart);
- const result = await removeCoupon('SAVE10');
+ const result = await removeDiscountCode('SAVE10');
expect(result).toEqual(updatedCart);
- expect(mockClient.carts.couponCodes.remove).toHaveBeenCalledWith(
+ expect(mockClient.carts.discountCodes.remove).toHaveBeenCalledWith(
'cart_1',
'SAVE10',
{ spreeToken: 'order_token', token: 'jwt_token' }
@@ -318,6 +322,50 @@ describe('cart actions', () => {
});
});
+ describe('applyGiftCard', () => {
+ it('applies gift card and revalidates checkout and cart', async () => {
+ const updatedCart = { id: 'cart_1', gift_card_total: '50.0', amount_due: '59.08' };
+ mockCookies({
+ '_spree_cart_token': 'order_token',
+ '_spree_cart_token_id': 'cart_1',
+ '_spree_jwt': 'jwt_token',
+ });
+ mockClient.carts.giftCards.apply.mockResolvedValue(updatedCart);
+
+ const result = await applyGiftCard('GC-ABCD-1234');
+ expect(result).toEqual(updatedCart);
+ expect(mockClient.carts.giftCards.apply).toHaveBeenCalledWith(
+ 'cart_1',
+ 'GC-ABCD-1234',
+ { spreeToken: 'order_token', token: 'jwt_token' }
+ );
+ expect(revalidateTag).toHaveBeenCalledWith('checkout');
+ expect(revalidateTag).toHaveBeenCalledWith('cart');
+ });
+ });
+
+ describe('removeGiftCard', () => {
+ it('removes gift card and revalidates checkout and cart', async () => {
+ const updatedCart = { id: 'cart_1', gift_card_total: '0.0', amount_due: '109.08' };
+ mockCookies({
+ '_spree_cart_token': 'order_token',
+ '_spree_cart_token_id': 'cart_1',
+ '_spree_jwt': 'jwt_token',
+ });
+ mockClient.carts.giftCards.remove.mockResolvedValue(updatedCart);
+
+ const result = await removeGiftCard('gc_abc123');
+ expect(result).toEqual(updatedCart);
+ expect(mockClient.carts.giftCards.remove).toHaveBeenCalledWith(
+ 'cart_1',
+ 'gc_abc123',
+ { spreeToken: 'order_token', token: 'jwt_token' }
+ );
+ expect(revalidateTag).toHaveBeenCalledWith('checkout');
+ expect(revalidateTag).toHaveBeenCalledWith('cart');
+ });
+ });
+
describe('complete', () => {
it('completes checkout and revalidates', async () => {
const mockOrder = { id: 'cart_1', state: 'complete' };
diff --git a/packages/sdk/.changeset/gift-card-discount-code-endpoints.md b/packages/sdk/.changeset/gift-card-discount-code-endpoints.md
new file mode 100644
index 0000000000..5a2124b4af
--- /dev/null
+++ b/packages/sdk/.changeset/gift-card-discount-code-endpoints.md
@@ -0,0 +1,12 @@
+---
+"@spree/sdk": minor
+---
+
+Split discount codes and gift cards into separate cart endpoints. Rename `couponCodes` to `discountCodes` and add dedicated `giftCards` resource.
+
+- `client.carts.discountCodes.apply(cartId, code)` — apply promotion discount code (was `couponCodes.apply`)
+- `client.carts.discountCodes.remove(cartId, code)` — remove discount code (was `couponCodes.remove`)
+- `client.carts.giftCards.apply(cartId, code)` — apply gift card (new)
+- `client.carts.giftCards.remove(cartId, giftCardId)` — remove gift card by prefixed ID (new)
+
+Cart and Order types now include `amount_due` and `display_amount_due` — the amount the customer still owes after store credits/gift cards are applied.
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index 93f0b0e5cf..2e0f6e1fc9 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -407,27 +407,28 @@ export class StoreClient {
},
/**
- * Nested resource: Coupon codes
+ * Nested resource: Discount codes
*/
- couponCodes: {
+ discountCodes: {
/**
- * Apply a coupon code to the cart
+ * Apply a discount code to the cart
* @param cartId - Cart prefixed ID
+ * @param code - Promotion discount code to apply (e.g., 'SAVE10')
*/
apply: (
cartId: string,
code: string,
options?: RequestOptions
): Promise<Cart> =>
- this.request<Cart>('POST', `/carts/${cartId}/coupon_codes`, {
+ this.request<Cart>('POST', `/carts/${cartId}/discount_codes`, {
...options,
body: { code },
}),
/**
- * Remove a coupon code from the cart
+ * Remove a discount code from the cart
* @param cartId - Cart prefixed ID
- * @param code - The coupon code string to remove (e.g., 'SAVE10')
+ * @param code - The discount code string to remove (e.g., 'SAVE10')
*/
remove: (
cartId: string,
@@ -436,7 +437,45 @@ export class StoreClient {
): Promise<Cart> =>
this.request<Cart>(
'DELETE',
- `/carts/${cartId}/coupon_codes/${code}`,
+ `/carts/${cartId}/discount_codes/${code}`,
+ options
+ ),
+ },
+
+ /**
+ * Nested resource: Gift cards
+ */
+ giftCards: {
+ /**
+ * Apply a gift card to the cart.
+ * Gift cards are treated as a payment method — the cart total remains unchanged
+ * while `amount_due` is reduced.
+ * @param cartId - Cart prefixed ID
+ * @param code - Gift card code to apply
+ */
+ apply: (
+ cartId: string,
+ code: string,
+ options?: RequestOptions
+ ): Promise<Cart> =>
+ this.request<Cart>('POST', `/carts/${cartId}/gift_cards`, {
+ ...options,
+ body: { code },
+ }),
+
+ /**
+ * Remove the applied gift card from the cart
+ * @param cartId - Cart prefixed ID
+ * @param giftCardId - Gift card prefixed ID (e.g., 'gc_abc123')
+ */
+ remove: (
+ cartId: string,
+ giftCardId: string,
+ options?: RequestOptions
+ ): Promise<Cart> =>
+ this.request<Cart>(
+ 'DELETE',
+ `/carts/${cartId}/gift_cards/${giftCardId}`,
options
),
},
diff --git a/packages/sdk/src/types/generated/Cart.ts b/packages/sdk/src/types/generated/Cart.ts
index af5c00d653..b34e5dc7a7 100644
--- a/packages/sdk/src/types/generated/Cart.ts
+++ b/packages/sdk/src/types/generated/Cart.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 74ce38d1c39231cbe9767dd3b5caeed6
+// Typelizer digest 9357c6093adf24fde9493c823cdaa56f
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Discount, LineItem, Fulfillment, Payment, Address, PaymentMethod, GiftCard} from '@/types'
@@ -26,14 +26,16 @@ interface Cart {
display_additional_tax_total: string;
total: string;
display_total: string;
+ gift_card_total: string;
+ display_gift_card_total: string;
+ amount_due: string;
+ display_amount_due: string;
delivery_total: string;
display_delivery_total: string;
created_at: string;
updated_at: string;
store_credit_total: string;
display_store_credit_total: string;
- gift_card_total: string;
- display_gift_card_total: string;
covered_by_store_credit: boolean;
current_step: string;
completed_steps: Array<string>;
diff --git a/packages/sdk/src/types/generated/Order.ts b/packages/sdk/src/types/generated/Order.ts
index 8bca44fc54..b5f0344773 100644
--- a/packages/sdk/src/types/generated/Order.ts
+++ b/packages/sdk/src/types/generated/Order.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 74b33a5de110af2129d54f1454d86b5f
+// Typelizer digest cdb62488679fefc757563ce1037170f3
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Discount, LineItem, Fulfillment, Payment, Address, GiftCard} from '@/types'
@@ -25,6 +25,10 @@ interface Order {
display_additional_tax_total: string;
total: string;
display_total: string;
+ gift_card_total: string;
+ display_gift_card_total: string;
+ amount_due: string;
+ display_amount_due: string;
delivery_total: string;
display_delivery_total: string;
fulfillment_status: string | null;
@@ -34,8 +38,6 @@ interface Order {
updated_at: string;
store_credit_total: string;
display_store_credit_total: string;
- gift_card_total: string;
- display_gift_card_total: string;
covered_by_store_credit: boolean;
discounts: Array<Discount>;
items: Array<LineItem>;
diff --git a/packages/sdk/src/zod/generated/Cart.ts b/packages/sdk/src/zod/generated/Cart.ts
index 2cc9611284..bd95c675ba 100644
--- a/packages/sdk/src/zod/generated/Cart.ts
+++ b/packages/sdk/src/zod/generated/Cart.ts
@@ -31,14 +31,16 @@ export const CartSchema = z.object({
display_additional_tax_total: z.string(),
total: z.string(),
display_total: z.string(),
+ gift_card_total: z.string(),
+ display_gift_card_total: z.string(),
+ amount_due: z.string(),
+ display_amount_due: z.string(),
delivery_total: z.string(),
display_delivery_total: z.string(),
created_at: z.string(),
updated_at: z.string(),
store_credit_total: z.string(),
display_store_credit_total: z.string(),
- gift_card_total: z.string(),
- display_gift_card_total: z.string(),
covered_by_store_credit: z.boolean(),
current_step: z.string(),
completed_steps: z.array(z.string()),
diff --git a/packages/sdk/src/zod/generated/Order.ts b/packages/sdk/src/zod/generated/Order.ts
index ca16562bbe..ff12f14315 100644
--- a/packages/sdk/src/zod/generated/Order.ts
+++ b/packages/sdk/src/zod/generated/Order.ts
@@ -29,6 +29,10 @@ export const OrderSchema = z.object({
display_additional_tax_total: z.string(),
total: z.string(),
display_total: z.string(),
+ gift_card_total: z.string(),
+ display_gift_card_total: z.string(),
+ amount_due: z.string(),
+ display_amount_due: z.string(),
delivery_total: z.string(),
display_delivery_total: z.string(),
fulfillment_status: z.string().nullable(),
@@ -38,8 +42,6 @@ export const OrderSchema = z.object({
updated_at: z.string(),
store_credit_total: z.string(),
display_store_credit_total: z.string(),
- gift_card_total: z.string(),
- display_gift_card_total: z.string(),
covered_by_store_credit: z.boolean(),
discounts: z.array(DiscountSchema),
items: z.array(LineItemSchema),
diff --git a/packages/sdk/tests/cart.test.ts b/packages/sdk/tests/cart.test.ts
index e5e6d3ae81..6972b0a10a 100644
--- a/packages/sdk/tests/cart.test.ts
+++ b/packages/sdk/tests/cart.test.ts
@@ -100,14 +100,26 @@ describe('carts', () => {
});
});
- describe('couponCodes', () => {
- it('applies a coupon code', async () => {
- const result = await client.carts.couponCodes.apply('cart_1', 'SAVE10', opts);
+ describe('discountCodes', () => {
+ it('applies a discount code', async () => {
+ const result = await client.carts.discountCodes.apply('cart_1', 'SAVE10', opts);
expect(result.id).toBe('cart_1');
});
- it('removes a coupon code by code string', async () => {
- const result = await client.carts.couponCodes.remove('cart_1', 'SAVE10', opts);
+ it('removes a discount code by code string', async () => {
+ const result = await client.carts.discountCodes.remove('cart_1', 'SAVE10', opts);
+ expect(result.id).toBe('cart_1');
+ });
+ });
+
+ describe('giftCards', () => {
+ it('applies a gift card', async () => {
+ const result = await client.carts.giftCards.apply('cart_1', 'GC-ABCD-1234', opts);
+ expect(result.id).toBe('cart_1');
+ });
+
+ it('removes a gift card by prefixed ID', async () => {
+ const result = await client.carts.giftCards.remove('cart_1', 'gc_abc123', opts);
expect(result.id).toBe('cart_1');
});
});
diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.ts
index 53fb86fe1f..9b2a308c37 100644
--- a/packages/sdk/tests/mocks/handlers.ts
+++ b/packages/sdk/tests/mocks/handlers.ts
@@ -242,12 +242,21 @@ export const handlers = [
HttpResponse.json(fixtures.cart)
),
- // Carts > Coupon Codes
- http.post(`${API_PREFIX}/carts/:cartId/coupon_codes`, () =>
+ // Carts > Discount Codes
+ http.post(`${API_PREFIX}/carts/:cartId/discount_codes`, () =>
HttpResponse.json(fixtures.cart)
),
- http.delete(`${API_PREFIX}/carts/:cartId/coupon_codes/:code`, () =>
+ http.delete(`${API_PREFIX}/carts/:cartId/discount_codes/:code`, () =>
+ HttpResponse.json(fixtures.cart)
+ ),
+
+ // Carts > Gift Cards
+ http.post(`${API_PREFIX}/carts/:cartId/gift_cards`, () =>
+ HttpResponse.json(fixtures.cart)
+ ),
+
+ http.delete(`${API_PREFIX}/carts/:cartId/gift_cards/:id`, () =>
HttpResponse.json(fixtures.cart)
),
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb b/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb
index 1b364d0c84..fc4c6044df 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb
@@ -48,6 +48,11 @@ module Spree
payment_processing_error: 'payment_processing_error',
gateway_error: 'gateway_error',
+ # Gift card errors
+ gift_card_not_found: 'gift_card_not_found',
+ gift_card_expired: 'gift_card_expired',
+ gift_card_already_redeemed: 'gift_card_already_redeemed',
+
# Digital download errors
attachment_missing: 'attachment_missing',
download_unauthorized: 'download_unauthorized',
diff --git a/spree/api/app/controllers/spree/api/v3/store/carts/coupon_codes_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/discount_codes_controller.rb
similarity index 75%
rename from spree/api/app/controllers/spree/api/v3/store/carts/coupon_codes_controller.rb
rename to spree/api/app/controllers/spree/api/v3/store/carts/discount_codes_controller.rb
index f25b85daae..cc197040d0 100644
--- a/spree/api/app/controllers/spree/api/v3/store/carts/coupon_codes_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/carts/discount_codes_controller.rb
@@ -3,14 +3,14 @@ module Spree
module V3
module Store
module Carts
- class CouponCodesController < Store::BaseController
+ class DiscountCodesController < Store::BaseController
include Spree::Api::V3::CartResolvable
include Spree::Api::V3::OrderLock
before_action :find_cart!
- # POST /api/v3/store/carts/:cart_id/coupon_codes
- # Apply a coupon code to the cart
+ # POST /api/v3/store/carts/:cart_id/discount_codes
+ # Apply a discount code to the cart
def create
with_order_lock do
@cart.coupon_code = permitted_params[:code]
@@ -25,9 +25,9 @@ module Spree
end
end
- # DELETE /api/v3/store/carts/:cart_id/coupon_codes/:id
- # Remove a coupon code from the cart
- # :id is the coupon code string (e.g., SAVE10)
+ # DELETE /api/v3/store/carts/:cart_id/discount_codes/:id
+ # Remove a discount code from the cart
+ # :id is the discount code string (e.g., SAVE10)
def destroy
with_order_lock do
coupon_handler.remove(params[:id])
@@ -43,7 +43,7 @@ module Spree
private
def coupon_handler
- @coupon_handler ||= Spree.coupon_handler.new(@cart)
+ @coupon_handler ||= Spree.coupon_handler.new(@cart, enable_gift_cards: false)
end
def permitted_params
diff --git a/spree/api/app/controllers/spree/api/v3/store/carts/gift_cards_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/gift_cards_controller.rb
new file mode 100644
index 0000000000..673d1a1fc6
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/carts/gift_cards_controller.rb
@@ -0,0 +1,72 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Carts
+ class GiftCardsController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
+ include Spree::Api::V3::OrderLock
+
+ before_action :find_cart!
+
+ # POST /api/v3/store/carts/:cart_id/gift_cards
+ def create
+ with_order_lock do
+ gift_card = find_gift_card!
+ return unless gift_card
+
+ result = @cart.apply_gift_card(gift_card)
+
+ if result.success?
+ render_cart(status: :created)
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ # DELETE /api/v3/store/carts/:cart_id/gift_cards/:id
+ def destroy
+ with_order_lock do
+ result = @cart.remove_gift_card
+
+ if result.success?
+ render_cart
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ private
+
+ def find_gift_card!
+ gift_card = @cart.store.gift_cards.find_by(code: permitted_params[:code]&.downcase)
+
+ if gift_card.nil?
+ render_error(code: ERROR_CODES[:gift_card_not_found], message: Spree.t(:gift_card_not_found), status: :not_found)
+ return
+ end
+
+ if gift_card.expired?
+ render_error(code: ERROR_CODES[:gift_card_expired], message: Spree.t(:gift_card_expired), status: :unprocessable_content)
+ return
+ end
+
+ if gift_card.redeemed?
+ render_error(code: ERROR_CODES[:gift_card_already_redeemed], message: Spree.t(:gift_card_already_redeemed), status: :unprocessable_content)
+ return
+ end
+
+ gift_card
+ end
+
+ def permitted_params
+ params.permit(:code)
+ end
+ end
+ end
+ end
+ end
+ 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 6b4414d5b0..4a0efa425a 100644
--- a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
@@ -18,6 +18,7 @@ module Spree
gift_card_total: :string, display_gift_card_total: :string,
covered_by_store_credit: :boolean,
total: :string, display_total: :string,
+ amount_due: :string, display_amount_due: :string,
shipping_eq_billing_address: :boolean,
billing_address: { nullable: true }, shipping_address: { nullable: true },
gift_card: { nullable: true }
@@ -34,6 +35,8 @@ module Spree
: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,
created_at: :iso8601, updated_at: :iso8601
@@ -45,8 +48,6 @@ module Spree
order.display_total_applied_store_credit.to_s
end
- attributes :gift_card_total, :display_gift_card_total
-
attribute :covered_by_store_credit do |order|
order.covered_by_store_credit?
end
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 00bdae063d..0b5c73f3da 100644
--- a/spree/api/app/serializers/spree/api/v3/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/order_serializer.rb
@@ -17,7 +17,9 @@ module Spree
store_credit_total: :string, display_store_credit_total: :string,
gift_card_total: :string, display_gift_card_total: :string,
covered_by_store_credit: :boolean,
- total: :string, display_total: :string, completed_at: [:string, nullable: true],
+ total: :string, display_total: :string,
+ amount_due: :string, display_amount_due: :string,
+ completed_at: [:string, nullable: true],
billing_address: { nullable: true }, shipping_address: { nullable: true },
gift_card: { nullable: true }
@@ -28,6 +30,8 @@ module Spree
: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, :fulfillment_status, :payment_status,
completed_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
@@ -39,8 +43,6 @@ module Spree
order.display_total_applied_store_credit.to_s
end
- attributes :gift_card_total, :display_gift_card_total
-
attribute :covered_by_store_credit do |order|
order.covered_by_store_credit?
end
diff --git a/spree/api/config/locales/en.yml b/spree/api/config/locales/en.yml
index 2a3cff6d0f..348a2e7b99 100644
--- a/spree/api/config/locales/en.yml
+++ b/spree/api/config/locales/en.yml
@@ -2,24 +2,24 @@
en:
spree:
api:
+ current_password_invalid: Current password is invalid or missing
gateway_error: 'There was a problem with the payment gateway: %{text}'
invalid_api_key: Invalid API key (%{key}) specified.
invalid_resource: Invalid resource. Please fix errors and try again.
invalid_taxonomy_id: Invalid taxonomy id.
- current_password_invalid: Current password is invalid or missing
- password_reset_requested: If an account exists for that email, password reset instructions have been sent.
- password_reset_token_invalid: Password reset token is invalid or has expired.
- redirect_url_not_allowed: The redirect URL is not from an allowed origin for this store.
must_specify_api_key: You must specify an API key.
negative_quantity: quantity is negative
order:
could_not_transition: The order could not be transitioned. Please fix the errors and try again.
insufficient_quantity: An item in your cart has become unavailable.
invalid_shipping_method: Invalid shipping method specified.
+ password_reset_requested: If an account exists for that email, password reset instructions have been sent.
+ password_reset_token_invalid: Password reset token is invalid or has expired.
payment:
credit_over_limit: This payment can only be credited up to %{limit}. Please specify an amount less than or equal to this number.
update_forbidden: This payment cannot be updated because it is %{state}.
- record_not_found: '%{model} not found'
+ record_not_found: "%{model} not found"
+ redirect_url_not_allowed: The redirect URL is not from an allowed origin for this store.
resource_not_found: The resource you were looking for could not be found.
shipment:
cannot_ready: Cannot ready shipment.
@@ -27,10 +27,6 @@ en:
shipment_transfer_success: Variants successfully transferred
stock_location_required: A stock_location_id parameter must be provided in order to retrieve stock movements.
unauthorized: You are not authorized to perform that action.
- v3:
- payments:
- session_required: This payment method requires a payment session. Use the payment sessions endpoint instead.
- method_unavailable: This payment method is not available for this order.
v2:
cart:
no_coupon_code: No coupon code provided and the Order doesn't have any coupon code promotions applied
@@ -47,4 +43,8 @@ en:
errors:
the_wishlist_could_not_be_destroyed: The wishlist could not be destroyed.
wrong_quantity: Quantity has to be greater than 0
+ v3:
+ payments:
+ method_unavailable: This payment method is not available for this order.
+ session_required: This payment method requires a payment session. Use the payment sessions endpoint instead.
wrong_shipment_target: target shipment is the same as original shipment
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 2a4a0c66d2..0d4dec5f38 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -38,7 +38,8 @@ Spree::Core::Engine.add_routes do
post :complete
end
resources :items, only: [:create, :update, :destroy], controller: 'carts/items'
- resources :coupon_codes, only: [:create, :destroy], controller: 'carts/coupon_codes'
+ resources :discount_codes, only: [:create, :destroy], controller: 'carts/discount_codes'
+ resources :gift_cards, only: [:create, :destroy], controller: 'carts/gift_cards'
resources :fulfillments, only: [:update], controller: 'carts/fulfillments'
resources :payments, only: [:create], controller: 'carts/payments'
resources :payment_sessions, only: [:create, :show, :update], controller: 'carts/payment_sessions' do
diff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/coupon_codes_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/discount_codes_controller_spec.rb
similarity index 78%
rename from spree/api/spec/controllers/spree/api/v3/store/carts/coupon_codes_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/store/carts/discount_codes_controller_spec.rb
index cfecdfc652..f899053dd0 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/carts/coupon_codes_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/discount_codes_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::Carts::DiscountCodesController, type: :controller do
render_views
include_context 'API v3 Store'
@@ -16,7 +16,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :contr
context 'with a standard promotion (single code)' do
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'SAVE10', stores: [store]) }
- it 'applies the coupon code successfully' do
+ it 'applies the discount code successfully' do
post :create, params: { cart_id: order.prefixed_id, code: 'SAVE10' }
expect(response).to have_http_status(:created)
@@ -29,14 +29,14 @@ RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :contr
expect(response).to have_http_status(:created)
end
- it 'returns error for invalid coupon code' do
+ it 'returns error for invalid discount code' do
post :create, params: { cart_id: order.prefixed_id, code: 'INVALID' }
expect(response).to have_http_status(:unprocessable_content)
expect(json_response['error']).to be_present
end
- it 'returns error when coupon is already applied' do
+ it 'returns error when discount is already applied' do
order.coupon_code = 'SAVE10'
Spree::PromotionHandler::Coupon.new(order).apply
@@ -52,7 +52,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :contr
end
let!(:coupon_code) { create(:coupon_code, promotion: promotion, code: 'multi1') }
- it 'applies the multi-code coupon successfully' do
+ it 'applies the multi-code discount successfully' do
post :create, params: { cart_id: order.prefixed_id, code: 'multi1' }
expect(response).to have_http_status(:created)
@@ -66,27 +66,10 @@ RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :contr
end
end
- context 'with a gift card' do
+ context 'with a gift card code' do
let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'giftcard123') }
- it 'applies the gift card successfully' do
- post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
-
- expect(response).to have_http_status(:created)
- expect(json_response['id']).to start_with('cart_')
- end
-
- it 'returns error for expired gift card' do
- gift_card.update!(expires_at: 1.day.ago)
-
- post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
-
- expect(response).to have_http_status(:unprocessable_content)
- end
-
- it 'returns error for redeemed gift card' do
- gift_card.update!(state: :redeemed, redeemed_at: Time.current, amount_used: gift_card.amount)
-
+ it 'does not apply gift cards (gift cards use dedicated endpoint)' do
post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
expect(response).to have_http_status(:unprocessable_content)
@@ -132,7 +115,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :contr
Spree::PromotionHandler::Coupon.new(order).apply
end
- it 'removes the coupon code successfully' do
+ it 'removes the discount code successfully' do
delete :destroy, params: { cart_id: order.prefixed_id, id: 'REMOVE10' }
expect(response).to have_http_status(:ok)
@@ -140,7 +123,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::CouponCodesController, type: :contr
end
end
- context 'with non-existent coupon code' do
+ context 'with non-existent discount code' do
it 'returns error' do
delete :destroy, params: { cart_id: order.prefixed_id, id: 'NONEXISTENT' }
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
new file mode 100644
index 0000000000..e4f5c1f590
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
@@ -0,0 +1,96 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Store::Carts::GiftCardsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Store'
+
+ let!(:order) { create(:order_with_line_items, store: store, user: user) }
+
+ before do
+ request.headers['X-Spree-Api-Key'] = api_key.token
+ request.headers['Authorization'] = "Bearer #{jwt_token}"
+ end
+
+ describe 'POST #create' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'giftcard123') }
+
+ it 'applies the gift card successfully' do
+ post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['id']).to start_with('cart_')
+ expect(json_response['gift_card_total']).to be_present
+ expect(json_response['amount_due']).to be_present
+ end
+
+ it 'is case insensitive' do
+ post :create, params: { cart_id: order.prefixed_id, code: 'GIFTCARD123' }
+
+ expect(response).to have_http_status(:created)
+ end
+
+ it 'returns error for non-existent gift card' do
+ post :create, params: { cart_id: order.prefixed_id, code: 'NONEXISTENT' }
+
+ expect(response).to have_http_status(:not_found)
+ expect(json_response['error']).to be_present
+ end
+
+ it 'returns error for expired gift card' do
+ gift_card.update!(expires_at: 1.day.ago)
+
+ post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+
+ it 'returns error for redeemed gift card' do
+ gift_card.update!(state: :redeemed, redeemed_at: Time.current, amount_used: gift_card.amount)
+
+ post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+
+ context 'with guest spree token' do
+ let(:guest_order) { create(:order_with_line_items, store: store, user: nil) }
+
+ before do
+ request.headers['Authorization'] = nil
+ request.headers['x-spree-token'] = guest_order.token
+ end
+
+ it 'allows access via spree token' do
+ post :create, params: { cart_id: guest_order.prefixed_id, code: 'giftcard123' }
+
+ expect(response).to have_http_status(:created)
+ end
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'giftcard123') }
+
+ context 'with an applied gift card' do
+ before do
+ order.apply_gift_card(gift_card)
+ end
+
+ it 'removes the gift card successfully' do
+ delete :destroy, params: { cart_id: order.prefixed_id, id: gift_card.prefixed_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(order.reload.gift_card).to be_nil
+ end
+ end
+
+ context 'without an applied gift card' do
+ it 'returns success (no-op)' do
+ delete :destroy, params: { cart_id: order.prefixed_id, id: gift_card.prefixed_id }
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb b/spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb
similarity index 71%
rename from spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb
rename to spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb
index 5f533ebe80..1470271c05 100644
--- a/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/discount_codes_spec.rb
@@ -2,25 +2,26 @@
require 'swagger_helper'
-RSpec.describe 'Cart Coupon Codes API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Cart Discount Codes API', type: :request, swagger_doc: 'api-reference/store.yaml' do
include_context 'API v3 Store'
let!(:order) { create(:order_with_line_items, store: store, user: user) }
let(:cart_id) { order.prefixed_id }
- path '/api/v3/store/carts/{cart_id}/coupon_codes' do
- post 'Apply coupon code' do
+ path '/api/v3/store/carts/{cart_id}/discount_codes' do
+ post 'Apply discount code' do
tags 'Carts'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
description <<~DESC
- Applies a coupon code to the cart. Supports both promotion coupon codes and gift card codes.
- The code is matched case-insensitively.
+ Applies a promotion discount code to the cart. The code is matched case-insensitively.
+
+ For gift cards, use the dedicated `POST /carts/{cart_id}/gift_cards` endpoint instead.
DESC
sdk_example <<~JS
- const cart = await client.carts.couponCodes.apply('cart_abc123', 'SAVE10', {
+ const cart = await client.carts.discountCodes.apply('cart_abc123', 'SAVE10', {
bearerToken: '<token>',
})
JS
@@ -36,12 +37,12 @@ RSpec.describe 'Cart Coupon Codes API', type: :request, swagger_doc: 'api-refere
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
- code: { type: :string, example: 'SAVE10', description: 'Coupon code or gift card code to apply' }
+ code: { type: :string, example: 'SAVE10', description: 'Promotion discount code to apply' }
},
required: %w[code]
}
- response '201', 'coupon code applied (promotion)' do
+ response '201', 'discount code applied' do
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'SAVE10', stores: [store]) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
@@ -56,21 +57,7 @@ RSpec.describe 'Cart Coupon Codes API', type: :request, swagger_doc: 'api-refere
end
end
- response '201', 'coupon code applied (gift card)' do
- let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'giftcode1') }
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:body) { { code: 'giftcode1' } }
-
- schema '$ref' => '#/components/schemas/Cart'
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['number']).to eq(order.number)
- end
- end
-
- response '422', 'invalid coupon code' do
+ response '422', 'invalid discount code' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
let(:body) { { code: 'NONEXISTENT' } }
@@ -85,15 +72,15 @@ RSpec.describe 'Cart Coupon Codes API', type: :request, swagger_doc: 'api-refere
end
end
- path '/api/v3/store/carts/{cart_id}/coupon_codes/{id}' do
- delete 'Remove coupon code' do
+ path '/api/v3/store/carts/{cart_id}/discount_codes/{id}' do
+ delete 'Remove discount code' do
tags 'Carts'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Removes a previously applied coupon code from the cart. The ID is the coupon code string itself.'
+ description 'Removes a previously applied discount code from the cart. The ID is the discount code string itself.'
sdk_example <<~JS
- const cart = await client.carts.couponCodes.remove('cart_abc123', 'SAVE10', {
+ const cart = await client.carts.discountCodes.remove('cart_abc123', 'SAVE10', {
bearerToken: '<token>',
})
JS
@@ -103,11 +90,11 @@ RSpec.describe 'Cart Coupon Codes API', type: :request, swagger_doc: 'api-refere
description: 'Bearer token for authenticated customers'
parameter name: :cart_id, in: :path, type: :string, required: true, description: 'Cart prefixed ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'The coupon code string to remove (e.g., SAVE10)'
+ description: 'The discount code string to remove (e.g., SAVE10)'
parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
- response '200', 'coupon code removed' do
+ response '200', 'discount code removed' do
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'REMOVE10', stores: [store]) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
@@ -126,7 +113,7 @@ RSpec.describe 'Cart Coupon Codes API', type: :request, swagger_doc: 'api-refere
end
end
- response '422', 'coupon code not found on cart' do
+ response '422', 'discount code not found on cart' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
let(:id) { 'NONEXISTENT' }
diff --git a/spree/api/spec/integration/spree/api/v3/store/gift_card_cart_spec.rb b/spree/api/spec/integration/spree/api/v3/store/gift_card_cart_spec.rb
new file mode 100644
index 0000000000..a3716e4473
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/store/gift_card_cart_spec.rb
@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Cart Gift Card API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:order) { create(:order_with_line_items, store: store, user: user) }
+ let(:cart_id) { order.prefixed_id }
+
+ path '/api/v3/store/carts/{cart_id}/gift_cards' do
+ post 'Apply gift card' do
+ tags 'Carts'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount —
+ the cart `total` remains unchanged while `amount_due` is reduced.
+
+ For promotion discount codes, use the `POST /carts/{cart_id}/discount_codes` endpoint instead.
+ DESC
+
+ sdk_example <<~JS
+ const cart = await client.carts.giftCards.apply('cart_abc123', 'GC-ABCD-1234', {
+ bearerToken: '<token>',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer token for authenticated customers'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
+ description: 'Order token for guest access'
+ parameter name: :cart_id, in: :path, type: :string, required: true, description: 'Cart prefixed ID (e.g., cart_abc123)'
+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
+ description: 'Unique key for request idempotency.'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ code: { type: :string, example: 'GC-ABCD-1234', description: 'Gift card code to apply' }
+ },
+ required: %w[code]
+ }
+
+ response '201', 'gift card applied' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'giftcode1') }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { code: 'giftcode1' } }
+
+ schema '$ref' => '#/components/schemas/Cart'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
+ expect(data['gift_card_total']).to be_present
+ expect(data['amount_due']).to be_present
+ end
+ end
+
+ response '404', 'gift card not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { code: 'NONEXISTENT' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data.dig('error', 'code')).to eq('gift_card_not_found')
+ end
+ end
+
+ response '422', 'gift card expired' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'expiredgc', expires_at: 1.day.ago) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { code: 'expiredgc' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data.dig('error', 'code')).to eq('gift_card_expired')
+ end
+ end
+
+ response '422', 'gift card already redeemed' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'redeemedgc', amount_used: 50, state: :redeemed, redeemed_at: Time.current) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { code: 'redeemedgc' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data.dig('error', 'code')).to eq('gift_card_already_redeemed')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/store/carts/{cart_id}/gift_cards/{id}' do
+ delete 'Remove gift card' do
+ tags 'Carts'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Removes a previously applied gift card from the cart.'
+
+ sdk_example <<~JS
+ const cart = await client.carts.giftCards.remove('cart_abc123', 'gc_abc123', {
+ bearerToken: '<token>',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer token for authenticated customers'
+ parameter name: :cart_id, in: :path, type: :string, required: true, description: 'Cart prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Gift card prefixed ID (e.g., gc_abc123)'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
+ description: 'Order token for guest access'
+
+ response '200', 'gift card removed' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'removegc') }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) do
+ order.apply_gift_card(gift_card)
+ gift_card.prefixed_id
+ end
+
+ schema '$ref' => '#/components/schemas/Cart'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index e57005f6e7..6371335aef 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -49,10 +49,11 @@ module Spree
:included_tax_total, :additional_tax_total, :tax_total,
:shipment_total, :promo_total, :total,
:cart_promo_total, :pre_tax_item_amount, :pre_tax_total,
- :payment_total
+ :payment_total, :amount_due
alias display_ship_total display_shipment_total
alias_attribute :ship_total, :shipment_total
+ alias amount_due total_minus_store_credits
# 5.5 API naming bridges (DB columns rename in 6.0)
alias_attribute :discount_total, :promo_total
diff --git a/spree/core/app/models/spree/promotion_handler/coupon.rb b/spree/core/app/models/spree/promotion_handler/coupon.rb
index d392847e34..c8887d94f1 100644
--- a/spree/core/app/models/spree/promotion_handler/coupon.rb
+++ b/spree/core/app/models/spree/promotion_handler/coupon.rb
@@ -11,7 +11,7 @@ module Spree
end
def apply
- if load_gift_card_code
+ if gift_cards_enabled? && load_gift_card_code
if @gift_card.expired?
set_error_code :gift_card_expired
@@ -47,7 +47,7 @@ module Spree
end
def remove(coupon_code)
- if order.gift_card
+ if gift_cards_enabled? && order.gift_card
result = order.remove_gift_card
if result.success?
@@ -212,6 +212,13 @@ module Spree
Spree::CouponCode.unused.find_by(promotion_id: discount.source.promotion_id, code: coupon_code)&.apply_order!(order)
end
+ # Whether the coupon handler should also handle gift card codes.
+ # Defaults to true for backwards compatibility. Pass enable_gift_cards: false
+ # when using the dedicated gift card endpoint.
+ def gift_cards_enabled?
+ options.fetch(:enable_gift_cards, true)
+ end
+
def load_gift_card_code
return unless order.coupon_code.present?
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index faf0c38362..d99c5ab712 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -1222,6 +1222,7 @@ en:
gift_card_expired: The Gift Card has expired.
gift_card_mismatched_currency: Gift Card cannot be applied with current currency.
gift_card_mismatched_customer: This gift card is associated with another user.
+ gift_card_not_found: The Gift Card was not found.
gift_card_removed: The Gift Card was successfully removed from your order
gift_card_using_store_credit_error: You can't apply the Gift Card after you applied the store credit.
gift_cards: Gift Cards
diff --git a/spree/core/spec/models/spree/promotion_handler/coupon_with_gift_card_spec.rb b/spree/core/spec/models/spree/promotion_handler/coupon_with_gift_card_spec.rb
index 11475a05b6..cdaed25970 100644
--- a/spree/core/spec/models/spree/promotion_handler/coupon_with_gift_card_spec.rb
+++ b/spree/core/spec/models/spree/promotion_handler/coupon_with_gift_card_spec.rb
@@ -93,4 +93,81 @@ describe Spree::PromotionHandler::Coupon, type: :model do
end
end
end
+
+ describe 'enable_gift_cards option' do
+ let(:store) { Spree::Store.default }
+ let(:order) { create(:order_with_line_items, store: store) }
+ let(:gift_card) { create(:gift_card, store: store, amount: 10) }
+
+ before do
+ order.update_column(:total, 30)
+ end
+
+ describe '#apply' do
+ context 'when enable_gift_cards: false' do
+ it 'does not apply gift card and falls through to coupon code lookup' do
+ order.coupon_code = gift_card.code
+ handler = described_class.new(order, enable_gift_cards: false)
+ handler.apply
+
+ expect(order.reload.gift_card).to be_nil
+ expect(handler.status_code).to eq(:coupon_code_not_found)
+ end
+ end
+
+ context 'when enable_gift_cards: true (explicit)' do
+ it 'applies gift card' do
+ order.coupon_code = gift_card.code
+ handler = described_class.new(order, enable_gift_cards: true)
+ handler.apply
+
+ expect(order.reload.gift_card).to eq(gift_card)
+ end
+ end
+
+ context 'when enable_gift_cards is not specified (default)' do
+ it 'applies gift card for backwards compatibility' do
+ order.coupon_code = gift_card.code
+ handler = described_class.new(order)
+ handler.apply
+
+ expect(order.reload.gift_card).to eq(gift_card)
+ end
+ end
+ end
+
+ describe '#remove' do
+ before do
+ order.apply_gift_card(gift_card)
+ end
+
+ context 'when enable_gift_cards: false' do
+ it 'does not remove gift card and falls through to coupon code lookup' do
+ handler = described_class.new(order, enable_gift_cards: false)
+ handler.remove(gift_card.code)
+
+ expect(order.reload.gift_card).to eq(gift_card)
+ expect(handler.status_code).to eq(:coupon_code_not_found)
+ end
+ end
+
+ context 'when enable_gift_cards: true (explicit)' do
+ it 'removes gift card' do
+ handler = described_class.new(order, enable_gift_cards: true)
+ handler.remove(gift_card.code)
+
+ expect(order.reload.gift_card).to be_nil
+ end
+ end
+
+ context 'when enable_gift_cards is not specified (default)' do
+ it 'removes gift card for backwards compatibility' do
+ handler = described_class.new(order)
+ handler.remove(gift_card.code)
+
+ expect(order.reload.gift_card).to be_nil
+ end
+ end
+ end
+ end
end