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.

Split Orders to Cart, Checkout, Orders in Store API

Damian Legawiec48186d38f966
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index d09fa88f26..a85cc08d48 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -20,7 +20,7 @@ info:
After login, include the JWT token in the `Authorization: Bearer <token>` header.
### Order Token (For guest checkout)
- When creating an order, a `token` is returned. Include this in the `x-spree-order-token` header
+ When creating an order, a `token` is returned. Include this in the `x-spree-token` header
for guest access to that specific order.
## Response Format
@@ -661,16 +661,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjRjZjZiNzkxLTZiY2MtNDUyMi05YTNhLWQ0ZmMyNzNmNmEwMSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjQzOTM2fQ.Zi2gcBzDMpqNSeJIoLphDWxYI0C8SQYXihILkuHnFkU
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImNkN2QyY2FhLTkyOWQtNDkzYS05NTQ0LTgwZDMyYTc0YmRjZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjYzNzY5fQ.ziT9ugb9kC8vLE8q41j5UM9vJb_dMea0feoumRqgBgA
user:
id: cus_UkLWZg9DAJ
- first_name: Elizebeth
- last_name: Herman
+ first_name: Mallory
+ last_name: Schmitt
phone:
accepts_email_marketing: false
- created_at: '2026-03-11T14:45:36.632Z'
- updated_at: '2026-03-11T14:45:36.632Z'
+ created_at: '2026-03-11T20:16:08.948Z'
+ updated_at: '2026-03-11T20:16:08.948Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -747,16 +747,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjBlZjM1Y2I0LTY2NDgtNDE5Zi04MjkzLTgxYjU1N2ExZDQwNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjQzOTM4fQ.gPHrg7pll8g-zU2xYEVR_1JyQZMxshSf7TEkvhX0QgI
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY4MTg5MjBmLTM5ODYtNDdiYy04NjE1LWUxMDBhMDFjYmMwNyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjYzNzcwfQ.QAFfl9n0ftXwpVd8NcRfD7pg39I8Eo7jibXguYer7vk
user:
id: cus_UkLWZg9DAJ
- first_name: Wilbur
- last_name: Romaguera
+ first_name: Loma
+ last_name: Hickle
phone:
accepts_email_marketing: false
- created_at: '2026-03-11T14:45:38.074Z'
- updated_at: '2026-03-11T14:45:38.074Z'
+ created_at: '2026-03-11T20:16:10.379Z'
+ updated_at: '2026-03-11T20:16:10.379Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -780,8 +780,8 @@ paths:
security:
- api_key: []
description: |
- Creates a new shopping cart (order). Can be created by guests or authenticated customers.
- Returns a `token` that must be used for guest access to the order.
+ Creates a new shopping cart. Can be created by guests or authenticated customers.
+ Returns a `token` that must be used for guest access to the cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -827,22 +827,20 @@ paths:
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R077815792
+ id: cart_UkLWZg9DAJ
+ number: R234338485
state: cart
checkout_steps:
- address
- delivery
- complete
- token: 6H3Y5-uIi04wYEUYjECsNQ1773240338859
+ token: 1WFmOSYStXOjNKWBoA9RTg1773260171159
email:
special_instructions:
currency: USD
locale: en
item_count: 0
state_lock_version: 0
- shipment_state:
- payment_state:
item_total: '0.0'
display_item_total: "$0.00"
ship_total: '0.0'
@@ -859,9 +857,8 @@ paths:
display_additional_tax_total: "$0.00"
total: '0.0'
display_total: "$0.00"
- completed_at:
- created_at: '2026-03-11T14:45:38.860Z'
- updated_at: '2026-03-11T14:45:38.860Z'
+ created_at: '2026-03-11T20:16:11.160Z'
+ updated_at: '2026-03-11T20:16:11.160Z'
order_promotions: []
line_items: []
shipments: []
@@ -870,7 +867,7 @@ paths:
ship_address:
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Cart"
'401':
description: unauthorized - invalid API key
content:
@@ -941,7 +938,7 @@ paths:
bearer_auth: []
description: |
Returns the current shopping cart (incomplete order).
- Authenticate via JWT token for logged-in users or via x-spree-order-token header for guests.
+ Authenticate via JWT token for logged-in users or via x-spree-token header for guests.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -974,7 +971,7 @@ paths:
description: Bearer JWT token for authenticated customers
schema:
type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
description: Order token for guest checkout
@@ -986,23 +983,21 @@ paths:
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R272523018
+ id: cart_UkLWZg9DAJ
+ number: R984383391
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: sGEy8hb61E75fgLCzSknZEKxk5W6Jrjw2kJ
+ token: RvY28jX4f7dPXw7cPnHeEJPE4CELLvXSpBM
special_instructions:
currency: USD
locale: en
item_count: 1
state_lock_version: 0
- shipment_state:
- payment_state:
item_total: '10.0'
display_item_total: "$10.00"
ship_total: '100.0'
@@ -1019,17 +1014,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:45:39.864Z'
- updated_at: '2026-03-11T14:45:39.923Z'
+ created_at: '2026-03-11T20:16:12.161Z'
+ updated_at: '2026-03-11T20:16:12.218Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 3148
- slug: product-3148
+ name: Product 36316
+ slug: product-36316
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1048,23 +1042,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:45:39.898Z'
- updated_at: '2026-03-11T14:45:39.898Z'
+ created_at: '2026-03-11T20:16:12.196Z'
+ updated_at: '2026-03-11T20:16:12.196Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H56116570825
+ number: H91527585123
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:45:39.905Z'
- updated_at: '2026-03-11T14:45:39.921Z'
+ created_at: '2026-03-11T20:16:12.201Z'
+ updated_at: '2026-03-11T20:16:12.215Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1072,7 +1066,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_42
- name: Perry Effertz
+ name: Idalia Predovic
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1127,7 +1121,7 @@ paths:
state_name: STATE_NAME_45
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Cart"
'404':
description: no cart found
content:
@@ -1138,6 +1132,47 @@ paths:
message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
+ delete:
+ summary: Delete current cart
+ tags:
+ - Cart
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Deletes/abandons the current shopping cart.
+ 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.cart.delete({
+ orderToken: 'ORDER_TOKEN',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ schema:
+ type: string
+ responses:
+ '204':
+ description: cart deleted
"/api/v3/store/cart/associate":
patch:
summary: Associate guest cart with authenticated user
@@ -1177,7 +1212,7 @@ paths:
description: Bearer JWT token (required)
schema:
type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: true
description: Order token for identifying the guest cart
@@ -1189,23 +1224,21 @@ paths:
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R745530903
+ id: cart_UkLWZg9DAJ
+ number: R300345614
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: M7c69YQScfTYk6xxwD7g7cXT39avBQ2i9Hk
+ token: WoRC24UvkSqpTXHRP2sX23Gs6m7hoHPNjCQ
special_instructions:
currency: USD
locale: en
item_count: 1
state_lock_version: 0
- shipment_state:
- payment_state:
item_total: '10.0'
display_item_total: "$10.00"
ship_total: '100.0'
@@ -1222,17 +1255,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:45:40.501Z'
- updated_at: '2026-03-11T14:45:40.556Z'
+ created_at: '2026-03-11T20:16:13.450Z'
+ updated_at: '2026-03-11T20:16:13.517Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 48828
- slug: product-48828
+ name: Product 51231
+ slug: product-51231
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1251,37 +1283,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:45:40.532Z'
- updated_at: '2026-03-11T14:45:40.532Z'
+ created_at: '2026-03-11T20:16:13.487Z'
+ updated_at: '2026-03-11T20:16:13.487Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H66232635703
+ number: H00139797754
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:45:40.537Z'
- updated_at: '2026-03-11T14:45:40.553Z'
+ created_at: '2026-03-11T20:16:13.493Z'
+ updated_at: '2026-03-11T20:16:13.515Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_46
- name: Nickie Considine
+ state_abbr: STATE_ABBR_50
+ name: Lai Harvey
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_46
+ state_text: STATE_ABBR_50
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -1299,7 +1331,7 @@ paths:
firstname: John
lastname: Doe
full_name: John Doe
- address1: 47 Lovely Street
+ address1: 51 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -1307,16 +1339,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_48
- state_abbr: STATE_ABBR_48
+ state_text: STATE_ABBR_52
+ state_abbr: STATE_ABBR_52
quick_checkout: false
- state_name: STATE_NAME_48
+ state_name: STATE_NAME_52
ship_address:
id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 48 Lovely Street
+ address1: 52 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -1324,13 +1356,13 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_49
- state_abbr: STATE_ABBR_49
+ state_text: STATE_ABBR_53
+ state_abbr: STATE_ABBR_53
quick_checkout: false
- state_name: STATE_NAME_49
+ state_name: STATE_NAME_53
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Cart"
'401':
description: unauthorized - JWT required
content:
@@ -1351,14 +1383,16 @@ paths:
message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/categories":
+ "/api/v3/store/carts":
get:
- summary: List categories
+ summary: List active carts
tags:
- - Product Catalog
+ - Cart
security:
- api_key: []
- description: Returns a paginated list of categories for the current store
+ bearer_auth: []
+ description: Returns all active (incomplete) carts for the authenticated user.
+ Useful for users who may have multiple carts.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1370,9 +1404,8 @@ paths:
publishableKey: '<api-key>',
})
- const categories = await client.categories.list({
- page: 1,
- limit: 25,
+ const carts = await client.carts.list({
+ bearerToken: '<token>',
})
parameters:
- name: x-spree-api-key
@@ -1380,393 +1413,320 @@ paths:
required: true
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name
- 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: categories found
- content:
- application/json:
- example:
- data:
- - id: ctg_UkLWZg9DAJ
- name: taxonomy_1
- permalink: taxonomy-1
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-11T14:45:42.864Z'
- updated_at: '2026-03-11T14:45:42.921Z'
- parent_id:
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: false
- - id: ctg_gbHJdmfrXB
- name: taxon_1
- permalink: taxonomy-1/taxon-1
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-11T14:45:42.873Z'
- updated_at: '2026-03-11T14:45:42.920Z'
- parent_id: ctg_UkLWZg9DAJ
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: false
- - id: ctg_EfhxLZ9ck8
- name: taxon_2
- permalink: taxonomy-1/taxon-1/taxon-2
- position: 0
- depth: 2
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-11T14:45:42.884Z'
- updated_at: '2026-03-11T14:45:42.890Z'
- parent_id: ctg_gbHJdmfrXB
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- meta:
- page: 1
- limit: 25
- count: 3
- pages: 1
- from: 1
- to: 3
- in: 3
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Category"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/categories/{id}":
- get:
- summary: Get a category
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a single category by permalink or prefix 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 category = await client.categories.get('categories/clothing/shirts', {
- expand: 'children',
- })
- parameters:
- - name: x-spree-api-key
+ - name: Authorization
in: header
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- description: Category permalink (e.g., clothing/shirts) or prefix ID (e.g.,
- ctg_abc123)
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Expand associations (children, parent, ancestors, metafields)
- 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: category found by prefix ID
- content:
- application/json:
- example:
- id: ctg_gbHJdmfrXB
- name: taxon_10
- permalink: taxonomy-7/taxon-10
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-11T14:45:43.305Z'
- updated_at: '2026-03-11T14:45:43.348Z'
- parent_id: ctg_UkLWZg9DAJ
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: false
- schema:
- "$ref": "#/components/schemas/Category"
- '404':
- description: category from other store not accessible
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Category not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/categories/{category_id}/products":
- get:
- summary: List products in a category
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a paginated list of products belonging to the specified
- category
- 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 products = await client.categories.products.list('categories/clothing', {
- page: 1,
- limit: 25,
- sort: 'price',
- with_option_value_ids: ['optval_abc'],
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: category_id
- in: path
- required: true
- description: Category permalink or prefix ID
- schema:
- type: string
- - name: page
- in: query
- required: false
- description: 'Page number (default: 1)'
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: 'Number of items per page (default: 25, max: 100)'
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Values: price, -price,
- best_selling, name, -name, -available_on, available_on'
- schema:
- type: string
- - name: q[price_gte]
- in: query
- required: false
- description: Filter by minimum price
- schema:
- type: number
- - name: q[price_lte]
- in: query
- required: false
- description: Filter by maximum price
- schema:
- type: number
- - name: q[with_option_value_ids][]
- in: query
- required: false
- description: Filter by option value prefix IDs
- schema:
- type: string
- - name: q[in_stock]
- in: query
- required: false
- description: Filter to only in-stock products
- schema:
- type: boolean
- - 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: products found
+ description: carts listed
content:
application/json:
example:
data:
- - id: prod_UkLWZg9DAJ
- name: Product 154952
- description: |-
- Facere fuga in provident praesentium architecto. Expedita excepturi voluptatem et corporis. Quia esse dolorem non cum doloribus. Adipisci officiis ex quibusdam recusandae doloremque aspernatur.
- Est id dignissimos dolor reiciendis modi. Quod modi laudantium ducimus deleniti consectetur quibusdam ut. Sint earum quidem nam sed ullam ratione similique ab. Labore magnam fuga eius enim.
- Itaque cum consequuntur vel placeat enim excepturi. Repellat doloremque dolore voluptatem eaque nulla. Sit maxime reiciendis explicabo sed voluptatem.
- Expedita fugit autem officia vero tenetur tempore sed quisquam. Aliquid optio nemo beatae vero natus. Explicabo repellendus eaque eligendi sit consequatur. Adipisci nobis repudiandae ipsa placeat eligendi molestias.
- Quis totam eligendi earum quos praesentium debitis. Ut adipisci aut exercitationem officia reprehenderit. Accusantium libero at nobis pariatur.
- slug: product-154952
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on: '2025-03-11T14:45:43.852Z'
- created_at: '2026-03-11T14:45:43.867Z'
- updated_at: '2026-03-11T14:45:43.889Z'
- purchasable: true
- in_stock: false
- backorderable: true
- available: true
- default_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
+ - id: cart_gbHJdmfrXB
+ number: R086891701
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: phVNSmF8sKw7t33JchC8ymQo4JN5wQjyugD
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ state_lock_version: 0
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ created_at: '2026-03-11T20:16:16.260Z'
+ updated_at: '2026-03-11T20:16:16.311Z'
+ order_promotions: []
+ line_items:
+ - id: li_gbHJdmfrXB
+ variant_id: variant_gbHJdmfrXB
+ quantity: 1
+ currency: USD
+ name: Product 108397
+ slug: product-108397
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:16.289Z'
+ updated_at: '2026-03-11T20:16:16.289Z'
compare_at_amount:
- compare_at_amount_in_cents:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_gbHJdmfrXB
+ number: H42649481070
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:16.297Z'
+ updated_at: '2026-03-11T20:16:16.309Z'
+ shipping_method:
+ id: shpm_gbHJdmfrXB
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_66
+ name: Janise Gaylord
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_66
+ shipping_rates:
+ - id: shpr_gbHJdmfrXB
+ shipping_method_id: shpm_gbHJdmfrXB
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_gbHJdmfrXB
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ bill_address:
+ id: addr_uw2YK1rnl0
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 69 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_70
+ state_abbr: STATE_ABBR_70
+ quick_checkout: false
+ state_name: STATE_NAME_70
+ ship_address:
+ id: addr_OIJLhNcSbf
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 70 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_71
+ state_abbr: STATE_ABBR_71
+ quick_checkout: false
+ state_name: STATE_NAME_71
+ payment_methods: []
+ - id: cart_UkLWZg9DAJ
+ number: R768632994
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: UgphxzbfnFWinPDepo4CheaxB4HVG8m6Ms7
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ state_lock_version: 0
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ created_at: '2026-03-11T20:16:16.196Z'
+ updated_at: '2026-03-11T20:16:16.248Z'
+ order_promotions: []
+ line_items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
+ name: Product 95834
+ slug: product-95834
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:16.226Z'
+ updated_at: '2026-03-11T20:16:16.226Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H16511579350
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:16.231Z'
+ updated_at: '2026-03-11T20:16:16.245Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_66
+ name: Janise Gaylord
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_66
+ shipping_rates:
+ - id: shpr_UkLWZg9DAJ
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ bill_address:
+ id: addr_EfhxLZ9ck8
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 67 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_68
+ state_abbr: STATE_ABBR_68
+ quick_checkout: false
+ state_name: STATE_NAME_68
+ ship_address:
+ id: addr_VqXmZF31wY
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 68 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_69
+ state_abbr: STATE_ABBR_69
+ quick_checkout: false
+ state_name: STATE_NAME_69
+ payment_methods: []
meta:
page: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '404':
- description: category not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Category not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
'401':
description: unauthorized
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/countries":
+ "/api/v3/store/categories":
get:
- summary: List countries
+ summary: List categories
tags:
- - Internationalization
+ - Product Catalog
security:
- api_key: []
- description: Returns countries available in the store. Use ?expand=market to
- include market details (currency, locale, tax_inclusive).
+ description: Returns a paginated list of categories for the current store
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1778,13 +1738,32 @@ paths:
publishableKey: '<api-key>',
})
- const countries = await client.countries.list()
+ const categories = await client.categories.list({
+ page: 1,
+ limit: 25,
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name
+ schema:
+ type: string
- name: fields
in: query
required: false
@@ -1794,30 +1773,87 @@ paths:
type: string
responses:
'200':
- description: countries found
+ description: categories found
content:
application/json:
example:
data:
- - iso: DE
- iso3: IS19
- name: Germany
- states_required: false
- zipcode_required: true
- - iso: US
- iso3: USA
- name: United States of America
- states_required: true
- zipcode_required: true
+ - id: ctg_UkLWZg9DAJ
+ name: taxonomy_1
+ permalink: taxonomy-1
+ position: 0
+ depth: 0
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ created_at: '2026-03-11T20:16:16.754Z'
+ updated_at: '2026-03-11T20:16:16.814Z'
+ parent_id:
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: true
+ is_child: false
+ is_leaf: false
+ - id: ctg_gbHJdmfrXB
+ name: taxon_1
+ permalink: taxonomy-1/taxon-1
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ created_at: '2026-03-11T20:16:16.764Z'
+ updated_at: '2026-03-11T20:16:16.814Z'
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: false
+ - id: ctg_EfhxLZ9ck8
+ name: taxon_2
+ permalink: taxonomy-1/taxon-1/taxon-2
+ position: 0
+ depth: 2
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ created_at: '2026-03-11T20:16:16.776Z'
+ updated_at: '2026-03-11T20:16:16.783Z'
+ parent_id: ctg_gbHJdmfrXB
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: true
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
schema:
type: object
properties:
data:
type: array
items:
- "$ref": "#/components/schemas/Country"
- required:
- - data
+ "$ref": "#/components/schemas/Category"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
'401':
description: unauthorized
content:
@@ -1828,15 +1864,14 @@ paths:
message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/countries/{iso}":
+ "/api/v3/store/categories/{id}":
get:
- summary: Get a country
+ summary: Get a category
tags:
- - Internationalization
+ - Product Catalog
security:
- api_key: []
- description: Returns a single country by ISO code. Supports ?expand=states for
- address forms and ?expand=market for market details.
+ description: Returns a single category by permalink or prefix ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1848,17 +1883,26 @@ paths:
publishableKey: '<api-key>',
})
- const country = await client.countries.get('US')
+ const category = await client.categories.get('categories/clothing/shirts', {
+ expand: 'children',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: iso
+ - name: id
in: path
required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
+ description: Category permalink (e.g., clothing/shirts) or prefix ID (e.g.,
+ ctg_abc123)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Expand associations (children, parent, ancestors, metafields)
schema:
type: string
- name: fields
@@ -1870,55 +1914,60 @@ paths:
type: string
responses:
'200':
- description: country found
+ description: category found by prefix ID
content:
application/json:
example:
- iso: US
- iso3: USA
- name: United States of America
- states_required: true
- zipcode_required: true
+ id: ctg_gbHJdmfrXB
+ name: taxon_10
+ permalink: taxonomy-7/taxon-10
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ created_at: '2026-03-11T20:16:17.226Z'
+ updated_at: '2026-03-11T20:16:17.263Z'
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: false
schema:
- type: object
- properties:
- iso:
- type: string
- iso3:
- type: string
- name:
- type: string
- states_required:
- type: boolean
- zipcode_required:
- type: boolean
- required:
- - iso
- - iso3
- - name
- - states_required
- - zipcode_required
+ "$ref": "#/components/schemas/Category"
'404':
- description: country not found
+ description: category from other store not accessible
content:
application/json:
example:
error:
code: record_not_found
- message: Country not found
+ message: Category not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/coupon_codes":
- post:
- summary: Apply coupon code
+ "/api/v3/store/categories/{category_id}/products":
+ get:
+ summary: List products in a category
tags:
- - Cart
+ - Product Catalog
security:
- api_key: []
- bearer_auth: []
- description: |
- Applies a coupon code to the order. Supports both promotion coupon codes and gift card codes.
- The code is matched case-insensitively.
+ description: Returns a paginated list of products belonging to the specified
+ category
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1930,8 +1979,11 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.couponCodes.apply('or_abc123', 'SAVE10', {
- bearerToken: '<token>',
+ const products = await client.categories.products.list('categories/clothing', {
+ page: 1,
+ limit: 25,
+ sort: 'price',
+ with_option_value_ids: ['optval_abc'],
})
parameters:
- name: x-spree-api-key
@@ -1939,253 +1991,149 @@ paths:
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: order_id
+ - name: category_id
in: path
required: true
- description: Order ID
+ description: Category permalink or prefix ID
schema:
type: string
- - name: x-spree-order-token
- in: header
+ - name: page
+ in: query
required: false
- description: Order token for guest access
+ description: 'Page number (default: 1)'
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: 'Number of items per page (default: 25, max: 100)'
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: 'Sort order. Prefix with - for descending. Values: price, -price,
+ best_selling, name, -name, -available_on, available_on'
schema:
type: string
- - name: Idempotency-Key
- in: header
+ - name: q[price_gte]
+ in: query
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Filter by minimum price
+ schema:
+ type: number
+ - name: q[price_lte]
+ in: query
+ required: false
+ description: Filter by maximum price
+ schema:
+ type: number
+ - name: q[with_option_value_ids][]
+ in: query
+ required: false
+ description: Filter by option value prefix IDs
+ schema:
+ type: string
+ - name: q[in_stock]
+ in: query
+ required: false
+ description: Filter to only in-stock products
+ schema:
+ type: boolean
+ - 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:
- '201':
- description: coupon code applied (gift card)
+ '200':
+ description: products found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R876411685
- state: cart
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: bty88BCdfBv1QJXGecUT5qdwkzesGTQW3Wt
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:45:45.801Z'
- updated_at: '2026-03-11T14:45:45.922Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 193788
- slug: product-193788
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:45:45.836Z'
- updated_at: '2026-03-11T14:45:45.836Z'
- compare_at_amount:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 208355
+ description: |-
+ Consectetur tenetur pariatur totam soluta. Quasi temporibus odio provident incidunt. Aut molestiae at maxime ullam consequatur laborum voluptatum. Illo autem eos modi quasi dicta fuga.
+ Modi cumque laudantium quod animi reprehenderit totam. Minus corporis consectetur temporibus est blanditiis iure quae. Alias eos consequatur delectus eaque quidem reprehenderit amet. Tempora numquam dolorem rem nemo autem quo blanditiis commodi.
+ slug: product-208355
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on: '2025-03-11T20:16:17.712Z'
+ created_at: '2026-03-11T20:16:17.731Z'
+ updated_at: '2026-03-11T20:16:17.746Z'
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ available: true
+ default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H04394759162
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:45:45.844Z'
- updated_at: '2026-03-11T14:45:45.859Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_76
- name: Rozella Orn
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_76
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- state: checkout
- response_code: 1-SC-20260311144545911349
- number: PSFC389G
- amount: '50.0'
- display_amount: "$50.00"
- created_at: '2026-03-11T14:45:45.916Z'
- updated_at: '2026-03-11T14:45:45.916Z'
- 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"
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
currency: USD
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: Spree::PaymentMethod::StoreCredit
- session_required: false
- bill_address:
- id: addr_EfhxLZ9ck8
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 67 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_78
- state_abbr: STATE_ABBR_78
- quick_checkout: false
- state_name: STATE_NAME_78
- ship_address:
- id: addr_VqXmZF31wY
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 68 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_79
- state_abbr: STATE_ABBR_79
- quick_checkout: false
- state_name: STATE_NAME_79
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: Spree::PaymentMethod::StoreCredit
- session_required: false
- schema:
- "$ref": "#/components/schemas/Order"
- '422':
- description: invalid coupon code
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '404':
+ description: category not found
content:
application/json:
example:
error:
- code: processing_error
- message: The coupon code you entered doesn't exist. Please try again.
+ code: record_not_found
+ message: Category not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: order not found
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: order_not_found
- message: Couldn't find Spree::Order with 'id'=245546638656678833
- [WHERE "spree_orders"."store_id" = ? AND "spree_orders"."user_id"
- = ?]
+ code: invalid_token
+ message: Valid API key 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/orders/{order_id}/coupon_codes/{id}":
- delete:
- summary: Remove coupon code
+ "/api/v3/store/checkout":
+ patch:
+ summary: Update checkout
tags:
- - Cart
+ - Checkout
security:
- api_key: []
bearer_auth: []
- description: Removes a previously applied coupon code from the order.
+ description: Updates checkout info (email, addresses, special instructions).
+ When addresses change, the order state is reverted to address to ensure shipments
+ are recalculated.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2197,7 +2145,18 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.couponCodes.remove('or_abc123', 'op_abc123', {
+ const cart = await client.checkout.update({
+ email: '[email protected]',
+ ship_address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ },
+ }, {
bearerToken: '<token>',
})
parameters:
@@ -2209,50 +2168,40 @@ paths:
- name: Authorization
in: header
required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
schema:
type: string
- - name: id
- in: path
- required: true
- description: Order promotion ID
+ - name: x-spree-token
+ in: header
+ required: false
schema:
type: string
- - name: x-spree-order-token
+ - name: Idempotency-Key
in: header
required: false
- description: Order token for guest access
+ description: Unique key for request idempotency.
schema:
type: string
responses:
'200':
- description: coupon code removed
+ description: checkout updated
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R556023391
+ id: cart_UkLWZg9DAJ
+ number: R588561123
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: atsEAqaNHZb2NUJH1G2AmgDG9eAFiSKjWtZ
- special_instructions:
+ token: MWAPtS8LeQokYsy4vPCw8KLhHkZoh6yT5Q3
+ special_instructions: Leave at door
currency: USD
locale: en
item_count: 1
state_lock_version: 1
- shipment_state:
- payment_state:
item_total: '10.0'
display_item_total: "$10.00"
ship_total: '100.0'
@@ -2269,17 +2218,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:45:47.705Z'
- updated_at: '2026-03-11T14:45:47.826Z'
+ created_at: '2026-03-11T20:16:18.705Z'
+ updated_at: '2026-03-11T20:16:18.781Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 22504
- slug: product-22504
+ name: Product 237577
+ slug: product-237577
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2298,37 +2246,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:45:47.737Z'
- updated_at: '2026-03-11T14:45:47.820Z'
+ created_at: '2026-03-11T20:16:18.738Z'
+ updated_at: '2026-03-11T20:16:18.738Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H45666021172
+ number: H23404285089
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:45:47.743Z'
- updated_at: '2026-03-11T14:45:47.758Z'
+ created_at: '2026-03-11T20:16:18.743Z'
+ updated_at: '2026-03-11T20:16:18.759Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_88
- name: Lonny Waelchi
+ state_abbr: STATE_ABBR_86
+ name: Weldon Towne
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_88
+ state_text: STATE_ABBR_86
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -2346,7 +2294,7 @@ paths:
firstname: John
lastname: Doe
full_name: John Doe
- address1: 79 Lovely Street
+ address1: 77 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -2354,16 +2302,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_90
- state_abbr: STATE_ABBR_90
+ state_text: STATE_ABBR_88
+ state_abbr: STATE_ABBR_88
quick_checkout: false
- state_name: STATE_NAME_90
+ state_name: STATE_NAME_88
ship_address:
id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 80 Lovely Street
+ address1: 78 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -2371,199 +2319,85 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_91
- state_abbr: STATE_ABBR_91
+ state_text: STATE_ABBR_89
+ state_abbr: STATE_ABBR_89
quick_checkout: false
- state_name: STATE_NAME_91
+ state_name: STATE_NAME_89
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: coupon code not found on order
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Couldn't find Spree::OrderPromotion with 'id'=245546638656678833
- [WHERE "spree_order_promotions"."order_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customer/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
- cc_type: visa
- last_digits: '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/customer/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: 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
- content:
- application/json:
- example:
- id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '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
+ "$ref": "#/components/schemas/Cart"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ special_instructions:
+ type: string
+ example: Leave at door
+ metadata:
+ type: object
+ additionalProperties: true
+ bill_address:
+ type: object
+ properties:
+ firstname:
+ type: string
+ lastname:
+ type: string
+ address1:
+ type: string
+ address2:
+ type: string
+ city:
+ type: string
+ zipcode:
+ type: string
+ phone:
+ type: string
+ company:
+ type: string
+ country_iso:
+ type: string
+ state_abbr:
+ type: string
+ ship_address:
+ type: object
+ properties:
+ firstname:
+ type: string
+ lastname:
+ type: string
+ address1:
+ type: string
+ address2:
+ type: string
+ city:
+ type: string
+ zipcode:
+ type: string
+ phone:
+ type: string
+ company:
+ type: string
+ country_iso:
+ type: string
+ state_abbr:
+ type: string
+ "/api/v3/store/checkout/complete":
+ post:
+ summary: Complete checkout
tags:
- - Customers
+ - Checkout
security:
- api_key: []
bearer_auth: []
- description: Removes a saved credit card from the customer account
+ description: Completes the checkout and finalizes the purchase. Returns an Order
+ (not Cart).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2575,7 +2409,7 @@ paths:
publishableKey: '<api-key>',
})
- await client.customer.creditCards.delete('cc_abc123', {
+ const order = await client.checkout.complete({
bearerToken: '<token>',
})
parameters:
@@ -2586,101 +2420,213 @@ paths:
type: string
- name: Authorization
in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
+ required: false
schema:
type: string
- 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:
- - Internationalization
- 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
+ - name: x-spree-token
in: header
- required: true
+ required: false
schema:
type: string
- - name: fields
- in: query
+ - name: Idempotency-Key
+ in: header
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: currencies found
+ description: checkout completed
content:
application/json:
example:
- 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
+ id: or_gbHJdmfrXB
+ number: R870413854
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ shipment_state: backorder
+ payment_state: paid
+ item_total: '19.99'
+ display_item_total: "$19.99"
+ ship_total: '10.0'
+ display_ship_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '29.99'
+ display_total: "$29.99"
+ completed_at: '2026-03-11T20:16:19.602Z'
+ created_at: '2026-03-11T20:16:19.386Z'
+ updated_at: '2026-03-11T20:16:19.602Z'
+ order_promotions: []
+ line_items:
+ - id: li_gbHJdmfrXB
+ variant_id: variant_gbHJdmfrXB
+ quantity: 1
+ currency: USD
+ name: Product 251178
+ slug: product-251178
+ options_text: ''
+ price: '19.99'
+ display_price: "$19.99"
+ total: '19.99'
+ display_total: "$19.99"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '19.99'
+ display_pre_tax_amount: "$19.99"
+ discounted_amount: '19.99'
+ display_discounted_amount: "$19.99"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:19.410Z'
+ updated_at: '2026-03-11T20:16:19.457Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_EfhxLZ9ck8
+ number: H68645938166
+ state: pending
+ tracking:
+ tracking_url:
+ cost: '10.0'
+ display_cost: "$10.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:19.478Z'
+ updated_at: '2026-03-11T20:16:19.597Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_90
+ name: Jack Sipes
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_90
+ shipping_rates:
+ - id: shpr_EfhxLZ9ck8
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ display_cost: "$10.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ - id: shpr_VqXmZF31wY
+ shipping_method_id: shpm_gbHJdmfrXB
+ name: UPS Ground
+ selected: false
+ cost: '10.0'
+ display_cost: "$10.00"
+ shipping_method:
+ id: shpm_gbHJdmfrXB
+ name: UPS Ground
+ code: UPS_GROUND
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ state: completed
+ response_code: '12345'
+ number: PJAIOR48
+ amount: '29.99'
+ display_amount: "$29.99"
+ created_at: '2026-03-11T20:16:19.556Z'
+ updated_at: '2026-03-11T20:16:19.583Z'
+ source_type: credit_card
+ source_id: card_UkLWZg9DAJ
+ source:
+ id: card_UkLWZg9DAJ
+ cc_type: visa
+ last_digits: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Check
+ description:
+ type: Spree::PaymentMethod::Check
+ session_required: false
+ bill_address:
+ id: addr_uw2YK1rnl0
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 83 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_94
+ state_abbr: STATE_ABBR_94
+ quick_checkout: false
+ state_name: STATE_NAME_94
+ ship_address:
+ id: addr_OIJLhNcSbf
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 84 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_95
+ state_abbr: STATE_ABBR_95
+ quick_checkout: false
+ state_name: STATE_NAME_95
+ schema:
+ "$ref": "#/components/schemas/Order"
+ '422':
+ description: cannot complete
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: order_already_completed
+ message: No payment found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customer/orders":
+ "/api/v3/store/countries":
get:
- summary: List customer orders
+ summary: List countries
tags:
- - Customers
+ - Internationalization
security:
- api_key: []
- bearer_auth: []
- description: Returns a paginated list of orders for the authenticated customer
+ description: Returns countries available in the store. Use ?expand=market to
+ include market details (currency, locale, tax_inclusive).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2692,51 +2638,13 @@ paths:
publishableKey: '<api-key>',
})
- const orders = await client.customer.orders.list({
- page: 1,
- limit: 25,
- }, {
- bearerToken: '<token>',
- })
+ const countries = await client.countries.list()
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: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Example: -completed_at'
- schema:
- type: string
- - name: q[state_eq]
- in: query
- required: false
- description: Filter by order state
- schema:
- type: string
- - name: q[completed_at_gte]
- in: query
- required: false
- description: Filter by completion date (after)
- schema:
- type: string
- name: fields
in: query
required: false
@@ -2746,188 +2654,49 @@ paths:
type: string
responses:
'200':
- description: orders found
+ description: countries found
content:
application/json:
example:
data:
- - id: or_UkLWZg9DAJ
- number: R939843740
- state: cart
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: XVdvFACWeHB6yfr5H7rqVg8B2GLtNEmiUZT
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 0
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:45:52.512Z'
- updated_at: '2026-03-11T14:45:52.596Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 248498
- slug: product-248498
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:45:52.566Z'
- updated_at: '2026-03-11T14:45:52.566Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H23827286331
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:45:52.574Z'
- updated_at: '2026-03-11T14:45:52.593Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_108
- name: Lindsy Mueller
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_108
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- bill_address:
- id: addr_EfhxLZ9ck8
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 99 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_110
- state_abbr: STATE_ABBR_110
- quick_checkout: false
- state_name: STATE_NAME_110
- ship_address:
- id: addr_VqXmZF31wY
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 100 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_111
- state_abbr: STATE_ABBR_111
- quick_checkout: false
- state_name: STATE_NAME_111
- payment_methods: []
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ - iso: DE
+ iso3: IS24
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ - iso: US
+ iso3: USA
+ name: United States of America
+ states_required: true
+ zipcode_required: true
schema:
type: object
properties:
data:
type: array
items:
- "$ref": "#/components/schemas/Order"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/Country"
+ required:
+ - data
'401':
- description: unauthorized - authentication required
+ description: unauthorized
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers":
- post:
- summary: Register a new customer
+ "/api/v3/store/countries/{iso}":
+ get:
+ summary: Get a country
tags:
- - Customers
+ - Internationalization
security:
- api_key: []
- description: Creates a new customer account and returns a JWT token
+ description: Returns a single country by ISO code. Supports ?expand=states for
+ address forms and ?expand=market for market details.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2939,101 +2708,77 @@ paths:
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' },
- })
+ const country = await client.countries.get('US')
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- responses:
- '201':
- description: registration successful
- content:
- application/json:
- example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFiNjcyN2RlLTE4ZmYtNDA4Ny05YTBiLWRkYWM4MWQ1MGVmYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjQzOTUzfQ.tyQZduHlN6j52kHMKfD6S1fBqonkEtcUgUfIwBBXgas
- user:
- id: cus_UkLWZg9DAJ
- first_name: John
- last_name: Doe
- phone: "+1234567890"
- accepts_email_marketing: true
- created_at: '2026-03-11T14:45:53.547Z'
- updated_at: '2026-03-11T14:45:53.547Z'
- addresses: []
- default_billing_address:
- default_shipping_address:
+ - name: iso
+ in: path
+ required: true
+ description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
+ 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: country found
+ content:
+ application/json:
+ example:
+ iso: US
+ iso3: USA
+ name: United States of America
+ states_required: true
+ zipcode_required: true
schema:
- "$ref": "#/components/schemas/AuthResponse"
- '422':
- description: email already taken
+ type: object
+ properties:
+ iso:
+ type: string
+ iso3:
+ type: string
+ name:
+ type: string
+ states_required:
+ type: boolean
+ zipcode_required:
+ type: boolean
+ required:
+ - iso
+ - iso3
+ - name
+ - states_required
+ - zipcode_required
+ '404':
+ description: country not found
content:
application/json:
example:
error:
- code: validation_error
- message: Email has already been taken
- details:
- email:
- - has already been taken
+ code: record_not_found
+ message: Country not found
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/customer":
- get:
- summary: Get current customer profile
+ "/api/v3/store/cart/coupon_codes":
+ post:
+ summary: Apply coupon code
tags:
- - Customers
+ - Cart
security:
- api_key: []
bearer_auth: []
- description: Returns the profile of the currently authenticated customer
+ description: |
+ Applies a coupon code to the cart. Supports both promotion coupon codes and gift card codes.
+ The code is matched case-insensitively.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3045,7 +2790,7 @@ paths:
publishableKey: '<api-key>',
})
- const customer = await client.customer.get({
+ const cart = await client.cart.couponCodes.apply('SAVE10', {
bearerToken: '<token>',
})
parameters:
@@ -3056,70 +2801,162 @@ paths:
type: string
- name: Authorization
in: header
- required: true
- description: Bearer JWT token
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: fields
- in: query
+ - name: x-spree-token
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: Idempotency-Key
+ in: header
+ required: false
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '200':
- description: profile found
+ '201':
+ description: coupon code applied (gift card)
content:
application/json:
example:
- id: cus_UkLWZg9DAJ
- first_name: Ashlea
- last_name: Gutkowski
- phone: 555-555-0199
- accepts_email_marketing: false
- created_at: '2026-03-11T14:45:54.093Z'
- updated_at: '2026-03-11T14:45:54.364Z'
- addresses:
- - id: addr_gbHJdmfrXB
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 106 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_117
- state_abbr: STATE_ABBR_117
- quick_checkout: false
- state_name: STATE_NAME_117
- - id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 105 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_116
- state_abbr: STATE_ABBR_116
- quick_checkout: false
- state_name: STATE_NAME_116
- default_billing_address:
- id: addr_gbHJdmfrXB
+ id: cart_UkLWZg9DAJ
+ number: R684605333
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: VE67cEJ9DR1dx51rgSvwWVWHs5ESp8JSseM
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ state_lock_version: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ created_at: '2026-03-11T20:16:21.735Z'
+ updated_at: '2026-03-11T20:16:21.835Z'
+ order_promotions: []
+ line_items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 286411
+ slug: product-286411
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:21.765Z'
+ updated_at: '2026-03-11T20:16:21.765Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H84193505229
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:21.770Z'
+ updated_at: '2026-03-11T20:16:21.784Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_104
+ name: Angelina Tromp
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_104
+ shipping_rates:
+ - id: shpr_UkLWZg9DAJ
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ state: checkout
+ response_code: 1-SC-20260311201621829283
+ number: PMEGFU0N
+ amount: '50.0'
+ display_amount: "$50.00"
+ created_at: '2026-03-11T20:16:21.830Z'
+ updated_at: '2026-03-11T20:16:21.830Z'
+ 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
+ bill_address:
+ id: addr_EfhxLZ9ck8
firstname: John
lastname: Doe
full_name: John Doe
- address1: 106 Lovely Street
+ address1: 95 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -3127,16 +2964,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_117
- state_abbr: STATE_ABBR_117
+ state_text: STATE_ABBR_106
+ state_abbr: STATE_ABBR_106
quick_checkout: false
- state_name: STATE_NAME_117
- default_shipping_address:
- id: addr_UkLWZg9DAJ
+ state_name: STATE_NAME_106
+ ship_address:
+ id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 105 Lovely Street
+ address1: 96 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -3144,30 +2981,50 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_116
- state_abbr: STATE_ABBR_116
+ state_text: STATE_ABBR_107
+ state_abbr: STATE_ABBR_107
quick_checkout: false
- state_name: STATE_NAME_116
+ state_name: STATE_NAME_107
+ payment_methods:
+ - id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: Spree::PaymentMethod::StoreCredit
+ session_required: false
schema:
- "$ref": "#/components/schemas/Customer"
- '401':
- description: unauthorized - invalid token
+ "$ref": "#/components/schemas/Cart"
+ '422':
+ description: invalid coupon code
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"
- patch:
- summary: Update current customer profile
+ 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/cart/coupon_codes/{id}":
+ delete:
+ summary: Remove coupon code
tags:
- - Customers
+ - Cart
security:
- api_key: []
bearer_auth: []
- description: Updates the profile of the currently authenticated customer
+ description: Removes a previously applied coupon code from the cart. The ID
+ is the coupon code string itself.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3179,11 +3036,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.cart.couponCodes.remove('SAVE10', {
bearerToken: '<token>',
})
parameters:
@@ -3194,62 +3047,136 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ description: Bearer token for authenticated customers
+ 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
schema:
type: string
responses:
'200':
- description: profile updated
+ description: coupon code removed
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-11T14:45:54.654Z'
- updated_at: '2026-03-11T14:45:54.935Z'
- addresses:
- - id: addr_gbHJdmfrXB
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 108 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_119
- state_abbr: STATE_ABBR_119
- quick_checkout: false
- state_name: STATE_NAME_119
- - id: addr_UkLWZg9DAJ
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 107 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_118
- state_abbr: STATE_ABBR_118
- quick_checkout: false
- state_name: STATE_NAME_118
- default_billing_address:
- id: addr_gbHJdmfrXB
+ id: cart_UkLWZg9DAJ
+ number: R561946058
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: N2ffiZoKdeftYDG5LBx7fkPmaJhGXaeijYV
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ state_lock_version: 1
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ created_at: '2026-03-11T20:16:22.999Z'
+ updated_at: '2026-03-11T20:16:23.104Z'
+ order_promotions: []
+ line_items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 30599
+ slug: product-30599
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:23.029Z'
+ updated_at: '2026-03-11T20:16:23.099Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H95858592120
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:23.034Z'
+ updated_at: '2026-03-11T20:16:23.047Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_112
+ name: Aileen Murray
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_112
+ shipping_rates:
+ - id: shpr_UkLWZg9DAJ
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ bill_address:
+ id: addr_EfhxLZ9ck8
firstname: John
lastname: Doe
full_name: John Doe
- address1: 108 Lovely Street
+ address1: 103 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -3257,133 +3184,49 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_119
- state_abbr: STATE_ABBR_119
+ state_text: STATE_ABBR_114
+ state_abbr: STATE_ABBR_114
quick_checkout: false
- state_name: STATE_NAME_119
- default_shipping_address:
- id: addr_UkLWZg9DAJ
+ state_name: STATE_NAME_114
+ ship_address:
+ id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 107 Lovely Street
+ address1: 104 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_118
- state_abbr: STATE_ABBR_118
- quick_checkout: false
- state_name: STATE_NAME_118
- schema:
- "$ref": "#/components/schemas/Customer"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Email can't be blank
- details:
- email:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- 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:
- - 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:
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_115
+ state_abbr: STATE_ABBR_115
+ quick_checkout: false
+ state_name: STATE_NAME_115
+ payment_methods: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: digital link not found
+ "$ref": "#/components/schemas/Cart"
+ '422':
+ description: coupon code not found on cart
content:
application/json:
example:
error:
- code: record_not_found
- message: Digital link not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- application/octet-stream:
+ code: processing_error
+ message: The coupon code you entered doesn't exist. Please try again.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customer/gift_cards":
+ "/api/v3/store/customer/credit_cards":
get:
- summary: List gift cards
+ summary: List saved credit cards
tags:
- Customers
security:
- api_key: []
bearer_auth: []
- description: Returns all gift cards for the authenticated customer
+ description: Returns all saved credit cards for the authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3395,7 +3238,7 @@ paths:
publishableKey: '<api-key>',
})
- const giftCards = await client.customer.giftCards.list({}, {
+ const cards = await client.customer.creditCards.list({}, {
bearerToken: '<token>',
})
parameters:
@@ -3428,28 +3271,19 @@ paths:
type: string
responses:
'200':
- description: gift cards found
+ description: credit cards found
content:
application/json:
example:
data:
- - id: gc_UkLWZg9DAJ
- code: 865326619F6C0947
- state: active
- currency: USD
- amount: '10.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '10.0'
- display_amount: "$10.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$10.00"
- expires_at:
- redeemed_at:
- expired: false
- active: true
- created_at: '2026-03-11T14:45:58.057Z'
- updated_at: '2026-03-11T14:45:58.057Z'
+ - id: card_UkLWZg9DAJ
+ cc_type: visa
+ last_digits: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
meta:
page: 1
limit: 25
@@ -3466,7 +3300,7 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/GiftCard"
+ "$ref": "#/components/schemas/CreditCard"
meta:
"$ref": "#/components/schemas/PaginationMeta"
'401':
@@ -3479,15 +3313,15 @@ paths:
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customer/gift_cards/{id}":
+ "/api/v3/store/customer/credit_cards/{id}":
get:
- summary: Get a gift card
+ summary: Get a credit card
tags:
- Customers
security:
- api_key: []
bearer_auth: []
- description: Returns a gift card by its ID
+ description: Returns a saved credit card by its ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3499,7 +3333,7 @@ paths:
publishableKey: '<api-key>',
})
- const giftCard = await client.customer.giftCards.get('gc_abc123', {
+ const card = await client.customer.creditCards.get('cc_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -3527,49 +3361,38 @@ paths:
type: string
responses:
'200':
- description: gift card found
+ description: credit card found
content:
application/json:
example:
- id: gc_UkLWZg9DAJ
- code: 9A67B41946E61B0F
- state: active
- currency: USD
- amount: '10.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '10.0'
- display_amount: "$10.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$10.00"
- expires_at:
- redeemed_at:
- expired: false
- active: true
- created_at: '2026-03-11T14:45:59.146Z'
- updated_at: '2026-03-11T14:45:59.146Z'
+ id: card_UkLWZg9DAJ
+ cc_type: visa
+ last_digits: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
schema:
- "$ref": "#/components/schemas/GiftCard"
+ "$ref": "#/components/schemas/CreditCard"
'404':
- description: gift card not found
+ description: credit card not found
content:
application/json:
example:
error:
code: record_not_found
- message: Gift card not found
+ message: Credit card not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/line_items":
- post:
- summary: Add item to cart
+ delete:
+ summary: Delete a credit card
tags:
- - Cart
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Adds a variant to the order. Creates a new line item or increases
- quantity if variant already in cart.
+ description: Removes a saved credit card from the customer account
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3581,10 +3404,7 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.lineItems.create('or_abc123', {
- variant_id: 'variant_abc123',
- quantity: 2,
- }, {
+ await client.customer.creditCards.delete('cc_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -3595,198 +3415,294 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- description: Bearer token for authenticated customers
+ required: true
schema:
type: string
- - name: order_id
+ - name: id
in: path
required: true
- description: Order ID or number
schema:
type: string
- - name: x-spree-order-token
+ 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:
+ - Internationalization
+ 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: 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: Idempotency-Key
+ responses:
+ '200':
+ description: currencies found
+ content:
+ application/json:
+ example:
+ 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/customer/orders":
+ get:
+ summary: List orders
+ tags:
+ - Customer
+ 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: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
- '201':
- description: item added with metadata
+ '200':
+ description: orders listed
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R153037447
- state: cart
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: do8ruoWJqGJMxXMHGeGiE2LoEYXu8eZa7e6
- special_instructions:
- currency: USD
- locale: en
- item_count: 2
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '29.99'
- display_item_total: "$29.99"
- ship_total: '0.0'
- display_ship_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '29.99'
- display_total: "$29.99"
- completed_at:
- created_at: '2026-03-11T14:46:00.913Z'
- updated_at: '2026-03-11T14:46:01.016Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 341458
- slug: product-341458
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
+ data:
+ - id: or_UkLWZg9DAJ
+ number: R749102215
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ shipment_state:
+ payment_state:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
promo_total: '0.0'
display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:00.944Z'
- updated_at: '2026-03-11T14:46:00.944Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
- quantity: 1
- currency: USD
- name: Product 353183
- slug: product-353183
- options_text: ''
- price: '19.99'
- display_price: "$19.99"
- total: '19.99'
- display_total: "$19.99"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '19.99'
- display_pre_tax_amount: "$19.99"
- discounted_amount: '19.99'
- display_discounted_amount: "$19.99"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:00.990Z'
- updated_at: '2026-03-11T14:46:00.990Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- shipments: []
- payments: []
- bill_address:
- id: addr_EfhxLZ9ck8
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 136 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_147
- state_abbr: STATE_ABBR_147
- quick_checkout: false
- state_name: STATE_NAME_147
- ship_address:
- payment_methods: []
- schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: order not found
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ completed_at: '2026-03-11T20:16:27.795Z'
+ created_at: '2026-03-11T20:16:27.710Z'
+ updated_at: '2026-03-11T20:16:27.794Z'
+ order_promotions: []
+ line_items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 328144
+ slug: product-328144
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:27.761Z'
+ updated_at: '2026-03-11T20:16:27.761Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H69766910536
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:27.769Z'
+ updated_at: '2026-03-11T20:16:27.791Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_132
+ name: Darla Franecki
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_132
+ shipping_rates:
+ - id: shpr_gbHJdmfrXB
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ display_cost: "$10.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ bill_address:
+ id: addr_EfhxLZ9ck8
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 123 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_134
+ state_abbr: STATE_ABBR_134
+ quick_checkout: false
+ state_name: STATE_NAME_134
+ ship_address:
+ id: addr_VqXmZF31wY
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 124 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_135
+ state_abbr: STATE_ABBR_135
+ quick_checkout: false
+ state_name: STATE_NAME_135
+ 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: order_not_found
- message: Order not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- variant_id:
- type: string
- example: variant_abc123
- description: Variant ID to add
- quantity:
- type: integer
- example: 2
- description: 'Quantity to add (default: 1)'
- metadata:
- type: object
- additionalProperties: true
- description: Arbitrary key-value metadata (stored, not returned
- in responses)
- example:
- gift_message: Happy Birthday!
- required:
- - variant_id
- "/api/v3/store/orders/{order_id}/line_items/{id}":
- patch:
- summary: Update line item quantity
+ "/api/v3/store/customer/orders/{id}":
+ get:
+ summary: Get an order
tags:
- - Cart
+ - Customer
security:
- api_key: []
bearer_auth: []
- description: Updates the quantity of a line item in the cart
+ description: Returns a single completed order for the authenticated customer.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3798,9 +3714,7 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.lineItems.update('or_abc123', 'li_abc123', {
- quantity: 5,
- }, {
+ const order = await client.customer.orders.get('or_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -3811,51 +3725,34 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- schema:
- type: string
- - name: order_id
- in: path
required: true
schema:
type: string
- name: id
in: path
required: true
- description: Line item ID
- schema:
- type: string
- - name: x-spree-order-token
- in: header
- required: false
+ description: Order prefixed ID
schema:
type: string
responses:
'200':
- description: metadata updated on line item
+ description: order found
content:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R599053352
- state: cart
- checkout_steps:
- - address
- - delivery
- - complete
- token: ELfSXoFpKiCeBLWD1Uuy9TYUgSfJnEkR7GN
+ number: R094723322
special_instructions:
currency: USD
locale: en
- item_count: 0
- state_lock_version: 1
+ item_count: 1
shipment_state:
payment_state:
- item_total: '0.0'
- display_item_total: "$0.00"
- ship_total: '0.0'
- display_ship_total: "$0.00"
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
promo_total: '0.0'
@@ -3866,19 +3763,19 @@ paths:
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- completed_at:
- created_at: '2026-03-11T14:46:03.390Z'
- updated_at: '2026-03-11T14:46:03.433Z'
+ total: '110.0'
+ display_total: "$110.00"
+ completed_at: '2026-03-11T20:16:28.486Z'
+ created_at: '2026-03-11T20:16:28.437Z'
+ updated_at: '2026-03-11T20:16:28.486Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 397255
- slug: product-397255
+ name: Product 341755
+ slug: product-341755
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3897,20 +3794,55 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:03.432Z'
- updated_at: '2026-03-11T14:46:03.455Z'
+ created_at: '2026-03-11T20:16:28.467Z'
+ updated_at: '2026-03-11T20:16:28.467Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
- shipments: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H68136358737
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:28.472Z'
+ updated_at: '2026-03-11T20:16:28.484Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_138
+ name: Leopoldo Monahan
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_138
+ shipping_rates:
+ - id: shpr_gbHJdmfrXB
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ display_cost: "$10.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
payments: []
bill_address:
id: addr_EfhxLZ9ck8
firstname: John
lastname: Doe
full_name: John Doe
- address1: 148 Lovely Street
+ address1: 129 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -3918,38 +3850,49 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_159
- state_abbr: STATE_ABBR_159
+ state_text: STATE_ABBR_140
+ state_abbr: STATE_ABBR_140
quick_checkout: false
- state_name: STATE_NAME_159
+ state_name: STATE_NAME_140
ship_address:
- payment_methods: []
+ id: addr_VqXmZF31wY
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 130 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_141
+ state_abbr: STATE_ABBR_141
+ quick_checkout: false
+ state_name: STATE_NAME_141
schema:
"$ref": "#/components/schemas/Order"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- quantity:
- type: integer
- minimum: 1
- example: 5
- metadata:
- type: object
- additionalProperties: true
- description: Arbitrary key-value metadata (merged with existing)
- example:
- engraving: J.D.
- delete:
- summary: Remove line item from cart
+ '404':
+ description: order belongs to another user
+ content:
+ application/json:
+ example:
+ error:
+ code: order_not_found
+ message: Couldn't find Spree::Order with 'id'=1 [WHERE "spree_orders"."user_id"
+ = ? AND "spree_orders"."store_id" = ? AND "spree_orders"."completed_at"
+ IS NOT NULL]
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customers":
+ post:
+ summary: Register a new customer
tags:
- - Cart
+ - Customers
security:
- api_key: []
- bearer_auth: []
- description: Removes a line item from the order
+ description: Creates a new customer account and returns a JWT token
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3961,8 +3904,15 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.lineItems.delete('or_abc123', 'li_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
@@ -3970,110 +3920,85 @@ paths:
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: false
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- - name: x-spree-order-token
- in: header
- required: false
- schema:
- type: string
responses:
- '200':
- description: line item removed, returns updated order
+ '201':
+ description: registration successful
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R705024898
- state: cart
- checkout_steps:
- - address
- - delivery
- - complete
- token: 4vfbWYeTWTeRjhtnr62wgGGtbfZFq88rJxF
- special_instructions:
- currency: USD
- locale: en
- item_count: 0
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '0.0'
- display_item_total: "$0.00"
- ship_total: '0.0'
- display_ship_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- completed_at:
- created_at: '2026-03-11T14:46:04.003Z'
- updated_at: '2026-03-11T14:46:04.053Z'
- order_promotions: []
- line_items: []
- shipments: []
- payments: []
- bill_address:
- id: addr_EfhxLZ9ck8
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 151 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_162
- state_abbr: STATE_ABBR_162
- quick_checkout: false
- state_name: STATE_NAME_162
- ship_address:
- payment_methods: []
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImU4NjQwMzgwLWI2NjAtNDZhNy05NDM4LTk3NmY4YjcwMDk0YiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjYzNzg5fQ.YMTjgRA2s6FXRb7KqeYDobu_TQEKQbBdfyHRPWCdsDY
+ user:
+ id: cus_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ phone: "+1234567890"
+ accepts_email_marketing: true
+ created_at: '2026-03-11T20:16:29.684Z'
+ updated_at: '2026-03-11T20:16:29.684Z'
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: line item not found
+ "$ref": "#/components/schemas/AuthResponse"
+ '422':
+ description: email already taken
content:
application/json:
example:
error:
- code: line_item_not_found
- message: Line item not found
+ code: validation_error
+ message: Email has already been taken
+ details:
+ email:
+ - has already been taken
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/locales":
+ 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/customer":
get:
- summary: List supported locales
+ summary: Get current customer profile
tags:
- - Internationalization
+ - Customers
security:
- api_key: []
- description: Returns locales supported by the store (derived from markets)
+ bearer_auth: []
+ description: Returns the profile of the currently authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4085,13 +4010,21 @@ paths:
publishableKey: '<api-key>',
})
- const locales = await client.locales.list()
+ 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
@@ -4101,43 +4034,105 @@ paths:
type: string
responses:
'200':
- description: locales found
+ description: profile found
content:
application/json:
example:
- data:
- - code: de
- name: de
- - code: en
- name: English (US)
+ id: cus_UkLWZg9DAJ
+ first_name: Cortney
+ last_name: Cartwright
+ phone: 555-555-0199
+ accepts_email_marketing: false
+ created_at: '2026-03-11T20:16:30.230Z'
+ updated_at: '2026-03-11T20:16:30.496Z'
+ addresses:
+ - id: addr_gbHJdmfrXB
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 136 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_147
+ state_abbr: STATE_ABBR_147
+ quick_checkout: false
+ state_name: STATE_NAME_147
+ - id: addr_UkLWZg9DAJ
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 135 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_146
+ state_abbr: STATE_ABBR_146
+ quick_checkout: false
+ state_name: STATE_NAME_146
+ default_billing_address:
+ id: addr_gbHJdmfrXB
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 136 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_147
+ state_abbr: STATE_ABBR_147
+ quick_checkout: false
+ state_name: STATE_NAME_147
+ default_shipping_address:
+ id: addr_UkLWZg9DAJ
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 135 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_146
+ state_abbr: STATE_ABBR_146
+ quick_checkout: false
+ state_name: STATE_NAME_146
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Locale"
- required:
- - data
+ "$ref": "#/components/schemas/Customer"
'401':
- description: unauthorized
+ description: unauthorized - invalid token
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets":
- get:
- summary: List markets
+ patch:
+ summary: Update current customer profile
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Returns all markets for the current store with their countries,
- currency, locales, and tax configuration.
+ bearer_auth: []
+ description: Updates the profile of the currently authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4149,171 +4144,211 @@ paths:
publishableKey: '<api-key>',
})
- const markets = await client.markets.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: markets found
+ description: profile updated
content:
application/json:
example:
- data:
- - id: mkt_UkLWZg9DAJ
- name: North America
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- supported_locales:
- - en
- - es
- countries:
- - iso: US
- iso3: USA
- name: United States of America
- states_required: true
- zipcode_required: true
- - id: mkt_gbHJdmfrXB
- name: Europe
- currency: EUR
- default_locale: de
- tax_inclusive: true
- default: false
- supported_locales:
- - de
- - en
- - fr
- countries:
- - iso: DE
- iso3: IS40
- name: Germany
- states_required: false
- zipcode_required: true
- - iso: FR
- iso3: IS41
- name: France
- states_required: false
- zipcode_required: true
+ id: cus_UkLWZg9DAJ
+ first_name: Updated
+ last_name: Name
+ phone: 555-555-0199
+ accepts_email_marketing: false
+ created_at: '2026-03-11T20:16:30.791Z'
+ updated_at: '2026-03-11T20:16:31.073Z'
+ addresses:
+ - id: addr_gbHJdmfrXB
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 138 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_149
+ state_abbr: STATE_ABBR_149
+ quick_checkout: false
+ state_name: STATE_NAME_149
+ - id: addr_UkLWZg9DAJ
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 137 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_148
+ state_abbr: STATE_ABBR_148
+ quick_checkout: false
+ state_name: STATE_NAME_148
+ default_billing_address:
+ id: addr_gbHJdmfrXB
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 138 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_149
+ state_abbr: STATE_ABBR_149
+ quick_checkout: false
+ state_name: STATE_NAME_149
+ default_shipping_address:
+ id: addr_UkLWZg9DAJ
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 137 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_148
+ state_abbr: STATE_ABBR_148
+ quick_checkout: false
+ state_name: STATE_NAME_148
schema:
- type: object
- properties:
- data:
- type: array
- 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/markets/{id}":
+ 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: Get a market
+ summary: Download a digital product
tags:
- - Markets
- security:
- - api_key: []
- description: Returns a single market by prefixed ID with its countries, currency,
- locales, and tax configuration.
- 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 market = await client.markets.get('mkt_xxx')
+ - 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
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Market prefixed ID (e.g., "mkt_k5nR8xLq")
- 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: token
+ in: path
+ required: true
+ description: Digital link token
schema:
type: string
responses:
'200':
- description: market found
+ description: file downloaded
+ content:
+ application/json: {}
+ '403':
+ description: download link expired or limit exceeded
content:
application/json:
example:
- id: mkt_gbHJdmfrXB
- name: Europe
- currency: EUR
- default_locale: de
- tax_inclusive: true
- default: false
- supported_locales:
- - de
- - en
- - fr
- countries:
- - iso: DE
- iso3: IS44
- name: Germany
- states_required: false
- zipcode_required: true
- - iso: FR
- iso3: IS45
- name: France
- states_required: false
- zipcode_required: true
+ error:
+ code: digital_link_expired
+ message: Download link expired or invalid
schema:
- type: object
+ "$ref": "#/components/schemas/ErrorResponse"
+ application/octet-stream:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
'404':
- description: market not found
+ description: digital link not found
content:
application/json:
example:
error:
code: record_not_found
- message: Couldn't find Spree::Market with 'id'=245546638656678833
- [WHERE "spree_markets"."deleted_at" IS NULL AND "spree_markets"."store_id"
- = ?]
+ message: Digital link not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets/resolve":
+ application/octet-stream:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customer/gift_cards":
get:
- summary: Resolve market by country
+ summary: List gift cards
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Determine which market applies for a given country ISO code. Useful
- for auto-selecting the correct currency and locale when a customer's location
- is known.
+ bearer_auth: []
+ description: Returns all gift cards for the authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4325,19 +4360,30 @@ paths:
publishableKey: '<api-key>',
})
- const market = await client.markets.resolve('DE')
+ const giftCards = await client.customer.giftCards.list({}, {
+ bearerToken: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: country
- in: query
+ - name: Authorization
+ in: header
required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")
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
@@ -4347,52 +4393,66 @@ paths:
type: string
responses:
'200':
- description: market resolved
+ description: gift cards found
content:
application/json:
example:
- id: mkt_gbHJdmfrXB
- name: Europe
- currency: EUR
- default_locale: de
- tax_inclusive: true
- default: false
- supported_locales:
- - de
- - en
- - fr
- countries:
- - iso: DE
- iso3: IS48
- name: Germany
- states_required: false
- zipcode_required: true
- - iso: FR
- iso3: IS49
- name: France
- states_required: false
- zipcode_required: true
+ data:
+ - id: gc_UkLWZg9DAJ
+ code: C7706CBAF6DA86AB
+ state: active
+ currency: USD
+ amount: '10.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '10.0'
+ display_amount: "$10.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$10.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
+ created_at: '2026-03-11T20:16:34.340Z'
+ updated_at: '2026-03-11T20:16:34.340Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
type: object
- '404':
- description: no market for country
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/GiftCard"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: record_not_found
- message: Country not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets/{market_id}/countries":
+ "/api/v3/store/customer/gift_cards/{id}":
get:
- summary: List countries in a market
+ summary: Get a gift card
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Returns countries belonging to a specific market. Use this for
- address form country dropdowns during checkout.
+ bearer_auth: []
+ description: Returns a gift card by its ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4404,17 +4464,23 @@ paths:
publishableKey: '<api-key>',
})
- const countries = await client.markets.countries.list('mkt_xxx')
+ const giftCard = await client.customer.giftCards.get('gc_abc123', {
+ bearerToken: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: market_id
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
in: path
required: true
- description: Market prefixed ID
schema:
type: string
- name: fields
@@ -4426,37 +4492,49 @@ paths:
type: string
responses:
'200':
- description: countries found
+ description: gift card found
content:
application/json:
example:
- data:
- - iso: FR
- iso3: IS53
- name: France
- states_required: false
- zipcode_required: true
- - iso: DE
- iso3: IS52
- name: Germany
- states_required: false
- zipcode_required: true
+ id: gc_UkLWZg9DAJ
+ code: A8CECCF67EA14278
+ state: active
+ currency: USD
+ amount: '10.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '10.0'
+ display_amount: "$10.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$10.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
+ created_at: '2026-03-11T20:16:35.429Z'
+ updated_at: '2026-03-11T20:16:35.429Z'
schema:
- type: object
- properties:
- data:
- type: array
- required:
- - data
- "/api/v3/store/markets/{market_id}/countries/{id}":
- get:
- summary: Get a country in a market
+ "$ref": "#/components/schemas/GiftCard"
+ '404':
+ description: gift card not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Gift card not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/cart/items":
+ post:
+ summary: Add item to cart
tags:
- - Markets
+ - Cart
security:
- api_key: []
- description: Returns a single country by ISO code within a market. Supports
- ?expand=states for address forms.
+ bearer_auth: []
+ description: Adds a variant to the cart. Creates a new line item or increases
+ quantity if variant already in cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4468,65 +4546,201 @@ paths:
publishableKey: '<api-key>',
})
- const country = await client.markets.countries.get('mkt_xxx', 'DE')
+ const cart = await client.cart.items.add({
+ variant_id: 'variant_abc123',
+ quantity: 2,
+ }, {
+ bearerToken: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: market_id
- in: path
- required: true
- description: Market prefixed ID
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: id
- in: path
- required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "DE")
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
schema:
type: string
- - name: fields
- in: query
+ - name: Idempotency-Key
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '200':
- description: country found
+ '201':
+ description: item added with metadata
content:
application/json:
example:
- iso: US
- iso3: USA
- name: United States of America
- states_required: true
- zipcode_required: true
+ id: cart_UkLWZg9DAJ
+ number: R516823008
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: PedZ9zcDBZR1Bhyd2mF9nnzXAmNJQXpjrtP
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 2
+ state_lock_version: 1
+ item_total: '29.99'
+ display_item_total: "$29.99"
+ ship_total: '0.0'
+ display_ship_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '29.99'
+ display_total: "$29.99"
+ created_at: '2026-03-11T20:16:37.178Z'
+ updated_at: '2026-03-11T20:16:37.272Z'
+ order_promotions: []
+ line_items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 449502
+ slug: product-449502
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:37.204Z'
+ updated_at: '2026-03-11T20:16:37.204Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ - id: li_gbHJdmfrXB
+ variant_id: variant_gbHJdmfrXB
+ quantity: 1
+ currency: USD
+ name: Product 458133
+ slug: product-458133
+ options_text: ''
+ price: '19.99'
+ display_price: "$19.99"
+ total: '19.99'
+ display_total: "$19.99"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '19.99'
+ display_pre_tax_amount: "$19.99"
+ discounted_amount: '19.99'
+ display_discounted_amount: "$19.99"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-11T20:16:37.239Z'
+ updated_at: '2026-03-11T20:16:37.239Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments: []
+ payments: []
+ bill_address:
+ id: addr_EfhxLZ9ck8
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 166 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_177
+ state_abbr: STATE_ABBR_177
+ quick_checkout: false
+ state_name: STATE_NAME_177
+ ship_address:
+ payment_methods: []
schema:
- type: object
+ "$ref": "#/components/schemas/Cart"
'404':
- description: country not in market
+ description: variant not found
content:
application/json:
example:
error:
- code: record_not_found
- message: Country not found
+ code: variant_not_found
+ message: Variant not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{id}":
- get:
- summary: Get an order
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ variant_id:
+ type: string
+ example: variant_abc123
+ description: Variant ID to add
+ quantity:
+ type: integer
+ example: 2
+ description: 'Quantity to add (default: 1)'
+ metadata:
+ type: object
+ additionalProperties: true
+ description: Arbitrary key-value metadata
+ example:
+ gift_message: Happy Birthday!
+ required:
+ - variant_id
+ "/api/v3/store/cart/items/{id}":
+ patch:
+ summary: Update line item quantity
tags:
- - Orders
+ - Cart
security:
- api_key: []
bearer_auth: []
- description: Returns a single order by ID or number. Guests must provide the
- x-spree-order-token header.
+ description: Updates the quantity of a line item in the cart
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4538,8 +4752,8 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.get('or_abc123', {
- expand: 'line_items,shipments',
+ const cart = await client.cart.items.update('li_abc123', {
+ quantity: 5,
}, {
bearerToken: '<token>',
})
@@ -4557,55 +4771,38 @@ paths:
- name: id
in: path
required: true
- description: Order ID (prefixed) or order number
+ description: Line item ID
schema:
type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
- description: Order token for guest access
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Expand associations (line_items, shipments, payments)
- 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: order found (guest with token)
+ description: metadata updated on line item
content:
application/json:
example:
- id: or_gbHJdmfrXB
- number: R940809780
+ id: cart_UkLWZg9DAJ
+ number: R467731208
state: cart
checkout_steps:
- address
- delivery
- - payment
- complete
- token: VKHJYstcpDPxeEnBaMYwSvSiM3nXWPojae9
- email:
+ token: XmefX8ayavKS3bKQeYx57guiYpJMBRcHoXM
special_instructions:
currency: USD
locale: en
- item_count: 1
- state_lock_version: 0
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
+ item_count: 0
+ state_lock_version: 1
+ item_total: '0.0'
+ display_item_total: "$0.00"
+ ship_total: '0.0'
+ display_ship_total: "$0.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
promo_total: '0.0'
@@ -4616,19 +4813,18 @@ paths:
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:46:06.349Z'
- updated_at: '2026-03-11T14:46:06.399Z'
+ total: '0.0'
+ display_total: "$0.00"
+ created_at: '2026-03-11T20:16:39.006Z'
+ updated_at: '2026-03-11T20:16:39.040Z'
order_promotions: []
line_items:
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 443663
- slug: product-443663
+ name: Product 487545
+ slug: product-487545
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4647,55 +4843,20 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:06.379Z'
- updated_at: '2026-03-11T14:46:06.379Z'
+ created_at: '2026-03-11T20:16:39.039Z'
+ updated_at: '2026-03-11T20:16:39.060Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
- shipments:
- - id: ship_gbHJdmfrXB
- number: H28618015022
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:46:06.386Z'
- updated_at: '2026-03-11T14:46:06.397Z'
- shipping_method:
- id: shpm_gbHJdmfrXB
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_170
- name: Davida Deckow
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_170
- shipping_rates:
- - id: shpr_gbHJdmfrXB
- shipping_method_id: shpm_gbHJdmfrXB
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_gbHJdmfrXB
- name: UPS Ground
- code: UPS_GROUND
+ shipments: []
payments: []
bill_address:
- id: addr_uw2YK1rnl0
+ id: addr_EfhxLZ9ck8
firstname: John
lastname: Doe
full_name: John Doe
- address1: 163 Lovely Street
+ address1: 175 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -4703,49 +4864,38 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_174
- state_abbr: STATE_ABBR_174
+ state_text: STATE_ABBR_186
+ state_abbr: STATE_ABBR_186
quick_checkout: false
- state_name: STATE_NAME_174
+ state_name: STATE_NAME_186
ship_address:
- id: addr_OIJLhNcSbf
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 164 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_175
- state_abbr: STATE_ABBR_175
- quick_checkout: false
- state_name: STATE_NAME_175
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: not found - order belongs to another user
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Couldn't find Spree::Order with 'id'=2 [WHERE "spree_orders"."store_id"
- = ? AND "spree_orders"."user_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update an order
+ "$ref": "#/components/schemas/Cart"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ quantity:
+ type: integer
+ minimum: 1
+ example: 5
+ metadata:
+ type: object
+ additionalProperties: true
+ description: Arbitrary key-value metadata (merged with existing)
+ example:
+ engraving: J.D.
+ delete:
+ summary: Remove line item from cart
tags:
- - Checkout
+ - Cart
security:
- api_key: []
bearer_auth: []
- description: Updates order attributes like email, special instructions, or addresses
+ description: Removes a line item from the cart
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4753,26 +4903,11 @@ paths:
import { createClient } from '@spree/sdk'
const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const order = await client.orders.update('or_abc123', {
- email: '[email protected]',
- special_instructions: 'Leave at door',
- line_items: [
- { variant_id: 'variant_abc123', quantity: 2 },
- ],
- bill_address: {
- firstname: 'John',
- lastname: 'Doe',
- address1: '123 Main St',
- city: 'New York',
- zipcode: '10001',
- country_iso: 'US',
- state_abbr: 'NY',
- },
- }, {
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const cart = await client.cart.items.remove('li_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -4791,45 +4926,35 @@ paths:
required: true
schema:
type: string
- - name: x-spree-order-token
- in: header
- required: false
- schema:
- type: string
- - name: Idempotency-Key
+ - name: x-spree-token
in: header
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
schema:
type: string
responses:
'200':
- description: order updated with metadata
+ description: line item removed, returns updated cart
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R463665774
+ id: cart_UkLWZg9DAJ
+ number: R770244240
state: cart
checkout_steps:
- address
- delivery
- - payment
- complete
- token: StutsTbAPhZaKLCy3UbnxWejcoK1gaQzXw8
+ token: 2wDhy4RHwbhhSD3voBxYTt5x8VmEtrDTweh
special_instructions:
currency: USD
locale: en
- item_count: 1
+ item_count: 0
state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
+ item_total: '0.0'
+ display_item_total: "$0.00"
+ ship_total: '0.0'
+ display_ship_total: "$0.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
promo_total: '0.0'
@@ -4840,86 +4965,20 @@ paths:
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:46:09.751Z'
- updated_at: '2026-03-11T14:46:09.829Z'
+ total: '0.0'
+ display_total: "$0.00"
+ created_at: '2026-03-11T20:16:39.615Z'
+ updated_at: '2026-03-11T20:16:39.702Z'
order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 505081
- slug: product-505081
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:09.786Z'
- updated_at: '2026-03-11T14:46:09.786Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H15150422408
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:46:09.793Z'
- updated_at: '2026-03-11T14:46:09.809Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_193
- name: Shaniqua Ebert
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_193
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
+ line_items: []
+ shipments: []
payments: []
bill_address:
id: addr_EfhxLZ9ck8
firstname: John
lastname: Doe
full_name: John Doe
- address1: 184 Lovely Street
+ address1: 178 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -4927,157 +4986,190 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_195
- state_abbr: STATE_ABBR_195
+ state_text: STATE_ABBR_189
+ state_abbr: STATE_ABBR_189
quick_checkout: false
- state_name: STATE_NAME_195
+ state_name: STATE_NAME_189
ship_address:
- id: addr_VqXmZF31wY
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 185 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_196
- state_abbr: STATE_ABBR_196
- quick_checkout: false
- state_name: STATE_NAME_196
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
- '403':
- description: cannot update completed order
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: line item not found
+ content:
+ application/json:
+ example:
+ error:
+ code: line_item_not_found
+ message: Line item not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/locales":
+ get:
+ summary: List supported locales
+ tags:
+ - Internationalization
+ security:
+ - api_key: []
+ description: Returns locales 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 locales = await client.locales.list()
+ 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.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: locales found
+ content:
+ application/json:
+ example:
+ data:
+ - code: de
+ name: de
+ - code: en
+ name: English (US)
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Locale"
+ 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/markets":
+ get:
+ summary: List markets
+ tags:
+ - Markets
+ security:
+ - api_key: []
+ description: Returns all markets for the current store with their countries,
+ currency, locales, and tax configuration.
+ 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 markets = await client.markets.list()
+ 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.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: markets found
+ content:
+ application/json:
+ example:
+ data:
+ - id: mkt_UkLWZg9DAJ
+ name: North America
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ supported_locales:
+ - en
+ - es
+ countries:
+ - iso: US
+ iso3: USA
+ name: United States of America
+ states_required: true
+ zipcode_required: true
+ - id: mkt_gbHJdmfrXB
+ name: Europe
+ currency: EUR
+ default_locale: de
+ tax_inclusive: true
+ default: false
+ supported_locales:
+ - de
+ - en
+ - fr
+ countries:
+ - iso: DE
+ iso3: IS45
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ - iso: FR
+ iso3: IS46
+ name: France
+ states_required: false
+ zipcode_required: true
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ required:
+ - data
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: access_denied
- message: You are not authorized to access this page.
+ 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
- locale:
- type: string
- example: en
- special_instructions:
- type: string
- example: Leave at door
- metadata:
- type: object
- additionalProperties: true
- description: Arbitrary key-value metadata (merged with existing)
- example:
- source: mobile_app
- bill_address:
- type: object
- properties:
- firstname:
- type: string
- example: John
- lastname:
- type: string
- example: Doe
- address1:
- type: string
- example: 123 Main St
- address2:
- type: string
- example: Apt 4B
- city:
- type: string
- example: New York
- zipcode:
- type: string
- example: '10001'
- phone:
- type: string
- example: "+1 555 123 4567"
- company:
- type: string
- example: Acme Inc
- country_iso:
- type: string
- example: US
- state_abbr:
- type: string
- example: NY
- ship_address:
- type: object
- properties:
- firstname:
- type: string
- example: Jane
- lastname:
- type: string
- example: Smith
- address1:
- type: string
- example: 456 Oak Ave
- address2:
- type: string
- example: Suite 200
- city:
- type: string
- example: Los Angeles
- zipcode:
- type: string
- example: '90001'
- phone:
- type: string
- example: "+1 555 987 6543"
- company:
- type: string
- country_iso:
- type: string
- example: US
- state_abbr:
- type: string
- example: CA
- line_items:
- type: array
- description: Line items to upsert (sets quantity for existing variants,
- creates new line items)
- items:
- type: object
- properties:
- variant_id:
- type: string
- example: variant_abc123
- description: Prefixed variant ID
- quantity:
- type: integer
- example: 2
- description: Quantity to set (defaults to 1)
- metadata:
- type: object
- additionalProperties: true
- description: Arbitrary key-value metadata (merged with existing)
- required:
- - variant_id
- "/api/v3/store/orders/{id}/next":
- patch:
- summary: Advance to next checkout step
+ "/api/v3/store/markets/{id}":
+ get:
+ summary: Get a market
tags:
- - Checkout
+ - Markets
security:
- api_key: []
- bearer_auth: []
- description: Advances the order to the next state in the checkout flow
+ description: Returns a single market by prefixed ID with its countries, currency,
+ locales, and tax configuration.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5089,205 +5181,77 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.next('or_abc123', {
- bearerToken: '<token>',
- })
+ const market = await client.markets.get('mkt_xxx')
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: false
- schema:
- type: string
- name: id
in: path
required: true
+ description: Market prefixed ID (e.g., "mkt_k5nR8xLq")
schema:
type: string
- - name: x-spree-order-token
- in: header
- required: false
- schema:
- type: string
- - name: Idempotency-Key
- in: header
+ - name: fields
+ in: query
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: order advanced
+ description: market found
content:
application/json:
example:
- id: or_gbHJdmfrXB
- number: R872065977
- state: address
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: DMW6AkxApqY2i3C5y1ExYVgX3yk2EDUNdvD
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:46:11.123Z'
- updated_at: '2026-03-11T14:46:11.199Z'
- order_promotions: []
- line_items:
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
- quantity: 1
- currency: USD
- name: Product 549296
- slug: product-549296
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:11.149Z'
- updated_at: '2026-03-11T14:46:11.149Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_gbHJdmfrXB
- number: H79412789239
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:46:11.162Z'
- updated_at: '2026-03-11T14:46:11.175Z'
- shipping_method:
- id: shpm_gbHJdmfrXB
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_203
- name: Corrin Parker
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_203
- shipping_rates:
- - id: shpr_gbHJdmfrXB
- shipping_method_id: shpm_gbHJdmfrXB
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_gbHJdmfrXB
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- bill_address:
- id: addr_uw2YK1rnl0
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 196 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_207
- state_abbr: STATE_ABBR_207
- quick_checkout: false
- state_name: STATE_NAME_207
- ship_address:
- id: addr_OIJLhNcSbf
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 197 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_208
- state_abbr: STATE_ABBR_208
- quick_checkout: false
- state_name: STATE_NAME_208
- payment_methods: []
+ id: mkt_gbHJdmfrXB
+ name: Europe
+ currency: EUR
+ default_locale: de
+ tax_inclusive: true
+ default: false
+ supported_locales:
+ - de
+ - en
+ - fr
+ countries:
+ - iso: DE
+ iso3: IS49
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ - iso: FR
+ iso3: IS50
+ name: France
+ states_required: false
+ zipcode_required: true
schema:
- "$ref": "#/components/schemas/Order"
- '422':
- description: cannot advance - validation errors
+ type: object
+ '404':
+ description: market not found
content:
application/json:
example:
error:
- code: order_cannot_transition
- message: We are unable to calculate shipping rates for the selected
- items.
+ code: record_not_found
+ message: Couldn't find Spree::Market with 'id'=245546638656678833
+ [WHERE "spree_markets"."deleted_at" IS NULL AND "spree_markets"."store_id"
+ = ?]
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{id}/advance":
- patch:
- summary: Advance through checkout
+ "/api/v3/store/markets/resolve":
+ get:
+ summary: Resolve market by country
tags:
- - Checkout
+ - Markets
security:
- api_key: []
- bearer_auth: []
- description: Advances the order through all possible checkout states
+ description: Determine which market applies for a given country ISO code. Useful
+ for auto-selecting the correct currency and locale when a customer's location
+ is known.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5299,204 +5263,208 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.advance('or_abc123', {
- bearerToken: '<token>',
- })
+ const market = await client.markets.resolve('DE')
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: country
+ in: query
+ required: true
+ description: Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")
+ 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
- - name: id
- in: path
+ responses:
+ '200':
+ description: market resolved
+ content:
+ application/json:
+ example:
+ id: mkt_gbHJdmfrXB
+ name: Europe
+ currency: EUR
+ default_locale: de
+ tax_inclusive: true
+ default: false
+ supported_locales:
+ - de
+ - en
+ - fr
+ countries:
+ - iso: DE
+ iso3: IS53
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ - iso: FR
+ iso3: IS54
+ name: France
+ states_required: false
+ zipcode_required: true
+ schema:
+ type: object
+ '404':
+ description: no market for country
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Country not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/markets/{market_id}/countries":
+ get:
+ summary: List countries in a market
+ tags:
+ - Markets
+ security:
+ - api_key: []
+ description: Returns countries belonging to a specific market. Use this for
+ address form country dropdowns during checkout.
+ 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 countries = await client.markets.countries.list('mkt_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
required: true
schema:
type: string
- - name: x-spree-order-token
- in: header
- required: false
+ - name: market_id
+ in: path
+ required: true
+ description: Market prefixed ID
schema:
type: string
- - name: Idempotency-Key
- in: header
+ - name: fields
+ in: query
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: order advanced
+ description: countries found
content:
application/json:
example:
- id: or_gbHJdmfrXB
- number: R076286330
- state: payment
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: haEJssNxc12QAR3dRYeS7ZHdqfwXArRd4e6
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state: backorder
- payment_state: balance_due
- item_total: '19.99'
- display_item_total: "$19.99"
- ship_total: '10.0'
- display_ship_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '29.99'
- display_total: "$29.99"
- completed_at:
- created_at: '2026-03-11T14:46:12.426Z'
- updated_at: '2026-03-11T14:46:12.631Z'
- order_promotions: []
- line_items:
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
- quantity: 1
- currency: USD
- name: Product 57296
- slug: product-57296
- options_text: ''
- price: '19.99'
- display_price: "$19.99"
- total: '19.99'
- display_total: "$19.99"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '19.99'
- display_pre_tax_amount: "$19.99"
- discounted_amount: '19.99'
- display_discounted_amount: "$19.99"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:12.452Z'
- updated_at: '2026-03-11T14:46:12.533Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_EfhxLZ9ck8
- number: H90196871256
- state: pending
- tracking:
- tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
- shipped_at:
- created_at: '2026-03-11T14:46:12.565Z'
- updated_at: '2026-03-11T14:46:12.586Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_213
- name: Lavenia Hackett
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_213
- shipping_rates:
- - id: shpr_EfhxLZ9ck8
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- - id: shpr_VqXmZF31wY
- shipping_method_id: shpm_gbHJdmfrXB
- name: UPS Ground
- selected: false
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_gbHJdmfrXB
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- bill_address:
- id: addr_uw2YK1rnl0
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 206 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_217
- state_abbr: STATE_ABBR_217
- quick_checkout: false
- state_name: STATE_NAME_217
- ship_address:
- id: addr_OIJLhNcSbf
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 207 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_218
- state_abbr: STATE_ABBR_218
- quick_checkout: false
- state_name: STATE_NAME_218
- payment_methods: []
+ data:
+ - iso: FR
+ iso3: IS58
+ name: France
+ states_required: false
+ zipcode_required: true
+ - iso: DE
+ iso3: IS57
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ required:
+ - data
+ "/api/v3/store/markets/{market_id}/countries/{id}":
+ get:
+ summary: Get a country in a market
+ tags:
+ - Markets
+ security:
+ - api_key: []
+ description: Returns a single country by ISO code within a market. Supports
+ ?expand=states for address forms.
+ 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 country = await client.markets.countries.get('mkt_xxx', 'DE')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: market_id
+ in: path
+ required: true
+ description: Market prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Country ISO 3166-1 alpha-2 code (e.g., "DE")
+ 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: country found
+ content:
+ application/json:
+ example:
+ iso: US
+ iso3: USA
+ name: United States of America
+ states_required: true
+ zipcode_required: true
schema:
- "$ref": "#/components/schemas/Order"
- "/api/v3/store/orders/{id}/complete":
- patch:
- summary: Complete the order
+ type: object
+ '404':
+ description: country not in market
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Country not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/orders/{id}":
+ get:
+ summary: Get an order
tags:
- - Checkout
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Completes the order (finalizes the purchase)
+ description: Returns a single completed order by prefixed ID. Accessible via
+ JWT (authenticated users) or order token header (guests).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5508,7 +5476,7 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.complete('or_abc123', {
+ const order = await client.orders.get('or_abc123', {
bearerToken: '<token>',
})
parameters:
@@ -5520,52 +5488,40 @@ paths:
- name: Authorization
in: header
required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- name: id
in: path
required: true
+ description: Order prefixed ID
schema:
type: string
- - name: x-spree-order-token
- in: header
- required: false
- schema:
- type: string
- - name: Idempotency-Key
+ - name: x-spree-token
in: header
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Order token for guest access
schema:
type: string
responses:
'200':
- description: order completed
+ description: order found (guest via order token)
content:
application/json:
example:
- id: or_gbHJdmfrXB
- number: R312364650
- state: complete
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: HHo1kQ5b6gYW3igDaaZydKnK8YgWNQMMGZ1
+ id: or_UkLWZg9DAJ
+ number: R286057069
special_instructions:
currency: USD
locale: en
item_count: 1
- state_lock_version: 1
- shipment_state: backorder
- payment_state: balance_due
- item_total: '19.99'
- display_item_total: "$19.99"
- ship_total: '10.0'
- display_ship_total: "$10.00"
+ shipment_state:
+ payment_state:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
promo_total: '0.0'
@@ -5576,24 +5532,24 @@ paths:
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '29.99'
- display_total: "$29.99"
- completed_at: '2026-03-11T14:46:13.566Z'
- created_at: '2026-03-11T14:46:13.339Z'
- updated_at: '2026-03-11T14:46:13.566Z'
+ total: '110.0'
+ display_total: "$110.00"
+ completed_at: '2026-03-11T20:16:41.401Z'
+ created_at: '2026-03-11T20:16:41.353Z'
+ updated_at: '2026-03-11T20:16:41.401Z'
order_promotions: []
line_items:
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 591606
- slug: product-591606
+ name: Product 526850
+ slug: product-526850
options_text: ''
- price: '19.99'
- display_price: "$19.99"
- total: '19.99'
- display_total: "$19.99"
+ 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'
@@ -5602,44 +5558,44 @@ paths:
display_included_tax_total: "$0.00"
promo_total: '0.0'
display_promo_total: "$0.00"
- pre_tax_amount: '19.99'
- display_pre_tax_amount: "$19.99"
- discounted_amount: '19.99'
- display_discounted_amount: "$19.99"
+ 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-11T14:46:13.363Z'
- updated_at: '2026-03-11T14:46:13.433Z'
+ created_at: '2026-03-11T20:16:41.380Z'
+ updated_at: '2026-03-11T20:16:41.380Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- - id: ship_EfhxLZ9ck8
- number: H47261238756
+ - id: ship_UkLWZg9DAJ
+ number: H90765027023
state: pending
- tracking:
+ tracking: U10000
tracking_url:
- cost: '10.0'
- display_cost: "$10.00"
+ cost: '100.0'
+ display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:46:13.460Z'
- updated_at: '2026-03-11T14:46:13.558Z'
+ created_at: '2026-03-11T20:16:41.385Z'
+ updated_at: '2026-03-11T20:16:41.398Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_219
- name: Candie Toy
+ state_abbr: STATE_ABBR_197
+ name: Toni Hessel
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_219
+ state_text: STATE_ABBR_197
shipping_rates:
- - id: shpr_EfhxLZ9ck8
+ - id: shpr_gbHJdmfrXB
shipping_method_id: shpm_UkLWZg9DAJ
name: UPS Ground
selected: true
@@ -5649,49 +5605,13 @@ paths:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
- - id: shpr_VqXmZF31wY
- shipping_method_id: shpm_gbHJdmfrXB
- name: UPS Ground
- selected: false
- cost: '10.0'
- display_cost: "$10.00"
- shipping_method:
- id: shpm_gbHJdmfrXB
- name: UPS Ground
- code: UPS_GROUND
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- state: checkout
- response_code: '12345'
- number: P2QKNM5G
- amount: '29.99'
- display_amount: "$29.99"
- created_at: '2026-03-11T14:46:13.532Z'
- updated_at: '2026-03-11T14:46:13.532Z'
- source_type: credit_card
- source_id: card_UkLWZg9DAJ
- source:
- id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Check
- description:
- type: Spree::PaymentMethod::Check
- session_required: false
+ payments: []
bill_address:
- id: addr_uw2YK1rnl0
+ id: addr_UkLWZg9DAJ
firstname: John
lastname: Doe
full_name: John Doe
- address1: 212 Lovely Street
+ address1: 186 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -5699,16 +5619,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_223
- state_abbr: STATE_ABBR_223
+ state_text: STATE_ABBR_197
+ state_abbr: STATE_ABBR_197
quick_checkout: false
- state_name: STATE_NAME_223
+ state_name: STATE_NAME_197
ship_address:
- id: addr_OIJLhNcSbf
+ id: addr_gbHJdmfrXB
firstname: John
lastname: Doe
full_name: John Doe
- address1: 213 Lovely Street
+ address1: 187 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -5716,34 +5636,25 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_224
- state_abbr: STATE_ABBR_224
+ state_text: STATE_ABBR_198
+ state_abbr: STATE_ABBR_198
quick_checkout: false
- state_name: STATE_NAME_224
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Check
- description:
- type: Spree::PaymentMethod::Check
- session_required: false
- - id: pm_gbHJdmfrXB
- name: Credit Card
- description:
- type: Spree::Gateway::Bogus
- session_required: true
+ state_name: STATE_NAME_198
schema:
"$ref": "#/components/schemas/Order"
- '422':
- description: cannot complete
+ '404':
+ description: incomplete order not accessible
content:
application/json:
example:
error:
- code: order_already_completed
- message: No payment found
+ code: order_not_found
+ message: Couldn't find Spree::Order with 'id'=1 [WHERE "spree_orders"."store_id"
+ = ? AND "spree_orders"."completed_at" IS NOT NULL AND "spree_orders"."user_id"
+ = ?]
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/payment_methods":
+ "/api/v3/store/checkout/payment_methods":
get:
summary: List available payment methods
tags:
@@ -5751,8 +5662,8 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: Returns payment methods available for the order based on store
- configuration and order state
+ description: Returns payment methods available for the current cart based on
+ store configuration and order state.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5764,7 +5675,7 @@ paths:
publishableKey: '<api-key>',
})
- const methods = await client.orders.paymentMethods.list('or_abc123', {
+ const methods = await client.checkout.paymentMethods.list({
bearerToken: '<token>',
})
parameters:
@@ -5776,16 +5687,13 @@ paths:
- name: Authorization
in: header
required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
+ description: Order token for guest access
schema:
type: string
responses:
@@ -5814,27 +5722,7 @@ paths:
properties:
count:
type: integer
- '404':
- description: order not found
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/payment_sessions":
+ "/api/v3/store/checkout/payment_sessions":
post:
summary: Create payment session
tags:
@@ -5842,8 +5730,8 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: Creates a new payment session for the specified order. Delegates
- to the payment gateway to initialize a provider-specific session (e.g. Stripe
+ description: Creates a new payment session for the current cart. Delegates to
+ the payment gateway to initialize a provider-specific session (e.g. Stripe
PaymentIntent, Adyen session, PayPal order).
x-codeSamples:
- lang: javascript
@@ -5856,7 +5744,7 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.orders.paymentSessions.create('or_abc123', {
+ const session = await client.checkout.paymentSessions.create({
payment_method_id: 'pm_abc123',
}, {
bearerToken: '<token>',
@@ -5873,13 +5761,7 @@ paths:
description: Bearer token for authenticated customers
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order ID or number
- schema:
- type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
description: Order token for guest access
@@ -5888,8 +5770,7 @@ paths:
- name: Idempotency-Key
in: header
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Unique key for request idempotency.
schema:
type: string
responses:
@@ -5901,13 +5782,13 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_c3f5b9f7bac3e180e6ca9e52
+ external_id: bogus_939206b9e39cf38a11c26a57
external_data:
- client_secret: bogus_secret_7a9472fcff4f3952
+ client_secret: bogus_secret_f4c6242151dd9228
customer_external_id:
expires_at:
- created_at: '2026-03-11T14:46:16.078Z'
- updated_at: '2026-03-11T14:46:16.078Z'
+ created_at: '2026-03-11T20:16:43.811Z'
+ updated_at: '2026-03-11T20:16:43.811Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5919,16 +5800,6 @@ paths:
session_required: true
schema:
"$ref": "#/components/schemas/PaymentSession"
- '404':
- description: order not found
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
@@ -5949,7 +5820,7 @@ paths:
description: Provider-specific data passed to the gateway
required:
- payment_method_id
- "/api/v3/store/orders/{order_id}/payment_sessions/{id}":
+ "/api/v3/store/checkout/payment_sessions/{id}":
parameters:
- name: x-spree-api-key
in: header
@@ -5962,19 +5833,13 @@ paths:
description: Bearer token for authenticated customers
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order ID or number
- schema:
- type: string
- name: id
in: path
required: true
description: Payment session ID
schema:
type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
description: Order token for guest access
@@ -6000,7 +5865,7 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.orders.paymentSessions.get('or_abc123', 'ps_abc123', {
+ const session = await client.checkout.paymentSessions.get('ps_abc123', {
bearerToken: '<token>',
})
responses:
@@ -6012,13 +5877,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_336d5c5b9c794137ab1abedc
+ external_id: bogus_bc82c2673de64ed729f48e41
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-11T14:46:17.421Z'
- updated_at: '2026-03-11T14:46:17.421Z'
+ created_at: '2026-03-11T20:16:44.400Z'
+ updated_at: '2026-03-11T20:16:44.400Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6060,7 +5925,7 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.orders.paymentSessions.update('or_abc123', 'ps_abc123', {
+ const session = await client.checkout.paymentSessions.update('ps_abc123', {
amount: '50.00',
}, {
bearerToken: '<token>',
@@ -6075,13 +5940,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_7852464e9e675ece9c58a135
+ external_id: bogus_f316a00803e0c9e1401ae1c3
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-11T14:46:18.755Z'
- updated_at: '2026-03-11T14:46:18.767Z'
+ created_at: '2026-03-11T20:16:45.634Z'
+ updated_at: '2026-03-11T20:16:45.647Z'
amount: '50.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6106,7 +5971,7 @@ paths:
external_data:
type: object
description: Provider-specific data to update
- "/api/v3/store/orders/{order_id}/payment_sessions/{id}/complete":
+ "/api/v3/store/checkout/payment_sessions/{id}/complete":
parameters:
- name: x-spree-api-key
in: header
@@ -6119,19 +5984,13 @@ paths:
description: Bearer token for authenticated customers
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order ID or number
- schema:
- type: string
- name: id
in: path
required: true
description: Payment session ID
schema:
type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
description: Order token for guest access
@@ -6157,7 +6016,7 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.orders.paymentSessions.complete('or_abc123', 'ps_abc123', {
+ const session = await client.checkout.paymentSessions.complete('ps_abc123', {
session_result: 'success',
}, {
bearerToken: '<token>',
@@ -6166,8 +6025,7 @@ paths:
- name: Idempotency-Key
in: header
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Unique key for request idempotency.
schema:
type: string
responses:
@@ -6179,13 +6037,13 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_4549bc3eab40446299163180
+ external_id: bogus_62e29b242af47209c88c5c5f
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-11T14:46:19.432Z'
- updated_at: '2026-03-11T14:46:19.449Z'
+ created_at: '2026-03-11T20:16:46.249Z'
+ updated_at: '2026-03-11T20:16:46.262Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6265,11 +6123,11 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_3d2fa5f1f03bda163c29a912
- external_client_secret: bogus_seti_secret_74ba16f4d510ce3e
+ external_id: bogus_seti_01a4dd0b5363cfafaa72ac6e
+ external_client_secret: bogus_seti_secret_16408d9c954c43f8
external_data: {}
- created_at: '2026-03-11T14:46:20.660Z'
- updated_at: '2026-03-11T14:46:20.660Z'
+ created_at: '2026-03-11T20:16:47.484Z'
+ updated_at: '2026-03-11T20:16:47.484Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6366,12 +6224,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_bcc8c5aa477a9c34899e35b1
- external_client_secret: seti_secret_ffcead150899cf16e5b4301a
+ external_id: seti_test_a011106e2f58cb1c542cb4d1
+ external_client_secret: seti_secret_0b2f92f40bd0afbbf7044da3
external_data:
client_secret: secret_123
- created_at: '2026-03-11T14:46:22.386Z'
- updated_at: '2026-03-11T14:46:22.386Z'
+ created_at: '2026-03-11T20:16:49.187Z'
+ updated_at: '2026-03-11T20:16:49.187Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6444,12 +6302,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_5d5f199c34c93bcb73eb3431
- external_client_secret: seti_secret_b3c37c1c53c57b970fcb8818
+ external_id: seti_test_66940b447b5069ab23b8d9fe
+ external_client_secret: seti_secret_ed8707996cca86b59bc6b1e7
external_data:
client_secret: secret_123
- created_at: '2026-03-11T14:46:23.508Z'
- updated_at: '2026-03-11T14:46:23.529Z'
+ created_at: '2026-03-11T20:16:50.300Z'
+ updated_at: '2026-03-11T20:16:50.313Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id: card_UkLWZg9DAJ
payment_source_type: Spree::CreditCard
@@ -6476,29 +6334,12 @@ paths:
content:
application/json:
schema:
- type: object
- properties:
- external_data:
- type: object
- description: Provider-specific completion data
- "/api/v3/store/orders/{order_id}/payments":
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: order_id
- in: path
- description: Order prefix ID
- required: true
- schema:
- type: string
+ type: object
+ properties:
+ external_data:
+ type: object
+ description: Provider-specific completion data
+ "/api/v3/store/checkout/payments":
get:
summary: List payments
tags:
@@ -6506,7 +6347,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: Returns a list of payments for the specified order
+ description: Returns all payments for the current cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6518,12 +6359,28 @@ paths:
publishableKey: '<api-key>',
})
- const payments = await client.orders.payments.list('or_abc123', {
+ const payments = await client.checkout.payments.list({
bearerToken: '<token>',
})
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ schema:
+ type: string
responses:
'200':
- description: payments found
+ description: payments listed
content:
application/json:
example:
@@ -6532,11 +6389,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PZB8DYTD
+ number: PJP8HO3U
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-11T14:46:24.725Z'
- updated_at: '2026-03-11T14:46:24.725Z'
+ created_at: '2026-03-11T20:16:51.472Z'
+ updated_at: '2026-03-11T20:16:51.472Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -6550,30 +6407,20 @@ paths:
gateway_payment_profile_id:
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card
+ name: Check
description:
- type: Spree::Gateway::Bogus
- session_required: true
- meta: {}
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Payment"
- meta:
- type: object
- '404':
- description: order not found
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ type: Spree::PaymentMethod::Check
+ session_required: false
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
post:
summary: Create payment
tags:
@@ -6595,13 +6442,23 @@ paths:
publishableKey: '<api-key>',
})
- const payment = await client.orders.payments.create('or_abc123', {
+ const payment = await client.checkout.createPayment({
payment_method_id: 'pm_abc123',
}, {
bearerToken: '<token>',
})
parameters:
- - name: x-spree-order-token
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ schema:
+ type: string
+ - name: x-spree-token
in: header
required: false
description: Order token for guest access
@@ -6613,20 +6470,20 @@ paths:
content:
application/json:
example:
- id: py_gbHJdmfrXB
- payment_method_id: pm_EfhxLZ9ck8
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code:
- number: P5W30ZLT
+ number: PL969YAG
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-11T14:46:25.982Z'
- updated_at: '2026-03-11T14:46:25.982Z'
+ created_at: '2026-03-11T20:16:52.105Z'
+ updated_at: '2026-03-11T20:16:52.105Z'
source_type:
source_id:
source:
payment_method:
- id: pm_EfhxLZ9ck8
+ id: pm_UkLWZg9DAJ
name: Check
description:
type: Spree::PaymentMethod::Check
@@ -6644,16 +6501,6 @@ paths:
payment sessions endpoint instead.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: order not found
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
@@ -6671,100 +6518,9 @@ paths:
credits)
metadata:
type: object
- description: Arbitrary metadata to attach to the payment (write-only,
- not returned in Store API responses)
+ description: Arbitrary metadata to attach to the payment
required:
- payment_method_id
- "/api/v3/store/orders/{order_id}/payments/{id}":
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: order_id
- in: path
- description: Order prefix ID
- required: true
- schema:
- type: string
- - name: id
- in: path
- description: Payment ID
- required: true
- schema:
- type: string
- get:
- summary: Get payment
- tags:
- - Checkout
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a single payment by 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 payment = await client.orders.payments.get('or_abc123', 'pay_abc123', {
- bearerToken: '<token>',
- })
- responses:
- '200':
- description: payment found
- content:
- application/json:
- example:
- id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- state: checkout
- response_code: '12345'
- number: PFXXLSLN
- amount: '110.0'
- display_amount: "$110.00"
- created_at: '2026-03-11T14:46:27.814Z'
- updated_at: '2026-03-11T14:46:27.814Z'
- source_type: credit_card
- source_id: card_UkLWZg9DAJ
- source:
- id: card_UkLWZg9DAJ
- cc_type: visa
- last_digits: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: Spree::Gateway::Bogus
- session_required: true
- schema:
- "$ref": "#/components/schemas/Payment"
- '404':
- description: payment not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Payment not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
"/api/v3/store/products":
get:
summary: List products
@@ -6879,18 +6635,17 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 791573
+ name: Product 648748
description: |-
- Dolor nihil nisi soluta voluptatem necessitatibus doloribus facilis. Accusantium quo esse at natus explicabo dolorem. Nesciunt corrupti quos voluptatibus exercitationem. Provident at natus molestias placeat odit veritatis. Enim temporibus maiores explicabo adipisci accusamus eius.
- Minima maiores porro aspernatur corporis ea deserunt quos. Accusantium libero dolor aspernatur rem omnis voluptatibus distinctio saepe. Inventore rerum temporibus voluptatum atque. Animi recusandae omnis ad commodi.
- Qui dicta amet consequuntur asperiores quasi esse blanditiis modi. Provident excepturi similique laborum ea. Repellat non hic temporibus nisi.
- slug: product-791573
+ Odio a officia sit perferendis vel quod doloremque. Dolore libero consectetur veniam aperiam odit consequatur eius. Aliquid praesentium illum facilis deleniti perspiciatis alias.
+ Beatae recusandae in odio impedit amet perferendis. Consequuntur repudiandae quis debitis quos aliquid necessitatibus totam. Ipsam commodi reprehenderit aperiam voluptatibus debitis odit dolorum itaque. Labore repellat perferendis ullam repudiandae.
+ slug: product-648748
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-11T14:46:28.471Z'
- created_at: '2026-03-11T14:46:28.484Z'
- updated_at: '2026-03-11T14:46:28.522Z'
+ available_on: '2025-03-11T20:16:52.791Z'
+ created_at: '2026-03-11T20:16:52.814Z'
+ updated_at: '2026-03-11T20:16:52.868Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6910,18 +6665,18 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 802302
+ name: Product 654485
description: |-
- Quo cum inventore ipsa ex ipsam quis. Optio et accusamus ducimus sed. Molestiae debitis libero culpa ipsum. Quam aspernatur eveniet adipisci dolorum.
- Suscipit ab quisquam magni velit perspiciatis veniam odio repellat. Necessitatibus ipsa quam amet reiciendis sunt. Doloremque quidem similique repellat nemo id deserunt dolor.
- Eaque occaecati nulla excepturi officia distinctio amet tempore. Voluptatem veniam corrupti sequi ullam placeat. Sit unde mollitia nulla repellendus ab dolor culpa.
- slug: product-802302
+ Occaecati deserunt voluptates quis quam optio quidem libero. Nobis cum nulla incidunt vitae optio. Ullam cumque molestiae hic sit nulla vel ratione. Voluptatem voluptas harum nihil quae expedita vel. Veritatis reprehenderit cupiditate tempora eos consectetur placeat iusto adipisci.
+ Quis necessitatibus et debitis explicabo nesciunt. Possimus earum neque nisi tempore. Dicta sint illo numquam culpa a.
+ Quia eligendi autem corporis vero tempora corrupti ducimus. Sit non necessitatibus delectus ullam doloribus. Explicabo laudantium voluptatibus doloribus atque corrupti odio.
+ slug: product-654485
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-03-11T14:46:28.527Z'
- created_at: '2026-03-11T14:46:28.536Z'
- updated_at: '2026-03-11T14:46:28.548Z'
+ available_on: '2025-03-11T20:16:52.874Z'
+ created_at: '2026-03-11T20:16:52.884Z'
+ updated_at: '2026-03-11T20:16:52.898Z'
purchasable: true
in_stock: false
backorderable: true
@@ -7027,19 +6782,18 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 916887
+ name: Product 767469
description: |-
- Velit atque repudiandae omnis ipsa magnam. Eaque molestiae facere consequatur molestias. Eius consequuntur sequi maxime quo.
- Facilis sed quasi laborum magnam repudiandae occaecati culpa ducimus. Illum dignissimos vero velit beatae non adipisci. Cupiditate deleniti adipisci nisi officia.
- Saepe iure odit rerum voluptatibus repudiandae blanditiis deleniti sequi. Fugit suscipit illum saepe cum et dignissimos. Autem nemo consectetur quae qui beatae nulla nostrum voluptatibus. Incidunt beatae dolore tempora amet corrupti quaerat quisquam.
- Vel quibusdam libero perspiciatis natus facere. Molestias accusantium cupiditate molestiae suscipit. Quidem perferendis facere laboriosam odio iste cum. Error illum deleniti non minus mollitia.
- slug: product-916887
+ Eum dolore accusantium temporibus ab nemo nulla itaque architecto. Quibusdam deserunt iste beatae magni nesciunt inventore porro. Aspernatur quos eius minus incidunt ratione cupiditate harum. Praesentium eum porro quasi sed placeat.
+ Facere voluptatum illo aspernatur dolore eligendi eveniet quae veniam. Veritatis voluptas officiis eligendi totam illum. Qui dolore deleniti voluptatum quidem.
+ Esse itaque magnam eligendi alias architecto a. Est dolorum dolorem magnam hic quo aperiam modi. Nesciunt suscipit vitae occaecati vel corporis.
+ slug: product-767469
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-11T14:46:29.120Z'
- created_at: '2026-03-11T14:46:29.134Z'
- updated_at: '2026-03-11T14:46:29.237Z'
+ available_on: '2025-03-11T20:16:53.494Z'
+ created_at: '2026-03-11T20:16:53.508Z'
+ updated_at: '2026-03-11T20:16:53.549Z'
purchasable: true
in_stock: false
backorderable: true
@@ -7186,148 +6940,46 @@ paths:
type: string
description: Default sort option ID
total_count:
- type: integer
- description: Total products matching current filters
- required:
- - filters
- - sort_options
- - default_sort
- - total_count
- '401':
- description: unauthorized - invalid or missing API key
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/shipments":
- get:
- summary: List shipments for an order
- tags:
- - Checkout
- security:
- - api_key: []
- bearer_auth: []
- description: Returns all shipments associated with the order
- 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 shipments = await client.orders.shipments.list('or_abc123', {
- bearerToken: '<token>',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: false
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: x-spree-order-token
- in: header
- required: false
- description: Order token for guest access
- schema:
- type: string
- responses:
- '200':
- description: shipments found
- content:
- application/json:
- example:
- data:
- - id: ship_UkLWZg9DAJ
- number: H56045510455
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:46:31.392Z'
- updated_at: '2026-03-11T14:46:31.406Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_317
- name: Len Corwin
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_317
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- 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/Shipment"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '404':
- description: order not found
+ type: integer
+ description: Total products matching current filters
+ required:
+ - filters
+ - sort_options
+ - default_sort
+ - total_count
+ '401':
+ description: unauthorized - invalid or missing API key
content:
application/json:
example:
error:
- code: order_not_found
- message: Order not found
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/shipments/{id}":
+ "/api/v3/store/checkout/shipments":
get:
- summary: Get a shipment
+ summary: List shipments
tags:
- Checkout
security:
- api_key: []
bearer_auth: []
- description: Returns details of a specific shipment
+ description: Returns all shipments with shipping rates for the current cart.
+ 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 shipments = await client.checkout.shipments.list({
+ bearerToken: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -7339,83 +6991,57 @@ paths:
required: false
schema:
type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Shipment ID
- schema:
- type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
description: Order token for guest access
schema:
type: string
- - name: expand
- in: query
- required: false
- description: Expand shipping_rates
- schema:
- type: string
responses:
'200':
- description: shipment found
+ description: shipments found
content:
application/json:
example:
- id: ship_UkLWZg9DAJ
- number: H00889849207
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-11T14:46:32.631Z'
- updated_at: '2026-03-11T14:46:32.658Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_325
- name: Louvenia Harvey
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_325
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
+ data:
+ - id: ship_UkLWZg9DAJ
+ number: H39889652757
+ state: pending
+ tracking: U10000
+ tracking_url:
cost: '100.0'
display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-11T20:16:55.577Z'
+ updated_at: '2026-03-11T20:16:55.591Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
- schema:
- "$ref": "#/components/schemas/Shipment"
- '404':
- description: shipment not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Couldn't find Spree::Shipment with 'id'=245546638656678833
- [WHERE "spree_shipments"."order_id" = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_269
+ name: Leonida Christiansen
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_269
+ shipping_rates:
+ - id: shpr_UkLWZg9DAJ
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ meta:
+ count: 1
+ "/api/v3/store/checkout/shipments/{id}":
patch:
summary: Select shipping rate for shipment
tags:
@@ -7423,7 +7049,8 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: Selects a shipping rate for the shipment
+ description: Selects a shipping rate for a specific shipment and auto-advances
+ checkout.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7435,8 +7062,8 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.shipments.update('or_abc123', 'shp_abc123', {
- selected_shipping_rate_id: 'shprt_abc123',
+ const cart = await client.checkout.shipments.update('ship_abc123', {
+ selected_shipping_rate_id: 'shpr_abc123',
}, {
bearerToken: '<token>',
})
@@ -7451,18 +7078,13 @@ paths:
required: false
schema:
type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- name: id
in: path
required: true
description: Shipment ID
schema:
type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
description: Order token for guest access
@@ -7470,27 +7092,25 @@ paths:
type: string
responses:
'200':
- description: shipping rate selected, returns updated order
+ description: shipping rate selected, returns updated cart
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R113462108
+ id: cart_UkLWZg9DAJ
+ number: R486934809
state: delivery
checkout_steps:
- address
- delivery
- payment
- complete
- token: oH5zJdWjEiE1WzuMXb3kSFhynrUmjUHWE3g
+ token: cFrQenShmVNV7uTV2ETsHJQGn1PWq1wbvt6
special_instructions:
currency: USD
locale: en
item_count: 1
state_lock_version: 1
- shipment_state:
- payment_state:
item_total: '10.0'
display_item_total: "$10.00"
ship_total: '100.0'
@@ -7507,17 +7127,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:46:33.866Z'
- updated_at: '2026-03-11T14:46:33.934Z'
+ created_at: '2026-03-11T20:16:56.155Z'
+ updated_at: '2026-03-11T20:16:56.243Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1233123
- slug: product-1233123
+ name: Product 105702
+ slug: product-105702
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7536,37 +7155,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:33.896Z'
- updated_at: '2026-03-11T14:46:33.896Z'
+ created_at: '2026-03-11T20:16:56.197Z'
+ updated_at: '2026-03-11T20:16:56.197Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H01376293569
+ number: H42723789632
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:46:33.901Z'
- updated_at: '2026-03-11T14:46:33.932Z'
+ created_at: '2026-03-11T20:16:56.204Z'
+ updated_at: '2026-03-11T20:16:56.242Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_333
- name: Mechelle Ledner
+ state_abbr: STATE_ABBR_273
+ name: Lizeth Bashirian
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_333
+ state_text: STATE_ABBR_273
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -7584,7 +7203,7 @@ paths:
firstname: John
lastname: Doe
full_name: John Doe
- address1: 314 Lovely Street
+ address1: 254 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -7592,16 +7211,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_335
- state_abbr: STATE_ABBR_335
+ state_text: STATE_ABBR_275
+ state_abbr: STATE_ABBR_275
quick_checkout: false
- state_name: STATE_NAME_335
+ state_name: STATE_NAME_275
ship_address:
id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 315 Lovely Street
+ address1: 255 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -7609,13 +7228,13 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_336
- state_abbr: STATE_ABBR_336
+ state_text: STATE_ABBR_276
+ state_abbr: STATE_ABBR_276
quick_checkout: false
- state_name: STATE_NAME_336
+ state_name: STATE_NAME_276
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Cart"
'404':
description: shipping rate not found
content:
@@ -7635,19 +7254,19 @@ paths:
properties:
selected_shipping_rate_id:
type: string
- example: shprt_abc123
+ example: shpr_abc123
description: Shipping rate ID to select
required:
- selected_shipping_rate_id
- "/api/v3/store/orders/{order_id}/store_credits":
+ "/api/v3/store/checkout/store_credits":
post:
- summary: Add store credit
+ summary: Apply store credit
tags:
- Checkout
security:
- api_key: []
bearer_auth: []
- description: Applies store credit to the order
+ description: Applies store credit to the current cart during checkout.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7659,7 +7278,7 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.addStoreCredit('or_abc123', 10.0, {
+ const cart = await client.checkout.applyStoreCredit(10.0, {
bearerToken: '<token>',
})
parameters:
@@ -7673,12 +7292,7 @@ paths:
required: true
schema:
type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
schema:
@@ -7686,8 +7300,7 @@ paths:
- name: Idempotency-Key
in: header
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Unique key for request idempotency.
schema:
type: string
responses:
@@ -7696,23 +7309,21 @@ paths:
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R418869961
+ id: cart_UkLWZg9DAJ
+ number: R769411673
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: MeADhwL96G5Zsy36KqthCP1mE9GawvfuuXw
+ token: 6kgCjWuw9VxQ4SuvK3KaBi3L5fF5sxoAiud
special_instructions:
currency: USD
locale: en
item_count: 1
state_lock_version: 1
- shipment_state:
- payment_state:
item_total: '10.0'
display_item_total: "$10.00"
ship_total: '100.0'
@@ -7729,17 +7340,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:46:35.123Z'
- updated_at: '2026-03-11T14:46:35.175Z'
+ created_at: '2026-03-11T20:16:57.400Z'
+ updated_at: '2026-03-11T20:16:57.447Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1254911
- slug: product-1254911
+ name: Product 1072748
+ slug: product-1072748
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7758,37 +7368,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:35.154Z'
- updated_at: '2026-03-11T14:46:35.154Z'
+ created_at: '2026-03-11T20:16:57.427Z'
+ updated_at: '2026-03-11T20:16:57.427Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H36977143143
+ number: H32477969001
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:46:35.159Z'
- updated_at: '2026-03-11T14:46:35.173Z'
+ created_at: '2026-03-11T20:16:57.432Z'
+ updated_at: '2026-03-11T20:16:57.444Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_341
- name: Kimberlee Dach
+ state_abbr: STATE_ABBR_281
+ name: Mendy Koss
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_341
+ state_text: STATE_ABBR_281
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -7804,12 +7414,12 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
state: checkout
- response_code: 1-SC-20260311144635483353
- number: PGMMUC9Z
+ response_code: 1-SC-20260311201657780014
+ number: PNEWMSZ6
amount: '10.0'
display_amount: "$10.00"
- created_at: '2026-03-11T14:46:35.487Z'
- updated_at: '2026-03-11T14:46:35.487Z'
+ created_at: '2026-03-11T20:16:57.785Z'
+ updated_at: '2026-03-11T20:16:57.785Z'
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
@@ -7832,7 +7442,7 @@ paths:
firstname: John
lastname: Doe
full_name: John Doe
- address1: 322 Lovely Street
+ address1: 262 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -7840,16 +7450,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_343
- state_abbr: STATE_ABBR_343
+ state_text: STATE_ABBR_283
+ state_abbr: STATE_ABBR_283
quick_checkout: false
- state_name: STATE_NAME_343
+ state_name: STATE_NAME_283
ship_address:
id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 323 Lovely Street
+ address1: 263 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -7857,10 +7467,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_344
- state_abbr: STATE_ABBR_344
+ state_text: STATE_ABBR_284
+ state_abbr: STATE_ABBR_284
quick_checkout: false
- state_name: STATE_NAME_344
+ state_name: STATE_NAME_284
payment_methods:
- id: pm_UkLWZg9DAJ
name: Store Credit
@@ -7868,7 +7478,7 @@ paths:
type: Spree::PaymentMethod::StoreCredit
session_required: false
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Cart"
'422':
description: no store credit available
content:
@@ -7896,7 +7506,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: Removes store credit from the order
+ description: Removes store credit from the current cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7908,7 +7518,7 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.removeStoreCredit('or_abc123', {
+ const cart = await client.checkout.removeStoreCredit({
bearerToken: '<token>',
})
parameters:
@@ -7922,12 +7532,7 @@ paths:
required: true
schema:
type: string
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: x-spree-order-token
+ - name: x-spree-token
in: header
required: false
schema:
@@ -7938,23 +7543,21 @@ paths:
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R176406903
+ id: cart_UkLWZg9DAJ
+ number: R023223592
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: o6HCgycDeUUk4qM1xsQcHX3XBynYmZ2eRLC
+ token: G1Sdq5jhpBeq29pYqvnq3Jcd1mxJ7fseXb8
special_instructions:
currency: USD
locale: en
item_count: 1
state_lock_version: 1
- shipment_state:
- payment_state:
item_total: '10.0'
display_item_total: "$10.00"
ship_total: '100.0'
@@ -7971,17 +7574,16 @@ paths:
display_additional_tax_total: "$0.00"
total: '110.0'
display_total: "$110.00"
- completed_at:
- created_at: '2026-03-11T14:46:36.664Z'
- updated_at: '2026-03-11T14:46:36.713Z'
+ created_at: '2026-03-11T20:16:59.026Z'
+ updated_at: '2026-03-11T20:16:59.073Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 127583
- slug: product-127583
+ name: Product 1096204
+ slug: product-1096204
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8000,37 +7602,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-11T14:46:36.694Z'
- updated_at: '2026-03-11T14:46:36.694Z'
+ created_at: '2026-03-11T20:16:59.053Z'
+ updated_at: '2026-03-11T20:16:59.053Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H44612030253
+ number: H82284414826
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-11T14:46:36.699Z'
- updated_at: '2026-03-11T14:46:36.711Z'
+ created_at: '2026-03-11T20:16:59.058Z'
+ updated_at: '2026-03-11T20:16:59.071Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_349
- name: Melaine Beier
+ state_abbr: STATE_ABBR_289
+ name: Marcelene Smitham
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_349
+ state_text: STATE_ABBR_289
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -8048,7 +7650,7 @@ paths:
firstname: John
lastname: Doe
full_name: John Doe
- address1: 330 Lovely Street
+ address1: 270 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -8056,16 +7658,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_351
- state_abbr: STATE_ABBR_351
+ state_text: STATE_ABBR_291
+ state_abbr: STATE_ABBR_291
quick_checkout: false
- state_name: STATE_NAME_351
+ state_name: STATE_NAME_291
ship_address:
id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 331 Lovely Street
+ address1: 271 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -8073,13 +7675,13 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_352
- state_abbr: STATE_ABBR_352
+ state_text: STATE_ABBR_292
+ state_abbr: STATE_ABBR_292
quick_checkout: false
- state_name: STATE_NAME_352
+ state_name: STATE_NAME_292
payment_methods: []
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Cart"
"/api/v3/store/wishlists":
get:
summary: List wishlists
@@ -8140,9 +7742,9 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: i4KkuH3yB8s2YBm7s7BructR
- created_at: '2026-03-11T14:46:37.275Z'
- updated_at: '2026-03-11T14:46:37.275Z'
+ token: 3YQ4fd4a1CvqbKLtNEPHG1ZF
+ created_at: '2026-03-11T20:16:59.638Z'
+ updated_at: '2026-03-11T20:16:59.638Z'
is_default: false
is_private: true
meta:
@@ -8218,9 +7820,9 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: cHskWcu665FJV1ubD3nc7T3i
- created_at: '2026-03-11T14:46:38.457Z'
- updated_at: '2026-03-11T14:46:38.457Z'
+ token: 86y11tQTHf5Lahkkds4Z4mT1
+ created_at: '2026-03-11T20:17:00.852Z'
+ updated_at: '2026-03-11T20:17:00.852Z'
is_default: false
is_private: true
schema:
@@ -8316,9 +7918,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: CQtCzpXN8LtU5rnZkz9rVEHV
- created_at: '2026-03-11T14:46:39.578Z'
- updated_at: '2026-03-11T14:46:39.578Z'
+ token: bKWGSxheujTMekoudUVVkktL
+ created_at: '2026-03-11T20:17:01.972Z'
+ updated_at: '2026-03-11T20:17:01.972Z'
is_default: false
is_private: true
schema:
@@ -8380,9 +7982,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: pVfqT75mC5QtFmKdeQU3eTvC
- created_at: '2026-03-11T14:46:40.832Z'
- updated_at: '2026-03-11T14:46:40.876Z'
+ token: tpGAt3HC5t39Mz1fxesJt9Ez
+ created_at: '2026-03-11T20:17:03.122Z'
+ updated_at: '2026-03-11T20:17:03.160Z'
is_default: false
is_private: true
schema:
@@ -8494,18 +8096,18 @@ paths:
variant_id: variant_gbHJdmfrXB
wishlist_id: wl_UkLWZg9DAJ
quantity: 1
- created_at: '2026-03-11T14:46:42.040Z'
- updated_at: '2026-03-11T14:46:42.040Z'
+ created_at: '2026-03-11T20:17:04.425Z'
+ updated_at: '2026-03-11T20:17:04.425Z'
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-149
+ sku: SKU-130
is_master: true
options_text: ''
track_inventory: true
image_count: 0
- created_at: '2026-03-11T14:46:42.018Z'
- updated_at: '2026-03-11T14:46:42.026Z'
+ created_at: '2026-03-11T20:17:04.402Z'
+ updated_at: '2026-03-11T20:17:04.412Z'
thumbnail:
purchasable: true
in_stock: false
@@ -8859,6 +8461,138 @@ components:
required:
- id
x-typelizer: true
+ Cart:
+ type: object
+ properties:
+ id:
+ type: string
+ number:
+ type: string
+ state:
+ type: string
+ checkout_steps:
+ type: array
+ items:
+ type: string
+ token:
+ type: string
+ email:
+ type: string
+ nullable: true
+ special_instructions:
+ type: string
+ nullable: true
+ currency:
+ type: string
+ locale:
+ type: string
+ nullable: true
+ item_count:
+ type: number
+ state_lock_version:
+ type: number
+ item_total:
+ type: string
+ display_item_total:
+ type: string
+ ship_total:
+ type: string
+ display_ship_total:
+ type: string
+ adjustment_total:
+ type: string
+ display_adjustment_total:
+ type: string
+ promo_total:
+ type: string
+ display_promo_total:
+ type: string
+ tax_total:
+ type: string
+ display_tax_total:
+ type: string
+ included_tax_total:
+ type: string
+ display_included_tax_total:
+ type: string
+ additional_tax_total:
+ type: string
+ display_additional_tax_total:
+ type: string
+ total:
+ type: string
+ display_total:
+ type: string
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ order_promotions:
+ type: array
+ items:
+ "$ref": "#/components/schemas/OrderPromotion"
+ line_items:
+ type: array
+ items:
+ "$ref": "#/components/schemas/LineItem"
+ shipments:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Shipment"
+ payments:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Payment"
+ bill_address:
+ allOf:
+ - "$ref": "#/components/schemas/Address"
+ nullable: true
+ ship_address:
+ allOf:
+ - "$ref": "#/components/schemas/Address"
+ nullable: true
+ payment_methods:
+ type: array
+ items:
+ "$ref": "#/components/schemas/PaymentMethod"
+ required:
+ - id
+ - number
+ - state
+ - checkout_steps
+ - token
+ - email
+ - special_instructions
+ - currency
+ - locale
+ - item_count
+ - state_lock_version
+ - item_total
+ - display_item_total
+ - ship_total
+ - display_ship_total
+ - adjustment_total
+ - display_adjustment_total
+ - promo_total
+ - display_promo_total
+ - tax_total
+ - display_tax_total
+ - included_tax_total
+ - display_included_tax_total
+ - additional_tax_total
+ - display_additional_tax_total
+ - total
+ - display_total
+ - created_at
+ - updated_at
+ - order_promotions
+ - line_items
+ - shipments
+ - payments
+ - bill_address
+ - ship_address
+ - payment_methods
+ x-typelizer: true
Category:
type: object
properties:
@@ -9720,17 +9454,8 @@ components:
type: string
number:
type: string
- state:
- type: string
- checkout_steps:
- type: array
- items:
- type: string
- token:
- type: string
email:
type: string
- nullable: true
special_instructions:
type: string
nullable: true
@@ -9741,8 +9466,6 @@ components:
nullable: true
item_count:
type: number
- state_lock_version:
- type: number
shipment_state:
type: string
nullable: true
@@ -9812,22 +9535,14 @@ components:
allOf:
- "$ref": "#/components/schemas/Address"
nullable: true
- payment_methods:
- type: array
- items:
- "$ref": "#/components/schemas/PaymentMethod"
required:
- id
- number
- - state
- - checkout_steps
- - token
- email
- special_instructions
- currency
- locale
- item_count
- - state_lock_version
- shipment_state
- payment_state
- item_total
@@ -9855,7 +9570,6 @@ components:
- payments
- bill_address
- ship_address
- - payment_methods
x-typelizer: true
PaymentMethod:
type: object
diff --git a/docs/developer/sdk/authentication.mdx b/docs/developer/sdk/authentication.mdx
index 9dbcf7aa86..e3a96cd789 100644
--- a/docs/developer/sdk/authentication.mdx
+++ b/docs/developer/sdk/authentication.mdx
@@ -45,18 +45,18 @@ const { token, user } = await client.customers.create({
## Guest Checkout
-For guest checkout, use the `token` returned when creating a cart. The SDK automatically sends it via the `x-spree-order-token` header:
+For guest checkout, use the `token` returned when creating a cart. The SDK automatically sends it via the `x-spree-token` header:
<AuthGuestCart />
```typescript
-const options = { orderToken: cart.token }
+const options = { spreeToken: cart.token }
-// Update order with email
-await client.orders.update(cart.id, {
+// Update checkout with email
+await client.checkout.update({
}, options)
// Complete checkout
-await client.orders.complete(cart.id, options)
+await client.checkout.complete(options)
```
diff --git a/docs/developer/sdk/store/cart-checkout.mdx b/docs/developer/sdk/store/cart-checkout.mdx
index 9c3814f69a..7948c3c380 100644
--- a/docs/developer/sdk/store/cart-checkout.mdx
+++ b/docs/developer/sdk/store/cart-checkout.mdx
@@ -1,46 +1,73 @@
---
-title: Cart & Checkout
-description: Manage carts, line items, coupons, and checkout flow with the Spree SDK
+title: Cart, Checkout & Orders
+description: Manage carts, line items, coupons, checkout flow, and completed orders with the Spree SDK
---
+The Store API is split into three resource groups:
+
+- **Cart** — managing the shopping cart (items, coupon codes)
+- **Checkout** — advancing through checkout (addresses, shipping, payments, completion)
+- **Orders** — retrieving completed orders
+
+All cart and checkout endpoints use an **implicit cart** resolved from the `spreeToken` header (guest) or JWT (authenticated customer). You never pass an `orderId`.
+
## Cart
+### Create & Retrieve
+
```typescript
// Create a new cart
const cart = await client.cart.create();
// Get current cart
-const cart = await client.cart.get({ orderToken: 'xxx' });
+const cart = await client.cart.get({ spreeToken: 'xxx' });
// Associate guest cart with authenticated user
// (after user logs in, merge their guest cart with their account)
await client.cart.associate({
- token: jwtToken, // User's JWT token
- orderToken: cart.token, // Guest cart token
+ token: jwtToken, // User's JWT token
+ spreeToken: cart.token, // Guest cart token
});
```
-## Orders & Checkout
-
-### List Orders
+### Line Items
```typescript
-// List orders for authenticated customer
-const orders = await client.customer.orders.list({}, { token });
+const options = { spreeToken: cart.token };
+
+// Add item
+await client.cart.items.create({
+ variant_id: 'var_123',
+ quantity: 2,
+}, options);
+
+// Update item quantity
+await client.cart.items.update(lineItemId, {
+ quantity: 3,
+}, options);
+
+// Remove item
+await client.cart.items.delete(lineItemId, options);
```
-### Get an Order
+### Coupon Codes
```typescript
-const order = await client.orders.get('R123456789', {
- expand: ['line_items', 'shipments'],
-}, { orderToken: cart.token });
+const options = { spreeToken: cart.token };
+
+// Apply a coupon code
+await client.cart.couponCodes.apply('SAVE20', options);
+
+// Remove a coupon code
+await client.cart.couponCodes.remove('promo_xxx', options);
```
-### Update an Order
+## Checkout
+
+### Update Checkout
```typescript
-await client.orders.update(cart.id, {
+await client.checkout.update({
ship_address: {
firstname: 'John',
@@ -53,62 +80,56 @@ await client.orders.update(cart.id, {
state_abbr: 'NY',
},
bill_address_id: 'addr_xxx', // Or use existing address by ID
-}, { orderToken: cart.token });
+}, { spreeToken: cart.token });
```
-### Checkout Flow
+### Complete Checkout
```typescript
-const options = { orderToken: cart.token };
-
-await client.orders.next(cart.id, options); // Move to next step
-await client.orders.advance(cart.id, options); // Advance through all steps
-await client.orders.complete(cart.id, options); // Complete the order
+await client.checkout.complete({ spreeToken: cart.token });
```
-## Line Items
+### Shipments
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// Add item
-await client.orders.lineItems.create(cart.id, {
- variant_id: 'var_123',
- quantity: 2,
-}, options);
+// List shipments
+const shipments = await client.checkout.shipments.list(options);
-// Update item quantity
-await client.orders.lineItems.update(cart.id, lineItemId, {
- quantity: 3,
+// Select a shipping rate
+await client.checkout.shipments.update(shipmentId, {
+ selected_shipping_rate_id: 'rate_xxx',
}, options);
-
-// Remove item
-await client.orders.lineItems.delete(cart.id, lineItemId, options);
```
-## Coupon Codes
+### Store Credits
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// Apply a coupon code
-await client.orders.couponCodes.apply(cart.id, 'SAVE20', options);
+// Apply store credit (applies maximum available by default)
+await client.checkout.storeCredits.apply(undefined, options);
-// Remove a coupon code
-await client.orders.couponCodes.remove(cart.id, 'promo_xxx', options);
+// Apply specific amount of store credit
+await client.checkout.storeCredits.apply(25.00, options);
+
+// Remove store credit from order
+await client.checkout.storeCredits.remove(options);
```
-## Store Credits
+## Orders
-```typescript
-const options = { orderToken: cart.token };
+### Get a Completed Order
-// Apply store credit to order (applies maximum available by default)
-await client.orders.addStoreCredit(cart.id, undefined, options);
+```typescript
+const order = await client.orders.get('R123456789', {
+ expand: ['line_items', 'shipments'],
+}, { spreeToken: cart.token });
+```
-// Apply specific amount of store credit
-await client.orders.addStoreCredit(cart.id, 25.00, options);
+### List Orders (Authenticated Customer)
-// Remove store credit from order
-await client.orders.removeStoreCredit(cart.id, options);
+```typescript
+const orders = await client.customer.orders.list({}, { token });
```
diff --git a/docs/developer/sdk/store/payments.mdx b/docs/developer/sdk/store/payments.mdx
index 2842ad24b8..a1a0267273 100644
--- a/docs/developer/sdk/store/payments.mdx
+++ b/docs/developer/sdk/store/payments.mdx
@@ -3,13 +3,15 @@ title: Payments & Shipping
description: Handle payments, payment sessions, and shipping with the Spree SDK
---
+All payment and shipping endpoints use the **implicit cart** resolved from the `spreeToken` header or JWT. You never pass an `orderId`.
+
## Payment Methods
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// Get available payment methods for an order
-const methods = await client.orders.paymentMethods.list(cart.id, options);
+// Get available payment methods for the current checkout
+const methods = await client.checkout.paymentMethods.list(options);
// Each method includes a `session_required` flag:
// - true → use Payment Sessions (Stripe, Adyen, PayPal, etc.)
@@ -19,17 +21,17 @@ const methods = await client.orders.paymentMethods.list(cart.id, options);
## Payments
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// List payments on an order
-const payments = await client.orders.payments.list(cart.id, options);
+// List payments on the current checkout
+const payments = await client.checkout.payments.list(options);
// Get a specific payment
-const payment = await client.orders.payments.get(cart.id, paymentId, options);
+const payment = await client.checkout.payments.get(paymentId, options);
// Create a payment for a non-session payment method
// (e.g. Check, Cash on Delivery, Bank Transfer, Purchase Order)
-const payment = await client.orders.payments.create(cart.id, {
+const payment = await client.checkout.payments.create({
payment_method_id: 'pm_xxx',
amount: '99.99', // Optional, defaults to order total minus store credits
metadata: { // Optional, write-only metadata
@@ -48,10 +50,10 @@ const payment = await client.orders.payments.create(cart.id, {
Payment sessions provide a unified, provider-agnostic interface for payment processing. They work with any payment gateway (Stripe, Adyen, PayPal, etc.) through a single API.
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
// Create a payment session (initializes a session with the payment gateway)
-const session = await client.orders.paymentSessions.create(cart.id, {
+const session = await client.checkout.paymentSessions.create({
payment_method_id: 'pm_xxx',
amount: '99.99', // Optional, defaults to order total
external_data: { // Optional, provider-specific data
@@ -63,18 +65,18 @@ const session = await client.orders.paymentSessions.create(cart.id, {
console.log(session.external_data.client_secret);
// Get a payment session
-const existing = await client.orders.paymentSessions.get(
- cart.id, session.id, options
+const existing = await client.checkout.paymentSessions.get(
+ session.id, options
);
// Update a payment session (e.g., after order total changes)
-await client.orders.paymentSessions.update(cart.id, session.id, {
+await client.checkout.paymentSessions.update(session.id, {
amount: '149.99',
}, options);
// Complete the payment session (after customer confirms payment on the frontend)
-const completed = await client.orders.paymentSessions.complete(
- cart.id, session.id,
+const completed = await client.checkout.paymentSessions.complete(
+ session.id,
{ session_result: 'success' },
options
);
@@ -84,13 +86,13 @@ console.log(completed.status); // 'completed'
## Shipments
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// List shipments for an order
-const shipments = await client.orders.shipments.list(cart.id, options);
+// List shipments for the current checkout
+const shipments = await client.checkout.shipments.list(options);
// Select a shipping rate
-await client.orders.shipments.update(cart.id, shipmentId, {
+await client.checkout.shipments.update(shipmentId, {
selected_shipping_rate_id: 'rate_xxx',
}, options);
```
diff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdx
index 81a2579dcc..986768fb90 100644
--- a/docs/developer/storefront/nextjs/spree-next-package.mdx
+++ b/docs/developer/storefront/nextjs/spree-next-package.mdx
@@ -114,14 +114,12 @@ await associateCart(); // link guest cart to logged-in user
### Checkout
-All checkout functions take `orderId` as the first argument:
+Checkout functions use the implicit cart resolved from cookies. No `orderId` is needed.
```typescript
import {
getCheckout,
- updateAddresses,
- advance,
- next,
+ updateCheckout,
getShipments,
selectShippingRate,
applyCoupon,
@@ -129,15 +127,13 @@ import {
complete,
} from '@spree/next';
-const checkout = await getCheckout(orderId);
-await updateAddresses(orderId, { ship_address: { ... }, bill_address: { ... } });
-await advance(orderId);
-await next(orderId);
-const shipments = await getShipments(orderId);
-await selectShippingRate(orderId, shipmentId, shippingRateId);
-await applyCoupon(orderId, 'SAVE20');
-await removeCoupon(orderId, promotionId);
-await complete(orderId);
+const checkout = await getCheckout();
+await updateCheckout({ ship_address: { ... }, bill_address: { ... } });
+const shipments = await getShipments();
+await selectShippingRate(shipmentId, shippingRateId);
+await applyCoupon('SAVE20');
+await removeCoupon(promotionId);
+await complete();
```
### Authentication
@@ -175,6 +171,8 @@ const order = await getOrder(orderId);
### Payment Sessions
+Payment session functions use the implicit cart. No `orderId` is needed.
+
```typescript
import {
createPaymentSession,
@@ -183,14 +181,14 @@ import {
completePaymentSession,
} from '@spree/next';
-const session = await createPaymentSession(orderId, { payment_method_id: 'pm_123' });
+const session = await createPaymentSession({ payment_method_id: 'pm_123' });
// Access provider data (e.g., Stripe client secret)
const clientSecret = session.external_data.client_secret;
-const current = await getPaymentSession(orderId, sessionId);
-await updatePaymentSession(orderId, sessionId, { amount: '50.00' });
-await completePaymentSession(orderId, sessionId, { session_result: 'success' });
+const current = await getPaymentSession(sessionId);
+await updatePaymentSession(sessionId, { amount: '50.00' });
+await completePaymentSession(sessionId, { session_result: 'success' });
```
### Payment Setup Sessions
diff --git a/docs/snippets/store-api/auth-guest-cart.mdx b/docs/snippets/store-api/auth-guest-cart.mdx
index 7cd4cbf895..ba14ee7b5b 100644
--- a/docs/snippets/store-api/auth-guest-cart.mdx
+++ b/docs/snippets/store-api/auth-guest-cart.mdx
@@ -2,11 +2,11 @@
// Create a cart (guest)
const cart = await client.cart.create()
-// Use orderToken for all cart operations
-const options = { orderToken: cart.token }
+// Use spreeToken for all cart and checkout operations
+const options = { spreeToken: cart.token }
// Add items
-await client.orders.lineItems.create(cart.id, {
+await client.cart.items.create({
variant_id: 'variant_abc123',
quantity: 1,
}, options)
diff --git a/packages/admin-sdk/src/types/generated/Category.ts b/packages/admin-sdk/src/types/generated/Category.ts
index e23c5f49e7..ad29a969de 100644
--- a/packages/admin-sdk/src/types/generated/Category.ts
+++ b/packages/admin-sdk/src/types/generated/Category.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 3dc94402588169b6deff8033e8b9a8c5
+// Typelizer digest 20ede22f18045ffca2d5d1c5c6deabf6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Metafield} from '@/types'
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index 75a4c31536..461d4fd7ee 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 1430128d0c3d7f817455af363e2bfac8
+// Typelizer digest 2c54cfb0b1b1be672e0793136aae19c9
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {OrderPromotion, LineItem, Shipment, Payment, Address, PaymentMethod, Customer, Adjustment, ReturnAuthorization, Reimbursement} from '@/types'
@@ -6,15 +6,11 @@ import type {OrderPromotion, LineItem, Shipment, Payment, Address, PaymentMethod
type Order = {
id: string;
number: string;
- state: string;
- checkout_steps: Array<string>;
- token: string;
- email: string | null;
+ email: string;
special_instructions: string | null;
currency: string;
locale: string | null;
item_count: number;
- state_lock_version: number;
shipment_state: string | null;
payment_state: string | null;
item_total: string;
@@ -42,7 +38,6 @@ type Order = {
payments?: Array<Payment>;
bill_address?: Address | null;
ship_address?: Address | null;
- payment_methods?: Array<PaymentMethod>;
channel: string | null;
last_ip_address: string | null;
considered_risky: boolean;
@@ -58,6 +53,7 @@ type Order = {
canceler_id: string | null;
created_by_id: string | null;
user_id: string | null;
+ payment_methods?: Array<PaymentMethod>;
user?: Customer;
approver?: Customer;
canceler?: Customer;
diff --git a/packages/admin-sdk/src/types/generated/Product.ts b/packages/admin-sdk/src/types/generated/Product.ts
index 9ca6675632..db9d12dae1 100644
--- a/packages/admin-sdk/src/types/generated/Product.ts
+++ b/packages/admin-sdk/src/types/generated/Product.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 645a2f6c5a8bc5e6d7aa115ed2613816
+// Typelizer digest 3f80b68185ecc8b201bb41c384acaa05
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Price, Image, Variant, OptionType, Category, Metafield} from '@/types'
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index f2841e6687..aca0c57f17 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest fe4c0228dbe7e34377a02ea036656bc5
+// Typelizer digest 07c3216434ae36f2d5204abb7ac05832
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
diff --git a/packages/next/README.md b/packages/next/README.md
index c1723f98b1..2e31cae5ea 100644
--- a/packages/next/README.md
+++ b/packages/next/README.md
@@ -58,7 +58,7 @@ export default async function ProductsPage() {
import { addItem, removeItem, getCart } from '@spree/next';
export default async function CartPage() {
- const cart = await getCart();
+ const cart = await getCart(); // Cart | null
async function handleAddItem(formData: FormData) {
'use server';
@@ -127,23 +127,23 @@ Server actions handle mutations and auth-dependent reads. They automatically man
```typescript
import { getCart, getOrCreateCart, addItem, updateItem, removeItem, clearCart } from '@spree/next';
-const cart = await getCart();
-const cart = await getOrCreateCart();
-await addItem(variantId, quantity, { gift_message: 'Happy Birthday!' });
-await updateItem(lineItemId, { quantity: 3 });
-await updateItem(lineItemId, { metadata: { engraving: 'J.D.' } });
-await removeItem(lineItemId);
+const cart = await getCart(); // Cart | null
+const cart = await getOrCreateCart(); // Cart
+await addItem(variantId, quantity, { gift_message: 'Happy Birthday!' }); // Cart
+await updateItem(lineItemId, { quantity: 3 }); // Cart
+await updateItem(lineItemId, { metadata: { engraving: 'J.D.' } }); // Cart
+await removeItem(lineItemId); // Cart
await clearCart();
```
### Checkout
+All checkout functions operate on the current cart implicitly (via the cart cookie).
+
```typescript
import {
getCheckout,
- updateAddresses,
- advance,
- next,
+ updateCheckout,
getShipments,
selectShippingRate,
applyCoupon,
@@ -152,13 +152,11 @@ import {
} from '@spree/next';
const checkout = await getCheckout();
-await updateAddresses({ ship_address: { ... }, bill_address: { ... } });
-await advance();
-await next();
+await updateCheckout({ ship_address: { ... }, bill_address: { ... } });
const shipments = await getShipments();
await selectShippingRate(shipmentId, rateId);
await applyCoupon('SAVE20');
-await removeCoupon(promoId);
+await removeCoupon('SAVE20');
await complete();
```
@@ -197,12 +195,14 @@ const order = await getOrder(orderId);
### Payments (Manual/Offline)
+All payment functions operate on the current cart implicitly (via the cart cookie).
+
```typescript
import { createPayment } from '@spree/next';
// Create a payment for a non-session payment method
// (e.g. Check, Cash on Delivery, Bank Transfer, Purchase Order)
-await createPayment(orderId, {
+await createPayment({
payment_method_id: 'pm_123',
amount: '99.99', // Optional, defaults to order total minus store credits
metadata: { // Optional, write-only metadata
@@ -213,6 +213,8 @@ await createPayment(orderId, {
### Payment Sessions (Stripe, Adyen, PayPal, etc.)
+All payment session functions operate on the current cart implicitly (via the cart cookie).
+
```typescript
import {
createPaymentSession,
@@ -222,19 +224,19 @@ import {
} from '@spree/next';
// Create a payment session (initializes provider-specific session)
-const session = await createPaymentSession(orderId, { payment_method_id: 'pm_123' });
+const session = await createPaymentSession({ payment_method_id: 'pm_123' });
// Access provider data (e.g., Stripe client secret)
const clientSecret = session.external_data.client_secret;
// Get a payment session
-const session = await getPaymentSession(orderId, sessionId);
+const session = await getPaymentSession(sessionId);
// Update a payment session
-await updatePaymentSession(orderId, sessionId, { amount: '50.00' });
+await updatePaymentSession(sessionId, { amount: '50.00' });
// Complete a payment session (confirms payment with provider)
-await completePaymentSession(orderId, sessionId, { session_result: 'success' });
+await completePaymentSession(sessionId, { session_result: 'success' });
```
### Credit Cards & Gift Cards
@@ -299,11 +301,13 @@ All types are re-exported from `@spree/sdk` for convenience:
```typescript
import type {
+ Cart,
StoreProduct,
StoreOrder,
StoreLineItem,
StorePaymentSession,
StoreCategory,
+ UpdateCheckoutParams,
PaginatedResponse,
SpreeError,
} from '@spree/next';
diff --git a/packages/next/src/actions/auth.ts b/packages/next/src/actions/auth.ts
index c58d83bacf..a6506e12b0 100644
--- a/packages/next/src/actions/auth.ts
+++ b/packages/next/src/actions/auth.ts
@@ -24,7 +24,7 @@ export async function login(
try {
await getClient().cart.associate({
token: result.token,
- orderToken: cartToken,
+ spreeToken: cartToken,
});
} catch {
// Cart association failure is non-fatal
@@ -68,7 +68,7 @@ export async function register(
try {
await getClient().cart.associate({
token: result.token,
- orderToken: cartToken,
+ spreeToken: cartToken,
});
} catch {
// Non-fatal
diff --git a/packages/next/src/actions/cart.ts b/packages/next/src/actions/cart.ts
index a81b4bf2d0..92c8c4916c 100644
--- a/packages/next/src/actions/cart.ts
+++ b/packages/next/src/actions/cart.ts
@@ -1,23 +1,23 @@
'use server';
import { revalidateTag } from 'next/cache';
-import type { Order, CreateCartParams } from '@spree/sdk';
+import type { Cart, CreateCartParams } from '@spree/sdk';
import { getClient } from '../config';
import { getCartToken, setCartToken, clearCartToken, getAccessToken } from '../cookies';
/**
* Get the current cart. Returns null if no cart exists.
*/
-export async function getCart(): Promise<(Order & { token: string }) | null> {
- const orderToken = await getCartToken();
+export async function getCart(): Promise<Cart | null> {
+ const spreeToken = await getCartToken();
const token = await getAccessToken();
- if (!orderToken && !token) return null;
+ if (!spreeToken && !token) return null;
try {
- return await getClient().cart.get({ orderToken, token });
+ return await getClient().cart.get({ spreeToken, token });
} catch {
// Cart not found (e.g., order was completed) — clear stale token
- if (orderToken) {
+ if (spreeToken) {
await clearCartToken();
}
return null;
@@ -30,7 +30,7 @@ export async function getCart(): Promise<(Order & { token: string }) | null> {
*/
export async function getOrCreateCart(
params?: CreateCartParams
-): Promise<Order & { token: string }> {
+): Promise<Cart> {
const existing = await getCart();
if (existing) return existing;
@@ -48,30 +48,29 @@ export async function getOrCreateCart(
/**
* Add an item to the cart. Creates a cart if none exists.
- * Returns the updated order with recalculated totals.
+ * Returns the updated cart with recalculated totals.
*/
export async function addItem(
variantId: string,
quantity: number = 1,
metadata?: Record<string, unknown>
-): Promise<Order> {
- const cart = await getOrCreateCart();
- const orderToken = cart.token;
+): Promise<Cart> {
+ await getOrCreateCart();
+ const spreeToken = await getCartToken();
const token = await getAccessToken();
- const order = await getClient().orders.lineItems.create(
- cart.id,
+ const cart = await getClient().cart.items.create(
{ variant_id: variantId, quantity, metadata },
- { orderToken, token }
+ { spreeToken, token }
);
revalidateTag('cart');
- return order;
+ return cart;
}
/**
* Update a line item in the cart (quantity and/or metadata).
- * Returns the updated order with recalculated totals.
+ * Returns the updated cart with recalculated totals.
*
* @example
* // Update quantity only
@@ -86,42 +85,37 @@ export async function addItem(
export async function updateItem(
lineItemId: string,
params: { quantity?: number; metadata?: Record<string, unknown> }
-): Promise<Order> {
- const orderToken = await getCartToken();
+): Promise<Cart> {
+ const spreeToken = await getCartToken();
const token = await getAccessToken();
- if (!orderToken && !token) throw new Error('No cart found');
-
- const cart = await getClient().cart.get({ orderToken, token });
+ if (!spreeToken && !token) throw new Error('No cart found');
- const order = await getClient().orders.lineItems.update(
- cart.id,
+ const cart = await getClient().cart.items.update(
lineItemId,
params,
- { orderToken, token }
+ { spreeToken, token }
);
revalidateTag('cart');
- return order;
+ return cart;
}
/**
* Remove a line item from the cart.
- * Returns the updated order with recalculated totals.
+ * Returns the updated cart with recalculated totals.
*/
-export async function removeItem(lineItemId: string): Promise<Order> {
- const orderToken = await getCartToken();
+export async function removeItem(lineItemId: string): Promise<Cart> {
+ const spreeToken = await getCartToken();
const token = await getAccessToken();
- if (!orderToken && !token) throw new Error('No cart found');
+ if (!spreeToken && !token) throw new Error('No cart found');
- const cart = await getClient().cart.get({ orderToken, token });
-
- const order = await getClient().orders.lineItems.delete(cart.id, lineItemId, {
- orderToken,
+ const cart = await getClient().cart.items.delete(lineItemId, {
+ spreeToken,
token,
});
revalidateTag('cart');
- return order;
+ return cart;
}
/**
@@ -136,13 +130,13 @@ export async function clearCart(): Promise<void> {
* Associate a guest cart with the currently authenticated user.
* Call this after login/register when the user has an existing guest cart.
*/
-export async function associateCart(): Promise<(Order & { token: string }) | null> {
- const orderToken = await getCartToken();
+export async function associateCart(): Promise<Cart | null> {
+ const spreeToken = await getCartToken();
const token = await getAccessToken();
- if (!orderToken || !token) return null;
+ if (!spreeToken || !token) return null;
try {
- const result = await getClient().cart.associate({ orderToken, token });
+ const result = await getClient().cart.associate({ spreeToken, token });
revalidateTag('cart');
return result;
} catch {
diff --git a/packages/next/src/actions/checkout.ts b/packages/next/src/actions/checkout.ts
index 2380257a08..1acd44253e 100644
--- a/packages/next/src/actions/checkout.ts
+++ b/packages/next/src/actions/checkout.ts
@@ -1,86 +1,48 @@
'use server';
import { revalidateTag } from 'next/cache';
-import type { Order, Shipment, UpdateOrderParams } from '@spree/sdk';
+import type { Cart, Order, Shipment, UpdateCheckoutParams, ListResponse } from '@spree/sdk';
import { getClient } from '../config';
-import { getCartToken, getAccessToken } from '../cookies';
-
-async function getCheckoutOptions() {
- const orderToken = await getCartToken();
- const token = await getAccessToken();
- return { orderToken, token };
-}
+import { getCheckoutOptions } from '../cookies';
/**
- * Get the current checkout order state.
- * Includes line_items, shipments, and addresses by default.
+ * Get the current checkout state (cart with expanded associations).
*/
-export async function getCheckout(
- orderId: string
-): Promise<Order> {
+export async function getCheckout(): Promise<Cart> {
const options = await getCheckoutOptions();
- return getClient().orders.get(
- orderId,
- { expand: ['line_items', 'shipments', 'ship_address', 'bill_address'] },
- options
- );
+ return getClient().cart.get(options);
}
/**
- * Update an order (addresses, email, currency, locale, metadata, etc.).
+ * Update checkout info (email, addresses, special instructions).
*/
-export async function updateOrder(
- orderId: string,
- params: UpdateOrderParams
-): Promise<Order> {
+export async function updateCheckout(
+ params: UpdateCheckoutParams
+): Promise<Cart> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.update(orderId, params, options);
+ const result = await getClient().checkout.update(params, options);
revalidateTag('checkout');
return result;
}
/**
- * Advance the checkout to the next step.
+ * Get shipments with shipping rates for the current cart.
*/
-export async function advance(orderId: string): Promise<Order> {
+export async function getShipments(): Promise<ListResponse<Shipment>> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.advance(orderId, options);
- revalidateTag('checkout');
- return result;
-}
-
-/**
- * Move the checkout to the next step (alias for advance).
- */
-export async function next(orderId: string): Promise<Order> {
- const options = await getCheckoutOptions();
- const result = await getClient().orders.next(orderId, options);
- revalidateTag('checkout');
- return result;
-}
-
-/**
- * Get shipments for the order (includes available shipping rates).
- */
-export async function getShipments(
- orderId: string
-): Promise<{ data: Shipment[] }> {
- const options = await getCheckoutOptions();
- return getClient().orders.shipments.list(orderId, options);
+ return getClient().checkout.shipments.list(options);
}
/**
* Select a shipping rate for a shipment.
- * Returns the updated order with recalculated totals.
+ * Returns the updated cart with recalculated totals.
*/
export async function selectShippingRate(
- orderId: string,
shipmentId: string,
shippingRateId: string
-): Promise<Order> {
+): Promise<Cart> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.shipments.update(
- orderId,
+ const result = await getClient().checkout.shipments.update(
shipmentId,
{ selected_shipping_rate_id: shippingRateId },
options
@@ -90,28 +52,26 @@ export async function selectShippingRate(
}
/**
- * Apply a coupon code to the order.
+ * Apply a coupon code to the cart.
*/
export async function applyCoupon(
- orderId: string,
code: string
-): Promise<Order> {
+): Promise<Cart> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.couponCodes.apply(orderId, code, options);
+ const result = await getClient().cart.couponCodes.apply(code, options);
revalidateTag('checkout');
revalidateTag('cart');
return result;
}
/**
- * Remove a coupon/promotion from the order.
+ * Remove a coupon code from the cart.
*/
export async function removeCoupon(
- orderId: string,
- promotionId: string
-): Promise<Order> {
+ code: string
+): Promise<Cart> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.couponCodes.remove(orderId, promotionId, options);
+ const result = await getClient().cart.couponCodes.remove(code, options);
revalidateTag('checkout');
revalidateTag('cart');
return result;
@@ -120,9 +80,9 @@ export async function removeCoupon(
/**
* Complete the checkout and place the order.
*/
-export async function complete(orderId: string): Promise<Order> {
+export async function complete(): Promise<Order> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.complete(orderId, options);
+ const result = await getClient().checkout.complete(options);
revalidateTag('checkout');
revalidateTag('cart');
return result;
diff --git a/packages/next/src/actions/payment-sessions.ts b/packages/next/src/actions/payment-sessions.ts
index 0e9ec7b40c..222362cd74 100644
--- a/packages/next/src/actions/payment-sessions.ts
+++ b/packages/next/src/actions/payment-sessions.ts
@@ -8,24 +8,17 @@ import type {
CompletePaymentSessionParams,
} from '@spree/sdk';
import { getClient } from '../config';
-import { getCartToken, getAccessToken } from '../cookies';
-
-async function getCheckoutOptions() {
- const orderToken = await getCartToken();
- const token = await getAccessToken();
- return { orderToken, token };
-}
+import { getCheckoutOptions } from '../cookies';
/**
- * Create a payment session for an order.
+ * Create a payment session for the current cart.
* Delegates to the payment gateway to initialize a provider-specific session.
*/
export async function createPaymentSession(
- orderId: string,
params: CreatePaymentSessionParams
): Promise<PaymentSession> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.paymentSessions.create(orderId, params, options);
+ const result = await getClient().checkout.paymentSessions.create(params, options);
revalidateTag('checkout');
return result;
}
@@ -34,11 +27,10 @@ export async function createPaymentSession(
* Get a payment session by ID.
*/
export async function getPaymentSession(
- orderId: string,
sessionId: string
): Promise<PaymentSession> {
const options = await getCheckoutOptions();
- return getClient().orders.paymentSessions.get(orderId, sessionId, options);
+ return getClient().checkout.paymentSessions.get(sessionId, options);
}
/**
@@ -46,12 +38,11 @@ export async function getPaymentSession(
* Delegates to the payment gateway to sync changes with the provider.
*/
export async function updatePaymentSession(
- orderId: string,
sessionId: string,
params: UpdatePaymentSessionParams
): Promise<PaymentSession> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.paymentSessions.update(orderId, sessionId, params, options);
+ const result = await getClient().checkout.paymentSessions.update(sessionId, params, options);
revalidateTag('checkout');
return result;
}
@@ -61,12 +52,11 @@ export async function updatePaymentSession(
* Confirms the payment with the provider, triggering capture/authorization.
*/
export async function completePaymentSession(
- orderId: string,
sessionId: string,
params?: CompletePaymentSessionParams
): Promise<PaymentSession> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.paymentSessions.complete(orderId, sessionId, params, options);
+ const result = await getClient().checkout.paymentSessions.complete(sessionId, params, options);
revalidateTag('checkout');
return result;
}
diff --git a/packages/next/src/actions/payments.ts b/packages/next/src/actions/payments.ts
index 39ddcc0938..484fbff65f 100644
--- a/packages/next/src/actions/payments.ts
+++ b/packages/next/src/actions/payments.ts
@@ -3,24 +3,17 @@
import { revalidateTag } from 'next/cache';
import type { Payment, CreatePaymentParams } from '@spree/sdk';
import { getClient } from '../config';
-import { getCartToken, getAccessToken } from '../cookies';
-
-async function getCheckoutOptions() {
- const orderToken = await getCartToken();
- const token = await getAccessToken();
- return { orderToken, token };
-}
+import { getCheckoutOptions } from '../cookies';
/**
* Create a payment for a non-session payment method (e.g. Check, Cash on Delivery, Bank Transfer).
* For session-based payment methods (e.g. Stripe, PayPal), use createPaymentSession instead.
*/
export async function createPayment(
- orderId: string,
params: CreatePaymentParams
): Promise<Payment> {
const options = await getCheckoutOptions();
- const result = await getClient().orders.payments.create(orderId, params, options);
+ const result = await getClient().checkout.payments.create(params, options);
revalidateTag('checkout');
return result;
}
diff --git a/packages/next/src/cookies.ts b/packages/next/src/cookies.ts
index 63905dde69..6658cd8a46 100644
--- a/packages/next/src/cookies.ts
+++ b/packages/next/src/cookies.ts
@@ -73,3 +73,14 @@ export async function clearAccessToken(): Promise<void> {
path: '/',
});
}
+
+// --- Checkout Options (combined cart + access tokens for checkout/payment actions) ---
+
+export async function getCheckoutOptions(): Promise<{
+ spreeToken: string | undefined;
+ token: string | undefined;
+}> {
+ const spreeToken = await getCartToken();
+ const token = await getAccessToken();
+ return { spreeToken, token };
+}
diff --git a/packages/next/src/index.ts b/packages/next/src/index.ts
index d1ebb6244e..5e4b492534 100644
--- a/packages/next/src/index.ts
+++ b/packages/next/src/index.ts
@@ -23,9 +23,7 @@ export {
export {
getCheckout,
- updateOrder,
- advance,
- next,
+ updateCheckout,
getShipments,
selectShippingRate,
applyCoupon,
@@ -71,6 +69,7 @@ export {
// Re-export commonly used SDK types for convenience
export type {
+ Cart,
Product,
Order,
LineItem,
@@ -100,7 +99,7 @@ export type {
AddressParams,
CreateCartParams,
LineItemInput,
- UpdateOrderParams,
+ UpdateCheckoutParams,
ProductFiltersResponse,
CreatePaymentParams,
CreatePaymentSessionParams,
diff --git a/packages/next/tests/actions/auth.test.ts b/packages/next/tests/actions/auth.test.ts
index c9718c3c3e..d8d082ffa3 100644
--- a/packages/next/tests/actions/auth.test.ts
+++ b/packages/next/tests/actions/auth.test.ts
@@ -72,7 +72,7 @@ describe('auth actions', () => {
await login('[email protected]', 'pass');
expect(mockClient.cart.associate).toHaveBeenCalledWith({
token: 'jwt_new',
- orderToken: 'guest_cart_token',
+ spreeToken: 'guest_cart_token',
});
});
@@ -156,7 +156,7 @@ describe('auth actions', () => {
expect(mockClient.cart.associate).toHaveBeenCalledWith({
token: 'jwt_new',
- orderToken: 'guest_cart_token',
+ spreeToken: 'guest_cart_token',
});
});
diff --git a/packages/next/tests/actions/cart.test.ts b/packages/next/tests/actions/cart.test.ts
index 40f6192d06..e1bcf2cc6b 100644
--- a/packages/next/tests/actions/cart.test.ts
+++ b/packages/next/tests/actions/cart.test.ts
@@ -8,13 +8,15 @@ const mockClient = {
get: vi.fn(),
create: vi.fn(),
associate: vi.fn(),
- },
- orders: {
- lineItems: {
+ items: {
create: vi.fn(),
update: vi.fn(),
delete: vi.fn(),
},
+ couponCodes: {
+ apply: vi.fn(),
+ remove: vi.fn(),
+ },
},
};
@@ -22,7 +24,7 @@ vi.mock('@spree/sdk', () => ({
createClient: vi.fn(() => mockClient),
}));
-import { getCart, getOrCreateCart, addItem, removeItem, clearCart, associateCart } from '../../src/actions/cart';
+import { getCart, getOrCreateCart, addItem, updateItem, removeItem, clearCart, associateCart } from '../../src/actions/cart';
import { revalidateTag } from 'next/cache';
describe('cart actions', () => {
@@ -47,7 +49,7 @@ describe('cart actions', () => {
const cart = await getCart();
expect(cart).toEqual(mockCart);
expect(mockClient.cart.get).toHaveBeenCalledWith(
- expect.objectContaining({ orderToken: 'order_abc' })
+ expect.objectContaining({ spreeToken: 'order_abc' })
);
});
@@ -90,17 +92,33 @@ describe('cart actions', () => {
describe('addItem', () => {
it('adds line item and invalidates cache', async () => {
const mockCart = { id: '1', token: 'cart_token', line_items: [] };
- const mockLineItem = { id: 'li_1', quantity: 2, variant_id: 'v1' };
+ const updatedCart = { id: '1', token: 'cart_token', line_items: [{ id: 'li_1' }] };
mockCookieStore.get.mockReturnValue({ value: 'cart_token' });
mockClient.cart.get.mockResolvedValue(mockCart);
- mockClient.orders.lineItems.create.mockResolvedValue(mockLineItem);
+ mockClient.cart.items.create.mockResolvedValue(updatedCart);
const result = await addItem('v1', 2);
- expect(result).toEqual(mockLineItem);
- expect(mockClient.orders.lineItems.create).toHaveBeenCalledWith(
- '1',
+ expect(result).toEqual(updatedCart);
+ expect(mockClient.cart.items.create).toHaveBeenCalledWith(
{ variant_id: 'v1', quantity: 2 },
- expect.objectContaining({ orderToken: 'cart_token' })
+ expect.objectContaining({ spreeToken: 'cart_token' })
+ );
+ expect(revalidateTag).toHaveBeenCalledWith('cart');
+ });
+ });
+
+ describe('updateItem', () => {
+ it('updates line item and invalidates cache', async () => {
+ const updatedCart = { id: '1', token: 'cart_token', item_count: 3 };
+ mockCookieStore.get.mockReturnValue({ value: 'cart_token' });
+ mockClient.cart.items.update.mockResolvedValue(updatedCart);
+
+ const result = await updateItem('li_1', { quantity: 3 });
+ expect(result).toEqual(updatedCart);
+ expect(mockClient.cart.items.update).toHaveBeenCalledWith(
+ 'li_1',
+ { quantity: 3 },
+ expect.objectContaining({ spreeToken: 'cart_token' })
);
expect(revalidateTag).toHaveBeenCalledWith('cart');
});
@@ -108,16 +126,15 @@ describe('cart actions', () => {
describe('removeItem', () => {
it('deletes line item and invalidates cache', async () => {
- const mockCart = { id: '1', token: 'cart_token' };
+ const updatedCart = { id: '1', token: 'cart_token', item_count: 0 };
mockCookieStore.get.mockReturnValue({ value: 'cart_token' });
- mockClient.cart.get.mockResolvedValue(mockCart);
- mockClient.orders.lineItems.delete.mockResolvedValue(undefined);
+ mockClient.cart.items.delete.mockResolvedValue(updatedCart);
- await removeItem('li_1');
- expect(mockClient.orders.lineItems.delete).toHaveBeenCalledWith(
- '1',
+ const result = await removeItem('li_1');
+ expect(result).toEqual(updatedCart);
+ expect(mockClient.cart.items.delete).toHaveBeenCalledWith(
'li_1',
- expect.objectContaining({ orderToken: 'cart_token' })
+ expect.objectContaining({ spreeToken: 'cart_token' })
);
expect(revalidateTag).toHaveBeenCalledWith('cart');
});
@@ -153,7 +170,7 @@ describe('cart actions', () => {
const result = await associateCart();
expect(result).toEqual(mockCart);
expect(mockClient.cart.associate).toHaveBeenCalledWith({
- orderToken: 'cart_token',
+ spreeToken: 'cart_token',
token: 'jwt_token',
});
});
diff --git a/packages/next/tests/actions/checkout.test.ts b/packages/next/tests/actions/checkout.test.ts
index 3ef83977ce..731889ba9f 100644
--- a/packages/next/tests/actions/checkout.test.ts
+++ b/packages/next/tests/actions/checkout.test.ts
@@ -3,20 +3,20 @@ import { mockCookieStore } from '../setup';
import { initSpreeNext, resetClient } from '../../src/config';
const mockClient = {
- orders: {
+ cart: {
get: vi.fn(),
+ couponCodes: {
+ apply: vi.fn(),
+ remove: vi.fn(),
+ },
+ },
+ checkout: {
update: vi.fn(),
- advance: vi.fn(),
- next: vi.fn(),
complete: vi.fn(),
shipments: {
list: vi.fn(),
update: vi.fn(),
},
- couponCodes: {
- apply: vi.fn(),
- remove: vi.fn(),
- },
},
};
@@ -26,9 +26,7 @@ vi.mock('@spree/sdk', () => ({
import {
getCheckout,
- updateOrder,
- advance,
- next,
+ updateCheckout,
getShipments,
selectShippingRate,
applyCoupon,
@@ -49,96 +47,62 @@ describe('checkout actions', () => {
});
describe('getCheckout', () => {
- it('fetches order with expand and auth options', async () => {
- const mockOrder = { id: '1', number: 'R123', line_items: [{ id: 'li1' }] };
- mockClient.orders.get.mockResolvedValue(mockOrder);
-
- const result = await getCheckout('1');
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.get).toHaveBeenCalledWith(
- '1',
- { expand: ['line_items', 'shipments', 'ship_address', 'bill_address'] },
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
- );
+ it('fetches cart with auth options', async () => {
+ const mockCart = { id: '1', number: 'R123', line_items: [{ id: 'li1' }] };
+ mockClient.cart.get.mockResolvedValue(mockCart);
+
+ const result = await getCheckout();
+ expect(result).toEqual(mockCart);
+ expect(mockClient.cart.get).toHaveBeenCalledWith({
+ spreeToken: 'order_token_123',
+ token: 'jwt_token_abc',
+ });
});
});
- describe('updateOrder', () => {
- it('updates order and revalidates checkout', async () => {
- const mockOrder = { id: '1', number: 'R123' };
+ describe('updateCheckout', () => {
+ it('updates checkout and revalidates', async () => {
+ const mockCart = { id: '1', number: 'R123' };
const params = {
ship_address: { firstname: 'John', lastname: 'Doe', address1: '123 Main St', city: 'NY', zipcode: '10001', country_iso: 'US' },
};
- mockClient.orders.update.mockResolvedValue(mockOrder);
+ mockClient.checkout.update.mockResolvedValue(mockCart);
- const result = await updateOrder('1', params);
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.update).toHaveBeenCalledWith(
- '1',
+ const result = await updateCheckout(params);
+ expect(result).toEqual(mockCart);
+ expect(mockClient.checkout.update).toHaveBeenCalledWith(
params,
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
- );
- expect(revalidateTag).toHaveBeenCalledWith('checkout');
- });
- });
-
- describe('advance', () => {
- it('advances checkout and revalidates', async () => {
- const mockOrder = { id: '1', state: 'delivery' };
- mockClient.orders.advance.mockResolvedValue(mockOrder);
-
- const result = await advance('1');
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.advance).toHaveBeenCalledWith(
- '1',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
- );
- expect(revalidateTag).toHaveBeenCalledWith('checkout');
- });
- });
-
- describe('next', () => {
- it('moves checkout to next step and revalidates', async () => {
- const mockOrder = { id: '1', state: 'payment' };
- mockClient.orders.next.mockResolvedValue(mockOrder);
-
- const result = await next('1');
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.next).toHaveBeenCalledWith(
- '1',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
});
});
describe('getShipments', () => {
- it('returns shipments for the order', async () => {
+ it('returns shipments for the cart', async () => {
const mockShipments = { data: [{ id: 's1', shipping_rates: [] }] };
- mockClient.orders.shipments.list.mockResolvedValue(mockShipments);
+ mockClient.checkout.shipments.list.mockResolvedValue(mockShipments);
- const result = await getShipments('1');
+ const result = await getShipments();
expect(result).toEqual(mockShipments);
- expect(mockClient.orders.shipments.list).toHaveBeenCalledWith(
- '1',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ expect(mockClient.checkout.shipments.list).toHaveBeenCalledWith(
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
});
});
describe('selectShippingRate', () => {
it('selects shipping rate and revalidates checkout', async () => {
- const mockOrder = { id: '1', number: 'R123', ship_total: '10.0' };
- mockClient.orders.shipments.update.mockResolvedValue(mockOrder);
+ const mockCart = { id: '1', number: 'R123', ship_total: '10.0' };
+ mockClient.checkout.shipments.update.mockResolvedValue(mockCart);
- const result = await selectShippingRate('1', 's1', 'sr1');
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.shipments.update).toHaveBeenCalledWith(
- '1',
+ const result = await selectShippingRate('s1', 'sr1');
+ expect(result).toEqual(mockCart);
+ expect(mockClient.checkout.shipments.update).toHaveBeenCalledWith(
's1',
{ selected_shipping_rate_id: 'sr1' },
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
});
@@ -146,15 +110,14 @@ describe('checkout actions', () => {
describe('applyCoupon', () => {
it('applies coupon and revalidates checkout and cart', async () => {
- const mockOrder = { id: '1', promo_total: -10 };
- mockClient.orders.couponCodes.apply.mockResolvedValue(mockOrder);
+ const mockCart = { id: '1', promo_total: -10 };
+ mockClient.cart.couponCodes.apply.mockResolvedValue(mockCart);
- const result = await applyCoupon('1', 'SAVE10');
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.couponCodes.apply).toHaveBeenCalledWith(
- '1',
+ const result = await applyCoupon('SAVE10');
+ expect(result).toEqual(mockCart);
+ expect(mockClient.cart.couponCodes.apply).toHaveBeenCalledWith(
'SAVE10',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
expect(revalidateTag).toHaveBeenCalledWith('cart');
@@ -163,15 +126,14 @@ describe('checkout actions', () => {
describe('removeCoupon', () => {
it('removes coupon and revalidates checkout and cart', async () => {
- const mockOrder = { id: '1', promo_total: 0 };
- mockClient.orders.couponCodes.remove.mockResolvedValue(mockOrder);
+ const mockCart = { id: '1', promo_total: 0 };
+ mockClient.cart.couponCodes.remove.mockResolvedValue(mockCart);
- const result = await removeCoupon('1', 'promo_1');
- expect(result).toEqual(mockOrder);
- expect(mockClient.orders.couponCodes.remove).toHaveBeenCalledWith(
- '1',
- 'promo_1',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ const result = await removeCoupon('SAVE10');
+ expect(result).toEqual(mockCart);
+ expect(mockClient.cart.couponCodes.remove).toHaveBeenCalledWith(
+ 'SAVE10',
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
expect(revalidateTag).toHaveBeenCalledWith('cart');
@@ -181,13 +143,12 @@ describe('checkout actions', () => {
describe('complete', () => {
it('completes checkout and revalidates checkout and cart', async () => {
const mockOrder = { id: '1', state: 'complete' };
- mockClient.orders.complete.mockResolvedValue(mockOrder);
+ mockClient.checkout.complete.mockResolvedValue(mockOrder);
- const result = await complete('1');
+ const result = await complete();
expect(result).toEqual(mockOrder);
- expect(mockClient.orders.complete).toHaveBeenCalledWith(
- '1',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ expect(mockClient.checkout.complete).toHaveBeenCalledWith(
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
expect(revalidateTag).toHaveBeenCalledWith('cart');
diff --git a/packages/next/tests/actions/payment-sessions.test.ts b/packages/next/tests/actions/payment-sessions.test.ts
index b251b74ce2..b23ecab932 100644
--- a/packages/next/tests/actions/payment-sessions.test.ts
+++ b/packages/next/tests/actions/payment-sessions.test.ts
@@ -3,7 +3,7 @@ import { mockCookieStore } from '../setup';
import { initSpreeNext, resetClient } from '../../src/config';
const mockClient = {
- orders: {
+ checkout: {
paymentSessions: {
create: vi.fn(),
get: vi.fn(),
@@ -38,14 +38,13 @@ describe('payment session actions', () => {
describe('createPaymentSession', () => {
it('creates a payment session and revalidates checkout', async () => {
const mockSession = { id: 'ps_1', status: 'pending', payment_method_id: 'pm_1' };
- mockClient.orders.paymentSessions.create.mockResolvedValue(mockSession);
+ mockClient.checkout.paymentSessions.create.mockResolvedValue(mockSession);
- const result = await createPaymentSession('order_1', { payment_method_id: 'pm_1' });
+ const result = await createPaymentSession({ payment_method_id: 'pm_1' });
expect(result).toEqual(mockSession);
- expect(mockClient.orders.paymentSessions.create).toHaveBeenCalledWith(
- 'order_1',
+ expect(mockClient.checkout.paymentSessions.create).toHaveBeenCalledWith(
{ payment_method_id: 'pm_1' },
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
});
@@ -54,14 +53,13 @@ describe('payment session actions', () => {
describe('getPaymentSession', () => {
it('returns a payment session by ID', async () => {
const mockSession = { id: 'ps_1', status: 'pending', amount: '99.99' };
- mockClient.orders.paymentSessions.get.mockResolvedValue(mockSession);
+ mockClient.checkout.paymentSessions.get.mockResolvedValue(mockSession);
- const result = await getPaymentSession('order_1', 'ps_1');
+ const result = await getPaymentSession('ps_1');
expect(result).toEqual(mockSession);
- expect(mockClient.orders.paymentSessions.get).toHaveBeenCalledWith(
- 'order_1',
+ expect(mockClient.checkout.paymentSessions.get).toHaveBeenCalledWith(
'ps_1',
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
});
});
@@ -69,15 +67,14 @@ describe('payment session actions', () => {
describe('updatePaymentSession', () => {
it('updates a payment session and revalidates checkout', async () => {
const mockSession = { id: 'ps_1', status: 'pending', amount: '50.00' };
- mockClient.orders.paymentSessions.update.mockResolvedValue(mockSession);
+ mockClient.checkout.paymentSessions.update.mockResolvedValue(mockSession);
- const result = await updatePaymentSession('order_1', 'ps_1', { amount: '50.00' });
+ const result = await updatePaymentSession('ps_1', { amount: '50.00' });
expect(result).toEqual(mockSession);
- expect(mockClient.orders.paymentSessions.update).toHaveBeenCalledWith(
- 'order_1',
+ expect(mockClient.checkout.paymentSessions.update).toHaveBeenCalledWith(
'ps_1',
{ amount: '50.00' },
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
});
@@ -86,30 +83,28 @@ describe('payment session actions', () => {
describe('completePaymentSession', () => {
it('completes a payment session and revalidates checkout', async () => {
const mockSession = { id: 'ps_1', status: 'completed' };
- mockClient.orders.paymentSessions.complete.mockResolvedValue(mockSession);
+ mockClient.checkout.paymentSessions.complete.mockResolvedValue(mockSession);
- const result = await completePaymentSession('order_1', 'ps_1', { session_result: 'success' });
+ const result = await completePaymentSession('ps_1', { session_result: 'success' });
expect(result).toEqual(mockSession);
- expect(mockClient.orders.paymentSessions.complete).toHaveBeenCalledWith(
- 'order_1',
+ expect(mockClient.checkout.paymentSessions.complete).toHaveBeenCalledWith(
'ps_1',
{ session_result: 'success' },
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
expect(revalidateTag).toHaveBeenCalledWith('checkout');
});
it('completes without params', async () => {
const mockSession = { id: 'ps_1', status: 'completed' };
- mockClient.orders.paymentSessions.complete.mockResolvedValue(mockSession);
+ mockClient.checkout.paymentSessions.complete.mockResolvedValue(mockSession);
- const result = await completePaymentSession('order_1', 'ps_1');
+ const result = await completePaymentSession('ps_1');
expect(result).toEqual(mockSession);
- expect(mockClient.orders.paymentSessions.complete).toHaveBeenCalledWith(
- 'order_1',
+ expect(mockClient.checkout.paymentSessions.complete).toHaveBeenCalledWith(
'ps_1',
undefined,
- { orderToken: 'order_token_123', token: 'jwt_token_abc' }
+ { spreeToken: 'order_token_123', token: 'jwt_token_abc' }
);
});
});
diff --git a/packages/sdk-core/src/request.ts b/packages/sdk-core/src/request.ts
index 33fee8ee3c..515227d284 100644
--- a/packages/sdk-core/src/request.ts
+++ b/packages/sdk-core/src/request.ts
@@ -16,8 +16,8 @@ export interface RetryConfig {
export interface RequestOptions {
/** Bearer token for authenticated requests */
token?: string;
- /** Order token for guest checkout */
- orderToken?: string;
+ /** Spree token for guest cart/checkout/order access */
+ spreeToken?: string;
/** Locale for translated content (e.g., 'en', 'fr') */
locale?: string;
/** Currency for prices (e.g., 'USD', 'EUR') */
@@ -107,7 +107,7 @@ export function createRequestFn(
path: string,
options: InternalRequestOptions = {}
): Promise<T> {
- const { token, orderToken, idempotencyKey, headers = {}, body, params } = options;
+ const { token, spreeToken, idempotencyKey, headers = {}, body, params } = options;
// Per-request options override client-level defaults
const locale = options.locale ?? defaults?.locale;
@@ -141,8 +141,8 @@ export function createRequestFn(
requestHeaders['Authorization'] = `Bearer ${token}`;
}
- if (orderToken) {
- requestHeaders['x-spree-order-token'] = orderToken;
+ if (spreeToken) {
+ requestHeaders['x-spree-token'] = spreeToken;
}
if (locale) {
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index d355562525..dad287483c 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -40,14 +40,16 @@ const { token, user } = await client.auth.login({
// Create a cart and add items
const cart = await client.cart.create();
-await client.orders.lineItems.create(cart.id, {
+await client.cart.items.create({
variant_id: 'var_abc123',
quantity: 2,
-}, { orderToken: cart.token });
+}, { spreeToken: cart.token });
// Checkout flow
-await client.orders.next(cart.id, { orderToken: cart.token });
-await client.orders.complete(cart.id, { orderToken: cart.token });
+await client.checkout.update({
+ email: '[email protected]',
+}, { spreeToken: cart.token });
+await client.checkout.complete({ spreeToken: cart.token });
```
## Client Architecture
@@ -56,10 +58,13 @@ All Store API resources are available directly on the client:
```typescript
client.products.list() // Products
-client.cart.create() // Cart
-client.orders.complete(id, opt) // Checkout
+client.cart.create() // Cart (singleton)
+client.cart.items.create(params) // Cart line items
+client.carts.list() // List active carts
+client.checkout.complete(opt) // Checkout
client.customers.create(params) // Registration
client.customer.get(opt) // Account
+client.customer.orders.list() // Order history
```
## Authentication
@@ -88,7 +93,7 @@ const { token, user } = await client.auth.login({
});
// Use token for authenticated requests
-const orders = await client.orders.list({}, { token });
+const orders = await client.customer.orders.list({}, { token });
// Refresh token when needed
const newTokens = await client.auth.refresh({ token });
@@ -108,28 +113,28 @@ const { token, user } = await client.customers.create({
## Guest Checkout
-For guest checkout, use the `token` (or `order_token`) returned when creating a cart:
+For guest checkout, use the `token` returned when creating a cart:
```typescript
// Create a cart (guest)
const cart = await client.cart.create();
-// Use orderToken for all cart operations
-const options = { orderToken: cart.token };
+// Use spreeToken for all cart/checkout operations
+const options = { spreeToken: cart.token };
// Add items
-await client.orders.lineItems.create(cart.id, {
+await client.cart.items.create({
variant_id: 'var_abc123',
quantity: 1,
}, options);
-// Update order with email
-await client.orders.update(cart.id, {
+// Update checkout with email and addresses
+await client.checkout.update({
}, options);
// Complete checkout
-await client.orders.complete(cart.id, options);
+await client.checkout.complete(options);
```
## API Reference
@@ -187,139 +192,139 @@ const categoryProducts = await client.categories.products.list('clothing/shirts'
### Cart
+The cart API uses an implicit cart model -- no order ID is needed. The cart is resolved
+from the `spreeToken` header (guest) or JWT token (authenticated user).
+
```typescript
+// Create a new cart
+const cart = await client.cart.create();
+
// Get current cart
-const cart = await client.cart.get({ orderToken: 'xxx' });
+const cart = await client.cart.get({ spreeToken: cart.token });
-// Create a new cart
-const newCart = await client.cart.create();
+// Delete / empty current cart
+await client.cart.delete({ spreeToken: cart.token });
// Associate guest cart with authenticated user
// (after user logs in, merge their guest cart with their account)
await client.cart.associate({
- token: jwtToken, // User's JWT token
- orderToken: cart.token, // Guest cart token
+ token: jwtToken, // User's JWT token
+ spreeToken: cart.token, // Guest cart token
});
-```
-
-### Orders & Checkout
-
-```typescript
-// List orders for authenticated customer
-const orders = await client.orders.list({}, { token });
-
-// Create a new order (cart)
-const cart = await client.orders.create();
-const options = { orderToken: cart.order_token };
-
-// Get order by ID or number
-const order = await client.orders.get('R123456789', {
- expand: ['line_items', 'shipments'],
-}, options);
-
-// Update order (email, addresses)
-await client.orders.update(cart.id, {
- email: '[email protected]',
- ship_address: {
- firstname: 'John',
- lastname: 'Doe',
- address1: '123 Main St',
- city: 'New York',
- zipcode: '10001',
- phone: '+1 555 123 4567',
- country_iso: 'US',
- state_abbr: 'NY',
- },
- bill_address_id: 'addr_xxx', // Or use existing address by ID
-}, options);
-// Checkout flow
-await client.orders.next(cart.id, options); // Move to next step
-await client.orders.advance(cart.id, options); // Advance through all steps
-await client.orders.complete(cart.id, options); // Complete the order
+// List all active carts for authenticated user
+const { data: carts } = await client.carts.list({ token: jwtToken });
```
-### Line Items
+### Cart Items (Line Items)
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
// Add item
-await client.orders.lineItems.create(cart.id, {
+await client.cart.items.create({
variant_id: 'var_123',
quantity: 2,
}, options);
// Update item quantity
-await client.orders.lineItems.update(cart.id, lineItemId, {
+await client.cart.items.update(lineItemId, {
quantity: 3,
}, options);
// Remove item
-await client.orders.lineItems.delete(cart.id, lineItemId, options);
+await client.cart.items.delete(lineItemId, options);
```
### Coupon Codes
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
// Apply a coupon code
-await client.orders.couponCodes.apply(cart.id, 'SAVE20', options);
+await client.cart.couponCodes.apply('SAVE20', options);
// Remove a coupon code
-await client.orders.couponCodes.remove(cart.id, 'promo_xxx', options);
+await client.cart.couponCodes.remove('promo_xxx', options);
```
-### Store Credits
+### Checkout
-```typescript
-const options = { orderToken: cart.token };
+The checkout API operates on the current cart, resolved implicitly from the
+`spreeToken` header or JWT token.
-// Apply store credit to order (applies maximum available by default)
-await client.orders.addStoreCredit(cart.id, undefined, options);
+```typescript
+const options = { spreeToken: cart.token };
-// Apply specific amount of store credit
-await client.orders.addStoreCredit(cart.id, 25.00, options);
+// Update checkout (email, addresses)
+await client.checkout.update({
+ email: '[email protected]',
+ ship_address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ phone: '+1 555 123 4567',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ },
+ bill_address_id: 'addr_xxx', // Or use existing address by ID
+}, options);
-// Remove store credit from order
-await client.orders.removeStoreCredit(cart.id, options);
+// Complete the order
+await client.checkout.complete(options);
```
### Shipments
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// List shipments for an order
-const shipments = await client.orders.shipments.list(cart.id, options);
+// List shipments for the current checkout
+const shipments = await client.checkout.shipments.list(options);
// Select a shipping rate
-await client.orders.shipments.update(cart.id, shipmentId, {
+await client.checkout.shipments.update(shipmentId, {
selected_shipping_rate_id: 'rate_xxx',
}, options);
```
+### Store Credits
+
+```typescript
+const options = { spreeToken: cart.token };
+
+// Apply store credit to checkout (applies maximum available by default)
+await client.checkout.storeCredits.apply(undefined, options);
+
+// Apply specific amount of store credit
+await client.checkout.storeCredits.apply(25.00, options);
+
+// Remove store credit from checkout
+await client.checkout.storeCredits.remove(options);
+```
+
### Payments
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
-// Get available payment methods for an order
-const methods = await client.orders.paymentMethods.list(cart.id, options);
+// Get available payment methods for the current checkout
+const methods = await client.checkout.paymentMethods.list(options);
// Each method includes `session_required` flag:
-// - true → use paymentSessions (Stripe, Adyen, PayPal, etc.)
-// - false → use payments.create (Check, Cash on Delivery, Bank Transfer, etc.)
+// - true -> use paymentSessions (Stripe, Adyen, PayPal, etc.)
+// - false -> use payments.create (Check, Cash on Delivery, Bank Transfer, etc.)
-// List payments on an order
-const payments = await client.orders.payments.list(cart.id, options);
+// List payments on the current checkout
+const payments = await client.checkout.payments.list(options);
// Get a specific payment
-const payment = await client.orders.payments.get(cart.id, paymentId, options);
+const payment = await client.checkout.payments.get(paymentId, options);
// Create a payment for a non-session payment method
// (e.g. Check, Cash on Delivery, Bank Transfer, Purchase Order)
-const payment = await client.orders.payments.create(cart.id, {
+const payment = await client.checkout.payments.create({
payment_method_id: 'pm_xxx',
amount: '99.99', // Optional, defaults to order total minus store credits
metadata: { // Optional, write-only metadata
@@ -333,10 +338,10 @@ const payment = await client.orders.payments.create(cart.id, {
Payment sessions provide a unified, provider-agnostic interface for payment processing. They work with any payment gateway (Stripe, Adyen, PayPal, etc.) through a single API.
```typescript
-const options = { orderToken: cart.token };
+const options = { spreeToken: cart.token };
// Create a payment session (initializes a session with the payment gateway)
-const session = await client.orders.paymentSessions.create(cart.id, {
+const session = await client.checkout.paymentSessions.create({
payment_method_id: 'pm_xxx',
amount: '99.99', // Optional, defaults to order total
external_data: { // Optional, provider-specific data
@@ -348,24 +353,49 @@ const session = await client.orders.paymentSessions.create(cart.id, {
console.log(session.external_data.client_secret);
// Get a payment session
-const existing = await client.orders.paymentSessions.get(
- cart.id, session.id, options
+const existing = await client.checkout.paymentSessions.get(
+ session.id, options
);
// Update a payment session (e.g., after order total changes)
-await client.orders.paymentSessions.update(cart.id, session.id, {
+await client.checkout.paymentSessions.update(session.id, {
amount: '149.99',
}, options);
// Complete the payment session (after customer confirms payment on the frontend)
-const completed = await client.orders.paymentSessions.complete(
- cart.id, session.id,
+const completed = await client.checkout.paymentSessions.complete(
+ session.id,
{ session_result: 'success' },
options
);
console.log(completed.status); // 'completed'
```
+### Orders
+
+Completed orders can be looked up by ID or number:
+
+```typescript
+// Get a completed order by ID or number
+const order = await client.orders.get('R123456789', {
+ expand: ['line_items', 'shipments'],
+}, { spreeToken: orderToken });
+```
+
+For order history, use the customer orders resource:
+
+```typescript
+const options = { token: jwtToken };
+
+// List order history for authenticated customer
+const orders = await client.customer.orders.list({}, options);
+
+// Get a specific order from history
+const order = await client.customer.orders.get('or_xxx', {
+ expand: ['line_items', 'shipments'],
+}, options);
+```
+
### Markets
```typescript
@@ -517,26 +547,34 @@ The SDK uses a resource builder pattern for nested resources:
| Parent Resource | Nested Resource | Available Methods |
|-----------------|-----------------|-------------------|
-| `orders` | `lineItems` | `create`, `update`, `delete` |
-| `orders` | `payments` | `list`, `get`, `create` |
-| `orders` | `paymentMethods` | `list` |
-| `orders` | `paymentSessions` | `create`, `get`, `update`, `complete` |
-| `orders` | `shipments` | `list`, `update` |
-| `orders` | `couponCodes` | `apply`, `remove` |
+| `cart` | `items` | `create`, `update`, `delete` |
+| `cart` | `couponCodes` | `apply`, `remove` |
+| `checkout` | `shipments` | `list`, `update` |
+| `checkout` | `paymentMethods` | `list` |
+| `checkout` | `payments` | `list`, `get`, `create` |
+| `checkout` | `paymentSessions` | `create`, `get`, `update`, `complete` |
+| `checkout` | `storeCredits` | `apply`, `remove` |
| `customer` | `addresses` | `list`, `get`, `create`, `update`, `delete`, `markAsDefault` |
| `customer` | `creditCards` | `list`, `get`, `delete` |
| `customer` | `giftCards` | `list`, `get` |
+| `customer` | `orders` | `list`, `get` |
| `markets` | `countries` | `list`, `get` |
| `categories` | `products` | `list` |
| `wishlists` | `items` | `create`, `update`, `delete` |
Example:
```typescript
-// Nested resources follow the pattern: client.parent.nested.method(parentId, ...)
-await client.orders.lineItems.create(orderId, params, options);
-await client.orders.payments.list(orderId, options);
-await client.orders.shipments.update(orderId, shipmentId, params, options);
+// Cart and checkout resources are implicit -- no order ID needed
+await client.cart.items.create(params, options);
+await client.cart.couponCodes.apply(code, options);
+await client.checkout.shipments.update(shipmentId, params, options);
+await client.checkout.payments.list(options);
+await client.checkout.paymentSessions.create(params, options);
+await client.checkout.storeCredits.apply(amount, options);
+
+// Other nested resources follow the pattern: client.parent.nested.method(parentId, ...)
await client.customer.addresses.list({}, options);
+await client.customer.orders.list({}, options);
await client.markets.countries.list(marketId);
await client.categories.products.list(categoryId, params, options);
await client.wishlists.items.create(wishlistId, params, options);
@@ -605,6 +643,7 @@ The SDK includes full TypeScript support with generated types from the API seria
```typescript
import type {
StoreProduct,
+ StoreCart,
StoreOrder,
StoreVariant,
StoreCategory,
@@ -617,6 +656,7 @@ import type {
// All responses are fully typed
const products: PaginatedResponse<StoreProduct> = await client.products.list();
const category: StoreCategory = await client.categories.get('clothing');
+const cart: StoreCart = await client.cart.create();
```
## Available Types
@@ -626,7 +666,8 @@ The SDK exports all Store API types:
### Core Types
- `StoreProduct` - Product data
- `StoreVariant` - Variant data
-- `StoreOrder` - Order/cart data
+- `StoreCart` - Cart data (uses `cart_` prefixed IDs)
+- `StoreOrder` - Completed order data (uses `or_` prefixed IDs)
- `StoreLineItem` - Line item in cart
- `StoreCategory` - Category
- `StoreCountry` - Country with states
@@ -668,6 +709,7 @@ The SDK exports all Store API types:
- `PaginatedResponse<T>` - Paginated API response
- `AuthTokens` - JWT tokens from login
- `AddressParams` - Address input parameters
+- `UpdateCheckoutParams` - Checkout update parameters
- `CreatePaymentParams` - Direct payment creation parameters (for non-session payment methods)
- `CreatePaymentSessionParams` - Payment session creation parameters
- `UpdatePaymentSessionParams` - Payment session update parameters
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index 78a395b334..84da2e12f7 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -18,13 +18,14 @@ import type {
CreateCartParams,
AddLineItemParams,
UpdateLineItemParams,
- UpdateOrderParams,
+ UpdateCheckoutParams,
CreatePaymentParams,
CreatePaymentSessionParams,
UpdatePaymentSessionParams,
CompletePaymentSessionParams,
CreatePaymentSetupSessionParams,
CompletePaymentSetupSessionParams,
+ Cart,
CreditCard,
GiftCard,
Product,
@@ -278,174 +279,199 @@ export class StoreClient {
};
// ============================================
- // Cart (convenience wrapper for current incomplete order)
+ // Carts (list all active carts for authenticated users)
// ============================================
- readonly cart = {
- /**
- * Get current cart (returns null if none exists)
- * Pass orderToken for guest checkout, or use JWT for authenticated users
- */
- get: (options?: RequestOptions): Promise<Order & { token: string }> =>
- this.request<Order & { token: string }>('GET', '/cart', options),
-
- /**
- * Create a new cart
- * @param params - Optional cart parameters (e.g., metadata)
- */
- create: (params?: CreateCartParams, options?: RequestOptions): Promise<Order & { token: string }> =>
- this.request<Order & { token: string }>('POST', '/cart', {
- ...options,
- body: params,
- }),
-
+ readonly carts = {
/**
- * Associate a guest cart with the currently authenticated user
- * Requires both JWT token (for authentication) and orderToken (to identify the cart)
- * @param options - Must include both `token` (JWT) and `orderToken` (guest cart token)
+ * List all active (incomplete) carts for the authenticated user
*/
- associate: (options: RequestOptions): Promise<Order & { token: string }> =>
- this.request<Order & { token: string }>('PATCH', '/cart/associate', options),
+ list: (options?: RequestOptions): Promise<ListResponse<Cart>> =>
+ this.request<ListResponse<Cart>>('GET', '/carts', options),
};
// ============================================
- // Orders (individual order management & checkout)
+ // Cart (pre-purchase, mutable)
// ============================================
- readonly orders = {
+ readonly cart = {
/**
- * Get an order by ID or number
+ * Get current cart
+ * Pass spreeToken for guest checkout, or use JWT for authenticated users
*/
- get: (
- idOrNumber: string,
- params?: { expand?: string[]; fields?: string[] },
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>('GET', `/orders/${idOrNumber}`, {
- ...options,
- params: getParams(params),
- }),
+ get: (options?: RequestOptions): Promise<Cart> =>
+ this.request<Cart>('GET', '/cart', options),
/**
- * Update an order
+ * Create a new cart
+ * @param params - Optional cart parameters (e.g., metadata, line_items)
*/
- update: (
- idOrNumber: string,
- params: UpdateOrderParams,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>('PATCH', `/orders/${idOrNumber}`, {
+ create: (params?: CreateCartParams, options?: RequestOptions): Promise<Cart> =>
+ this.request<Cart>('POST', '/cart', {
...options,
body: params,
}),
/**
- * Advance order to next checkout step
- */
- next: (
- idOrNumber: string,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>('PATCH', `/orders/${idOrNumber}/next`, options),
-
- /**
- * Advance through all checkout steps
- */
- advance: (
- idOrNumber: string,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
- 'PATCH',
- `/orders/${idOrNumber}/advance`,
- options
- ),
-
- /**
- * Complete the order
- */
- complete: (
- idOrNumber: string,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
- 'PATCH',
- `/orders/${idOrNumber}/complete`,
- options
- ),
-
- /**
- * Add store credit to order
+ * Delete the current cart
*/
- addStoreCredit: (
- idOrNumber: string,
- amount?: number,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>('POST', `/orders/${idOrNumber}/store_credits`, {
- ...options,
- body: amount ? { amount } : undefined,
- }),
+ delete: (options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', '/cart', options),
/**
- * Remove store credit from order
+ * Associate a guest cart with the currently authenticated user
+ * Requires both JWT token (for authentication) and spreeToken (to identify the cart)
+ * @param options - Must include both `token` (JWT) and `spreeToken` (guest cart token)
*/
- removeStoreCredit: (
- idOrNumber: string,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
- 'DELETE',
- `/orders/${idOrNumber}/store_credits`,
- options
- ),
+ associate: (options: RequestOptions): Promise<Cart> =>
+ this.request<Cart>('PATCH', '/cart/associate', options),
/**
* Nested resource: Line items
*/
- lineItems: {
+ items: {
/**
- * Add a line item to an order.
- * Returns the updated order with recalculated totals.
+ * Add an item to the cart.
+ * Returns the updated cart with recalculated totals.
*/
create: (
- orderId: string,
params: AddLineItemParams,
options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>('POST', `/orders/${orderId}/line_items`, {
+ ): Promise<Cart> =>
+ this.request<Cart>('POST', '/cart/items', {
...options,
body: params,
}),
/**
* Update a line item quantity.
- * Returns the updated order with recalculated totals.
+ * Returns the updated cart with recalculated totals.
*/
update: (
- orderId: string,
lineItemId: string,
params: UpdateLineItemParams,
options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
+ ): Promise<Cart> =>
+ this.request<Cart>(
'PATCH',
- `/orders/${orderId}/line_items/${lineItemId}`,
+ `/cart/items/${lineItemId}`,
{ ...options, body: params }
),
/**
- * Remove a line item from an order.
- * Returns the updated order with recalculated totals.
+ * Remove a line item from the cart.
+ * Returns the updated cart with recalculated totals.
*/
delete: (
- orderId: string,
lineItemId: string,
options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
+ ): Promise<Cart> =>
+ this.request<Cart>(
+ 'DELETE',
+ `/cart/items/${lineItemId}`,
+ options
+ ),
+ },
+
+ /**
+ * Nested resource: Coupon codes
+ */
+ couponCodes: {
+ /**
+ * Apply a coupon code to the cart
+ */
+ apply: (
+ code: string,
+ options?: RequestOptions
+ ): Promise<Cart> =>
+ this.request<Cart>('POST', '/cart/coupon_codes', {
+ ...options,
+ body: { code },
+ }),
+
+ /**
+ * Remove a coupon code from the cart
+ * @param code - The coupon code string to remove (e.g., 'SAVE10')
+ */
+ remove: (
+ code: string,
+ options?: RequestOptions
+ ): Promise<Cart> =>
+ this.request<Cart>(
'DELETE',
- `/orders/${orderId}/line_items/${lineItemId}`,
+ `/cart/coupon_codes/${code}`,
+ options
+ ),
+ },
+ };
+
+ // ============================================
+ // Checkout (cart → order transition)
+ // ============================================
+
+ readonly checkout = {
+ /**
+ * Update checkout info (email, addresses, special instructions).
+ * When addresses change, the order state is reverted to address
+ * to ensure shipments are recalculated.
+ */
+ update: (
+ params: UpdateCheckoutParams,
+ options?: RequestOptions
+ ): Promise<Cart> =>
+ this.request<Cart>('PATCH', '/checkout', {
+ ...options,
+ body: params,
+ }),
+
+ /**
+ * Complete the checkout and finalize the purchase.
+ * Returns an Order (not Cart).
+ */
+ complete: (options?: RequestOptions): Promise<Order> =>
+ this.request<Order>('POST', '/checkout/complete', options),
+
+ /**
+ * Nested resource: Shipments
+ */
+ shipments: {
+ /**
+ * List shipments with shipping rates for the current cart
+ */
+ list: (options?: RequestOptions): Promise<ListResponse<Shipment>> =>
+ this.request<ListResponse<Shipment>>(
+ 'GET',
+ '/checkout/shipments',
+ options
+ ),
+
+ /**
+ * Select a shipping rate for a specific shipment.
+ * Returns the updated cart with recalculated totals.
+ */
+ update: (
+ shipmentId: string,
+ params: { selected_shipping_rate_id: string },
+ options?: RequestOptions
+ ): Promise<Cart> =>
+ this.request<Cart>(
+ 'PATCH',
+ `/checkout/shipments/${shipmentId}`,
+ { ...options, body: params }
+ ),
+ },
+
+ /**
+ * Nested resource: Payment methods
+ */
+ paymentMethods: {
+ /**
+ * List available payment methods for the current cart
+ */
+ list: (options?: RequestOptions): Promise<ListResponse<PaymentMethod>> =>
+ this.request<ListResponse<PaymentMethod>>(
+ 'GET',
+ '/checkout/payment_methods',
options
),
},
@@ -455,15 +481,12 @@ export class StoreClient {
*/
payments: {
/**
- * List payments for an order
+ * List payments for the current cart
*/
- list: (
- orderId: string,
- options?: RequestOptions
- ): Promise<PaginatedResponse<Payment>> =>
- this.request<PaginatedResponse<Payment>>(
+ list: (options?: RequestOptions): Promise<ListResponse<Payment>> =>
+ this.request<ListResponse<Payment>>(
'GET',
- `/orders/${orderId}/payments`,
+ '/checkout/payments',
options
),
@@ -471,66 +494,45 @@ export class StoreClient {
* Get a payment by ID
*/
get: (
- orderId: string,
paymentId: string,
options?: RequestOptions
): Promise<Payment> =>
this.request<Payment>(
'GET',
- `/orders/${orderId}/payments/${paymentId}`,
+ `/checkout/payments/${paymentId}`,
options
),
/**
- * Create a payment for a non-session payment method (e.g. Check, Cash on Delivery, Bank Transfer)
- * For session-based payment methods (e.g. Stripe, PayPal), use paymentSessions.create() instead
+ * Create a payment for a non-session payment method (e.g. Check, Cash on Delivery, Bank Transfer).
+ * For session-based payment methods (e.g. Stripe, PayPal), use checkout.paymentSessions.create() instead.
*/
create: (
- orderId: string,
params: CreatePaymentParams,
options?: RequestOptions
): Promise<Payment> =>
this.request<Payment>(
'POST',
- `/orders/${orderId}/payments`,
+ '/checkout/payments',
{ ...options, body: params }
),
},
- /**
- * Nested resource: Payment methods
- */
- paymentMethods: {
- /**
- * List available payment methods for an order
- */
- list: (
- orderId: string,
- options?: RequestOptions
- ): Promise<ListResponse<PaymentMethod>> =>
- this.request<ListResponse<PaymentMethod>>(
- 'GET',
- `/orders/${orderId}/payment_methods`,
- options
- ),
- },
-
/**
* Nested resource: Payment sessions
*/
paymentSessions: {
/**
- * Create a payment session for an order
- * Delegates to the payment gateway to initialize a provider-specific session
+ * Create a payment session for the current cart.
+ * Delegates to the payment gateway to initialize a provider-specific session.
*/
create: (
- orderId: string,
params: CreatePaymentSessionParams,
options?: RequestOptions
): Promise<PaymentSession> =>
this.request<PaymentSession>(
'POST',
- `/orders/${orderId}/payment_sessions`,
+ '/checkout/payment_sessions',
{ ...options, body: params }
),
@@ -538,115 +540,92 @@ export class StoreClient {
* Get a payment session by ID
*/
get: (
- orderId: string,
sessionId: string,
options?: RequestOptions
): Promise<PaymentSession> =>
this.request<PaymentSession>(
'GET',
- `/orders/${orderId}/payment_sessions/${sessionId}`,
+ `/checkout/payment_sessions/${sessionId}`,
options
),
/**
- * Update a payment session
- * Delegates to the payment gateway to sync changes with the provider
+ * Update a payment session.
+ * Delegates to the payment gateway to sync changes with the provider.
*/
update: (
- orderId: string,
sessionId: string,
params: UpdatePaymentSessionParams,
options?: RequestOptions
): Promise<PaymentSession> =>
this.request<PaymentSession>(
'PATCH',
- `/orders/${orderId}/payment_sessions/${sessionId}`,
+ `/checkout/payment_sessions/${sessionId}`,
{ ...options, body: params }
),
/**
- * Complete a payment session
- * Confirms the payment with the provider, triggering capture/authorization
+ * Complete a payment session.
+ * Confirms the payment with the provider, triggering capture/authorization.
*/
complete: (
- orderId: string,
sessionId: string,
params?: CompletePaymentSessionParams,
options?: RequestOptions
): Promise<PaymentSession> =>
this.request<PaymentSession>(
'PATCH',
- `/orders/${orderId}/payment_sessions/${sessionId}/complete`,
+ `/checkout/payment_sessions/${sessionId}/complete`,
{ ...options, body: params }
),
},
/**
- * Nested resource: Coupon codes
+ * Store credits
*/
- couponCodes: {
+ storeCredits: {
/**
- * Apply a coupon code to an order
+ * Apply store credit to the current cart
*/
apply: (
- orderId: string,
- code: string,
+ amount?: number,
options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>('POST', `/orders/${orderId}/coupon_codes`, {
+ ): Promise<Cart> =>
+ this.request<Cart>('POST', '/checkout/store_credits', {
...options,
- body: { code },
+ body: amount ? { amount } : undefined,
}),
/**
- * Remove a coupon code from an order
- * @param promotionId - The promotion prefix_id (e.g., 'promo_xxx')
+ * Remove store credit from the current cart
*/
- remove: (
- orderId: string,
- promotionId: string,
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
+ remove: (options?: RequestOptions): Promise<Cart> =>
+ this.request<Cart>(
'DELETE',
- `/orders/${orderId}/coupon_codes/${promotionId}`,
+ '/checkout/store_credits',
options
),
},
+ };
+
+ // ============================================
+ // Orders (post-purchase, read-only)
+ // ============================================
+ readonly orders = {
/**
- * Nested resource: Shipments
+ * Get a completed order by prefixed ID.
+ * Accessible via JWT (authenticated users) or spreeToken (guests).
*/
- shipments: {
- /**
- * List shipments for an order
- */
- list: (
- orderId: string,
- options?: RequestOptions
- ): Promise<ListResponse<Shipment>> =>
- this.request<ListResponse<Shipment>>(
- 'GET',
- `/orders/${orderId}/shipments`,
- options
- ),
-
- /**
- * Select a shipping rate for a shipment.
- * Returns the updated order with recalculated totals.
- */
- update: (
- orderId: string,
- shipmentId: string,
- params: { selected_shipping_rate_id: string },
- options?: RequestOptions
- ): Promise<Order> =>
- this.request<Order>(
- 'PATCH',
- `/orders/${orderId}/shipments/${shipmentId}`,
- { ...options, body: params }
- ),
- },
+ get: (
+ id: string,
+ params?: { expand?: string[]; fields?: string[] },
+ options?: RequestOptions
+ ): Promise<Order> =>
+ this.request<Order>('GET', `/orders/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
};
// ============================================
@@ -820,7 +799,7 @@ export class StoreClient {
*/
orders: {
/**
- * List orders for the authenticated customer
+ * List completed orders for the authenticated customer
*/
list: (
params?: OrderListParams,
@@ -830,6 +809,19 @@ export class StoreClient {
...options,
params: transformListParams({ ...params }),
}),
+
+ /**
+ * Get a completed order by prefixed ID
+ */
+ get: (
+ id: string,
+ params?: { expand?: string[]; fields?: string[] },
+ options?: RequestOptions
+ ): Promise<Order> =>
+ this.request<Order>('GET', `/customer/orders/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
},
/**
diff --git a/packages/sdk/src/types/generated/Cart.ts b/packages/sdk/src/types/generated/Cart.ts
new file mode 100644
index 0000000000..a2dc50d125
--- /dev/null
+++ b/packages/sdk/src/types/generated/Cart.ts
@@ -0,0 +1,45 @@
+// Typelizer digest 636fc64e20299ec2f2808ce74a3346d8
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {OrderPromotion, LineItem, Shipment, Payment, Address, PaymentMethod} from '@/types'
+
+type Cart = {
+ id: string;
+ number: string;
+ state: string;
+ checkout_steps: Array<string>;
+ token: string;
+ email: string | null;
+ special_instructions: string | null;
+ currency: string;
+ locale: string | null;
+ item_count: number;
+ state_lock_version: number;
+ item_total: string;
+ display_item_total: string;
+ ship_total: string;
+ display_ship_total: string;
+ adjustment_total: string;
+ display_adjustment_total: string;
+ promo_total: string;
+ display_promo_total: string;
+ tax_total: string;
+ display_tax_total: string;
+ included_tax_total: string;
+ display_included_tax_total: string;
+ additional_tax_total: string;
+ display_additional_tax_total: string;
+ total: string;
+ display_total: string;
+ created_at: string;
+ updated_at: string;
+ order_promotions: Array<OrderPromotion>;
+ line_items: Array<LineItem>;
+ shipments: Array<Shipment>;
+ payments: Array<Payment>;
+ bill_address: Address | null;
+ ship_address: Address | null;
+ payment_methods: Array<PaymentMethod>;
+}
+
+export default Cart;
diff --git a/packages/sdk/src/types/generated/Category.ts b/packages/sdk/src/types/generated/Category.ts
index a812ee3f9d..40207efca1 100644
--- a/packages/sdk/src/types/generated/Category.ts
+++ b/packages/sdk/src/types/generated/Category.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 9d24694ed1aa8cd06315bdec2f4d5f98
+// Typelizer digest 7b585549662bf0388cb0eb3108e6b307
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Metafield} from '@/types'
diff --git a/packages/sdk/src/types/generated/Order.ts b/packages/sdk/src/types/generated/Order.ts
index b17ee8db7e..e90eee49c9 100644
--- a/packages/sdk/src/types/generated/Order.ts
+++ b/packages/sdk/src/types/generated/Order.ts
@@ -1,20 +1,16 @@
-// Typelizer digest 39661d343ce5d6855bafc2f8ec8cbe76
+// Typelizer digest 00690139290656f5d604f525be3f822d
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {OrderPromotion, LineItem, Shipment, Payment, Address, PaymentMethod} from '@/types'
+import type {OrderPromotion, LineItem, Shipment, Payment, Address} from '@/types'
type Order = {
id: string;
number: string;
- state: string;
- checkout_steps: Array<string>;
- token: string;
- email: string | null;
+ email: string;
special_instructions: string | null;
currency: string;
locale: string | null;
item_count: number;
- state_lock_version: number;
shipment_state: string | null;
payment_state: string | null;
item_total: string;
@@ -42,7 +38,6 @@ type Order = {
payments: Array<Payment>;
bill_address: Address | null;
ship_address: Address | null;
- payment_methods: Array<PaymentMethod>;
}
export default Order;
diff --git a/packages/sdk/src/types/generated/Product.ts b/packages/sdk/src/types/generated/Product.ts
index 18441f363a..b3a4348df3 100644
--- a/packages/sdk/src/types/generated/Product.ts
+++ b/packages/sdk/src/types/generated/Product.ts
@@ -1,4 +1,4 @@
-// Typelizer digest f9a8a140f08fdd17935cce9e01ba77cd
+// Typelizer digest 91825afbdee8d60521a89338e3d8b720
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Price, Image, Variant, OptionType, Category, Metafield} from '@/types'
diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.ts
index 99d0e38e55..c97b02bfe7 100644
--- a/packages/sdk/src/types/generated/index.ts
+++ b/packages/sdk/src/types/generated/index.ts
@@ -1,9 +1,10 @@
-// Typelizer digest 450ded3dad2271ca66edb94fbfcdc4f2
+// Typelizer digest f872a587635fbfb2192dbd96b097b4e3
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
export type { default as Asset } from './Asset'
export type { default as Base } from './Base'
+export type { default as Cart } from './Cart'
export type { default as Category } from './Category'
export type { default as Country } from './Country'
export type { default as CreditCard } from './CreditCard'
diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.ts
index 410c992f07..3c71c314b8 100644
--- a/packages/sdk/src/types/index.ts
+++ b/packages/sdk/src/types/index.ts
@@ -5,6 +5,7 @@ export type {
Address,
Asset,
Base,
+ Cart,
Category,
Country,
CreditCard,
@@ -61,6 +62,7 @@ export type {
// Backward compatibility aliases (Store* prefix)
export type { Address as StoreAddress } from './generated';
export type { Asset as StoreAsset } from './generated';
+export type { Cart as StoreCart } from './generated';
export type { Category as StoreCategory } from './generated';
export type { Country as StoreCountry } from './generated';
export type { CreditCard as StoreCreditCard } from './generated';
@@ -221,7 +223,7 @@ export interface UpdateLineItemParams {
metadata?: Record<string, unknown>;
}
-export interface UpdateOrderParams {
+export interface UpdateCheckoutParams {
email?: string;
currency?: string;
locale?: string;
diff --git a/packages/sdk/src/zod/generated/Cart.ts b/packages/sdk/src/zod/generated/Cart.ts
new file mode 100644
index 0000000000..f5ae3f041b
--- /dev/null
+++ b/packages/sdk/src/zod/generated/Cart.ts
@@ -0,0 +1,49 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { AddressSchema } from './Address';
+import { LineItemSchema } from './LineItem';
+import { OrderPromotionSchema } from './OrderPromotion';
+import { PaymentSchema } from './Payment';
+import { PaymentMethodSchema } from './PaymentMethod';
+import { ShipmentSchema } from './Shipment';
+
+export const CartSchema = z.object({
+ id: z.string(),
+ number: z.string(),
+ state: z.string(),
+ checkout_steps: z.array(z.string()),
+ token: z.string(),
+ email: z.string().nullable(),
+ special_instructions: z.string().nullable(),
+ currency: z.string(),
+ locale: z.string().nullable(),
+ item_count: z.number(),
+ state_lock_version: z.number(),
+ item_total: z.string(),
+ display_item_total: z.string(),
+ ship_total: z.string(),
+ display_ship_total: z.string(),
+ adjustment_total: z.string(),
+ display_adjustment_total: z.string(),
+ promo_total: z.string(),
+ display_promo_total: z.string(),
+ tax_total: z.string(),
+ display_tax_total: z.string(),
+ included_tax_total: z.string(),
+ display_included_tax_total: z.string(),
+ additional_tax_total: z.string(),
+ display_additional_tax_total: z.string(),
+ total: z.string(),
+ display_total: z.string(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ order_promotions: z.array(OrderPromotionSchema),
+ line_items: z.array(LineItemSchema),
+ shipments: z.array(ShipmentSchema),
+ payments: z.array(PaymentSchema),
+ bill_address: AddressSchema.nullable(),
+ ship_address: AddressSchema.nullable(),
+ payment_methods: z.array(PaymentMethodSchema),
+});
+
+export type Cart = z.infer<typeof CartSchema>;
diff --git a/packages/sdk/src/zod/generated/Order.ts b/packages/sdk/src/zod/generated/Order.ts
index 8a364552e8..7ee082fe4d 100644
--- a/packages/sdk/src/zod/generated/Order.ts
+++ b/packages/sdk/src/zod/generated/Order.ts
@@ -4,21 +4,16 @@ import { AddressSchema } from './Address';
import { LineItemSchema } from './LineItem';
import { OrderPromotionSchema } from './OrderPromotion';
import { PaymentSchema } from './Payment';
-import { PaymentMethodSchema } from './PaymentMethod';
import { ShipmentSchema } from './Shipment';
export const OrderSchema = z.object({
id: z.string(),
number: z.string(),
- state: z.string(),
- checkout_steps: z.array(z.string()),
- token: z.string(),
- email: z.string().nullable(),
+ email: z.string(),
special_instructions: z.string().nullable(),
currency: z.string(),
locale: z.string().nullable(),
item_count: z.number(),
- state_lock_version: z.number(),
shipment_state: z.string().nullable(),
payment_state: z.string().nullable(),
item_total: z.string(),
@@ -46,7 +41,6 @@ export const OrderSchema = z.object({
payments: z.array(PaymentSchema),
bill_address: AddressSchema.nullable(),
ship_address: AddressSchema.nullable(),
- payment_methods: z.array(PaymentMethodSchema),
});
export type Order = z.infer<typeof OrderSchema>;
diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.ts
index 3bccd82243..04f293b040 100644
--- a/packages/sdk/src/zod/generated/index.ts
+++ b/packages/sdk/src/zod/generated/index.ts
@@ -2,6 +2,7 @@
export { AddressSchema, type Address } from './Address';
export { AssetSchema, type Asset } from './Asset';
export { BaseSchema, type Base } from './Base';
+export { CartSchema, type Cart } from './Cart';
export { CategorySchema, type Category } from './Category';
export { CountrySchema, type Country } from './Country';
export { CreditCardSchema, type CreditCard } from './CreditCard';
diff --git a/packages/sdk/tests/cart.test.ts b/packages/sdk/tests/cart.test.ts
index 9dc9513df2..773a2cacdd 100644
--- a/packages/sdk/tests/cart.test.ts
+++ b/packages/sdk/tests/cart.test.ts
@@ -2,20 +2,37 @@ import { describe, it, expect, beforeAll } from 'vitest';
import { createTestClient } from './helpers';
import type { Client } from '../src';
+describe('carts', () => {
+ let client: Client;
+ beforeAll(() => { client = createTestClient(); });
+
+ describe('list', () => {
+ it('lists all active carts for authenticated user', async () => {
+ const result = await client.carts.list({ token: 'user-jwt' });
+ expect(result.data).toHaveLength(1);
+ expect(result.data[0].id).toBe('cart_1');
+ expect(result.meta.count).toBe(1);
+ });
+ });
+});
+
describe('cart', () => {
let client: Client;
beforeAll(() => { client = createTestClient(); });
+ const opts = { token: 'user-jwt' };
describe('get', () => {
it('returns the current cart', async () => {
const result = await client.cart.get({ token: 'user-jwt' });
- expect(result.id).toBe('order_1');
+ expect(result.id).toBe('cart_1');
expect(result.token).toBeDefined();
+ expect(result.state).toBeDefined();
+ expect(result.checkout_steps).toBeDefined();
});
it('works with order token for guest checkout', async () => {
- const result = await client.cart.get({ orderToken: 'guest-token' });
+ const result = await client.cart.get({ spreeToken: 'guest-token' });
expect(result).toBeDefined();
});
});
@@ -27,13 +44,55 @@ describe('cart', () => {
});
});
+ describe('delete', () => {
+ it('deletes the current cart', async () => {
+ await expect(client.cart.delete(opts)).resolves.toBeUndefined();
+ });
+ });
+
describe('associate', () => {
it('associates guest cart with authenticated user', async () => {
const result = await client.cart.associate({
token: 'user-jwt',
- orderToken: 'guest-token',
+ spreeToken: 'guest-token',
});
expect(result).toBeDefined();
});
});
+
+ describe('items', () => {
+ it('adds an item to the cart', async () => {
+ const result = await client.cart.items.create(
+ { variant_id: 'var_1', quantity: 2 },
+ opts
+ );
+ expect(result.id).toBe('cart_1');
+ });
+
+ it('updates a line item', async () => {
+ const result = await client.cart.items.update(
+ 'li_1',
+ { quantity: 5 },
+ opts
+ );
+ expect(result.id).toBe('cart_1');
+ });
+
+ it('removes a line item', async () => {
+ const result = await client.cart.items.delete('li_1', opts);
+ expect(result.id).toBe('cart_1');
+ });
+ });
+
+ describe('couponCodes', () => {
+ it('applies a coupon code', async () => {
+ const result = await client.cart.couponCodes.apply('SAVE10', opts);
+ expect(result.id).toBe('cart_1');
+ });
+
+ it('removes a coupon code by code string', async () => {
+ const result = await client.cart.couponCodes.remove('SAVE10', opts);
+ expect(result.id).toBe('cart_1');
+ });
+ });
});
diff --git a/packages/sdk/tests/checkout.test.ts b/packages/sdk/tests/checkout.test.ts
new file mode 100644
index 0000000000..8f6473724f
--- /dev/null
+++ b/packages/sdk/tests/checkout.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createTestClient } from './helpers';
+import type { Client } from '../src';
+
+describe('checkout', () => {
+ let client: Client;
+ beforeAll(() => { client = createTestClient(); });
+ const opts = { token: 'user-jwt' };
+
+ describe('update', () => {
+ it('updates checkout info', async () => {
+ const result = await client.checkout.update(
+ { email: '[email protected]' },
+ opts
+ );
+ expect(result.id).toBe('cart_1');
+ });
+ });
+
+ describe('complete', () => {
+ it('completes the checkout and returns an order', async () => {
+ const result = await client.checkout.complete(opts);
+ expect(result.id).toBe('or_1');
+ expect(result.completed_at).toBeDefined();
+ });
+ });
+
+ describe('shipments', () => {
+ it('lists shipments', async () => {
+ const result = await client.checkout.shipments.list(opts);
+ expect(result.data).toBeDefined();
+ });
+
+ it('selects a shipping rate', async () => {
+ const result = await client.checkout.shipments.update(
+ 'ship_1',
+ { selected_shipping_rate_id: 'rate_1' },
+ opts
+ );
+ expect(result.id).toBe('cart_1');
+ });
+ });
+
+ describe('paymentMethods', () => {
+ it('lists payment methods', async () => {
+ const result = await client.checkout.paymentMethods.list(opts);
+ expect(result.data).toBeDefined();
+ });
+ });
+
+ describe('storeCredits', () => {
+ it('applies store credit', async () => {
+ const result = await client.checkout.storeCredits.apply(10, opts);
+ expect(result.id).toBe('cart_1');
+ });
+
+ it('removes store credit', async () => {
+ const result = await client.checkout.storeCredits.remove(opts);
+ expect(result.id).toBe('cart_1');
+ });
+ });
+});
diff --git a/packages/sdk/tests/customer.test.ts b/packages/sdk/tests/customer.test.ts
index d37fb464a0..f3ed8dd4ac 100644
--- a/packages/sdk/tests/customer.test.ts
+++ b/packages/sdk/tests/customer.test.ts
@@ -116,6 +116,11 @@ describe('customer', () => {
expect(result.data).toHaveLength(1);
expect(result.meta.page).toBe(1);
});
+
+ it('gets a customer order by ID', async () => {
+ const result = await client.customer.orders.get('or_abc123', undefined, opts);
+ expect(result.id).toBe('or_1');
+ });
});
describe('giftCards', () => {
diff --git a/packages/sdk/tests/error-handling.test.ts b/packages/sdk/tests/error-handling.test.ts
index 381e1b569e..2414985aa1 100644
--- a/packages/sdk/tests/error-handling.test.ts
+++ b/packages/sdk/tests/error-handling.test.ts
@@ -124,7 +124,7 @@ describe('error handling', () => {
it('handles 204 No Content responses', async () => {
const client = createTestClient();
- const result = await client.orders.lineItems.delete('order_1', 'li_1', { token: 'jwt' });
+ const result = await client.cart.delete({ token: 'jwt' });
expect(result).toBeUndefined();
});
});
diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.ts
index 63c2bfb109..fd8ead4996 100644
--- a/packages/sdk/tests/mocks/handlers.ts
+++ b/packages/sdk/tests/mocks/handlers.ts
@@ -14,13 +14,27 @@ export const fixtures = {
purchasable: true,
in_stock: true,
},
- order: {
- id: 'order_1',
+ cart: {
+ id: 'cart_1',
number: 'R123456',
state: 'cart',
total: '0.00',
item_total: '0.00',
token: 'guest-order-token',
+ checkout_steps: ['address', 'delivery', 'payment', 'confirm'],
+ state_lock_version: 0,
+ line_items: [],
+ payment_methods: [],
+ },
+ order: {
+ id: 'or_1',
+ number: 'R123456',
+ email: '[email protected]',
+ total: '0.00',
+ item_total: '0.00',
+ completed_at: '2026-03-01T00:00:00.000Z',
+ shipment_state: 'shipped',
+ payment_state: 'paid',
line_items: [],
},
lineItem: {
@@ -182,120 +196,114 @@ export const handlers = [
HttpResponse.json(fixtures.market)
),
+ // Carts (list)
+ http.get(`${API_PREFIX}/carts`, () =>
+ HttpResponse.json({ data: [fixtures.cart], meta: { count: 1 } })
+ ),
+
// Cart
http.get(`${API_PREFIX}/cart`, () =>
- HttpResponse.json({ ...fixtures.order, token: 'guest-order-token' })
+ HttpResponse.json(fixtures.cart)
),
http.post(`${API_PREFIX}/cart`, () =>
- HttpResponse.json({ ...fixtures.order, token: 'new-cart-token' })
+ HttpResponse.json({ ...fixtures.cart, token: 'new-cart-token' })
+ ),
+
+ http.delete(`${API_PREFIX}/cart`, () =>
+ new HttpResponse(null, { status: 204 })
),
http.patch(`${API_PREFIX}/cart/associate`, () =>
- HttpResponse.json({ ...fixtures.order, token: 'guest-order-token' })
+ HttpResponse.json(fixtures.cart)
),
- // Customer Orders
- http.get(`${API_PREFIX}/customer/orders`, () =>
- HttpResponse.json({ data: [fixtures.order], meta: paginationMeta })
+ // Cart > Items
+ http.post(`${API_PREFIX}/cart/items`, () =>
+ HttpResponse.json(fixtures.cart)
),
- // Orders
+ http.patch(`${API_PREFIX}/cart/items/:id`, () =>
+ HttpResponse.json(fixtures.cart)
+ ),
- http.get(`${API_PREFIX}/orders/:id`, () =>
- HttpResponse.json(fixtures.order)
+ http.delete(`${API_PREFIX}/cart/items/:id`, () =>
+ HttpResponse.json(fixtures.cart)
),
- http.patch(`${API_PREFIX}/orders/:id`, () =>
- HttpResponse.json(fixtures.order)
+ // Cart > Coupon Codes
+ http.post(`${API_PREFIX}/cart/coupon_codes`, () =>
+ HttpResponse.json(fixtures.cart)
),
- http.patch(`${API_PREFIX}/orders/:id/next`, () =>
- HttpResponse.json({ ...fixtures.order, state: 'address' })
+ http.delete(`${API_PREFIX}/cart/coupon_codes/:code`, () =>
+ HttpResponse.json(fixtures.cart)
),
- http.patch(`${API_PREFIX}/orders/:id/advance`, () =>
- HttpResponse.json({ ...fixtures.order, state: 'complete' })
+ // Checkout
+ http.patch(`${API_PREFIX}/checkout`, () =>
+ HttpResponse.json(fixtures.cart)
),
- http.patch(`${API_PREFIX}/orders/:id/complete`, () =>
- HttpResponse.json({ ...fixtures.order, state: 'complete' })
+ http.post(`${API_PREFIX}/checkout/complete`, () =>
+ HttpResponse.json(fixtures.order)
),
- // Line Items
- http.post(`${API_PREFIX}/orders/:orderId/line_items`, () =>
- HttpResponse.json(fixtures.lineItem)
+ // Checkout > Shipments
+ http.get(`${API_PREFIX}/checkout/shipments`, () =>
+ HttpResponse.json({ data: [], meta: { count: 0 } })
),
- http.patch(`${API_PREFIX}/orders/:orderId/line_items/:id`, () =>
- HttpResponse.json({ ...fixtures.lineItem, quantity: 5 })
+ http.patch(`${API_PREFIX}/checkout/shipments/:id`, () =>
+ HttpResponse.json(fixtures.cart)
),
- http.delete(`${API_PREFIX}/orders/:orderId/line_items/:id`, () =>
- new HttpResponse(null, { status: 204 })
+ // Checkout > Payment Methods
+ http.get(`${API_PREFIX}/checkout/payment_methods`, () =>
+ HttpResponse.json({ data: [], meta: { count: 0 } })
),
- // Payments
- http.get(`${API_PREFIX}/orders/:orderId/payments`, () =>
+ // Checkout > Payments
+ http.get(`${API_PREFIX}/checkout/payments`, () =>
HttpResponse.json({
- data: [
- {
- id: 'py_1',
- payment_method_id: 'pm_1',
- state: 'checkout',
- response_code: '12345',
- number: 'P1234',
- amount: '19.99',
- display_amount: '$19.99',
- source_type: 'credit_card',
- source_id: 'card_1',
- source: {
- id: 'card_1',
- cc_type: 'visa',
- last_digits: '4242',
- month: 12,
- year: 2028,
- name: 'John Doe',
- default: true,
- gateway_payment_profile_id: 'pm_stripe_123',
- },
- created_at: '2026-02-17T00:00:00.000Z',
- updated_at: '2026-02-17T00:00:00.000Z',
- payment_method: { id: 'pm_1', name: 'Credit Card', description: null, type: 'Spree::Gateway::Bogus', session_required: false },
- },
- ],
- meta: paginationMeta,
+ data: [{
+ id: 'py_1',
+ payment_method_id: 'pm_1',
+ state: 'checkout',
+ response_code: null,
+ number: 'P1234',
+ amount: '19.99',
+ display_amount: '$19.99',
+ source_type: 'credit_card',
+ source_id: 'card_1',
+ source: { id: 'card_1', cc_type: 'visa', last_digits: '4242', name: 'Test User', month: '12', year: '2028' },
+ created_at: '2026-02-17T00:00:00.000Z',
+ updated_at: '2026-02-17T00:00:00.000Z',
+ payment_method: { id: 'pm_1', name: 'Credit Card', description: null, type: 'Spree::Gateway::Bogus', session_required: true },
+ }],
+ meta: { count: 1 },
})
),
- http.get(`${API_PREFIX}/orders/:orderId/payments/:id`, () =>
+ http.get(`${API_PREFIX}/checkout/payments/:id`, () =>
HttpResponse.json({
id: 'py_1',
payment_method_id: 'pm_1',
state: 'checkout',
- response_code: '12345',
+ response_code: null,
number: 'P1234',
amount: '19.99',
display_amount: '$19.99',
source_type: 'credit_card',
source_id: 'card_1',
- source: {
- id: 'card_1',
- cc_type: 'visa',
- last_digits: '4242',
- month: 12,
- year: 2028,
- name: 'John Doe',
- default: true,
- gateway_payment_profile_id: 'pm_stripe_123',
- },
+ source: { id: 'card_1', cc_type: 'visa', last_digits: '4242', name: 'Test User', month: '12', year: '2028' },
created_at: '2026-02-17T00:00:00.000Z',
updated_at: '2026-02-17T00:00:00.000Z',
- payment_method: { id: 'pm_1', name: 'Credit Card', description: null, type: 'Spree::Gateway::Bogus', session_required: false },
+ payment_method: { id: 'pm_1', name: 'Credit Card', description: null, type: 'Spree::Gateway::Bogus', session_required: true },
})
),
- http.post(`${API_PREFIX}/orders/:orderId/payments`, () =>
+ http.post(`${API_PREFIX}/checkout/payments`, () =>
HttpResponse.json({
id: 'py_2',
payment_method_id: 'pm_2',
@@ -313,13 +321,8 @@ export const handlers = [
}, { status: 201 })
),
- // Payment Methods
- http.get(`${API_PREFIX}/orders/:orderId/payment_methods`, () =>
- HttpResponse.json({ data: [], meta: paginationMeta })
- ),
-
- // Payment Sessions
- http.post(`${API_PREFIX}/orders/:orderId/payment_sessions`, () =>
+ // Checkout > Payment Sessions
+ http.post(`${API_PREFIX}/checkout/payment_sessions`, () =>
HttpResponse.json({
id: 'ps_1',
status: 'pending',
@@ -337,7 +340,7 @@ export const handlers = [
}, { status: 201 })
),
- http.get(`${API_PREFIX}/orders/:orderId/payment_sessions/:id`, () =>
+ http.get(`${API_PREFIX}/checkout/payment_sessions/:id`, () =>
HttpResponse.json({
id: 'ps_1',
status: 'pending',
@@ -355,7 +358,7 @@ export const handlers = [
})
),
- http.patch(`${API_PREFIX}/orders/:orderId/payment_sessions/:id/complete`, () =>
+ http.patch(`${API_PREFIX}/checkout/payment_sessions/:id/complete`, () =>
HttpResponse.json({
id: 'ps_1',
status: 'completed',
@@ -373,7 +376,7 @@ export const handlers = [
})
),
- http.patch(`${API_PREFIX}/orders/:orderId/payment_sessions/:id`, () =>
+ http.patch(`${API_PREFIX}/checkout/payment_sessions/:id`, () =>
HttpResponse.json({
id: 'ps_1',
status: 'pending',
@@ -391,30 +394,17 @@ export const handlers = [
})
),
- // Coupon Codes
- http.post(`${API_PREFIX}/orders/:orderId/coupon_codes`, () =>
- HttpResponse.json(fixtures.order)
+ // Checkout > Store Credits
+ http.post(`${API_PREFIX}/checkout/store_credits`, () =>
+ HttpResponse.json(fixtures.cart)
),
- http.delete(`${API_PREFIX}/orders/:orderId/coupon_codes/:id`, () =>
- HttpResponse.json(fixtures.order)
+ http.delete(`${API_PREFIX}/checkout/store_credits`, () =>
+ HttpResponse.json(fixtures.cart)
),
- // Shipments
- http.get(`${API_PREFIX}/orders/:orderId/shipments`, () =>
- HttpResponse.json({ data: [] })
- ),
-
- http.patch(`${API_PREFIX}/orders/:orderId/shipments/:id`, () =>
- HttpResponse.json({ id: 'ship_1', selected_shipping_rate_id: 'rate_1' })
- ),
-
- // Store Credits
- http.post(`${API_PREFIX}/orders/:orderId/store_credits`, () =>
- HttpResponse.json(fixtures.order)
- ),
-
- http.delete(`${API_PREFIX}/orders/:orderId/store_credits`, () =>
+ // Orders (read-only, single lookup)
+ http.get(`${API_PREFIX}/orders/:id`, () =>
HttpResponse.json(fixtures.order)
),
@@ -427,7 +417,16 @@ export const handlers = [
HttpResponse.json({ ...fixtures.user, first_name: 'Updated' })
),
- // Customer Addresses
+ // Customer > Orders
+ http.get(`${API_PREFIX}/customer/orders`, () =>
+ HttpResponse.json({ data: [fixtures.order], meta: paginationMeta })
+ ),
+
+ http.get(`${API_PREFIX}/customer/orders/:id`, () =>
+ HttpResponse.json(fixtures.order)
+ ),
+
+ // Customer > Addresses
http.get(`${API_PREFIX}/customer/addresses`, () =>
HttpResponse.json({ data: [fixtures.address], meta: paginationMeta })
),
@@ -448,7 +447,7 @@ export const handlers = [
new HttpResponse(null, { status: 204 })
),
- // Customer Credit Cards
+ // Customer > Credit Cards
http.get(`${API_PREFIX}/customer/credit_cards`, () =>
HttpResponse.json({ data: [], meta: paginationMeta })
),
@@ -461,7 +460,7 @@ export const handlers = [
new HttpResponse(null, { status: 204 })
),
- // Customer Gift Cards
+ // Customer > Gift Cards
http.get(`${API_PREFIX}/customer/gift_cards`, () =>
HttpResponse.json({ data: [], meta: paginationMeta })
),
@@ -470,7 +469,7 @@ export const handlers = [
HttpResponse.json({ id: 'gc_1', code: 'GIFT123', balance: '50.00' })
),
- // Customer Payment Setup Sessions
+ // Customer > Payment Setup Sessions
http.post(`${API_PREFIX}/customer/payment_setup_sessions`, () =>
HttpResponse.json({
id: 'pss_1',
diff --git a/packages/sdk/tests/orders.test.ts b/packages/sdk/tests/orders.test.ts
index ab2a4c1997..80e504d7f7 100644
--- a/packages/sdk/tests/orders.test.ts
+++ b/packages/sdk/tests/orders.test.ts
@@ -8,113 +8,30 @@ describe('orders', () => {
const opts = { token: 'user-jwt' };
describe('get', () => {
- it('returns an order by number', async () => {
- const result = await client.orders.get('R123456', undefined, opts);
- expect(result.number).toBe('R123456');
+ it('returns an order by prefixed ID', async () => {
+ const result = await client.orders.get('or_abc123', undefined, opts);
+ expect(result.id).toBe('or_1');
+ expect(result.completed_at).toBeDefined();
});
- });
-
- describe('update', () => {
- it('updates order attributes', async () => {
- const result = await client.orders.update(
- 'order_1',
- { email: '[email protected]' },
- opts
- );
- expect(result).toBeDefined();
- });
- });
-
- describe('checkout flow', () => {
- it('advances to next step', async () => {
- const result = await client.orders.next('order_1', opts);
- expect(result.state).toBe('address');
- });
-
- it('advances through all steps', async () => {
- const result = await client.orders.advance('order_1', opts);
- expect(result.state).toBe('complete');
- });
-
- it('completes the order', async () => {
- const result = await client.orders.complete('order_1', opts);
- expect(result.state).toBe('complete');
- });
- });
-
- describe('lineItems', () => {
- it('creates a line item', async () => {
- const result = await client.orders.lineItems.create(
- 'order_1',
- { variant_id: 'var_1', quantity: 2 },
- opts
- );
- expect(result.quantity).toBe(2);
- });
-
- it('updates a line item', async () => {
- const result = await client.orders.lineItems.update(
- 'order_1',
- 'li_1',
- { quantity: 5 },
- opts
- );
- expect(result.quantity).toBe(5);
- });
-
- it('deletes a line item', async () => {
- await expect(
- client.orders.lineItems.delete('order_1', 'li_1', opts)
- ).resolves.toBeUndefined();
- });
- });
- describe('couponCodes', () => {
- it('applies a coupon code', async () => {
- const result = await client.orders.couponCodes.apply(
- 'order_1',
- 'SAVE10',
- opts
- );
- expect(result).toBeDefined();
- });
-
- it('removes a coupon code', async () => {
- const result = await client.orders.couponCodes.remove(
- 'order_1',
- 'promo_1',
- opts
- );
+ it('works with order token for guest access', async () => {
+ const result = await client.orders.get('or_abc123', undefined, {
+ spreeToken: 'guest-token',
+ });
expect(result).toBeDefined();
});
});
- describe('shipments', () => {
- it('lists shipments', async () => {
- const result = await client.orders.shipments.list('order_1', opts);
- expect(result.data).toBeDefined();
+ describe('customer.orders', () => {
+ it('lists customer orders', async () => {
+ const result = await client.customer.orders.list(undefined, opts);
+ expect(result.data).toHaveLength(1);
+ expect(result.meta.page).toBe(1);
});
- it('updates a shipment', async () => {
- const result = await client.orders.shipments.update(
- 'order_1',
- 'ship_1',
- { selected_shipping_rate_id: 'rate_1' },
- opts
- );
- expect(result).toBeDefined();
- });
- });
-
- describe('storeCredits', () => {
- it('adds store credit', async () => {
- const result = await client.orders.addStoreCredit('order_1', 10, opts);
- expect(result).toBeDefined();
- });
-
- it('removes store credit', async () => {
- const result = await client.orders.removeStoreCredit('order_1', opts);
- expect(result).toBeDefined();
+ it('gets a customer order by ID', async () => {
+ const result = await client.customer.orders.get('or_abc123', undefined, opts);
+ expect(result.id).toBe('or_1');
});
});
});
diff --git a/packages/sdk/tests/payment-sessions.test.ts b/packages/sdk/tests/payment-sessions.test.ts
index 0e6ae7391a..4facbae71d 100644
--- a/packages/sdk/tests/payment-sessions.test.ts
+++ b/packages/sdk/tests/payment-sessions.test.ts
@@ -9,8 +9,7 @@ describe('paymentSessions', () => {
describe('create', () => {
it('creates a payment session', async () => {
- const result = await client.orders.paymentSessions.create(
- 'order_1',
+ const result = await client.checkout.paymentSessions.create(
{ payment_method_id: 'pm_1' },
opts
);
@@ -22,8 +21,7 @@ describe('paymentSessions', () => {
});
it('accepts optional amount and external_data', async () => {
- const result = await client.orders.paymentSessions.create(
- 'order_1',
+ const result = await client.checkout.paymentSessions.create(
{ payment_method_id: 'pm_1', amount: '50.00', external_data: { channel: 'Web' } },
opts
);
@@ -33,11 +31,7 @@ describe('paymentSessions', () => {
describe('get', () => {
it('returns a payment session by ID', async () => {
- const result = await client.orders.paymentSessions.get(
- 'order_1',
- 'ps_1',
- opts
- );
+ const result = await client.checkout.paymentSessions.get('ps_1', opts);
expect(result.id).toBe('ps_1');
expect(result.status).toBe('pending');
expect(result.amount).toBe('99.99');
@@ -48,8 +42,7 @@ describe('paymentSessions', () => {
describe('update', () => {
it('updates a payment session', async () => {
- const result = await client.orders.paymentSessions.update(
- 'order_1',
+ const result = await client.checkout.paymentSessions.update(
'ps_1',
{ amount: '50.00' },
opts
@@ -61,8 +54,7 @@ describe('paymentSessions', () => {
describe('complete', () => {
it('completes a payment session', async () => {
- const result = await client.orders.paymentSessions.complete(
- 'order_1',
+ const result = await client.checkout.paymentSessions.complete(
'ps_1',
{ session_result: 'success' },
opts
@@ -72,8 +64,7 @@ describe('paymentSessions', () => {
});
it('completes without params', async () => {
- const result = await client.orders.paymentSessions.complete(
- 'order_1',
+ const result = await client.checkout.paymentSessions.complete(
'ps_1',
undefined,
opts
diff --git a/packages/sdk/tests/payments.test.ts b/packages/sdk/tests/payments.test.ts
index f472580d92..9ffdccb46e 100644
--- a/packages/sdk/tests/payments.test.ts
+++ b/packages/sdk/tests/payments.test.ts
@@ -8,8 +8,8 @@ describe('payments', () => {
const opts = { token: 'user-jwt' };
describe('list', () => {
- it('returns payments for an order', async () => {
- const result = await client.orders.payments.list('order_1', opts);
+ it('returns payments for the current cart', async () => {
+ const result = await client.checkout.payments.list(opts);
expect(result.data).toHaveLength(1);
expect(result.data[0].id).toBe('py_1');
expect(result.data[0].state).toBe('checkout');
@@ -17,7 +17,7 @@ describe('payments', () => {
});
it('includes source_type, source_id, and source for credit card payments', async () => {
- const result = await client.orders.payments.list('order_1', opts);
+ const result = await client.checkout.payments.list(opts);
const payment = result.data[0];
expect(payment.source_type).toBe('credit_card');
expect(payment.source_id).toBe('card_1');
@@ -31,7 +31,7 @@ describe('payments', () => {
});
it('includes payment_method association', async () => {
- const result = await client.orders.payments.list('order_1', opts);
+ const result = await client.checkout.payments.list(opts);
expect(result.data[0].payment_method.id).toBe('pm_1');
expect(result.data[0].payment_method.name).toBe('Credit Card');
});
@@ -39,7 +39,7 @@ describe('payments', () => {
describe('get', () => {
it('returns a payment by ID', async () => {
- const result = await client.orders.payments.get('order_1', 'py_1', opts);
+ const result = await client.checkout.payments.get('py_1', opts);
expect(result.id).toBe('py_1');
expect(result.state).toBe('checkout');
expect(result.number).toBe('P1234');
@@ -47,7 +47,7 @@ describe('payments', () => {
});
it('includes source details', async () => {
- const result = await client.orders.payments.get('order_1', 'py_1', opts);
+ const result = await client.checkout.payments.get('py_1', opts);
expect(result.source_type).toBe('credit_card');
expect(result.source_id).toBe('card_1');
expect(result.source).toBeDefined();
@@ -57,8 +57,7 @@ describe('payments', () => {
describe('create', () => {
it('creates a payment for a non-session payment method', async () => {
- const result = await client.orders.payments.create(
- 'order_1',
+ const result = await client.checkout.payments.create(
{ payment_method_id: 'pm_2' },
opts
);
@@ -70,8 +69,7 @@ describe('payments', () => {
});
it('accepts optional amount', async () => {
- const result = await client.orders.payments.create(
- 'order_1',
+ const result = await client.checkout.payments.create(
{ payment_method_id: 'pm_2', amount: '50.00' },
opts
);
@@ -79,8 +77,7 @@ describe('payments', () => {
});
it('includes payment_method association', async () => {
- const result = await client.orders.payments.create(
- 'order_1',
+ const result = await client.checkout.payments.create(
{ payment_method_id: 'pm_2' },
opts
);
diff --git a/server/Gemfile.lock b/server/Gemfile.lock
index ae5b5b91cb..98772f5e07 100644
--- a/server/Gemfile.lock
+++ b/server/Gemfile.lock
@@ -11,7 +11,7 @@ GIT
PATH
remote: ../spree/admin
specs:
- spree_admin (5.4.0.beta5)
+ spree_admin (5.4.0.beta6)
active_link_to
breadcrumbs_on_rails (~> 4.1)
chartkick (~> 5.0)
@@ -23,7 +23,7 @@ PATH
mapkick-rb (~> 0.1)
pagy (~> 43.0)
ruby-oembed (~> 0.18)
- spree (>= 5.4.0.beta5)
+ spree (>= 5.4.0.beta6)
stimulus-rails
tailwindcss-rails (>= 4.0)
tailwindcss-ruby (>= 4.0)
@@ -33,22 +33,22 @@ PATH
PATH
remote: ../spree/emails
specs:
- spree_emails (5.4.0.beta5)
- spree (>= 5.4.0.beta5)
+ spree_emails (5.4.0.beta6)
+ spree (>= 5.4.0.beta6)
PATH
remote: ../spree
specs:
- spree (5.4.0.beta5)
- spree_api (= 5.4.0.beta5)
- spree_core (= 5.4.0.beta5)
- spree_api (5.4.0.beta5)
+ spree (5.4.0.beta6)
+ spree_api (= 5.4.0.beta6)
+ spree_core (= 5.4.0.beta6)
+ spree_api (5.4.0.beta6)
alba (~> 3.0)
oj (~> 3.16)
pagy (~> 43.0)
- spree_core (= 5.4.0.beta5)
+ spree_core (= 5.4.0.beta6)
typelizer (~> 0.10.0)
- spree_core (5.4.0.beta5)
+ spree_core (5.4.0.beta6)
active_storage_validations (= 1.3.0)
acts-as-taggable-on
acts_as_list (>= 0.8)
@@ -1122,12 +1122,12 @@ CHECKSUMS
simplecov-cobertura (3.1.0) sha256=6d7f38aa32c965ca2174b2e5bd88cb17138eaf629518854976ac50e628925dc5
simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
- spree (5.4.0.beta5)
- spree_admin (5.4.0.beta5)
- spree_api (5.4.0.beta5)
- spree_core (5.4.0.beta5)
+ spree (5.4.0.beta6)
+ spree_admin (5.4.0.beta6)
+ spree_api (5.4.0.beta6)
+ spree_core (5.4.0.beta6)
spree_dev_tools (0.5.3) sha256=64ae7b215ac5d5c5f5890f6fc0dbcb12882b9af305a860f36f95f564ec240a75
- spree_emails (5.4.0.beta5)
+ spree_emails (5.4.0.beta6)
spree_extension (1.0.2) sha256=71725dafe45319a2be1bd2b564a416afe8029af8e18ac703bdb835e09553e1df
spree_i18n (5.3.2) sha256=03b805235ca156644951f6bc3d07cbe43d0aa01134c4a27e3f3304011956f79b
spree_stripe (1.6.0.beta)
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/cart_resolvable.rb b/spree/api/app/controllers/concerns/spree/api/v3/cart_resolvable.rb
new file mode 100644
index 0000000000..28c897bb69
--- /dev/null
+++ b/spree/api/app/controllers/concerns/spree/api/v3/cart_resolvable.rb
@@ -0,0 +1,52 @@
+module Spree
+ module Api
+ module V3
+ module CartResolvable
+ extend ActiveSupport::Concern
+
+ protected
+
+ def find_cart
+ scope = current_store.carts
+
+ # Try order_token first (guest checkout)
+ if cart_token.present?
+ return scope.find_by!(token: cart_token)
+ end
+
+ # Then try JWT authenticated user
+ if current_user.present?
+ cart = scope.where(user: current_user).order(created_at: :desc).first
+ return cart if cart
+ end
+
+ raise ActiveRecord::RecordNotFound.new(nil, 'Spree::Order')
+ end
+
+ # Find the cart and authorize it for update using the cart token from the request headers.
+ # @return [Spree::Order]
+ def find_cart!
+ @cart = find_cart
+ authorize!(:update, @cart, cart_token)
+ @cart
+ end
+
+ # Render the cart as JSON using the cart serializer.
+ def render_cart(status: :ok)
+ render json: Spree.api.cart_serializer.new(@cart.reload, params: serializer_params).to_h, status: status
+ end
+
+ # Render the order as JSON using the order serializer (for complete action).
+ def render_order(status: :ok)
+ render json: Spree.api.order_serializer.new(@cart.reload, params: serializer_params).to_h, status: status
+ end
+
+ # Return the cart token from the request headers.
+ # @return [String, nil]
+ def cart_token
+ request.headers['x-spree-token']
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/order_concern.rb b/spree/api/app/controllers/concerns/spree/api/v3/order_concern.rb
deleted file mode 100644
index af1ed6045f..0000000000
--- a/spree/api/app/controllers/concerns/spree/api/v3/order_concern.rb
+++ /dev/null
@@ -1,46 +0,0 @@
-module Spree
- module Api
- module V3
- module OrderConcern
- extend ActiveSupport::Concern
-
- # Allow access to order via order token for guests or authenticated users
- # Expects @parent to be set to the order
- def authorize_order_access!
- authorize!(:update, @parent, order_token)
- end
-
- def set_parent
- return if params[:order_id].blank?
-
- @parent = order_scope.find_by_prefix_id!(params[:order_id])
- end
-
- def order_scope
- base = current_store.orders
- base = if current_user
- base.where(user: current_user)
- elsif order_token.present?
- base.where(token: order_token)
- else
- base.none
- end
- base.preload_associations_lazily
- end
-
- protected
-
- # Render the parent order as JSON using the order serializer.
- # Use this when sub-resource mutations should return the updated order
- # (e.g., line items, coupon codes, store credits).
- def render_order(status: :ok)
- render json: Spree.api.order_serializer.new(@parent.reload, params: serializer_params).to_h, status: status
- end
-
- def order_token
- request.headers['x-spree-order-token']
- end
- end
- end
- end
-end
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/order_lock.rb b/spree/api/app/controllers/concerns/spree/api/v3/order_lock.rb
index 54c4c279f9..9f845b33a8 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/order_lock.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/order_lock.rb
@@ -12,7 +12,7 @@ module Spree
private
def with_order_lock
- order = @order || @parent
+ order = @order || @parent || @cart
order.with_lock do
# Persist increment within the transaction so reloads inside yield see the new version
diff --git a/spree/api/app/controllers/spree/api/v3/store/cart/coupon_codes_controller.rb b/spree/api/app/controllers/spree/api/v3/store/cart/coupon_codes_controller.rb
new file mode 100644
index 0000000000..5d4910a983
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/cart/coupon_codes_controller.rb
@@ -0,0 +1,57 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Cart
+ class CouponCodesController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
+ include Spree::Api::V3::OrderLock
+
+ before_action :find_cart!
+
+ # POST /api/v3/store/cart/coupon_codes
+ # Apply a coupon code to the cart
+ def create
+ with_order_lock do
+ @cart.coupon_code = permitted_params[:code]
+
+ coupon_handler.apply
+
+ if coupon_handler.successful?
+ render_cart(status: :created)
+ else
+ render_errors(coupon_handler.error)
+ end
+ end
+ end
+
+ # DELETE /api/v3/store/cart/coupon_codes/:id
+ # Remove a coupon code from the cart
+ # :id is the coupon code string (e.g., SAVE10)
+ def destroy
+ with_order_lock do
+ coupon_handler.remove(params[:id])
+
+ if coupon_handler.successful?
+ render_cart
+ else
+ render_errors(coupon_handler.error)
+ end
+ end
+ end
+
+ private
+
+ def coupon_handler
+ @coupon_handler ||= Spree.coupon_handler.new(@cart)
+ end
+
+ def permitted_params
+ params.permit(:code)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rb b/spree/api/app/controllers/spree/api/v3/store/cart/items_controller.rb
similarity index 64%
rename from spree/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rb
rename to spree/api/app/controllers/spree/api/v3/store/cart/items_controller.rb
index 700f1f69f7..f21fde8622 100644
--- a/spree/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/cart/items_controller.rb
@@ -2,19 +2,18 @@ module Spree
module Api
module V3
module Store
- module Orders
- class LineItemsController < ResourceController
- include Spree::Api::V3::OrderConcern
+ module Cart
+ class ItemsController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
include Spree::Api::V3::OrderLock
- skip_before_action :set_resource
- before_action :authorize_order_access!
+ before_action :find_cart!
- # POST /api/v3/store/orders/:order_id/line_items
+ # POST /api/v3/store/cart/items
def create
with_order_lock do
result = Spree.cart_add_item_service.call(
- order: @parent,
+ order: @cart,
variant: variant,
quantity: permitted_params[:quantity] || 1,
metadata: permitted_params[:metadata] || {},
@@ -22,73 +21,62 @@ module Spree
)
if result.success?
- render_order(status: :created)
+ render_cart(status: :created)
else
render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
end
end
end
- # PATCH /api/v3/store/orders/:order_id/line_items/:id
+ # PATCH /api/v3/store/cart/items/:id
def update
with_order_lock do
- @line_item = scope.find_by_prefix_id!(params[:id])
+ @line_item = @cart.line_items.find_by_prefix_id!(params[:id])
@line_item.metadata = @line_item.metadata.merge(permitted_params[:metadata].to_h) if permitted_params[:metadata].present?
if permitted_params[:quantity].present?
result = Spree.cart_set_item_quantity_service.call(
- order: @parent,
+ order: @cart,
line_item: @line_item,
quantity: permitted_params[:quantity]
)
if result.success?
- render_order
+ render_cart
else
render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
end
elsif @line_item.changed?
@line_item.save!
- render_order
+ render_cart
else
- render_order
+ render_cart
end
end
end
- # DELETE /api/v3/store/orders/:order_id/line_items/:id
+ # DELETE /api/v3/store/cart/items/:id
def destroy
with_order_lock do
- @line_item = scope.find_by_prefix_id!(params[:id])
+ @line_item = @cart.line_items.find_by_prefix_id!(params[:id])
Spree.cart_remove_line_item_service.call(
- order: @parent,
+ order: @cart,
line_item: @line_item
)
- render_order
+ render_cart
end
end
- protected
+ private
- def parent_association
- :line_items
- end
def variant
@variant ||= current_store.variants.accessible_by(current_ability).find_by_prefix_id!(permitted_params[:variant_id])
end
- def model_class
- Spree::LineItem
- end
-
- def serializer_class
- Spree.api.line_item_serializer
- end
-
def permitted_params
params.permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/cart_controller.rb b/spree/api/app/controllers/spree/api/v3/store/cart_controller.rb
index 150b0de083..99767bc9ec 100644
--- a/spree/api/app/controllers/spree/api/v3/store/cart_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/cart_controller.rb
@@ -3,7 +3,7 @@ module Spree
module V3
module Store
class CartController < Store::BaseController
- include Spree::Api::V3::OrderConcern
+ include Spree::Api::V3::CartResolvable
before_action :require_authentication!, only: [:associate]
@@ -22,7 +22,7 @@ module Spree
if result.success?
@cart = result.value
- render json: serialize_resource(@cart), status: :created
+ render_cart(status: :created)
else
render_service_error(result.error.to_s)
end
@@ -31,11 +31,26 @@ module Spree
# GET /api/v3/store/cart
# Returns current incomplete order (cart)
# Returns 404 if no cart exists - use POST /cart to create one
- # Authorize via order_token param or JWT Bearer token
+ # Authorize via cart_token param or JWT Bearer token
+ # Uses find_cart (without bang) intentionally — read-only access, no authorize! needed
def show
@cart = find_cart
- render json: serialize_resource(@cart)
+ render_cart
+ end
+
+ # DELETE /api/v3/store/cart
+ # Deletes/abandons the current cart
+ def destroy
+ find_cart!
+
+ result = Spree.cart_destroy_service.call(order: @cart)
+
+ if result.success?
+ head :no_content
+ else
+ render_service_error(result.error.to_s)
+ end
end
# PATCH /api/v3/store/cart/associate
@@ -47,18 +62,12 @@ module Spree
result = Spree.cart_associate_service.call(guest_order: @cart, user: current_user, guest_only: true)
if result.success?
- render json: serialize_resource(@cart)
+ render_cart
else
render_service_error(result.error.to_s)
end
end
- protected
-
- def serializer_class
- Spree.api.order_serializer
- end
-
private
def cart_params
@@ -71,24 +80,7 @@ module Spree
# Find incomplete cart by order token for associate action
# Only finds guest carts (no user) or carts already owned by current user (idempotent)
def find_cart_by_token
- current_store.orders.incomplete.where(user: [ nil, current_user ]).find_by!(token: order_token)
- end
-
- def find_cart
- scope = current_store.orders.incomplete
-
- # Try order_token first (guest checkout)
- if order_token.present?
- return scope.find_by!(token: order_token)
- end
-
- # Then try JWT authenticated user
- if current_user.present?
- cart = scope.where(user: current_user).order(created_at: :desc).first
- return cart if cart
- end
-
- raise ActiveRecord::RecordNotFound.new(nil, 'Spree::Order')
+ current_store.carts.where(user: [nil, current_user]).find_by!(token: cart_token)
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb
new file mode 100644
index 0000000000..5fa704af52
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb
@@ -0,0 +1,33 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ class CartsController < Store::ResourceController
+ prepend_before_action :require_authentication!
+
+ protected
+
+ def set_parent
+ @parent = current_user
+ end
+
+ def parent_association
+ :carts
+ end
+
+ def model_class
+ Spree::Order
+ end
+
+ def serializer_class
+ Spree.api.cart_serializer
+ end
+
+ def apply_collection_sort(collection)
+ collection.order(updated_at: :desc)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/checkout/payment_methods_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout/payment_methods_controller.rb
new file mode 100644
index 0000000000..027b56dfbf
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/checkout/payment_methods_controller.rb
@@ -0,0 +1,24 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Checkout
+ class PaymentMethodsController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
+
+ before_action :find_cart!
+
+ # GET /api/v3/store/checkout/payment_methods
+ def index
+ methods = @cart.collect_frontend_payment_methods
+ render json: {
+ data: methods.map { |m| Spree.api.payment_method_serializer.new(m, params: serializer_params).to_h },
+ meta: { count: methods.size }
+ }
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/payment_sessions_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout/payment_sessions_controller.rb
similarity index 74%
rename from spree/api/app/controllers/spree/api/v3/store/orders/payment_sessions_controller.rb
rename to spree/api/app/controllers/spree/api/v3/store/checkout/payment_sessions_controller.rb
index 4d1919051f..22fac81106 100644
--- a/spree/api/app/controllers/spree/api/v3/store/orders/payment_sessions_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/checkout/payment_sessions_controller.rb
@@ -2,20 +2,19 @@ module Spree
module Api
module V3
module Store
- module Orders
- class PaymentSessionsController < ResourceController
- include Spree::Api::V3::OrderConcern
+ module Checkout
+ class PaymentSessionsController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
- skip_before_action :set_resource
- before_action :authorize_order_access!
+ before_action :find_cart!
before_action :set_payment_session, only: [:show, :update, :complete]
- # POST /api/v3/store/orders/:order_id/payment_sessions
+ # POST /api/v3/store/checkout/payment_sessions
def create
payment_method = current_store.payment_methods.find_by_prefix_id!(permitted_params[:payment_method_id])
@payment_session = payment_method.create_payment_session(
- order: @parent,
+ order: @cart,
amount: permitted_params[:amount],
external_data: permitted_params[:external_data] || {}
)
@@ -27,12 +26,12 @@ module Spree
end
end
- # GET /api/v3/store/orders/:order_id/payment_sessions/:id
+ # GET /api/v3/store/checkout/payment_sessions/:id
def show
render json: serialize_resource(@payment_session)
end
- # PATCH /api/v3/store/orders/:order_id/payment_sessions/:id
+ # PATCH /api/v3/store/checkout/payment_sessions/:id
def update
@payment_session.payment_method.update_payment_session(
payment_session: @payment_session,
@@ -47,7 +46,7 @@ module Spree
end
end
- # PATCH /api/v3/store/orders/:order_id/payment_sessions/:id/complete
+ # PATCH /api/v3/store/checkout/payment_sessions/:id/complete
def complete
@payment_session.payment_method.complete_payment_session(
payment_session: @payment_session,
@@ -63,14 +62,6 @@ module Spree
protected
- def parent_association
- :payment_sessions
- end
-
- def model_class
- Spree::PaymentSession
- end
-
def serializer_class
Spree.api.payment_session_serializer
end
@@ -86,7 +77,11 @@ module Spree
private
def set_payment_session
- @payment_session = @parent.payment_sessions.find_by_prefix_id!(params[:id])
+ @payment_session = @cart.payment_sessions.find_by_prefix_id!(params[:id])
+ end
+
+ def serialize_resource(resource)
+ serializer_class.new(resource, params: serializer_params).to_h
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/payments_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout/payments_controller.rb
similarity index 61%
rename from spree/api/app/controllers/spree/api/v3/store/orders/payments_controller.rb
rename to spree/api/app/controllers/spree/api/v3/store/checkout/payments_controller.rb
index c255cddc2f..930de60360 100644
--- a/spree/api/app/controllers/spree/api/v3/store/orders/payments_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/checkout/payments_controller.rb
@@ -2,29 +2,11 @@ module Spree
module Api
module V3
module Store
- module Orders
- class PaymentsController < Store::BaseController
- include Spree::Api::V3::OrderConcern
- include Spree::Api::V3::ResourceSerializer
+ module Checkout
+ class PaymentsController < Store::ResourceController
+ include Spree::Api::V3::CartResolvable
- before_action :set_parent
- before_action :set_payment, only: [:show]
-
- # GET /api/v3/store/orders/:order_id/payments
- def index
- payments = @parent.payments.includes(:payment_method)
- render json: {
- data: serialize_payments(payments),
- meta: {}
- }
- end
-
- # GET /api/v3/store/orders/:order_id/payments/:id
- def show
- render json: serialize_resource(@payment)
- end
-
- # POST /api/v3/store/orders/:order_id/payments
+ # POST /api/v3/store/checkout/payments
# Creates a payment for non-session payment methods (e.g. Check, Cash on Delivery, Bank Transfer)
def create
payment_method = current_store.payment_methods.find_by_prefix_id!(params[:payment_method_id])
@@ -53,8 +35,6 @@ module Spree
metadata: params[:metadata].present? ? params[:metadata].to_unsafe_h : {}
)
- authorize!(:update, @parent, order_token)
-
if @payment.save
render json: serialize_resource(@payment), status: :created
else
@@ -62,18 +42,27 @@ module Spree
end
end
- private
+ protected
+
+ def set_parent
+ find_cart!
+ @parent = @cart
+ end
+
+ def parent_association
+ :payments
+ end
- def set_payment
- @payment = @parent.payments.find_by_prefix_id!(params[:id])
+ def model_class
+ Spree::Payment
end
def serializer_class
Spree.api.payment_serializer
end
- def serialize_payments(payments)
- payments.map { |p| serializer_class.new(p, params: serializer_params).to_h }
+ # Authorization is handled by find_cart! in set_parent
+ def authorize_resource!(*)
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/checkout/shipments_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout/shipments_controller.rb
new file mode 100644
index 0000000000..2e4ddd9068
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/checkout/shipments_controller.rb
@@ -0,0 +1,47 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Checkout
+ class ShipmentsController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
+ include Spree::Api::V3::OrderLock
+
+ before_action :find_cart!
+
+ # GET /api/v3/store/checkout/shipments
+ def index
+ shipments = @cart.shipments.includes(shipping_rates: :shipping_method)
+ render json: {
+ data: shipments.map { |s| Spree.api.shipment_serializer.new(s, params: serializer_params).to_h },
+ meta: { count: shipments.size }
+ }
+ end
+
+ # PATCH /api/v3/store/checkout/shipments/:id
+ # Select a shipping rate for a specific shipment
+ def update
+ with_order_lock do
+ shipment = @cart.shipments.find_by_prefix_id!(params[:id])
+
+ if permitted_params[:selected_shipping_rate_id].present?
+ shipping_rate = shipment.shipping_rates.find_by_prefix_id!(permitted_params[:selected_shipping_rate_id])
+ shipment.selected_shipping_rate_id = shipping_rate.id
+ shipment.save!
+ end
+
+ render_cart
+ end
+ end
+
+ private
+
+ def permitted_params
+ params.permit(:selected_shipping_rate_id)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout/store_credits_controller.rb
similarity index 69%
rename from spree/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb
rename to spree/api/app/controllers/spree/api/v3/store/checkout/store_credits_controller.rb
index f2e1960d77..8be8ae001d 100644
--- a/spree/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/checkout/store_credits_controller.rb
@@ -2,38 +2,37 @@ module Spree
module Api
module V3
module Store
- module Orders
+ module Checkout
class StoreCreditsController < Store::BaseController
- include Spree::Api::V3::OrderConcern
+ include Spree::Api::V3::CartResolvable
include Spree::Api::V3::OrderLock
before_action :require_authentication!
- before_action :set_parent
- before_action :authorize_order_access!
+ before_action :find_cart!
- # POST /api/v3/store/orders/:order_id/store_credits
+ # POST /api/v3/store/checkout/store_credits
def create
with_order_lock do
result = Spree.checkout_add_store_credit_service.call(
- order: @parent,
+ order: @cart,
amount: params[:amount].try(:to_f)
)
if result.success?
- render_order
+ render_cart
else
render_service_error(result.error)
end
end
end
- # DELETE /api/v3/store/orders/:order_id/store_credits
+ # DELETE /api/v3/store/checkout/store_credits
def destroy
with_order_lock do
- result = Spree.checkout_remove_store_credit_service.call(order: @parent)
+ result = Spree.checkout_remove_store_credit_service.call(order: @cart)
if result.success?
- render_order
+ render_cart
else
render_service_error(result.error)
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/checkout_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout_controller.rb
new file mode 100644
index 0000000000..35beeb278c
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/checkout_controller.rb
@@ -0,0 +1,66 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ class CheckoutController < Store::BaseController
+ include Spree::Api::V3::CartResolvable
+ include Spree::Api::V3::OrderLock
+
+ before_action :find_cart!
+
+ # PATCH /api/v3/store/checkout
+ # Update checkout info (email, addresses, special instructions).
+ # Does NOT auto-advance — the frontend controls navigation between steps.
+ def update
+ with_order_lock do
+ result = Spree.order_update_service.call(
+ order: @cart,
+ params: checkout_params
+ )
+
+ if result.success?
+ render_cart
+ else
+ render_service_error(result.error, code: ERROR_CODES[:validation_error])
+ end
+ end
+ end
+
+ # POST /api/v3/store/checkout/complete
+ # Complete the checkout — returns Order (not Cart)
+ def complete
+ with_order_lock do
+ result = Spree.checkout_complete_service.call(order: @cart)
+
+ if result.success?
+ render_order
+ else
+ render_service_error(result.error, code: ERROR_CODES[:order_already_completed])
+ end
+ end
+ end
+
+ private
+
+ def checkout_params
+ params.permit(
+ :email,
+ :special_instructions,
+ ship_address: address_params,
+ bill_address: address_params,
+ metadata: {}
+ )
+ end
+
+ def address_params
+ [
+ :id, :firstname, :lastname, :address1, :address2,
+ :city, :zipcode, :phone, :company,
+ :country_iso, :state_abbr, :state_name, :quick_checkout
+ ]
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/customer/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/store/customer/orders_controller.rb
index e723a04139..f842a08966 100644
--- a/spree/api/app/controllers/spree/api/v3/store/customer/orders_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/customer/orders_controller.rb
@@ -25,7 +25,7 @@ module Spree
end
def scope
- super.for_store(current_store)
+ super.for_store(current_store).complete
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/coupon_codes_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders/coupon_codes_controller.rb
deleted file mode 100644
index b8be43bd47..0000000000
--- a/spree/api/app/controllers/spree/api/v3/store/orders/coupon_codes_controller.rb
+++ /dev/null
@@ -1,73 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- module Orders
- class CouponCodesController < ResourceController
- include Spree::Api::V3::OrderConcern
- include Spree::Api::V3::OrderLock
-
- before_action :authorize_order_access!
- skip_before_action :set_resource
-
- # POST /api/v3/store/orders/:order_id/coupon_codes
- # Apply a coupon code to the order
- def create
- with_order_lock do
- @parent.coupon_code = permitted_params[:code]
-
- coupon_handler.apply
-
- if coupon_handler.successful?
- render_order(status: :created)
- else
- render_errors(coupon_handler.error)
- end
- end
- end
-
- # DELETE /api/v3/store/orders/:order_id/coupon_codes/:id
- # Remove a coupon code from the order
- # :id is the promotion prefix_id (e.g., promo_xxx)
- def destroy
- with_order_lock do
- @resource = scope.find_by_prefix_id!(params[:id])
- coupon_code = @resource.code.presence || @resource.name
-
- coupon_handler.remove(coupon_code)
-
- if coupon_handler.successful?
- render_order
- else
- render_errors(coupon_handler.error)
- end
- end
- end
-
- protected
-
- def parent_association
- :order_promotions
- end
-
- def coupon_handler
- @coupon_handler ||= Spree.coupon_handler.new(@parent)
- end
-
- def permitted_params
- params.permit(:code)
- end
-
- def model_class
- Spree::OrderPromotion
- end
-
- def serializer_class
- Spree.api.order_promotion_serializer
- end
- end
- end
- end
- end
- end
-end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb
deleted file mode 100644
index 5421c6f517..0000000000
--- a/spree/api/app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb
+++ /dev/null
@@ -1,43 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- module Orders
- class PaymentMethodsController < Store::BaseController
- include Spree::Api::V3::OrderConcern
-
- before_action :set_parent
-
- # GET /api/v3/store/orders/:order_id/payment_methods
- # Returns available payment methods for the current order
- def index
- payment_methods = @parent.collect_frontend_payment_methods
- render json: {
- data: serialize_collection(payment_methods),
- meta: { count: payment_methods.size }
- }
- end
-
- protected
-
- def serializer_class
- Spree.api.payment_method_serializer
- end
-
- def serialize_collection(collection)
- collection.map { |item| serializer_class.new(item, params: serializer_params).to_h }
- end
-
- def serializer_params
- {
- currency: current_currency,
- store: current_store,
- user: current_user
- }
- end
- end
- end
- end
- end
- end
-end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/shipments_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders/shipments_controller.rb
deleted file mode 100644
index d9e0fd8776..0000000000
--- a/spree/api/app/controllers/spree/api/v3/store/orders/shipments_controller.rb
+++ /dev/null
@@ -1,56 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- module Orders
- class ShipmentsController < ResourceController
- include Spree::Api::V3::OrderConcern
- include Spree::Api::V3::OrderLock
-
- before_action :authorize_order_access!
- skip_before_action :set_resource
- before_action :set_shipment, only: [:show, :update]
-
- # PATCH /api/v3/store/orders/:order_id/shipments/:id
- def update
- with_order_lock do
- if permitted_params[:selected_shipping_rate_id].present?
- shipping_rate = @resource.shipping_rates.find_by_prefix_id!(permitted_params[:selected_shipping_rate_id])
- @resource.selected_shipping_rate_id = shipping_rate.id
- @resource.save!
- end
-
- render_order
- end
- end
-
- protected
-
- def parent_association
- :shipments
- end
-
- def model_class
- Spree::Shipment
- end
-
- def serializer_class
- Spree.api.shipment_serializer
- end
-
- def permitted_params
- params.permit(:selected_shipping_rate_id)
- end
-
- private
-
- # Find shipment without additional authorization - order access already verified
- def set_shipment
- @resource = scope.find_by_prefix_id!(params[:id])
- end
- end
- end
- end
- end
- end
-end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders_controller.rb
index 3f168cf10d..c9a86d385a 100644
--- a/spree/api/app/controllers/spree/api/v3/store/orders_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/orders_controller.rb
@@ -2,133 +2,40 @@ module Spree
module Api
module V3
module Store
- class OrdersController < ResourceController
- include Spree::Api::V3::OrderConcern
- include Spree::Api::V3::OrderLock
+ class OrdersController < Store::BaseController
+ # GET /api/v3/store/orders/:id
+ # Single order lookup — accessible via order token (guests) or JWT (authenticated users)
+ before_action :find_order!
- # Skip base controller's set_resource and define our own complete list
- skip_before_action :set_resource
- before_action :set_resource, only: [:show, :update, :next, :advance, :complete]
-
- # PATCH /api/v3/store/orders/:id
- #
- # Accepts flat parameters:
- # {
- # "email": "[email protected]",
- # "currency": "EUR",
- # "ship_address": { "firstname": "John", "country_iso": "US", ... },
- # "bill_address": { "firstname": "John", "country_iso": "US", ... }
- # }
- #
- def update
- with_order_lock do
- result = Spree.order_update_service.call(
- order: @order,
- params: order_params
- )
-
- if result.success?
- render json: serialize_resource(@order.reload)
- else
- render_service_error(result.error, code: ERROR_CODES[:validation_error])
- end
- end
- end
-
- # PATCH /api/v3/store/orders/:id/next
- def next
- with_order_lock do
- result = Spree.checkout_next_service.call(order: @order)
-
- if result.success?
- render json: serialize_resource(@order)
- else
- render_service_error(result.error, code: ERROR_CODES[:order_cannot_transition])
- end
- end
- end
-
- # PATCH /api/v3/store/orders/:id/advance
- def advance
- with_order_lock do
- result = Spree.checkout_advance_service.call(order: @order)
-
- if result.success?
- render json: serialize_resource(@order)
- else
- render_service_error(result.error, code: ERROR_CODES[:order_cannot_transition])
- end
- end
+ def show
+ render json: serializer_class.new(@order, params: serializer_params).to_h
end
- # PATCH /api/v3/store/orders/:id/complete
- def complete
- with_order_lock do
- result = Spree.checkout_complete_service.call(order: @order)
+ private
- if result.success?
- render json: serialize_resource(@order)
- else
- render_service_error(result.error, code: ERROR_CODES[:order_already_completed])
- end
- end
+ def find_order!
+ @order = scope.find_by_prefix_id!(params[:id])
+ authorize!(:show, @order, order_token)
end
- protected
-
- # Override scope to avoid accessible_by (Order permissions use blocks)
def scope
- order_scope
- end
-
- # Override set_resource to scope lookup by user or order token (IDOR prevention)
- def set_resource
- @order = order_scope.find_by_prefix_id!(params[:id])
- @resource = @order
- authorize_resource!(@order)
- end
-
- # override authorize_resource! to pass the order token
- # Maps custom checkout actions to appropriate permissions
- def authorize_resource!(resource = @resource, action = action_name.to_sym)
- mapped_action = case action
- when :next, :advance, :complete
- :update # Checkout actions require update (non-completed order)
- else
- action
- end
- authorize!(mapped_action, resource, order_token)
- end
-
- def model_class
- Spree::Order
+ base = current_store.orders.complete
+
+ if current_user.present?
+ base.where(user: current_user)
+ elsif order_token.present?
+ base.where(token: order_token)
+ else
+ base.none
+ end
end
def serializer_class
Spree.api.order_serializer
end
- def order_params
- params.permit(
- :email,
- :currency,
- :locale,
- :special_instructions,
- :ship_address_id,
- :bill_address_id,
- ship_address: address_params,
- bill_address: address_params,
- metadata: {},
- line_items: [:variant_id, :quantity, { metadata: {}, options: {} }]
- )
- end
-
- def address_params
- [
- :id, :firstname, :lastname, :address1, :address2,
- :city, :zipcode, :phone, :company,
- :country_iso, :state_abbr, :state_name, :quick_checkout
- ]
+ def order_token
+ request.headers['x-spree-token']
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
new file mode 100644
index 0000000000..7239101f41
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/cart_serializer.rb
@@ -0,0 +1,44 @@
+module Spree
+ module Api
+ module V3
+ # Store API Cart Serializer
+ # Pre-purchase cart data with checkout progression info
+ class CartSerializer < BaseSerializer
+ typelize number: :string, state: :string, checkout_steps: 'string[]', token: :string, email: [:string, nullable: true],
+ special_instructions: [:string, nullable: true], currency: :string, locale: [:string, nullable: true], item_count: :number,
+ state_lock_version: :number,
+ item_total: :string, display_item_total: :string,
+ ship_total: :string, display_ship_total: :string,
+ adjustment_total: :string, display_adjustment_total: :string,
+ promo_total: :string, display_promo_total: :string,
+ tax_total: :string, display_tax_total: :string,
+ included_tax_total: :string, display_included_tax_total: :string,
+ additional_tax_total: :string, display_additional_tax_total: :string,
+ total: :string, display_total: :string,
+ bill_address: { nullable: true }, ship_address: { nullable: true }
+
+ # Override ID to use cart_ prefix
+ attribute :id do |order|
+ "cart_#{Spree::PrefixedId::SQIDS.encode([order.id])}"
+ end
+
+ attributes :number, :state, :checkout_steps, :token, :email, :special_instructions,
+ :currency, :locale, :item_count, :state_lock_version,
+ :item_total, :display_item_total, :ship_total, :display_ship_total,
+ :adjustment_total, :display_adjustment_total, :promo_total, :display_promo_total,
+ :tax_total, :display_tax_total, :included_tax_total, :display_included_tax_total,
+ :additional_tax_total, :display_additional_tax_total, :total, :display_total,
+ created_at: :iso8601, updated_at: :iso8601
+
+ many :order_promotions, resource: Spree.api.order_promotion_serializer
+ many :line_items, resource: Spree.api.line_item_serializer
+ many :shipments, resource: Spree.api.shipment_serializer
+ many :payments, resource: Spree.api.payment_serializer
+ one :bill_address, resource: Spree.api.address_serializer
+ one :ship_address, resource: Spree.api.address_serializer
+
+ many :payment_methods, resource: Spree.api.payment_method_serializer
+ end
+ end
+ end
+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 fd2897284b..e612f7afa6 100644
--- a/spree/api/app/serializers/spree/api/v3/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/order_serializer.rb
@@ -2,11 +2,11 @@ module Spree
module Api
module V3
# Store API Order Serializer
- # Customer-facing order data
+ # Post-purchase order data (completed orders)
class OrderSerializer < BaseSerializer
- typelize number: :string, state: :string, checkout_steps: 'string[]', token: :string, email: [:string, nullable: true],
+ typelize number: :string, email: :string,
special_instructions: [:string, nullable: true], currency: :string, locale: [:string, nullable: true], item_count: :number,
- state_lock_version: :number, shipment_state: [:string, nullable: true], payment_state: [:string, nullable: true],
+ shipment_state: [:string, nullable: true], payment_state: [:string, nullable: true],
item_total: :string, display_item_total: :string,
ship_total: :string, display_ship_total: :string,
adjustment_total: :string, display_adjustment_total: :string,
@@ -17,8 +17,8 @@ module Spree
total: :string, display_total: :string, completed_at: [:string, nullable: true],
bill_address: { nullable: true }, ship_address: { nullable: true }
- attributes :number, :state, :checkout_steps, :token, :email, :special_instructions,
- :currency, :locale, :item_count, :state_lock_version, :shipment_state, :payment_state,
+ attributes :number, :email, :special_instructions,
+ :currency, :locale, :item_count, :shipment_state, :payment_state,
:item_total, :display_item_total, :ship_total, :display_ship_total,
:adjustment_total, :display_adjustment_total, :promo_total, :display_promo_total,
:tax_total, :display_tax_total, :included_tax_total, :display_included_tax_total,
@@ -31,8 +31,6 @@ module Spree
many :payments, resource: Spree.api.payment_serializer
one :bill_address, resource: Spree.api.address_serializer
one :ship_address, resource: Spree.api.address_serializer
-
- many :payment_methods, resource: Spree.api.payment_method_serializer
end
end
end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 5acf84faa5..09fc0723f8 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -7,9 +7,6 @@ Spree::Core::Engine.add_routes do
post 'auth/refresh', to: 'auth#refresh'
post 'auth/oauth/callback', to: 'auth#oauth_callback'
- # Customer registration
- resources :customers, only: [:create]
-
# Markets
resources :markets, only: [:index, :show] do
collection do
@@ -33,46 +30,46 @@ Spree::Core::Engine.add_routes do
resources :products, only: [:index], controller: 'categories/products'
end
- # Cart
- resource :cart, only: [:show, :create], controller: 'cart' do
+ # Carts (list all active carts for authenticated users)
+ resources :carts, only: [:index]
+
+ # Cart (pre-purchase, mutable)
+ resource :cart, only: [:show, :create, :destroy], controller: 'cart' do
patch :associate
+ resources :items, only: [:create, :update, :destroy], controller: 'cart/items'
+ resources :coupon_codes, only: [:create, :destroy], controller: 'cart/coupon_codes'
end
- # Orders - individual order management and checkout
- resources :orders, only: [:show, :update] do
- member do
- # State transitions
- patch :next # Move to next checkout step
- patch :advance # Advance through all steps
- patch :complete # Complete the order
- end
-
- # Nested resources - all require order access
- resource :store_credits, only: [:create, :destroy], controller: 'orders/store_credits'
- resources :line_items, only: [:create, :update, :destroy], controller: 'orders/line_items'
- resources :coupon_codes, only: [:create, :destroy], controller: 'orders/coupon_codes'
- resources :payments, only: [:index, :show, :create], controller: 'orders/payments'
- resources :payment_methods, only: [:index], controller: 'orders/payment_methods'
- resources :payment_sessions, only: [:create, :show, :update], controller: 'orders/payment_sessions' do
+ # Checkout (cart → order transition)
+ resource :checkout, only: [:update], controller: 'checkout' do
+ post :complete
+ resources :shipments, only: [:index, :update], controller: 'checkout/shipments'
+ resources :payment_methods, only: [:index], controller: 'checkout/payment_methods'
+ resources :payments, only: [:index, :show, :create], controller: 'checkout/payments'
+ resources :payment_sessions, only: [:create, :show, :update], controller: 'checkout/payment_sessions' do
member do
patch :complete
end
end
- resources :shipments, only: [:index, :show, :update], controller: 'orders/shipments'
+ resource :store_credits, only: [:create, :destroy], controller: 'checkout/store_credits'
end
+ # Orders (single order lookup, guest-accessible via order token)
+ resources :orders, only: [:show]
+
# Customer (current user profile)
+ resources :customers, only: [:create]
get 'customer', to: 'customers#show'
patch 'customer', to: 'customers#update'
# Customer nested resources
namespace :customer, path: 'customer' do
+ resources :orders, only: [:index, :show]
resources :addresses, only: [:index, :show, :create, :update, :destroy] do
member do
patch :mark_as_default
end
end
- resources :orders, only: [:index]
resources :credit_cards, only: [:index, :show, :destroy]
resources :gift_cards, only: [:index, :show]
resources :payment_setup_sessions, only: [:create, :show] do
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index 4886e0b67d..07e41156af 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -99,6 +99,7 @@ module Spree
image_serializer: 'Spree::Api::V3::ImageSerializer',
option_type_serializer: 'Spree::Api::V3::OptionTypeSerializer',
option_value_serializer: 'Spree::Api::V3::OptionValueSerializer',
+ cart_serializer: 'Spree::Api::V3::CartSerializer',
order_serializer: 'Spree::Api::V3::OrderSerializer',
line_item_serializer: 'Spree::Api::V3::LineItemSerializer',
payment_serializer: 'Spree::Api::V3::PaymentSerializer',
diff --git a/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rb b/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rb
index 835e5ff7d1..63568a2d05 100644
--- a/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rb
+++ b/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rb
@@ -83,7 +83,7 @@ RSpec.describe Spree::Api::V3::Idempotent, type: :controller do
it 'does not apply to GET requests' do
cart = create(:order, store: store)
- request.headers['x-spree-order-token'] = cart.token
+ request.headers['x-spree-token'] = cart.token
request.headers['Idempotency-Key'] = idempotency_key
get :show
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/coupon_codes_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/cart/coupon_codes_controller_spec.rb
similarity index 61%
rename from spree/api/spec/controllers/spree/api/v3/store/orders/coupon_codes_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/store/cart/coupon_codes_controller_spec.rb
index 26a7da26c1..1f3288260b 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/coupon_codes_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/cart/coupon_codes_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::Cart::CouponCodesController, type: :controller do
render_views
include_context 'API v3 Store'
@@ -10,7 +10,6 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
before do
request.headers['X-Spree-Api-Key'] = api_key.token
request.headers['Authorization'] = "Bearer #{jwt_token}"
- request.headers['x-spree-order-token'] = order.token
end
describe 'POST #create' do
@@ -18,20 +17,20 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'SAVE10', stores: [store]) }
it 'applies the coupon code successfully' do
- post :create, params: { order_id: order.to_param, code: 'SAVE10' }
+ post :create, params: { code: 'SAVE10' }
expect(response).to have_http_status(:created)
- expect(json_response['number']).to eq(order.number)
+ expect(json_response['id']).to start_with('cart_')
end
it 'is case insensitive' do
- post :create, params: { order_id: order.to_param, code: 'save10' }
+ post :create, params: { code: 'save10' }
expect(response).to have_http_status(:created)
end
it 'returns error for invalid coupon code' do
- post :create, params: { order_id: order.to_param, code: 'INVALID' }
+ post :create, params: { code: 'INVALID' }
expect(response).to have_http_status(:unprocessable_content)
expect(json_response['error']).to be_present
@@ -41,7 +40,7 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
order.coupon_code = 'SAVE10'
Spree::PromotionHandler::Coupon.new(order).apply
- post :create, params: { order_id: order.to_param, code: 'SAVE10' }
+ post :create, params: { code: 'SAVE10' }
expect(response).to have_http_status(:unprocessable_content)
end
@@ -54,14 +53,14 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
let!(:coupon_code) { create(:coupon_code, promotion: promotion, code: 'multi1') }
it 'applies the multi-code coupon successfully' do
- post :create, params: { order_id: order.to_param, code: 'multi1' }
+ post :create, params: { code: 'multi1' }
expect(response).to have_http_status(:created)
- expect(json_response['number']).to eq(order.number)
+ expect(json_response['id']).to start_with('cart_')
end
it 'marks the coupon code as used' do
- post :create, params: { order_id: order.to_param, code: 'multi1' }
+ post :create, params: { code: 'multi1' }
expect(coupon_code.reload.state).to eq('used')
end
@@ -71,16 +70,16 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
let!(:gift_card) { create(:gift_card, store: store, amount: 50, code: 'giftcard123') }
it 'applies the gift card successfully' do
- post :create, params: { order_id: order.to_param, code: 'giftcard123' }
+ post :create, params: { code: 'giftcard123' }
expect(response).to have_http_status(:created)
- expect(json_response['number']).to eq(order.number)
+ 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: { order_id: order.to_param, code: 'giftcard123' }
+ post :create, params: { code: 'giftcard123' }
expect(response).to have_http_status(:unprocessable_content)
end
@@ -88,7 +87,7 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
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: { order_id: order.to_param, code: 'giftcard123' }
+ post :create, params: { code: 'giftcard123' }
expect(response).to have_http_status(:unprocessable_content)
end
@@ -101,34 +100,23 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
end
it 'returns error' do
- post :create, params: { order_id: order.to_param, code: 'EXPIRED' }
+ post :create, params: { code: 'EXPIRED' }
expect(response).to have_http_status(:unprocessable_content)
end
end
- context 'without order access' do
- let(:other_order) { create(:order, store: store) }
-
- it 'returns not found' do
- request.headers['x-spree-order-token'] = nil
- post :create, params: { order_id: other_order.to_param, code: 'SAVE10' }
-
- expect(response).to have_http_status(:not_found)
- end
- end
-
- context 'with guest order token' do
+ context 'with guest spree token' do
let(:guest_order) { create(:order_with_line_items, store: store, user: nil) }
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'GUEST10', stores: [store]) }
before do
request.headers['Authorization'] = nil
- request.headers['x-spree-order-token'] = guest_order.token
+ request.headers['x-spree-token'] = guest_order.token
end
- it 'allows access via order token' do
- post :create, params: { order_id: guest_order.to_param, code: 'GUEST10' }
+ it 'allows access via spree token' do
+ post :create, params: { code: 'GUEST10' }
expect(response).to have_http_status(:created)
end
@@ -145,22 +133,18 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :cont
end
it 'removes the coupon code successfully' do
- order_promotion = order.order_promotions.find_by(promotion: promotion)
- # OrderPromotion lacks has_prefix_id, so construct a decodable param
- encoded_id = "op_#{Spree::PrefixedId::SQIDS.encode([order_promotion.id])}"
-
- delete :destroy, params: { order_id: order.to_param, id: encoded_id }
+ delete :destroy, params: { id: 'REMOVE10' }
expect(response).to have_http_status(:ok)
expect(order.reload.promotions).not_to include(promotion)
end
end
- context 'with non-existent promotion' do
- it 'returns not found' do
- delete :destroy, params: { order_id: order.to_param, id: 'op_nonexistent' }
+ context 'with non-existent coupon code' do
+ it 'returns error' do
+ delete :destroy, params: { id: 'NONEXISTENT' }
- expect(response).to have_http_status(:not_found)
+ expect(response).to have_http_status(:unprocessable_content)
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/cart/items_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/cart/items_controller_spec.rb
new file mode 100644
index 0000000000..1d0b17f128
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/store/cart/items_controller_spec.rb
@@ -0,0 +1,155 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Store::Cart::ItemsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Store'
+
+ let(:product) { create(:product, stores: [store]) }
+ let(:variant) { create(:variant, product: product) }
+ let!(:order) { create(:order, user: user, store: store) }
+
+ before do
+ request.headers['X-Spree-Api-Key'] = api_key.token
+ request.headers['Authorization'] = "Bearer #{jwt_token}"
+ end
+
+ describe 'POST #create' do
+ it 'adds a line item and returns updated cart' do
+ expect do
+ post :create, params: { variant_id: variant.prefixed_id, quantity: 2 }
+ end.to change(Spree::LineItem, :count).by(1)
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['id']).to start_with('cart_')
+ expect(json_response['item_count']).to eq(2)
+ end
+
+ it 'defaults quantity to 1' do
+ post :create, params: { variant_id: variant.prefixed_id }
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['item_count']).to eq(1)
+ end
+
+ it 'returns updated totals' do
+ post :create, params: { variant_id: variant.prefixed_id, quantity: 2 }
+
+ expect(json_response['item_total'].to_f).to be > 0
+ end
+
+ context 'with metadata' do
+ it 'adds a line item with metadata' do
+ post :create, params: {
+ variant_id: variant.prefixed_id,
+ quantity: 1,
+ metadata: { 'gift_note' => 'Happy Birthday!' }
+ }
+
+ expect(response).to have_http_status(:created)
+ line_item = order.reload.line_items.last
+ expect(line_item.metadata).to eq({ 'gift_note' => 'Happy Birthday!' })
+ end
+ end
+
+ context 'with spree token (guest)' do
+ let(:guest_order) { create(:order, user: nil, store: store) }
+
+ before { request.headers['Authorization'] = nil }
+
+ it 'adds line item with valid spree token' do
+ request.headers['x-spree-token'] = guest_order.token
+ post :create, params: { variant_id: variant.prefixed_id, quantity: 1 }
+
+ expect(response).to have_http_status(:created)
+ end
+
+ it 'returns not found without spree token' do
+ post :create, params: { variant_id: variant.prefixed_id, quantity: 1 }
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ context 'validation errors' do
+ it 'returns error for invalid variant' do
+ post :create, params: { variant_id: 'invalid_0', quantity: 1 }
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ describe 'PATCH #update' do
+ let!(:line_item) { create(:line_item, order: order, variant: variant, quantity: 1) }
+
+ it 'updates line item quantity and returns updated cart' do
+ patch :update, params: { id: line_item.prefixed_id, quantity: 5 }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to start_with('cart_')
+ expect(line_item.reload.quantity).to eq(5)
+ end
+
+ it 'returns updated totals' do
+ original_total = order.item_total
+ patch :update, params: { id: line_item.prefixed_id, quantity: 5 }
+
+ expect(json_response['item_total'].to_f).to be > original_total
+ end
+
+ context 'with metadata' do
+ it 'updates line item metadata' do
+ patch :update, params: {
+ id: line_item.prefixed_id,
+ metadata: { 'gift_note' => 'Happy Birthday!' }
+ }
+
+ expect(response).to have_http_status(:ok)
+ expect(line_item.reload.metadata).to eq({ 'gift_note' => 'Happy Birthday!' })
+ end
+
+ it 'updates metadata and quantity together' do
+ patch :update, params: {
+ id: line_item.prefixed_id,
+ quantity: 3,
+ metadata: { 'gift_note' => 'Happy Birthday!' }
+ }
+
+ expect(response).to have_http_status(:ok)
+ line_item.reload
+ expect(line_item.quantity).to eq(3)
+ expect(line_item.metadata).to eq({ 'gift_note' => 'Happy Birthday!' })
+ end
+ end
+
+ context 'error handling' do
+ it 'returns not found for non-existent line item' do
+ patch :update, params: { id: 'li_nonexistent', quantity: 5 }
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ let!(:line_item) { create(:line_item, order: order, variant: variant) }
+
+ it 'removes line item and returns updated cart' do
+ expect do
+ delete :destroy, params: { id: line_item.prefixed_id }
+ end.to change(Spree::LineItem, :count).by(-1)
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to start_with('cart_')
+ end
+
+ context 'error handling' do
+ it 'returns not found for non-existent line item' do
+ delete :destroy, params: { id: 'li_nonexistent' }
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/cart_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/cart_controller_spec.rb
index eb548e1a92..d43322f03e 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/cart_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/cart_controller_spec.rb
@@ -141,10 +141,10 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
end
describe 'GET #show' do
- context 'with x-spree-order-token header' do
+ context 'with x-spree-token header' do
let(:cart) { create(:order_with_line_items, store: store) }
- before { request.headers['x-spree-order-token'] = cart.token }
+ before { request.headers['x-spree-token'] = cart.token }
it 'returns the cart' do
get :show
@@ -168,7 +168,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
end
it 'returns not found for invalid token' do
- request.headers['x-spree-order-token'] = 'invalid_token'
+ request.headers['x-spree-token'] = 'invalid_token'
get :show
expect(response).to have_http_status(:not_found)
@@ -177,7 +177,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
it 'returns not found for completed order token' do
completed_order = create(:completed_order_with_totals, store: store)
- request.headers['x-spree-order-token'] = completed_order.token
+ request.headers['x-spree-token'] = completed_order.token
get :show
expect(response).to have_http_status(:not_found)
@@ -187,7 +187,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
it 'returns not found for other store cart' do
other_store = create(:store)
other_cart = create(:order_with_line_items, store: other_store)
- request.headers['x-spree-order-token'] = other_cart.token
+ request.headers['x-spree-token'] = other_cart.token
get :show
expect(response).to have_http_status(:not_found)
@@ -244,7 +244,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
end
context 'without authentication' do
- it 'returns not found without order_token or JWT' do
+ it 'returns not found without cart_token or JWT' do
get :show
expect(response).to have_http_status(:not_found)
@@ -266,7 +266,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
context 'response structure' do
let(:cart) { create(:order_with_line_items, store: store) }
- before { request.headers['x-spree-order-token'] = cart.token }
+ before { request.headers['x-spree-token'] = cart.token }
it 'returns expected cart attributes' do
get :show
@@ -311,8 +311,8 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
request.headers['Authorization'] = "Bearer #{jwt_token}"
end
- it 'associates guest cart with current user via x-spree-order-token header' do
- request.headers['x-spree-order-token'] = guest_cart.token
+ it 'associates guest cart with current user via x-spree-token header' do
+ request.headers['x-spree-token'] = guest_cart.token
patch :associate
expect(response).to have_http_status(:ok)
@@ -321,7 +321,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
end
it 'updates cart email to users email' do
- request.headers['x-spree-order-token'] = guest_cart.token
+ request.headers['x-spree-token'] = guest_cart.token
patch :associate
expect(response).to have_http_status(:ok)
@@ -333,7 +333,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
ship = create(:address, firstname: 'Ship')
user.update!(bill_address: bill, ship_address: ship)
- request.headers['x-spree-order-token'] = guest_cart.token
+ request.headers['x-spree-token'] = guest_cart.token
patch :associate
expect(response).to have_http_status(:ok)
@@ -345,7 +345,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
it 'allows re-associating cart already owned by current user' do
guest_cart.update!(user: user)
- request.headers['x-spree-order-token'] = guest_cart.token
+ request.headers['x-spree-token'] = guest_cart.token
patch :associate
expect(response).to have_http_status(:ok)
@@ -353,7 +353,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
end
it 'returns not found for invalid token' do
- request.headers['x-spree-order-token'] = 'invalid_token'
+ request.headers['x-spree-token'] = 'invalid_token'
patch :associate
expect(response).to have_http_status(:not_found)
@@ -370,7 +370,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
it 'returns not found for completed order' do
completed_order = create(:completed_order_with_totals, store: store, user: nil)
- request.headers['x-spree-order-token'] = completed_order.token
+ request.headers['x-spree-token'] = completed_order.token
patch :associate
expect(response).to have_http_status(:not_found)
@@ -381,7 +381,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
other_user = create(:user)
other_user_cart = create(:order_with_line_items, store: store, user: other_user)
- request.headers['x-spree-order-token'] = other_user_cart.token
+ request.headers['x-spree-token'] = other_user_cart.token
patch :associate
expect(response).to have_http_status(:not_found)
@@ -393,7 +393,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
other_store = create(:store)
other_store_cart = create(:order_with_line_items, store: other_store)
- request.headers['x-spree-order-token'] = other_store_cart.token
+ request.headers['x-spree-token'] = other_store_cart.token
patch :associate
expect(response).to have_http_status(:not_found)
@@ -402,7 +402,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
context 'without JWT authentication' do
it 'returns unauthorized' do
- request.headers['x-spree-order-token'] = guest_cart.token
+ request.headers['x-spree-token'] = guest_cart.token
patch :associate
expect(response).to have_http_status(:unauthorized)
@@ -414,7 +414,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller do
before { request.headers['X-Spree-Api-Key'] = nil }
it 'returns unauthorized' do
- request.headers['x-spree-order-token'] = guest_cart.token
+ request.headers['x-spree-token'] = guest_cart.token
patch :associate
expect(response).to have_http_status(:unauthorized)
diff --git a/spree/api/spec/controllers/spree/api/v3/store/checkout/payment_methods_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/checkout/payment_methods_controller_spec.rb
new file mode 100644
index 0000000000..182a062ae9
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/store/checkout/payment_methods_controller_spec.rb
@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Store::Checkout::PaymentMethodsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Store'
+
+ let!(:order) { create(:order_with_line_items, user: user, store: store, state: 'payment') }
+ let!(:payment_method) { create(:credit_card_payment_method, stores: [store], display_on: 'both') }
+ let!(:backend_only_pm) { create(:credit_card_payment_method, stores: [store], display_on: 'back_end') }
+
+ before do
+ request.headers['X-Spree-Api-Key'] = api_key.token
+ request.headers['Authorization'] = "Bearer #{jwt_token}"
+ end
+
+ describe 'GET #index' do
+ it 'returns available payment methods for the cart' do
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].map { |pm| pm['id'] }).to include(payment_method.prefixed_id)
+ end
+
+ it 'excludes backend-only payment methods' do
+ get :index
+
+ expect(json_response['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefixed_id)
+ end
+
+ it 'includes session_required in the response' do
+ get :index
+
+ pm = json_response['data'].find { |p| p['id'] == payment_method.prefixed_id }
+ expect(pm).to have_key('session_required')
+ end
+
+ it 'includes payment method count in meta' do
+ get :index
+
+ expect(json_response['meta']['count']).to be_present
+ end
+
+ context 'with spree token (guest)' do
+ let(:guest_order) { create(:order_with_line_items, store: store, user: nil, state: 'payment') }
+
+ before { request.headers['Authorization'] = nil }
+
+ it 'returns payment methods with valid spree token' do
+ request.headers['x-spree-token'] = guest_order.token
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_present
+ end
+
+ it 'returns not found without spree token' do
+ get :index
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/payment_sessions_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/checkout/payment_sessions_controller_spec.rb
similarity index 59%
rename from spree/api/spec/controllers/spree/api/v3/store/orders/payment_sessions_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/store/checkout/payment_sessions_controller_spec.rb
index b74368cdfc..bc44e1c8e2 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/payment_sessions_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/checkout/payment_sessions_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::Checkout::PaymentSessionsController, type: :controller do
render_views
include_context 'API v3 Store'
@@ -22,10 +22,7 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :
describe 'POST #create' do
it 'creates a payment session' do
- post :create, params: {
- order_id: order.to_param,
- payment_method_id: payment_method.prefixed_id
- }
+ post :create, params: { payment_method_id: payment_method.prefixed_id }
expect(response).to have_http_status(:created)
expect(json_response['id']).to be_present
@@ -36,7 +33,6 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :
it 'passes external_data to the gateway' do
post :create, params: {
- order_id: order.to_param,
payment_method_id: payment_method.prefixed_id,
external_data: { channel: 'Web' }
}
@@ -45,58 +41,37 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :
expect(json_response['external_data']).to include('channel' => 'Web')
end
- context 'with order token (guest)' do
+ context 'with spree token (guest)' do
let(:guest_order) { create(:order_with_line_items, user: nil, store: store, state: 'payment') }
before { request.headers['Authorization'] = nil }
- it 'creates payment session with valid order token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- post :create, params: {
- order_id: guest_order.to_param,
- payment_method_id: payment_method.prefixed_id
- }
+ it 'creates payment session with valid spree token' do
+ request.headers['x-spree-token'] = guest_order.token
+ post :create, params: { payment_method_id: payment_method.prefixed_id }
expect(response).to have_http_status(:created)
end
- it 'returns not found without order token' do
- post :create, params: {
- order_id: guest_order.to_param,
- payment_method_id: payment_method.prefixed_id
- }
+ it 'returns not found without spree token' do
+ post :create, params: { payment_method_id: payment_method.prefixed_id }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
end
end
context 'error handling' do
- it 'returns not found for non-existent order' do
- post :create, params: {
- order_id: 'invalid',
- payment_method_id: payment_method.prefixed_id
- }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
-
it 'returns not found for non-existent payment method' do
- post :create, params: {
- order_id: order.to_param,
- payment_method_id: 'invalid'
- }
+ post :create, params: { payment_method_id: 'pm_invalid' }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
end
end
end
describe 'GET #show' do
it 'returns a payment session' do
- get :show, params: { order_id: order.to_param, id: payment_session.to_param }
+ get :show, params: { id: payment_session.to_param }
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(payment_session.prefixed_id)
@@ -107,33 +82,28 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :
context 'error handling' do
it 'returns not found for non-existent payment session' do
- get :show, params: { order_id: order.to_param, id: 'invalid' }
+ get :show, params: { id: 'ps_invalid' }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
end
it 'returns not found for payment session from another order' do
- other_order = create(:order_with_line_items, user: user, store: store, state: 'payment')
+ other_user = create(:user)
+ other_order = create(:order_with_line_items, user: other_user, store: store, state: 'payment')
other_session = create(:bogus_payment_session,
order: other_order,
payment_method: payment_method)
- get :show, params: { order_id: order.to_param, id: other_session.to_param }
+ get :show, params: { id: other_session.to_param }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
end
end
end
describe 'PATCH #update' do
it 'updates the payment session' do
- patch :update, params: {
- order_id: order.to_param,
- id: payment_session.to_param,
- amount: 50.00
- }
+ patch :update, params: { id: payment_session.to_param, amount: 50.00 }
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(payment_session.prefixed_id)
@@ -143,11 +113,7 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :
describe 'PATCH #complete' do
it 'completes the payment session' do
- patch :complete, params: {
- order_id: order.to_param,
- id: payment_session.to_param,
- session_result: 'success'
- }
+ patch :complete, params: { id: payment_session.to_param, session_result: 'success' }
expect(response).to have_http_status(:ok)
expect(json_response['status']).to eq('completed')
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/payments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/checkout/payments_controller_spec.rb
similarity index 60%
rename from spree/api/spec/controllers/spree/api/v3/store/orders/payments_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/store/checkout/payments_controller_spec.rb
index 9cb4f65d51..5e587f7c04 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/payments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/checkout/payments_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::Checkout::PaymentsController, type: :controller do
render_views
include_context 'API v3 Store'
@@ -15,8 +15,8 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
end
describe 'GET #index' do
- it 'returns a list of payments for the order' do
- get :index, params: { order_id: order.to_param }
+ it 'returns a list of payments for the cart' do
+ get :index
expect(response).to have_http_status(:ok)
expect(json_response['data'].size).to eq(1)
@@ -24,55 +24,36 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
end
it 'includes payment method information' do
- get :index, params: { order_id: order.to_param }
+ get :index
expect(json_response['data'].first['payment_method_id']).to eq(payment_method.prefixed_id)
end
- context 'with order token (guest)' do
+ context 'with spree token (guest)' do
let(:guest_order) { create(:order_with_line_items, user: nil, store: store, state: 'payment') }
let!(:guest_payment) { create(:payment, order: guest_order, payment_method: payment_method) }
before { request.headers['Authorization'] = nil }
- it 'returns payments with valid order token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- get :index, params: { order_id: guest_order.to_param }
+ it 'returns payments with valid spree token' do
+ request.headers['x-spree-token'] = guest_order.token
+ get :index
expect(response).to have_http_status(:ok)
expect(json_response['data'].size).to eq(1)
end
- it 'returns not found without order token' do
- get :index, params: { order_id: guest_order.to_param }
+ it 'returns not found without spree token' do
+ get :index
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent order' do
- get :index, params: { order_id: 'invalid' }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
-
- it 'returns not found for other users order' do
- other_order = create(:order, store: store)
-
- get :index, params: { order_id: other_order.to_param }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
end
end
end
describe 'GET #show' do
it 'returns a single payment' do
- get :show, params: { order_id: order.to_param, id: payment.to_param }
+ get :show, params: { id: payment.to_param }
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(payment.prefixed_id)
@@ -82,20 +63,19 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
context 'error handling' do
it 'returns not found for non-existent payment' do
- get :show, params: { order_id: order.to_param, id: 'invalid' }
+ get :show, params: { id: 'py_invalid' }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
end
it 'returns not found for payment from another order' do
- other_order = create(:order_with_line_items, user: user, store: store, state: 'payment')
+ other_user = create(:user)
+ other_order = create(:order_with_line_items, user: other_user, store: store, state: 'payment')
other_payment = create(:payment, order: other_order, payment_method: payment_method, amount: other_order.total)
- get :show, params: { order_id: order.to_param, id: other_payment.to_param }
+ get :show, params: { id: other_payment.to_param }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
end
end
end
@@ -104,17 +84,16 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
let(:check_payment_method) { create(:check_payment_method, stores: [store]) }
it 'creates a payment with a non-session payment method' do
- post :create, params: { order_id: order.to_param, payment_method_id: check_payment_method.prefixed_id }
+ post :create, params: { payment_method_id: check_payment_method.prefixed_id }
expect(response).to have_http_status(:created)
expect(json_response['id']).to be_present
expect(json_response['state']).to eq('checkout')
expect(json_response['payment_method_id']).to eq(check_payment_method.prefixed_id)
- expect(json_response['amount']).to eq(order.total_minus_store_credits.to_s)
end
it 'creates a payment with a custom amount' do
- post :create, params: { order_id: order.to_param, payment_method_id: check_payment_method.prefixed_id, amount: '50.00' }
+ post :create, params: { payment_method_id: check_payment_method.prefixed_id, amount: '50.00' }
expect(response).to have_http_status(:created)
expect(json_response['amount']).to eq('50.0')
@@ -122,7 +101,6 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
it 'creates a payment with metadata' do
post :create, params: {
- order_id: order.to_param,
payment_method_id: check_payment_method.prefixed_id,
metadata: { purchase_order_number: 'PO-12345' }
}
@@ -135,7 +113,7 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
it 'rejects session-required payment methods' do
bogus_method = create(:bogus_payment_method, stores: [store])
- post :create, params: { order_id: order.to_param, payment_method_id: bogus_method.prefixed_id }
+ post :create, params: { payment_method_id: bogus_method.prefixed_id }
expect(response).to have_http_status(:unprocessable_content)
expect(json_response['error']['code']).to eq('payment_session_required')
@@ -145,26 +123,26 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :control
unavailable_method = create(:check_payment_method, stores: [store])
allow_any_instance_of(Spree::PaymentMethod::Check).to receive(:available_for_order?).and_return(false)
- post :create, params: { order_id: order.to_param, payment_method_id: unavailable_method.prefixed_id }
+ post :create, params: { payment_method_id: unavailable_method.prefixed_id }
expect(response).to have_http_status(:unprocessable_content)
expect(json_response['error']['code']).to eq('payment_method_unavailable')
end
it 'returns not found for invalid payment method' do
- post :create, params: { order_id: order.to_param, payment_method_id: 'pm_invalid' }
+ post :create, params: { payment_method_id: 'pm_invalid' }
expect(response).to have_http_status(:not_found)
end
- context 'with order token (guest)' do
+ context 'with spree token (guest)' do
let(:guest_order) { create(:order_with_line_items, user: nil, store: store, state: 'payment') }
before { request.headers['Authorization'] = nil }
- it 'creates a payment with valid order token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- post :create, params: { order_id: guest_order.to_param, payment_method_id: check_payment_method.prefixed_id }
+ it 'creates a payment with valid spree token' do
+ request.headers['x-spree-token'] = guest_order.token
+ post :create, params: { payment_method_id: check_payment_method.prefixed_id }
expect(response).to have_http_status(:created)
expect(json_response['payment_method_id']).to eq(check_payment_method.prefixed_id)
diff --git a/spree/api/spec/controllers/spree/api/v3/store/checkout/shipments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/checkout/shipments_controller_spec.rb
new file mode 100644
index 0000000000..158467458f
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/store/checkout/shipments_controller_spec.rb
@@ -0,0 +1,98 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Store::Checkout::ShipmentsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Store'
+
+ let!(:order) do
+ create(:order_with_line_items, user: user, store: store, state: 'delivery').tap do |o|
+ o.create_proposed_shipments
+ o.shipments.first.refresh_rates
+ o.reload
+ end
+ end
+ let!(:shipment) { order.shipments.first }
+
+ before do
+ request.headers['X-Spree-Api-Key'] = api_key.token
+ request.headers['Authorization'] = "Bearer #{jwt_token}"
+ end
+
+ describe 'GET #index' do
+ it 'returns a list of shipments for the cart' do
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].size).to eq(order.shipments.count)
+ expect(json_response['data'].first['id']).to eq(shipment.prefixed_id)
+ end
+
+ context 'with spree token (guest)' do
+ let(:guest_order) do
+ create(:order_with_line_items, user: nil, store: store, state: 'delivery').tap do |o|
+ o.create_proposed_shipments
+ o.reload
+ end
+ end
+
+ before { request.headers['Authorization'] = nil }
+
+ it 'returns shipments with valid spree token' do
+ request.headers['x-spree-token'] = guest_order.token
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_present
+ end
+
+ it 'returns not found without spree token' do
+ get :index
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ describe 'PATCH #update' do
+ context 'when selecting a different shipping rate' do
+ let(:cheaper_shipping_method) { create(:shipping_method, name: 'Cheap Shipping') }
+ let(:expensive_shipping_method) { create(:shipping_method, name: 'Express Shipping') }
+
+ before do
+ shipment.shipping_rates.delete_all
+ create(:shipping_rate, shipment: shipment, shipping_method: cheaper_shipping_method, cost: 5, selected: true)
+ create(:shipping_rate, shipment: shipment, shipping_method: expensive_shipping_method, cost: 25, selected: false)
+ shipment.reload
+ order.set_shipments_cost
+ end
+
+ it 'updates order totals when a different shipping rate is selected' do
+ expensive_rate = shipment.shipping_rates.find_by(shipping_method: expensive_shipping_method)
+
+ expect(order.shipment_total).to eq(5)
+
+ patch :update, params: {
+ id: shipment.to_param,
+ selected_shipping_rate_id: expensive_rate.to_param
+ }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to start_with('cart_')
+ order.reload
+ expect(order.shipment_total).to eq(25)
+ end
+ end
+
+ context 'error handling' do
+ it 'returns not found for non-existent shipping rate' do
+ patch :update, params: {
+ id: shipment.to_param,
+ selected_shipping_rate_id: 'sr_invalid'
+ }
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/checkout/store_credits_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/checkout/store_credits_controller_spec.rb
new file mode 100644
index 0000000000..bc4fd9be49
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/store/checkout/store_credits_controller_spec.rb
@@ -0,0 +1,71 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Store::Checkout::StoreCreditsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Store'
+
+ let!(:order) { create(:order_with_line_items, user: user, store: store, state: 'payment') }
+ let!(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
+ let!(:store_credit) { create(:store_credit, user: user, store: store, amount: 100) }
+
+ before do
+ request.headers['X-Spree-Api-Key'] = api_key.token
+ request.headers['Authorization'] = "Bearer #{jwt_token}"
+ end
+
+ describe 'POST #create' do
+ it 'applies store credit to the cart' do
+ post :create, params: { amount: 10 }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to start_with('cart_')
+ expect(order.reload.payments.store_credits.count).to eq(1)
+ end
+
+ context 'without available store credit' do
+ let(:user_without_credit) { create(:user) }
+ let!(:order_without_credit) { create(:order_with_line_items, user: user_without_credit, store: store, state: 'payment') }
+
+ it 'returns an error' do
+ jwt = Spree::Api::V3::TestingSupport.generate_jwt(user_without_credit)
+ request.headers['Authorization'] = "Bearer #{jwt}"
+ post :create, params: { amount: 10 }
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']).to be_present
+ end
+ end
+
+ context 'authentication' do
+ it 'requires authentication' do
+ request.headers['Authorization'] = nil
+
+ post :create, params: { amount: 10 }
+
+ expect(response).to have_http_status(:unauthorized)
+ end
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ it 'removes store credit and returns updated cart' do
+ Spree.checkout_add_store_credit_service.call(order: order, amount: 10)
+
+ delete :destroy
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to start_with('cart_')
+ end
+
+ context 'authentication' do
+ it 'requires authentication' do
+ request.headers['Authorization'] = nil
+
+ delete :destroy
+
+ expect(response).to have_http_status(:unauthorized)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/customer/orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/customer/orders_controller_spec.rb
index 1e9d033b99..82c95c453e 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/customer/orders_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/customer/orders_controller_spec.rb
@@ -5,8 +5,8 @@ RSpec.describe Spree::Api::V3::Store::Customer::OrdersController, type: :control
include_context 'API v3 Store'
- let!(:order) { create(:order_with_line_items, user: user, store: store) }
- let!(:other_user_order) { create(:order_with_line_items, store: store) }
+ let!(:order) { create(:completed_order_with_totals, user: user, store: store) }
+ let!(:other_user_order) { create(:completed_order_with_totals, store: store) }
before do
request.headers['X-Spree-Api-Key'] = api_key.token
@@ -31,7 +31,7 @@ RSpec.describe Spree::Api::V3::Store::Customer::OrdersController, type: :control
it 'does not return orders from other stores' do
other_store = create(:store)
- create(:order_with_line_items, user: user, store: other_store)
+ create(:completed_order_with_totals, user: user, store: other_store)
get :index
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/line_items_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/orders/line_items_controller_spec.rb
deleted file mode 100644
index 196e099fad..0000000000
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/line_items_controller_spec.rb
+++ /dev/null
@@ -1,243 +0,0 @@
-require 'spec_helper'
-
-RSpec.describe Spree::Api::V3::Store::Orders::LineItemsController, type: :controller do
- render_views
-
- include_context 'API v3 Store'
-
- let(:product) { create(:product, stores: [store]) }
- let(:variant) { create(:variant, product: product) }
- let(:order) { create(:order, user: user, store: store) }
-
- before do
- request.headers['X-Spree-Api-Key'] = api_key.token
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- request.headers['x-spree-order-token'] = order.token
- end
-
- describe 'POST #create' do
- it 'adds a line item and returns updated order' do
- expect do
- post :create, params: { order_id: order.to_param, variant_id: variant.prefixed_id, quantity: 2 }
- end.to change(Spree::LineItem, :count).by(1)
-
- expect(response).to have_http_status(:created)
- expect(json_response['id']).to eq(order.prefixed_id)
- expect(json_response['number']).to eq(order.number)
- expect(json_response['item_count']).to eq(2)
- end
-
- it 'defaults quantity to 1' do
- post :create, params: { order_id: order.to_param, variant_id: variant.prefixed_id }
-
- expect(response).to have_http_status(:created)
- expect(json_response['item_count']).to eq(1)
- end
-
- it 'returns updated totals' do
- post :create, params: { order_id: order.to_param, variant_id: variant.prefixed_id, quantity: 2 }
-
- expect(json_response['item_total'].to_f).to be > 0
- end
-
- context 'with metadata' do
- it 'adds a line item with metadata' do
- post :create, params: {
- order_id: order.to_param,
- variant_id: variant.prefixed_id,
- quantity: 1,
- metadata: { 'gift_note' => 'Happy Birthday!' }
- }
-
- expect(response).to have_http_status(:created)
- line_item = order.line_items.last
- expect(line_item.metadata).to eq({ 'gift_note' => 'Happy Birthday!' })
- end
-
- it 'does not return metadata in response' do
- post :create, params: {
- order_id: order.to_param,
- variant_id: variant.prefixed_id,
- quantity: 1,
- metadata: { 'gift_note' => 'Happy Birthday!' }
- }
-
- expect(response).to have_http_status(:created)
- json_response['line_items'].each do |li|
- expect(li).not_to have_key('metadata')
- expect(li).not_to have_key('private_metadata')
- end
- end
- end
-
- context 'with order token (guest)' do
- let(:guest_order) { create(:order, user: nil, store: store) }
-
- before { request.headers['Authorization'] = nil }
-
- it 'adds line item with valid order token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- post :create, params: { order_id: guest_order.to_param, variant_id: variant.prefixed_id, quantity: 1 }
-
- expect(response).to have_http_status(:created)
- end
-
- it 'returns not found without order token' do
- post :create, params: { order_id: guest_order.to_param, variant_id: variant.prefixed_id, quantity: 1 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
-
- context 'validation errors' do
- it 'returns error for invalid variant' do
- post :create, params: { order_id: order.to_param, variant_id: 0, quantity: 1 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('variant_not_found')
- expect(json_response['error']['message']).to be_present
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent order' do
- post :create, params: { order_id: 'invalid', variant_id: variant.prefixed_id, quantity: 1 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- expect(json_response['error']['message']).to be_present
- end
-
- it 'returns not found for other users order' do
- other_order = create(:order, store: store)
-
- post :create, params: { order_id: other_order.to_param, variant_id: variant.prefixed_id, quantity: 1 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-
- describe 'PATCH #update' do
- let!(:line_item) { create(:line_item, order: order, variant: variant, quantity: 1) }
-
- it 'updates line item quantity and returns updated order' do
- patch :update, params: { order_id: order.to_param, id: line_item.prefixed_id, quantity: 5 }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(order.prefixed_id)
- expect(json_response['number']).to eq(order.number)
- expect(line_item.reload.quantity).to eq(5)
- end
-
- it 'returns updated totals' do
- original_total = order.item_total
- patch :update, params: { order_id: order.to_param, id: line_item.prefixed_id, quantity: 5 }
-
- expect(json_response['item_total'].to_f).to be > original_total
- end
-
- context 'with metadata' do
- it 'updates line item metadata' do
- patch :update, params: {
- order_id: order.to_param,
- id: line_item.prefixed_id,
- metadata: { 'gift_note' => 'Happy Birthday!' }
- }
-
- expect(response).to have_http_status(:ok)
- expect(line_item.reload.metadata).to eq({ 'gift_note' => 'Happy Birthday!' })
- end
-
- it 'merges metadata with existing values' do
- line_item.update!(private_metadata: { 'existing_key' => 'value' })
-
- patch :update, params: {
- order_id: order.to_param,
- id: line_item.prefixed_id,
- metadata: { 'new_key' => 'new_value' }
- }
-
- expect(response).to have_http_status(:ok)
- expect(line_item.reload.metadata).to eq({ 'existing_key' => 'value', 'new_key' => 'new_value' })
- end
-
- it 'updates metadata and quantity together' do
- patch :update, params: {
- order_id: order.to_param,
- id: line_item.prefixed_id,
- quantity: 3,
- metadata: { 'gift_note' => 'Happy Birthday!' }
- }
-
- expect(response).to have_http_status(:ok)
- line_item.reload
- expect(line_item.quantity).to eq(3)
- expect(line_item.metadata).to eq({ 'gift_note' => 'Happy Birthday!' })
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent line item' do
- patch :update, params: { order_id: order.to_param, id: 0, quantity: 5 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('line_item_not_found')
- expect(json_response['error']['message']).to be_present
- end
-
- it 'returns not found for line item in other users order' do
- other_order = create(:order, store: store)
- other_line_item = create(:line_item, order: other_order, variant: variant)
-
- patch :update, params: { order_id: other_order.to_param, id: other_line_item.prefixed_id, quantity: 5 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-
- describe 'DELETE #destroy' do
- let!(:line_item) { create(:line_item, order: order, variant: variant) }
-
- it 'removes line item and returns updated order' do
- expect do
- delete :destroy, params: { order_id: order.to_param, id: line_item.prefixed_id }
- end.to change(Spree::LineItem, :count).by(-1)
-
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(order.prefixed_id)
- expect(json_response['number']).to eq(order.number)
- end
-
- it 'updates order totals' do
- order.update_columns(item_total: 100)
- delete :destroy, params: { order_id: order.to_param, id: line_item.prefixed_id }
-
- expect(order.reload.item_total).to eq(0)
- end
-
- context 'error handling' do
- it 'returns not found for non-existent line item' do
- delete :destroy, params: { order_id: order.to_param, id: 0 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('line_item_not_found')
- expect(json_response['error']['message']).to be_present
- end
-
- it 'returns not found for line item in other users order' do
- other_order = create(:order, store: store)
- other_line_item = create(:line_item, order: other_order, variant: variant)
-
- delete :destroy, params: { order_id: other_order.to_param, id: other_line_item.prefixed_id }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/payment_methods_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/orders/payment_methods_controller_spec.rb
deleted file mode 100644
index eb2bd1b70c..0000000000
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/payment_methods_controller_spec.rb
+++ /dev/null
@@ -1,84 +0,0 @@
-require 'spec_helper'
-
-RSpec.describe Spree::Api::V3::Store::Orders::PaymentMethodsController, type: :controller do
- render_views
-
- include_context 'API v3 Store'
-
- let(:order) { create(:order_with_line_items, user: user, store: store, state: 'payment') }
- let!(:payment_method) { create(:credit_card_payment_method, stores: [store], display_on: 'both') }
- let!(:backend_only_pm) { create(:credit_card_payment_method, stores: [store], display_on: 'back_end') }
-
- before do
- request.headers['X-Spree-Api-Key'] = api_key.token
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- end
-
- describe 'GET #index' do
- it 'returns available payment methods for the order' do
- get :index, params: { order_id: order.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['data'].map { |pm| pm['id'] }).to include(payment_method.prefixed_id)
- end
-
- it 'excludes backend-only payment methods' do
- get :index, params: { order_id: order.to_param }
-
- expect(json_response['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefixed_id)
- end
-
- it 'includes session_required in the response' do
- get :index, params: { order_id: order.to_param }
-
- pm = json_response['data'].find { |p| p['id'] == payment_method.prefixed_id }
- expect(pm).to have_key('session_required')
- expect(pm['session_required']).to eq(payment_method.session_required?)
- end
-
- it 'includes payment method count in meta' do
- get :index, params: { order_id: order.to_param }
-
- expect(json_response['meta']['count']).to be_present
- end
-
- context 'with order token (guest)' do
- let(:guest_order) { create(:order_with_line_items, store: store, state: 'payment') }
-
- before { request.headers['Authorization'] = nil }
-
- it 'returns payment methods with valid order token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- get :index, params: { order_id: guest_order.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['data']).to be_present
- end
-
- it 'returns not found without order token' do
- get :index, params: { order_id: guest_order.to_param }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent order' do
- get :index, params: { order_id: 'invalid' }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
-
- it 'returns not found for other users order' do
- other_order = create(:order, store: store)
-
- get :index, params: { order_id: other_order.to_param }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/shipments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/orders/shipments_controller_spec.rb
deleted file mode 100644
index e6b44bfeb2..0000000000
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/shipments_controller_spec.rb
+++ /dev/null
@@ -1,173 +0,0 @@
-require 'spec_helper'
-
-RSpec.describe Spree::Api::V3::Store::Orders::ShipmentsController, type: :controller do
- render_views
-
- include_context 'API v3 Store'
-
- let(:order) do
- create(:order_with_line_items, user: user, store: store, state: 'delivery').tap do |o|
- o.create_proposed_shipments
- o.shipments.first.refresh_rates
- o.reload
- end
- end
- let(:shipment) { order.shipments.first }
-
- before do
- request.headers['X-Spree-Api-Key'] = api_key.token
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- request.headers['X-Spree-Order-Token'] = order.token
- end
-
- describe 'GET #index' do
- it 'returns a list of shipments for the order' do
- get :index, params: { order_id: order.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['data'].size).to eq(order.shipments.count)
- expect(json_response['data'].first['id']).to eq(shipment.prefixed_id)
- end
-
- context 'with order token (guest)' do
- let(:guest_order) do
- create(:order_with_line_items, user: nil, store: store, state: 'delivery').tap do |o|
- o.create_proposed_shipments
- o.reload
- end
- end
-
- before { request.headers['Authorization'] = nil }
-
- it 'returns shipments with valid order token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- get :index, params: { order_id: guest_order.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['data']).to be_present
- end
-
- it 'returns not found without order token' do
- request.headers['X-Spree-Order-Token'] = nil
- get :index, params: { order_id: guest_order.to_param }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent order' do
- get :index, params: { order_id: 'invalid' }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
-
- it 'returns not found for other users order' do
- other_order = create(:order_with_line_items, store: store)
- request.headers['X-Spree-Order-Token'] = nil
-
- get :index, params: { order_id: other_order.to_param }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-
- describe 'GET #show' do
- it 'returns a single shipment' do
- get :show, params: { order_id: order.to_param, id: shipment.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(shipment.prefixed_id)
- expect(json_response['state']).to eq(shipment.state)
- end
-
- context 'error handling' do
- it 'returns not found for non-existent shipment' do
- get :show, params: { order_id: order.to_param, id: 'invalid' }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
- end
-
- it 'returns not found for shipment from another order' do
- other_order = create(:order_with_line_items, user: user, store: store).tap do |o|
- o.create_proposed_shipments
- o.reload
- end
- other_shipment = other_order.shipments.first
-
- get :show, params: { order_id: order.to_param, id: other_shipment.to_param }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
- end
- end
- end
-
- describe 'PATCH #update' do
- let(:shipping_rate) { shipment.shipping_rates.first }
-
- it 'selects a shipping rate and returns updated order' do
- skip 'Shipping rate setup requires more complex factory' unless shipping_rate.present?
-
- patch :update, params: {
- order_id: order.to_param,
- id: shipment.to_param,
- selected_shipping_rate_id: shipping_rate.to_param
- }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(order.prefixed_id)
- expect(json_response['number']).to eq(order.number)
- expect(shipment.reload.selected_shipping_rate_id).to eq(shipping_rate.id)
- end
-
- context 'when selecting a different shipping rate' do
- let(:cheaper_shipping_method) { create(:shipping_method, name: 'Cheap Shipping') }
- let(:expensive_shipping_method) { create(:shipping_method, name: 'Express Shipping') }
-
- before do
- shipment.shipping_rates.delete_all
- create(:shipping_rate, shipment: shipment, shipping_method: cheaper_shipping_method, cost: 5, selected: true)
- create(:shipping_rate, shipment: shipment, shipping_method: expensive_shipping_method, cost: 25, selected: false)
- shipment.reload
- order.set_shipments_cost
- end
-
- it 'updates order totals when a different shipping rate is selected' do
- expensive_rate = shipment.shipping_rates.find_by(shipping_method: expensive_shipping_method)
- original_shipment_total = order.shipment_total
-
- expect(original_shipment_total).to eq(5)
-
- patch :update, params: {
- order_id: order.to_param,
- id: shipment.to_param,
- selected_shipping_rate_id: expensive_rate.to_param
- }
-
- expect(response).to have_http_status(:ok)
- order.reload
- expect(order.shipment_total).to eq(25)
- expect(order.total).to eq(order.item_total + 25 + order.adjustment_total)
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent shipping rate' do
- patch :update, params: {
- order_id: order.to_param,
- id: shipment.to_param,
- selected_shipping_rate_id: 'invalid'
- }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
- end
- end
- end
-end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders/store_credits_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/orders/store_credits_controller_spec.rb
deleted file mode 100644
index 6182295dcb..0000000000
--- a/spree/api/spec/controllers/spree/api/v3/store/orders/store_credits_controller_spec.rb
+++ /dev/null
@@ -1,104 +0,0 @@
-require 'spec_helper'
-
-RSpec.describe Spree::Api::V3::Store::Orders::StoreCreditsController, type: :controller do
- render_views
-
- include_context 'API v3 Store'
-
- let(:order) { create(:order_with_line_items, user: user, store: store, state: 'payment') }
- let!(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
- let!(:store_credit) { create(:store_credit, user: user, store: store, amount: 100) }
-
- before do
- request.headers['X-Spree-Api-Key'] = api_key.token
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- end
-
- describe 'POST #create' do
- it 'applies store credit to the order' do
- post :create, params: { order_id: order.to_param, amount: 10 }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.payments.store_credits.count).to eq(1)
- end
-
- it 'returns the updated order' do
- post :create, params: { order_id: order.to_param, amount: 10 }
-
- expect(json_response['id']).to eq(order.prefixed_id)
- end
-
- context 'without available store credit' do
- let(:user_without_credit) { create(:user) }
- let(:order_without_credit) { create(:order_with_line_items, user: user_without_credit, store: store, state: 'payment') }
-
- it 'returns an error' do
- jwt = Spree::Api::V3::TestingSupport.generate_jwt(user_without_credit)
- request.headers['Authorization'] = "Bearer #{jwt}"
- post :create, params: { order_id: order_without_credit.to_param, amount: 10 }
-
- expect(response).to have_http_status(:unprocessable_content)
- expect(json_response['error']).to be_present
- end
- end
-
- context 'authentication' do
- it 'requires authentication' do
- request.headers['Authorization'] = nil
-
- post :create, params: { order_id: order.to_param, amount: 10 }
-
- expect(response).to have_http_status(:unauthorized)
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent order' do
- post :create, params: { order_id: 'invalid', amount: 10 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
-
- it 'returns not found for other users order' do
- other_order = create(:order, store: store)
-
- post :create, params: { order_id: other_order.to_param, amount: 10 }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-
- describe 'DELETE #destroy' do
- it 'returns the updated order' do
- # First add store credit, then remove it
- Spree.checkout_add_store_credit_service.call(order: order, amount: 10)
-
- delete :destroy, params: { order_id: order.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(order.prefixed_id)
- end
-
- context 'authentication' do
- it 'requires authentication' do
- request.headers['Authorization'] = nil
-
- delete :destroy, params: { order_id: order.to_param }
-
- expect(response).to have_http_status(:unauthorized)
- end
- end
-
- context 'error handling' do
- it 'returns not found for non-existent order' do
- delete :destroy, params: { order_id: 'invalid' }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/orders_controller_spec.rb
index a53e823000..733a5155f8 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/orders_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/orders_controller_spec.rb
@@ -10,7 +10,7 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller do
end
describe 'GET #show' do
- let(:order) { create(:order_with_line_items, user: user, store: store) }
+ let(:order) { create(:completed_order_with_totals, user: user, store: store) }
context 'authenticated user' do
before do
@@ -22,7 +22,6 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller do
expect(response).to have_http_status(:ok)
expect(json_response['number']).to eq(order.number)
- expect(json_response['state']).to eq(order.state)
end
it 'returns order with expected attributes' do
@@ -33,11 +32,11 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller do
end
end
- context 'with order token' do
- let(:guest_order) { create(:order_with_line_items, user: nil, store: store) }
+ context 'with spree token' do
+ let(:guest_order) { create(:completed_order_with_totals, user: nil, store: store) }
it 'returns the order for guest with valid token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
+ request.headers['x-spree-token'] = guest_order.token
get :show, params: { id: guest_order.to_param }
expect(response).to have_http_status(:ok)
@@ -45,18 +44,16 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller do
end
it 'returns not found with invalid token' do
- request.headers['X-Spree-Order-Token'] = 'invalid'
+ request.headers['x-spree-token'] = 'invalid'
get :show, params: { id: guest_order.to_param }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
end
it 'returns not found without token' do
get :show, params: { id: guest_order.to_param }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
end
end
@@ -65,202 +62,25 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller do
request.headers['Authorization'] = "Bearer #{jwt_token}"
end
- it 'returns not found for invalid order number' do
- get :show, params: { id: 'invalid' }
+ it 'returns not found for invalid order id' do
+ get :show, params: { id: 'or_invalid' }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- expect(json_response['error']['message']).to be_present
end
it 'returns not found for other users order' do
- other_order = create(:order_with_line_items, store: store)
+ other_order = create(:completed_order_with_totals, store: store)
get :show, params: { id: other_order.to_param }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
end
- end
- end
-
- describe 'PATCH #update' do
- let(:order) { create(:order_with_line_items, user: user, store: store) }
-
- context 'authenticated' do
- before do
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- end
-
- it 'updates the order email' do
- patch :update, params: { id: order.to_param, email: '[email protected]' }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.email).to eq('[email protected]')
- end
-
- it 'updates special instructions' do
- patch :update, params: { id: order.to_param, special_instructions: 'Leave at door' }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.special_instructions).to eq('Leave at door')
- end
-
- it 'updates the order locale' do
- create(:market, store: store, default_locale: 'en', supported_locales: 'en,fr')
-
- patch :update, params: { id: order.to_param, locale: 'fr' }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.locale).to eq('fr')
- expect(json_response['locale']).to eq('fr')
- end
-
- it 'returns error when locale is not supported by store' do
- create(:market, store: store, default_locale: 'en', supported_locales: 'en')
-
- patch :update, params: { id: order.to_param, locale: 'de' }
-
- expect(response).to have_http_status(:unprocessable_entity)
- end
-
- it 'updates order metadata' do
- patch :update, params: {
- id: order.to_param,
- metadata: { 'source' => 'mobile_app', 'utm_campaign' => 'summer' }
- }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.metadata).to eq({ 'source' => 'mobile_app', 'utm_campaign' => 'summer' })
- end
-
- it 'merges metadata with existing values' do
- order.update!(private_metadata: { 'existing' => 'value' })
-
- patch :update, params: {
- id: order.to_param,
- metadata: { 'new_key' => 'new_value' }
- }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.metadata).to eq({ 'existing' => 'value', 'new_key' => 'new_value' })
- end
-
- it 'does not return metadata in response' do
- patch :update, params: {
- id: order.to_param,
- metadata: { 'source' => 'mobile_app' }
- }
-
- expect(response).to have_http_status(:ok)
- expect(json_response).not_to have_key('metadata')
- expect(json_response).not_to have_key('private_metadata')
- end
- end
-
- context 'with order token' do
- let(:guest_order) { create(:order_with_line_items, user: nil, store: store) }
-
- it 'updates order for guest with valid token' do
- request.headers['X-Spree-Order-Token'] = guest_order.token
- patch :update, params: { id: guest_order.to_param, email: '[email protected]' }
-
- expect(response).to have_http_status(:ok)
- expect(guest_order.reload.email).to eq('[email protected]')
- end
- end
- context 'with line_items' do
- let(:product) { create(:product, stores: [store]) }
- let(:variant) { create(:variant, product: product) }
-
- before do
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- variant.stock_items.first.update!(count_on_hand: 10)
- end
-
- it 'adds new line items to the order' do
- patch :update, params: {
- id: order.to_param,
- line_items: [{ variant_id: variant.prefixed_id, quantity: 3 }]
- }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.line_items.find_by(variant: variant).quantity).to eq(3)
- end
-
- it 'upserts existing line items' do
- existing_variant = order.line_items.first.variant
-
- patch :update, params: {
- id: order.to_param,
- line_items: [{ variant_id: existing_variant.prefixed_id, quantity: 7 }]
- }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.line_items.find_by(variant: existing_variant).quantity).to eq(7)
- end
-
- it 'returns line items in response' do
- patch :update, params: {
- id: order.to_param,
- line_items: [{ variant_id: variant.prefixed_id, quantity: 2 }]
- }
-
- expect(response).to have_http_status(:ok)
- variant_ids = json_response['line_items'].map { |li| li['variant_id'] }
- expect(variant_ids).to include(variant.prefixed_id)
- end
-
- it 'returns variant_not_found for invalid variant_id' do
- patch :update, params: {
- id: order.to_param,
- line_items: [{ variant_id: 'variant_doesnotexist', quantity: 1 }]
- }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('variant_not_found')
- expect(json_response['error']['message']).to include('variant_doesnotexist')
- end
- end
-
- context 'error handling' do
- before do
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- end
-
- it 'returns not found for other users order' do
- other_order = create(:order_with_line_items, store: store)
- patch :update, params: { id: other_order.to_param, email: '[email protected]' }
+ it 'returns not found for incomplete orders' do
+ incomplete_order = create(:order_with_line_items, user: user, store: store)
+ get :show, params: { id: incomplete_order.to_param }
expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('order_not_found')
- end
- end
- end
-
- describe 'order locking' do
- let(:order) { create(:order_with_line_items, user: user, store: store) }
-
- before do
- request.headers['Authorization'] = "Bearer #{jwt_token}"
- end
-
- describe 'state_lock_version in responses' do
- it 'returns state_lock_version in show response' do
- get :show, params: { id: order.to_param }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['state_lock_version']).to eq(0)
- end
-
- it 'increments state_lock_version after successful update' do
- patch :update, params: { id: order.to_param, email: '[email protected]' }
-
- expect(response).to have_http_status(:ok)
- expect(order.reload.state_lock_version).to eq(1)
- expect(json_response['state_lock_version']).to eq(1)
end
end
-
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb b/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb
index d622e6ad3f..88d4976605 100644
--- a/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb
@@ -12,8 +12,8 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
produces 'application/json'
security [api_key: []]
description <<~DESC
- Creates a new shopping cart (order). Can be created by guests or authenticated customers.
- Returns a `token` that must be used for guest access to the order.
+ Creates a new shopping cart. Can be created by guests or authenticated customers.
+ Returns a `token` that must be used for guest access to the cart.
DESC
sdk_example <<~JS
@@ -56,10 +56,11 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
response '201', 'cart created (guest)' do
let(:'x-spree-api-key') { api_key.token }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to be_present
expect(data['state']).to eq('cart')
expect(data['token']).to be_present
@@ -70,7 +71,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test!
end
@@ -90,7 +91,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
}
end
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
@@ -104,7 +105,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
let(:'x-spree-api-key') { api_key.token }
let(:body) { { metadata: { 'source' => 'mobile_app', 'campaign' => 'summer_sale' } } }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
@@ -167,7 +168,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
security [api_key: [], bearer_auth: []]
description <<~DESC
Returns the current shopping cart (incomplete order).
- Authenticate via JWT token for logged-in users or via x-spree-order-token header for guests.
+ Authenticate via JWT token for logged-in users or via x-spree-token header for guests.
DESC
sdk_example <<~JS
@@ -185,18 +186,19 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: false,
description: 'Bearer JWT token for authenticated customers'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest checkout'
response '200', 'cart found (guest)' do
let(:cart) { create(:order_with_line_items, store: store) }
let(:'x-spree-api-key') { api_key.token }
- let(:'x-spree-order-token') { cart.token }
+ let(:'x-spree-token') { cart.token }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(cart.number)
expect(data['token']).to eq(cart.token)
expect(data['line_items']).to be_present
@@ -208,7 +210,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
@@ -227,6 +229,31 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
end
end
end
+
+ delete 'Delete current cart' do
+ tags 'Cart'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Deletes/abandons the current shopping cart.'
+
+ sdk_example <<~JS
+ await client.cart.delete({
+ orderToken: 'ORDER_TOKEN',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
+
+ response '204', 'cart deleted' do
+ let!(:cart) { create(:order_with_line_items, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ run_test!
+ end
+ end
end
path '/api/v3/store/cart/associate' do
@@ -250,19 +277,20 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true,
description: 'Bearer JWT token (required)'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: true,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: true,
description: 'Order token for identifying the guest cart'
response '200', 'cart associated successfully' do
let(:guest_cart) { create(:order_with_line_items, store: store, user: nil) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:'x-spree-order-token') { guest_cart.token }
+ let(:'x-spree-token') { guest_cart.token }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(guest_cart.number)
expect(guest_cart.reload.user).to eq(user)
end
@@ -272,7 +300,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
let(:guest_cart) { create(:order_with_line_items, store: store, user: nil) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { '' }
- let(:'x-spree-order-token') { guest_cart.token }
+ let(:'x-spree-token') { guest_cart.token }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -287,7 +315,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
let(:other_cart) { create(:order_with_line_items, store: store, user: other_user) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:'x-spree-order-token') { other_cart.token }
+ let(:'x-spree-token') { other_cart.token }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -300,7 +328,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
response '404', 'cart not found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:'x-spree-order-token') { 'invalid_token' }
+ let(:'x-spree-token') { 'invalid_token' }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -314,7 +342,7 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yam
let(:completed_order) { create(:completed_order_with_totals, store: store, user: nil) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:'x-spree-order-token') { completed_order.token }
+ let(:'x-spree-token') { completed_order.token }
schema '$ref' => '#/components/schemas/ErrorResponse'
diff --git a/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb b/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb
new file mode 100644
index 0000000000..03c43356d8
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/store/carts_spec.rb
@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Carts API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:user) { create(:user_with_addresses) }
+
+ path '/api/v3/store/carts' do
+ get 'List active carts' do
+ tags 'Cart'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all active (incomplete) carts for the authenticated user. Useful for users who may have multiple carts.'
+
+ sdk_example <<~JS
+ const carts = await client.carts.list({
+ bearerToken: '<token>',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+
+ response '200', 'carts listed' do
+ let!(:cart1) { create(:order_with_line_items, store: store, user: user) }
+ let!(:cart2) { create(:order_with_line_items, store: store, user: user) }
+ let!(:completed_order) { create(:completed_order_with_totals, store: store, user: user) }
+ let!(:other_user_cart) { create(:order_with_line_items, store: store, user: create(:user)) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ ids = data['data'].map { |c| c['id'] }
+ # All cart IDs should use cart_ prefix
+ expect(ids).to all(start_with('cart_'))
+ expect(ids.size).to eq(2)
+ expect(data['meta']['count']).to eq(2)
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { '' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/store/checkout_spec.rb b/spree/api/spec/integration/spree/api/v3/store/checkout_spec.rb
new file mode 100644
index 0000000000..70f496a10e
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/store/checkout_spec.rb
@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Checkout API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:user) { create(:user_with_addresses) }
+ let!(:order) { create(:order_with_line_items, store: store, user: user) }
+
+ path '/api/v3/store/checkout' do
+ patch 'Update checkout' do
+ tags 'Checkout'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates checkout info (email, addresses, special instructions). When addresses change, the order state is reverted to address to ensure shipments are recalculated.'
+
+ sdk_example <<~JS
+ const cart = await client.checkout.update({
+ email: '[email protected]',
+ ship_address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ },
+ }, {
+ bearerToken: '<token>',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
+ 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: {
+ email: { type: :string, format: 'email', example: '[email protected]' },
+ special_instructions: { type: :string, example: 'Leave at door' },
+ metadata: { type: :object, additionalProperties: true },
+ bill_address: {
+ type: :object,
+ properties: {
+ firstname: { type: :string }, lastname: { type: :string },
+ address1: { type: :string }, address2: { type: :string },
+ city: { type: :string }, zipcode: { type: :string },
+ phone: { type: :string }, company: { type: :string },
+ country_iso: { type: :string }, state_abbr: { type: :string }
+ }
+ },
+ ship_address: {
+ type: :object,
+ properties: {
+ firstname: { type: :string }, lastname: { type: :string },
+ address1: { type: :string }, address2: { type: :string },
+ city: { type: :string }, zipcode: { type: :string },
+ phone: { type: :string }, company: { type: :string },
+ country_iso: { type: :string }, state_abbr: { type: :string }
+ }
+ }
+ }
+ }
+
+ response '200', 'checkout updated' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { special_instructions: 'Leave at door' } }
+
+ schema '$ref' => '#/components/schemas/Cart'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
+ expect(data['special_instructions']).to eq('Leave at door')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/store/checkout/complete' do
+ post 'Complete checkout' do
+ tags 'Checkout'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Completes the checkout and finalizes the purchase. Returns an Order (not Cart).'
+
+ sdk_example <<~JS
+ const order = await client.checkout.complete({
+ bearerToken: '<token>',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false
+
+ response '200', 'checkout completed' do
+ let(:completable_order) do
+ order = create(:order_with_line_items, store: store, user: user)
+ Spree.checkout_advance_service.call(order: order)
+ payment_method = create(:check_payment_method, stores: [store])
+ create(:payment, order: order, amount: order.total, payment_method: payment_method, state: 'checkout')
+ order.reload
+ end
+ let!(:_ensure_order) { completable_order }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema '$ref' => '#/components/schemas/Order'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to start_with('or_')
+ expect(data['completed_at']).to be_present
+ end
+ end
+
+ response '422', 'cannot complete' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ 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/coupon_codes_spec.rb
index 363eaa3ac9..815930db42 100644
--- a/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb
@@ -2,24 +2,24 @@
require 'swagger_helper'
-RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Cart Coupon 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) }
- path '/api/v3/store/orders/{order_id}/coupon_codes' do
+ path '/api/v3/store/cart/coupon_codes' do
post 'Apply coupon code' do
tags 'Cart'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
description <<~DESC
- Applies a coupon code to the order. Supports both promotion coupon codes and gift card codes.
+ Applies a coupon code to the cart. Supports both promotion coupon codes and gift card codes.
The code is matched case-insensitively.
DESC
sdk_example <<~JS
- const order = await client.orders.couponCodes.apply('or_abc123', 'SAVE10', {
+ const cart = await client.cart.couponCodes.apply('SAVE10', {
bearerToken: '<token>',
})
JS
@@ -27,12 +27,10 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/s
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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
+ description: 'Unique key for request idempotency.'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -45,13 +43,13 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/s
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'SAVE10', stores: [store]) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { { code: 'SAVE10' } }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(order.number)
end
end
@@ -60,10 +58,9 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/s
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(:order_id) { order.to_param }
let(:body) { { code: 'giftcode1' } }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
@@ -74,7 +71,6 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/s
response '422', 'invalid coupon code' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { { code: 'NONEXISTENT' } }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -84,29 +80,18 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/s
expect(data['error']).to be_present
end
end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'or_nonexistent' }
- let(:body) { { code: 'SAVE10' } }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
end
end
- path '/api/v3/store/orders/{order_id}/coupon_codes/{id}' do
+ path '/api/v3/store/cart/coupon_codes/{id}' do
delete 'Remove coupon code' do
tags 'Cart'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Removes a previously applied coupon code from the order.'
+ description 'Removes a previously applied coupon code from the cart. The ID is the coupon code string itself.'
sdk_example <<~JS
- const order = await client.orders.couponCodes.remove('or_abc123', 'op_abc123', {
+ const cart = await client.cart.couponCodes.remove('SAVE10', {
bearerToken: '<token>',
})
JS
@@ -114,38 +99,34 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/s
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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Order promotion ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ description: 'The coupon 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
let!(:promotion) { create(:promotion_with_item_adjustment, code: 'REMOVE10', stores: [store]) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) do
order.coupon_code = 'REMOVE10'
Spree::PromotionHandler::Coupon.new(order).apply
- op = order.order_promotions.find_by(promotion: promotion)
- "op_#{Spree::PrefixedId::SQIDS.encode([op.id])}"
+ 'REMOVE10'
end
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(order.number)
end
end
- response '404', 'coupon code not found on order' do
+ response '422', 'coupon code not found on cart' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
- let(:id) { 'op_nonexistent' }
+ let(:id) { 'NONEXISTENT' }
schema '$ref' => '#/components/schemas/ErrorResponse'
diff --git a/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb b/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb
index 91e0c2847e..8aca1d8943 100644
--- a/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb
@@ -6,54 +6,38 @@ RSpec.describe 'Customer Orders API', type: :request, swagger_doc: 'api-referenc
include_context 'API v3 Store'
let(:user) { create(:user_with_addresses) }
- let!(:order) { create(:order_with_line_items, store: store, user: user) }
path '/api/v3/store/customer/orders' do
- get 'List customer orders' do
- tags 'Customers'
+ get 'List orders' do
+ tags 'Customer'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns a paginated list of orders for the authenticated customer'
+ description 'Returns a paginated list of completed orders for the authenticated customer.'
sdk_example <<~JS
const orders = await client.customer.orders.list({
- page: 1,
- limit: 25,
- }, {
bearerToken: '<token>',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
- parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :limit, in: :query, type: :integer, required: false
- parameter name: :sort, in: :query, type: :string, required: false,
- description: 'Sort order. Prefix with - for descending. Example: -completed_at'
- parameter name: 'q[state_eq]', in: :query, type: :string, required: false,
- description: 'Filter by order state'
- parameter name: 'q[completed_at_gte]', in: :query, type: :string, required: false,
- description: 'Filter by completion date (after)'
- parameter name: :fields, in: :query, type: :string, required: false,
- description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
-
- response '200', 'orders found' do
+
+ response '200', 'orders listed' do
+ let!(:completed_order) { create(:completed_order_with_totals, store: store, user: user) }
+ let!(:incomplete_order) { create(:order_with_line_items, store: store, user: user) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- schema type: :object,
- properties: {
- data: { type: :array, items: { '$ref' => '#/components/schemas/Order' } },
- meta: { '$ref' => '#/components/schemas/PaginationMeta' }
- }
-
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['data']).to be_an(Array)
+ ids = data['data'].map { |o| o['id'] }
+ expect(ids).to include(completed_order.prefixed_id)
+ expect(ids).not_to include(incomplete_order.prefixed_id)
end
end
- response '401', 'unauthorized - authentication required' do
+ response '401', 'unauthorized' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { '' }
@@ -63,4 +47,52 @@ RSpec.describe 'Customer Orders API', type: :request, swagger_doc: 'api-referenc
end
end
end
+
+ path '/api/v3/store/customer/orders/{id}' do
+ get 'Get an order' do
+ tags 'Customer'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns a single completed order for the authenticated customer.'
+
+ sdk_example <<~JS
+ const order = await client.customer.orders.get('or_abc123', {
+ bearerToken: '<token>',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+
+ response '200', 'order found' do
+ let(:completed_order) { create(:completed_order_with_totals, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { completed_order.to_param }
+
+ schema '$ref' => '#/components/schemas/Order'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to start_with('or_')
+ expect(data['number']).to eq(completed_order.number)
+ expect(data['completed_at']).to be_present
+ end
+ end
+
+ response '404', 'order belongs to another user' do
+ let(:other_user) { create(:user) }
+ let(:other_order) { create(:completed_order_with_totals, store: store, user: other_user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { other_order.to_param }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb b/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb
index 3c5318ea37..e3878354e9 100644
--- a/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb
@@ -2,7 +2,7 @@
require 'swagger_helper'
-RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Cart Items API', type: :request, swagger_doc: 'api-reference/store.yaml' do
include_context 'API v3 Store'
let!(:order) { create(:order, store: store, user: user) }
@@ -10,16 +10,16 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
let!(:variant) { product.master }
let!(:line_item) { create(:line_item, order: order, variant: variant, quantity: 1) }
- path '/api/v3/store/orders/{order_id}/line_items' do
+ path '/api/v3/store/cart/items' do
post 'Add item to cart' do
tags 'Cart'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Adds a variant to the order. Creates a new line item or increases quantity if variant already in cart.'
+ description 'Adds a variant to the cart. Creates a new line item or increases quantity if variant already in cart.'
sdk_example <<~JS
- const order = await client.orders.lineItems.create('or_abc123', {
+ const cart = await client.cart.items.add({
variant_id: 'variant_abc123',
quantity: 2,
}, {
@@ -30,34 +30,32 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID or number'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
+ description: 'Unique key for request idempotency.'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
variant_id: { type: :string, example: 'variant_abc123', description: 'Variant ID to add' },
quantity: { type: :integer, example: 2, description: 'Quantity to add (default: 1)' },
- metadata: { type: :object, additionalProperties: true, description: 'Arbitrary key-value metadata (stored, not returned in responses)', example: { gift_message: 'Happy Birthday!' } }
+ metadata: { type: :object, additionalProperties: true, description: 'Arbitrary key-value metadata', example: { gift_message: 'Happy Birthday!' } }
},
required: %w[variant_id]
}
- response '201', 'item added, returns updated order' do
+ response '201', 'item added, returns updated cart' do
let(:new_product) { create(:product, stores: [store]) }
let(:new_variant) { new_product.master }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { { variant_id: new_variant.prefixed_id, quantity: 2 } }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(order.number)
expect(data['line_items'].first).to have_key('currency')
end
@@ -68,7 +66,6 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
let(:new_variant) { new_product.master }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { { variant_id: new_variant.prefixed_id, quantity: 1, metadata: { gift_message: 'Happy Birthday!' } } }
run_test! do |_response|
@@ -80,28 +77,16 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
response '404', 'variant not found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { { variant_id: 'invalid', quantity: 1 } }
schema '$ref' => '#/components/schemas/ErrorResponse'
run_test!
end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'non-existent' }
- let(:body) { { variant_id: variant.prefixed_id, quantity: 1 } }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
end
end
- path '/api/v3/store/orders/{order_id}/line_items/{id}' do
+ path '/api/v3/store/cart/items/{id}' do
patch 'Update line item quantity' do
tags 'Cart'
consumes 'application/json'
@@ -110,7 +95,7 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
description 'Updates the quantity of a line item in the cart'
sdk_example <<~JS
- const order = await client.orders.lineItems.update('or_abc123', 'li_abc123', {
+ const cart = await client.cart.items.update('li_abc123', {
quantity: 5,
}, {
bearerToken: '<token>',
@@ -119,9 +104,8 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: false
- parameter name: :order_id, in: :path, type: :string, required: true
parameter name: :id, in: :path, type: :string, required: true, description: 'Line item ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -130,17 +114,17 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
}
}
- response '200', 'quantity updated, returns updated order' do
+ response '200', 'quantity updated, returns updated cart' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) { line_item.to_param }
let(:body) { { quantity: 5 } }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(order.number)
expect(line_item.reload.quantity).to eq(5)
end
@@ -149,7 +133,6 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
response '200', 'metadata updated on line item' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) { line_item.to_param }
let(:body) { { metadata: { engraving: 'J.D.' } } }
@@ -157,38 +140,36 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
expect(line_item.reload.metadata).to include('engraving' => 'J.D.')
end
end
-
end
delete 'Remove line item from cart' do
tags 'Cart'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Removes a line item from the order'
+ description 'Removes a line item from the cart'
sdk_example <<~JS
- const order = await client.orders.lineItems.delete('or_abc123', 'li_abc123', {
+ const cart = await client.cart.items.remove('li_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
- parameter name: :order_id, in: :path, type: :string, required: true
parameter name: :id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
- response '200', 'line item removed, returns updated order' do
+ response '200', 'line item removed, returns updated cart' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) { line_item.to_param }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
expect(order.reload.line_items).to be_empty
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(order.number)
end
end
@@ -196,7 +177,6 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/sto
response '404', 'line item not found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) { 'non-existent' }
schema '$ref' => '#/components/schemas/ErrorResponse'
diff --git a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
index b26a80dd07..3df492c114 100644
--- a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
@@ -6,353 +6,73 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.y
include_context 'API v3 Store'
let(:user) { create(:user_with_addresses) }
- let!(:order) { create(:order_with_line_items, store: store, user: user) }
path '/api/v3/store/orders/{id}' do
get 'Get an order' do
tags 'Orders'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns a single order by ID or number. Guests must provide the x-spree-order-token header.'
+ description 'Returns a single completed order by prefixed ID. Accessible via JWT (authenticated users) or order token header (guests).'
sdk_example <<~JS
const order = await client.orders.get('or_abc123', {
- expand: 'line_items,shipments',
- }, {
bearerToken: '<token>',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer token for authenticated customers'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Order ID (prefixed) or order number'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ description: 'Order prefixed ID'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
- parameter name: :expand, in: :query, type: :string, required: false,
- description: 'Expand associations (line_items, shipments, payments)'
- parameter name: :fields, in: :query, type: :string, required: false,
- description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
response '200', 'order found (authenticated)' do
+ let(:completed_order) { create(:completed_order_with_totals, store: store, user: user) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { order.to_param }
+ let(:id) { completed_order.to_param }
schema '$ref' => '#/components/schemas/Order'
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['number']).to eq(order.number)
- expect(data['checkout_steps']).to be_an(Array)
- expect(data['checkout_steps']).to include('address', 'complete')
+ expect(data['id']).to start_with('or_')
+ expect(data['number']).to eq(completed_order.number)
+ expect(data['completed_at']).to be_present
+ expect(data).not_to have_key('token')
+ expect(data).not_to have_key('checkout_steps')
+ expect(data).not_to have_key('state_lock_version')
end
end
- response '200', 'order found (guest with token)' do
- let(:guest_order) { create(:order_with_line_items, store: store, user: nil) }
+ response '200', 'order found (guest via order token)' do
+ let(:guest_order) { create(:completed_order_with_totals, store: store, user: nil, email: '[email protected]') }
let(:'x-spree-api-key') { api_key.token }
let(:id) { guest_order.to_param }
- let(:'x-spree-order-token') { guest_order.token }
-
- schema '$ref' => '#/components/schemas/Order'
-
- run_test!
- end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { 'R999999999' }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
-
- response '404', 'not found - order belongs to another user' do
- let(:other_user) { create(:user) }
- let(:other_order) { create(:order, store: store, user: other_user) }
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { other_order.to_param }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
- end
-
- patch 'Update an order' do
- tags 'Checkout'
- consumes 'application/json'
- produces 'application/json'
- security [api_key: [], bearer_auth: []]
- description 'Updates order attributes like email, special instructions, or addresses'
-
- sdk_example <<~JS
- const order = await client.orders.update('or_abc123', {
- email: '[email protected]',
- special_instructions: 'Leave at door',
- line_items: [
- { variant_id: 'variant_abc123', quantity: 2 },
- ],
- bill_address: {
- firstname: 'John',
- lastname: 'Doe',
- address1: '123 Main St',
- city: 'New York',
- zipcode: '10001',
- country_iso: 'US',
- state_abbr: 'NY',
- },
- }, {
- bearerToken: '<token>',
- })
- JS
-
- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: 'Authorization', in: :header, type: :string, required: false
- parameter name: :id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
- parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
- parameter name: :body, in: :body, schema: {
- type: :object,
- properties: {
- email: { type: :string, format: 'email', example: '[email protected]' },
- locale: { type: :string, example: 'en' },
- special_instructions: { type: :string, example: 'Leave at door' },
- metadata: { type: :object, additionalProperties: true, description: 'Arbitrary key-value metadata (merged with existing)', example: { source: 'mobile_app' } },
- bill_address: {
- type: :object,
- properties: {
- firstname: { type: :string, example: 'John' },
- lastname: { type: :string, example: 'Doe' },
- address1: { type: :string, example: '123 Main St' },
- address2: { type: :string, example: 'Apt 4B' },
- city: { type: :string, example: 'New York' },
- zipcode: { type: :string, example: '10001' },
- phone: { type: :string, example: '+1 555 123 4567' },
- company: { type: :string, example: 'Acme Inc' },
- country_iso: { type: :string, example: 'US' },
- state_abbr: { type: :string, example: 'NY' }
- }
- },
- ship_address: {
- type: :object,
- properties: {
- firstname: { type: :string, example: 'Jane' },
- lastname: { type: :string, example: 'Smith' },
- address1: { type: :string, example: '456 Oak Ave' },
- address2: { type: :string, example: 'Suite 200' },
- city: { type: :string, example: 'Los Angeles' },
- zipcode: { type: :string, example: '90001' },
- phone: { type: :string, example: '+1 555 987 6543' },
- company: { type: :string },
- country_iso: { type: :string, example: 'US' },
- state_abbr: { type: :string, example: 'CA' }
- }
- },
- line_items: {
- type: :array,
- description: 'Line items to upsert (sets quantity for existing variants, creates new line items)',
- items: {
- type: :object,
- properties: {
- variant_id: { type: :string, example: 'variant_abc123', description: 'Prefixed variant ID' },
- quantity: { type: :integer, example: 2, description: 'Quantity to set (defaults to 1)' },
- metadata: { type: :object, additionalProperties: true, description: 'Arbitrary key-value metadata (merged with existing)' }
- },
- required: %w[variant_id]
- }
- }
- }
- }
-
- response '200', 'order updated' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { order.to_param }
- let(:body) { { special_instructions: 'Leave at door' } }
-
- schema '$ref' => '#/components/schemas/Order'
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['special_instructions']).to eq('Leave at door')
- end
- end
-
- response '200', 'order updated with line items' do
- let(:product) { create(:product, stores: [store]) }
- let(:variant) { create(:variant, product: product) }
-
- before { variant.stock_items.first.update!(count_on_hand: 10) }
-
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { order.to_param }
- let(:body) do
- {
- line_items: [
- { variant_id: variant.prefixed_id, quantity: 2 }
- ]
- }
- end
+ let(:'x-spree-token') { guest_order.token }
schema '$ref' => '#/components/schemas/Order'
run_test! do |response|
data = JSON.parse(response.body)
- variant_ids = data['line_items'].map { |li| li['variant_id'] }
- expect(variant_ids).to include(variant.prefixed_id)
- expect(order.reload.line_items.find_by(variant: variant).quantity).to eq(2)
- end
- end
-
- response '200', 'order updated with metadata' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { order.to_param }
- let(:body) { { metadata: { source: 'mobile_app', campaign: 'summer_sale' } } }
-
- run_test! do |_response|
- expect(order.reload.metadata).to include('source' => 'mobile_app', 'campaign' => 'summer_sale')
+ expect(data['id']).to start_with('or_')
+ expect(data['number']).to eq(guest_order.number)
end
end
- response '403', 'cannot update completed order' do
- let(:completed_order) { create(:completed_order_with_totals, store: store, user: user) }
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { completed_order.to_param }
- let(:body) { { special_instructions: 'Test' } }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
- end
- end
-
- path '/api/v3/store/orders/{id}/next' do
- patch 'Advance to next checkout step' do
- tags 'Checkout'
- produces 'application/json'
- security [api_key: [], bearer_auth: []]
- description 'Advances the order to the next state in the checkout flow'
-
- sdk_example <<~JS
- const order = await client.orders.next('or_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
- parameter name: :id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
- parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
-
- response '200', 'order advanced' do
- let(:advanceable_order) { create(:order_with_line_items, store: store, user: user) }
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { advanceable_order.to_param }
-
- schema '$ref' => '#/components/schemas/Order'
-
- run_test!
- end
-
- response '422', 'cannot advance - validation errors' do
- let(:invalid_order) { create(:order, store: store, user: user, state: 'address', bill_address: nil, ship_address: nil) }
+ response '404', 'order not found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { invalid_order.to_param }
+ let(:id) { 'or_nonexistent' }
schema '$ref' => '#/components/schemas/ErrorResponse'
run_test!
end
- end
- end
-
- path '/api/v3/store/orders/{id}/advance' do
- patch 'Advance through checkout' do
- tags 'Checkout'
- produces 'application/json'
- security [api_key: [], bearer_auth: []]
- description 'Advances the order through all possible checkout states'
-
- sdk_example <<~JS
- const order = await client.orders.advance('or_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
- parameter name: :id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
- parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
-
- response '200', 'order advanced' do
- let(:advanceable_order) { create(:order_with_line_items, store: store, user: user) }
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { advanceable_order.to_param }
-
- schema '$ref' => '#/components/schemas/Order'
-
- run_test!
- end
- end
- end
-
- path '/api/v3/store/orders/{id}/complete' do
- patch 'Complete the order' do
- tags 'Checkout'
- produces 'application/json'
- security [api_key: [], bearer_auth: []]
- description 'Completes the order (finalizes the purchase)'
-
- sdk_example <<~JS
- const order = await client.orders.complete('or_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
- parameter name: :id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
- parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
-
- response '200', 'order completed' do
- let(:completable_order) do
- order = create(:order_with_line_items, store: store, user: user)
- # Advance through checkout - order_with_line_items has addresses set
- Spree.checkout_advance_service.call(order: order)
- # Add payment to reach confirm state
- payment_method = create(:check_payment_method, stores: [store])
- create(:payment, order: order, amount: order.total, payment_method: payment_method, state: 'checkout')
- order.reload
- end
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { completable_order.to_param }
-
- schema '$ref' => '#/components/schemas/Order'
-
- run_test!
- end
- response '422', 'cannot complete' do
+ response '404', 'incomplete order not accessible' do
let(:incomplete_order) { create(:order_with_line_items, store: store, user: user) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
diff --git a/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb b/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb
index 3b2cc091fb..613d430af7 100644
--- a/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb
@@ -2,36 +2,35 @@
require 'swagger_helper'
-RSpec.describe 'Payment Methods API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Checkout Payment Methods API', type: :request, swagger_doc: 'api-reference/store.yaml' do
include_context 'API v3 Store'
- let(:user) { create(:user) }
let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'payment') }
let!(:payment_method) { create(:credit_card_payment_method, stores: [store], display_on: 'both') }
let!(:backend_only_pm) { create(:credit_card_payment_method, stores: [store], display_on: 'back_end') }
- path '/api/v3/store/orders/{order_id}/payment_methods' do
+ path '/api/v3/store/checkout/payment_methods' do
get 'List available payment methods' do
tags 'Checkout'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns payment methods available for the order based on store configuration and order state'
+ description 'Returns payment methods available for the current cart based on store configuration and order state.'
sdk_example <<~JS
- const methods = await client.orders.paymentMethods.list('or_abc123', {
+ const methods = await client.checkout.paymentMethods.list({
bearerToken: '<token>',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: 'Authorization', in: :header, type: :string, required: false
- parameter name: :order_id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
+ 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'
response '200', 'payment methods found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
schema type: :object,
properties: {
@@ -51,25 +50,6 @@ RSpec.describe 'Payment Methods API', type: :request, swagger_doc: 'api-referenc
expect(data['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefixed_id)
end
end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'non-existent' }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
-
- response '401', 'unauthorized' do
- let(:'x-spree-api-key') { 'invalid' }
- let(:order_id) { order.to_param }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb b/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb
index ee2ff22849..4d55422d42 100644
--- a/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb
@@ -2,11 +2,10 @@
require 'swagger_helper'
-RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Checkout Payment Sessions 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, state: 'payment') }
- let(:order_id) { order.to_param }
+ let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'payment') }
let(:payment_method) { create(:bogus_payment_method, stores: [store]) }
let!(:payment_session) do
create(:bogus_payment_session,
@@ -16,16 +15,16 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
external_data: { 'client_secret' => 'secret_123' })
end
- path '/api/v3/store/orders/{order_id}/payment_sessions' do
+ path '/api/v3/store/checkout/payment_sessions' do
post 'Create payment session' do
tags 'Checkout'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Creates a new payment session for the specified order. Delegates to the payment gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent, Adyen session, PayPal order).'
+ description 'Creates a new payment session for the current cart. Delegates to the payment gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent, Adyen session, PayPal order).'
sdk_example <<~JS
- const session = await client.orders.paymentSessions.create('or_abc123', {
+ const session = await client.checkout.paymentSessions.create({
payment_method_id: 'pm_abc123',
}, {
bearerToken: '<token>',
@@ -35,12 +34,10 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID or number'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
+ description: 'Unique key for request idempotency.'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -64,28 +61,16 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
expect(data['payment_method_id']).to eq(payment_method.prefixed_id)
end
end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'invalid' }
- let(:body) { { payment_method_id: payment_method.prefixed_id } }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
- run_test!
- end
end
end
- path '/api/v3/store/orders/{order_id}/payment_sessions/{id}' do
+ path '/api/v3/store/checkout/payment_sessions/{id}' do
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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID or number'
parameter name: :id, in: :path, type: :string, required: true,
description: 'Payment session ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
get 'Get payment session' do
@@ -95,7 +80,7 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
description 'Returns a single payment session with its current status and provider data.'
sdk_example <<~JS
- const session = await client.orders.paymentSessions.get('or_abc123', 'ps_abc123', {
+ const session = await client.checkout.paymentSessions.get('ps_abc123', {
bearerToken: '<token>',
})
JS
@@ -132,7 +117,7 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
description 'Updates a payment session. Delegates to the payment gateway to sync changes with the provider.'
sdk_example <<~JS
- const session = await client.orders.paymentSessions.update('or_abc123', 'ps_abc123', {
+ const session = await client.checkout.paymentSessions.update('ps_abc123', {
amount: '50.00',
}, {
bearerToken: '<token>',
@@ -163,15 +148,13 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
end
end
- path '/api/v3/store/orders/{order_id}/payment_sessions/{id}/complete' do
+ path '/api/v3/store/checkout/payment_sessions/{id}/complete' do
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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID or number'
parameter name: :id, in: :path, type: :string, required: true,
description: 'Payment session ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
patch 'Complete payment session' do
@@ -182,7 +165,7 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
description 'Completes a payment session by confirming the payment with the provider. This triggers payment capture/authorization and order completion.'
sdk_example <<~JS
- const session = await client.orders.paymentSessions.complete('or_abc123', 'ps_abc123', {
+ const session = await client.checkout.paymentSessions.complete('ps_abc123', {
session_result: 'success',
}, {
bearerToken: '<token>',
@@ -197,7 +180,7 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referen
}
}
parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
+ description: 'Unique key for request idempotency.'
response '200', 'payment session completed' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb b/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb
index bfe4c32b4c..e9f5e9712b 100644
--- a/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb
@@ -2,59 +2,43 @@
require 'swagger_helper'
-RSpec.describe 'Payments API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Checkout Payments 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, state: 'payment') }
- let(:order_id) { order.to_param }
- let(:payment_method) { create(:credit_card_payment_method, stores: [store]) }
- let!(:payment) { create(:payment, order: order, payment_method: payment_method, amount: order.total) }
-
- path '/api/v3/store/orders/{order_id}/payments' do
- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: 'Authorization', in: :header, type: :string, required: true
- parameter name: :order_id, in: :path, type: :string, description: 'Order prefix ID'
+ let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'payment') }
+ path '/api/v3/store/checkout/payments' do
get 'List payments' do
tags 'Checkout'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns a list of payments for the specified order'
+ description 'Returns all payments for the current cart.'
sdk_example <<~JS
- const payments = await client.orders.payments.list('or_abc123', {
+ const payments = await client.checkout.payments.list({
bearerToken: '<token>',
})
JS
- response '200', 'payments found' do
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
+
+ response '200', 'payments listed' do
+ let!(:payment) do
+ pm = create(:check_payment_method, stores: [store])
+ create(:payment, order: order, payment_method: pm, amount: order.total, state: 'checkout')
+ end
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- schema type: :object,
- properties: {
- data: {
- type: :array,
- items: { '$ref' => '#/components/schemas/Payment' }
- },
- meta: { type: :object }
- }
-
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['data'].length).to eq(1)
- expect(data['data'].first['id']).to eq(payment.prefixed_id)
+ expect(data['data'].size).to eq(1)
+ expect(data['data'][0]['id']).to eq(payment.prefixed_id)
+ expect(data['meta']['count']).to eq(1)
end
end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'invalid' }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
- run_test!
- end
end
post 'Create payment' do
@@ -67,21 +51,23 @@ RSpec.describe 'Payments API', type: :request, swagger_doc: 'api-reference/store
description 'Creates a payment for a non-session payment method (e.g. Check, Cash on Delivery, Bank Transfer). For payment methods that require a session (e.g. Stripe, PayPal), use the payment sessions endpoint instead.'
sdk_example <<~JS
- const payment = await client.orders.payments.create('or_abc123', {
+ const payment = await client.checkout.createPayment({
payment_method_id: 'pm_abc123',
}, {
bearerToken: '<token>',
})
JS
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
description: 'Order token for guest access'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
payment_method_id: { type: :string, example: 'pm_abc123', description: 'Payment method ID (must be a non-session payment method)' },
amount: { type: :string, example: '99.99', description: 'Payment amount (defaults to order total minus store credits)' },
- metadata: { type: :object, description: 'Arbitrary metadata to attach to the payment (write-only, not returned in Store API responses)' }
+ metadata: { type: :object, description: 'Arbitrary metadata to attach to the payment' }
},
required: %w[payment_method_id]
}
@@ -101,62 +87,10 @@ RSpec.describe 'Payments API', type: :request, swagger_doc: 'api-reference/store
end
response '422', 'session-based payment method' do
+ let(:credit_card_method) { create(:credit_card_payment_method, stores: [store]) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:body) { { payment_method_id: payment_method.prefixed_id } }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
- run_test!
- end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'invalid' }
- let(:body) { { payment_method_id: check_method.prefixed_id } }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
- run_test!
- end
- end
- end
-
- path '/api/v3/store/orders/{order_id}/payments/{id}' do
- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: 'Authorization', in: :header, type: :string, required: true
- parameter name: :order_id, in: :path, type: :string, description: 'Order prefix ID'
- parameter name: :id, in: :path, type: :string, description: 'Payment ID'
-
- get 'Get payment' do
- tags 'Checkout'
- produces 'application/json'
- security [api_key: [], bearer_auth: []]
- description 'Returns a single payment by ID'
-
- sdk_example <<~JS
- const payment = await client.orders.payments.get('or_abc123', 'pay_abc123', {
- bearerToken: '<token>',
- })
- JS
-
- response '200', 'payment found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { payment.to_param }
-
- schema '$ref' => '#/components/schemas/Payment'
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['id']).to eq(payment.prefixed_id)
- expect(data['state']).to eq(payment.state)
- end
- end
-
- response '404', 'payment not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:id) { 'invalid' }
+ let(:body) { { payment_method_id: credit_card_method.prefixed_id } }
schema '$ref' => '#/components/schemas/ErrorResponse'
run_test!
diff --git a/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb b/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb
index 5ddcc61b49..b6a41c01ad 100644
--- a/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb
@@ -2,40 +2,32 @@
require 'swagger_helper'
-RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Checkout Shipments 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, state: 'delivery') }
let!(:shipment) { order.shipments.first }
- path '/api/v3/store/orders/{order_id}/shipments' do
- get 'List shipments for an order' do
+ path '/api/v3/store/checkout/shipments' do
+ get 'List shipments' do
tags 'Checkout'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Returns all shipments associated with the order'
+ description 'Returns all shipments with shipping rates for the current cart.'
sdk_example <<~JS
- const shipments = await client.orders.shipments.list('or_abc123', {
+ const shipments = await client.checkout.shipments.list({
bearerToken: '<token>',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: false
- parameter name: :order_id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false, description: 'Order token for guest access'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false, description: 'Order token for guest access'
response '200', 'shipments found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
-
- schema type: :object,
- properties: {
- data: { type: :array, items: { '$ref' => '#/components/schemas/Shipment' } },
- meta: { '$ref' => '#/components/schemas/PaginationMeta' }
- }
run_test! do |response|
data = JSON.parse(response.body)
@@ -43,72 +35,20 @@ RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/stor
expect(data['data'].size).to be >= 1
end
end
-
- response '404', 'order not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { 'R999999999' }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
end
end
- path '/api/v3/store/orders/{order_id}/shipments/{id}' do
- get 'Get a shipment' do
- tags 'Checkout'
- produces 'application/json'
- security [api_key: [], bearer_auth: []]
- description 'Returns details of a specific shipment'
-
- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: 'Authorization', in: :header, type: :string, required: false
- parameter name: :order_id, in: :path, type: :string, required: true
- parameter name: :id, in: :path, type: :string, required: true, description: 'Shipment ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false, description: 'Order token for guest access'
- parameter name: :expand, in: :query, type: :string, required: false,
- description: 'Expand shipping_rates'
-
- response '200', 'shipment found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
- let(:id) { shipment.to_param }
- let(:'x-spree-order-token') { order.token }
-
- schema '$ref' => '#/components/schemas/Shipment'
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['number']).to eq(shipment.number)
- end
- end
-
- response '404', 'shipment not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
- let(:id) { 'shp_nonexistent' }
- let(:'x-spree-order-token') { order.token }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
- end
-
+ path '/api/v3/store/checkout/shipments/{id}' do
patch 'Select shipping rate for shipment' do
tags 'Checkout'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Selects a shipping rate for the shipment'
+ description 'Selects a shipping rate for a specific shipment and auto-advances checkout.'
sdk_example <<~JS
- const order = await client.orders.shipments.update('or_abc123', 'shp_abc123', {
- selected_shipping_rate_id: 'shprt_abc123',
+ const cart = await client.checkout.shipments.update('ship_abc123', {
+ selected_shipping_rate_id: 'shpr_abc123',
}, {
bearerToken: '<token>',
})
@@ -116,30 +56,28 @@ RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/stor
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: false
- parameter name: :order_id, in: :path, type: :string, required: true
parameter name: :id, in: :path, type: :string, required: true, description: 'Shipment ID'
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false, description: 'Order token for guest access'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false, description: 'Order token for guest access'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
- selected_shipping_rate_id: { type: :string, example: 'shprt_abc123', description: 'Shipping rate ID to select' }
+ selected_shipping_rate_id: { type: :string, example: 'shpr_abc123', description: 'Shipping rate ID to select' }
},
required: %w[selected_shipping_rate_id]
}
- response '200', 'shipping rate selected, returns updated order' do
+ response '200', 'shipping rate selected, returns updated cart' do
let(:shipping_rate) { shipment.shipping_rates.first }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) { shipment.to_param }
- let(:'x-spree-order-token') { order.token }
let(:body) { { selected_shipping_rate_id: shipping_rate.to_param } }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test! do |response|
data = JSON.parse(response.body)
+ expect(data['id']).to start_with('cart_')
expect(data['number']).to eq(order.number)
end
end
@@ -147,10 +85,8 @@ RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/stor
response '404', 'shipping rate not found' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:id) { shipment.to_param }
- let(:'x-spree-order-token') { order.token }
- let(:body) { { selected_shipping_rate_id: 'shprt_invalid' } }
+ let(:body) { { selected_shipping_rate_id: 'shpr_invalid' } }
schema '$ref' => '#/components/schemas/ErrorResponse'
diff --git a/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb b/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb
index bd5ed00623..381c40f97f 100644
--- a/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb
@@ -2,32 +2,31 @@
require 'swagger_helper'
-RSpec.describe 'Store Credits API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Checkout Store Credits API', type: :request, swagger_doc: 'api-reference/store.yaml' do
include_context 'API v3 Store'
let(:user) { create(:user_with_addresses) }
let!(:order) { create(:order_with_line_items, store: store, user: user) }
- path '/api/v3/store/orders/{order_id}/store_credits' do
- post 'Add store credit' do
+ path '/api/v3/store/checkout/store_credits' do
+ post 'Apply store credit' do
tags 'Checkout'
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Applies store credit to the order'
+ description 'Applies store credit to the current cart during checkout.'
sdk_example <<~JS
- const order = await client.orders.addStoreCredit('or_abc123', 10.0, {
+ const cart = await client.checkout.applyStoreCredit(10.0, {
bearerToken: '<token>',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
- parameter name: :order_id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,
- description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'
+ description: 'Unique key for request idempotency.'
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -40,7 +39,6 @@ RSpec.describe 'Store Credits API', type: :request, swagger_doc: 'api-reference/
let(:store_credit) { create(:store_credit, user: user, store: store, amount: 50) }
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { { amount: 10 } }
before do
@@ -48,7 +46,7 @@ RSpec.describe 'Store Credits API', type: :request, swagger_doc: 'api-reference/
store_credit
end
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test!
end
@@ -56,7 +54,6 @@ RSpec.describe 'Store Credits API', type: :request, swagger_doc: 'api-reference/
response '422', 'no store credit available' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
let(:body) { {} }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -69,25 +66,23 @@ RSpec.describe 'Store Credits API', type: :request, swagger_doc: 'api-reference/
tags 'Checkout'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Removes store credit from the order'
+ description 'Removes store credit from the current cart.'
sdk_example <<~JS
- const order = await client.orders.removeStoreCredit('or_abc123', {
+ const cart = await client.checkout.removeStoreCredit({
bearerToken: '<token>',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
- parameter name: :order_id, in: :path, type: :string, required: true
- parameter name: 'x-spree-order-token', in: :header, type: :string, required: false
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false
response '200', 'store credit removed' do
let(:'x-spree-api-key') { api_key.token }
let(:'Authorization') { "Bearer #{jwt_token}" }
- let(:order_id) { order.to_param }
- schema '$ref' => '#/components/schemas/Order'
+ schema '$ref' => '#/components/schemas/Cart'
run_test!
end
diff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rb
index 3a700f20bf..f40bf3342d 100644
--- a/spree/api/spec/swagger_helper.rb
+++ b/spree/api/spec/swagger_helper.rb
@@ -35,7 +35,7 @@ RSpec.configure do |config|
After login, include the JWT token in the `Authorization: Bearer <token>` header.
### Order Token (For guest checkout)
- When creating an order, a `token` is returned. Include this in the `x-spree-order-token` header
+ When creating an order, a `token` is returned. Include this in the `x-spree-token` header
for guest access to that specific order.
## Response Format
diff --git a/spree/core/app/models/concerns/spree/user_methods.rb b/spree/core/app/models/concerns/spree/user_methods.rb
index 0d8eeca7d6..14b8e598dc 100644
--- a/spree/core/app/models/concerns/spree/user_methods.rb
+++ b/spree/core/app/models/concerns/spree/user_methods.rb
@@ -35,6 +35,7 @@ module Spree
has_many :promotion_rule_users, class_name: 'Spree::PromotionRuleUser', foreign_key: :user_id, dependent: :destroy
has_many :promotion_rules, through: :promotion_rule_users, class_name: 'Spree::PromotionRule'
has_many :orders, foreign_key: :user_id, class_name: 'Spree::Order'
+ has_many :carts, -> { incomplete }, foreign_key: :user_id, class_name: 'Spree::Order'
has_many :completed_orders, -> { complete }, foreign_key: :user_id, class_name: 'Spree::Order'
has_many :store_credits, class_name: 'Spree::StoreCredit', foreign_key: :user_id, dependent: :destroy
has_many :wishlists, class_name: 'Spree::Wishlist', foreign_key: :user_id, dependent: :destroy
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index 72842a611f..c0f4957b16 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -58,6 +58,7 @@ module Spree
#
# Associations
#
+ has_many :carts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :store
has_many :checkouts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :store
has_many :orders, class_name: 'Spree::Order'
has_many :line_items, through: :orders, class_name: 'Spree::LineItem'