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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Split Orders to Cart, Checkout, Orders in Store API
Damian Legawiec48186d38f966
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 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` headerfor 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_dMea0feoumRqgBgAuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Elizebeth- last_name: Herman+ first_name: Mallory+ last_name: Schmittphone: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.QAFfl9n0ftXwpVd8NcRfD7pg39I8Eo7jibXguYer7vkuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Wilbur- last_name: Romaguera+ first_name: Loma+ last_name: Hicklephone: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: javascriptlabel: Spree SDK@@ -827,22 +827,20 @@ paths:content:application/json:example:- id: or_UkLWZg9DAJ- number: R077815792+ id: cart_UkLWZg9DAJ+ number: R234338485state: cartcheckout_steps:- address- delivery- complete- token: 6H3Y5-uIi04wYEUYjECsNQ1773240338859+ token: 1WFmOSYStXOjNKWBoA9RTg1773260171159email:special_instructions:currency: USDlocale: enitem_count: 0state_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 keycontent:@@ -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: javascriptlabel: Spree SDK@@ -974,7 +971,7 @@ paths:description: Bearer JWT token for authenticated customersschema:type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: falsedescription: Order token for guest checkout@@ -986,23 +983,21 @@ paths:content:application/json:example:- id: or_UkLWZg9DAJ- number: R272523018+ id: cart_UkLWZg9DAJ+ number: R984383391state: cartcheckout_steps:- address- delivery- payment- complete- token: sGEy8hb61E75fgLCzSknZEKxk5W6Jrjw2kJ- email: [email protected]+ token: RvY28jX4f7dPXw7cPnHeEJPE4CELLvXSpBM+ email: [email protected]special_instructions:currency: USDlocale: enitem_count: 1state_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 3148- slug: product-3148+ name: Product 36316+ slug: product-36316options_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: H91527585123state: pendingtracking: U10000tracking_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_UkLWZg9DAJname: UPS Ground@@ -1072,7 +1066,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_42- name: Perry Effertz+ name: Idalia Predovicaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1127,7 +1121,7 @@ paths:state_name: STATE_NAME_45payment_methods: []schema:- "$ref": "#/components/schemas/Order"+ "$ref": "#/components/schemas/Cart"'404':description: no cart foundcontent:@@ -1138,6 +1132,47 @@ paths:message: Order not foundschema:"$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-tokenin: headerrequired: truedescription: 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: R300345614state: cartcheckout_steps:- address- delivery- payment- complete- token: M7c69YQScfTYk6xxwD7g7cXT39avBQ2i9Hk- email: [email protected]+ token: WoRC24UvkSqpTXHRP2sX23Gs6m7hoHPNjCQ+ email: [email protected]special_instructions:currency: USDlocale: enitem_count: 1state_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 48828- slug: product-48828+ name: Product 51231+ slug: product-51231options_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: H00139797754state: pendingtracking: U10000tracking_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_UkLWZg9DAJname: UPS Groundcode: UPS_GROUNDstock_location:id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_46- name: Nickie Considine+ state_abbr: STATE_ABBR_50+ name: Lai Harveyaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'country_iso: UScountry_name: United States of America- state_text: STATE_ABBR_46+ state_text: STATE_ABBR_50shipping_rates:- id: shpr_UkLWZg9DAJshipping_method_id: shpm_UkLWZg9DAJ@@ -1299,7 +1331,7 @@ paths:firstname: Johnlastname: Doefull_name: John Doe- address1: 47 Lovely Street+ address1: 51 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -1307,16 +1339,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_48- state_abbr: STATE_ABBR_48+ state_text: STATE_ABBR_52+ state_abbr: STATE_ABBR_52quick_checkout: false- state_name: STATE_NAME_48+ state_name: STATE_NAME_52ship_address:id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 48 Lovely Street+ address1: 52 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -1324,13 +1356,13 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_49- state_abbr: STATE_ABBR_49+ state_text: STATE_ABBR_53+ state_abbr: STATE_ABBR_53quick_checkout: false- state_name: STATE_NAME_49+ state_name: STATE_NAME_53payment_methods: []schema:- "$ref": "#/components/schemas/Order"+ "$ref": "#/components/schemas/Cart"'401':description: unauthorized - JWT requiredcontent:@@ -1351,14 +1383,16 @@ paths:message: Order not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/categories":+ "/api/v3/store/carts":get:- summary: List categories+ summary: List active cartstags:- - Product Catalog+ - Cartsecurity:- 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: javascriptlabel: 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: trueschema: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: Authorizationin: headerrequired: trueschema: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: stringresponses:'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 listedcontent: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+ email: [email protected]+ 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+ email: [email protected]+ 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: 1currency: 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: 1limit: 25- count: 1+ count: 2pages: 1from: 1- to: 1- in: 1+ to: 2+ in: 2previous: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: unauthorizedcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/countries":+ "/api/v3/store/categories":get:- summary: List countries+ summary: List categoriestags:- - Internationalization+ - Product Catalogsecurity:- 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 storex-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema: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: fieldsin: queryrequired: false@@ -1794,30 +1773,87 @@ paths:type: stringresponses:'200':- description: countries found+ description: categories foundcontent: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: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/Country"- required:- - data+ "$ref": "#/components/schemas/Category"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"'401':description: unauthorizedcontent:@@ -1828,15 +1864,14 @@ paths:message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/countries/{iso}":+ "/api/v3/store/categories/{id}":get:- summary: Get a country+ summary: Get a categorytags:- - Internationalization+ - Product Catalogsecurity:- 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 IDx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: iso+ - name: idin: pathrequired: 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: stringresponses:'200':- description: country found+ description: category found by prefix IDcontent: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: falseschema:- 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 accessiblecontent: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 requiredschema:"$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 categorytags:- - Cart+ - Product Catalogsecurity:- 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+ categoryx-codeSamples:- lang: javascriptlabel: 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: trueschema:type: string- - name: Authorization- in: header- required: false- description: Bearer token for authenticated customers- schema:- type: string- - name: order_id+ - name: category_idin: pathrequired: true- description: Order ID+ description: Category permalink or prefix IDschema:type: string- - name: x-spree-order-token- in: header+ - name: page+ in: queryrequired: 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: queryrequired: 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: stringresponses:- '201':- description: coupon code applied (gift card)+ '200':+ description: products foundcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R876411685- state: cart- checkout_steps:- - address- - delivery- - payment- - complete- token: bty88BCdfBv1QJXGecUT5qdwkzesGTQW3Wt- email: [email protected]- 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_UkLWZg9DAJthumbnail_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 foundcontent: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 foundschema:"$ref": "#/components/schemas/ErrorResponse"- '404':- description: order not found+ '401':+ description: unauthorizedcontent: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 requiredschema:"$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 checkouttags:- - Cart+ - Checkoutsecurity:- 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: javascriptlabel: 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: Authorizationin: headerrequired: false- description: Bearer token for authenticated customers- schema:- type: string- - name: order_id- in: path- required: true- description: Order IDschema:type: string- - name: id- in: path- required: true- description: Order promotion ID+ - name: x-spree-token+ in: header+ required: falseschema:type: string- - name: x-spree-order-token+ - name: Idempotency-Keyin: headerrequired: false- description: Order token for guest access+ description: Unique key for request idempotency.schema:type: stringresponses:'200':- description: coupon code removed+ description: checkout updatedcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R556023391+ id: cart_UkLWZg9DAJ+ number: R588561123state: cartcheckout_steps:- address- delivery- payment- complete- token: atsEAqaNHZb2NUJH1G2AmgDG9eAFiSKjWtZ- email: [email protected]- special_instructions:+ token: MWAPtS8LeQokYsy4vPCw8KLhHkZoh6yT5Q3+ email: [email protected]+ special_instructions: Leave at doorcurrency: USDlocale: enitem_count: 1state_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 22504- slug: product-22504+ name: Product 237577+ slug: product-237577options_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: H23404285089state: pendingtracking: U10000tracking_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_UkLWZg9DAJname: UPS Groundcode: UPS_GROUNDstock_location:id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_88- name: Lonny Waelchi+ state_abbr: STATE_ABBR_86+ name: Weldon Towneaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'country_iso: UScountry_name: United States of America- state_text: STATE_ABBR_88+ state_text: STATE_ABBR_86shipping_rates:- id: shpr_UkLWZg9DAJshipping_method_id: shpm_UkLWZg9DAJ@@ -2346,7 +2294,7 @@ paths:firstname: Johnlastname: Doefull_name: John Doe- address1: 79 Lovely Street+ address1: 77 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -2354,16 +2302,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_90- state_abbr: STATE_ABBR_90+ state_text: STATE_ABBR_88+ state_abbr: STATE_ABBR_88quick_checkout: false- state_name: STATE_NAME_90+ state_name: STATE_NAME_88ship_address:id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 80 Lovely Street+ address1: 78 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -2371,199 +2319,85 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_91- state_abbr: STATE_ABBR_91+ state_text: STATE_ABBR_89+ state_abbr: STATE_ABBR_89quick_checkout: false- state_name: STATE_NAME_91+ state_name: STATE_NAME_89payment_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+ 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+ "/api/v3/store/checkout/complete":+ post:+ summary: Complete checkouttags:- - Customers+ - Checkoutsecurity:- 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: javascriptlabel: 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: Authorizationin: header- required: true- schema:- type: string- - name: id- in: path- required: true+ required: falseschema: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-tokenin: header- required: true+ required: falseschema:type: string- - name: fields- in: query+ - name: Idempotency-Key+ in: headerrequired: false- description: Comma-separated list of fields to include (e.g., name,slug,price).- id is always included.schema:type: stringresponses:'200':- description: currencies found+ description: checkout completedcontent: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+ email: [email protected]+ 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 completecontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: order_already_completed+ message: No payment foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/customer/orders":+ "/api/v3/store/countries":get:- summary: List customer orders+ summary: List countriestags:- - Customers+ - Internationalizationsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: fieldsin: queryrequired: false@@ -2746,188 +2654,49 @@ paths:type: stringresponses:'200':- description: orders found+ description: countries foundcontent:application/json:example:data:- - id: or_UkLWZg9DAJ- number: R939843740- state: cart- checkout_steps:- - address- - delivery- - payment- - complete- token: XVdvFACWeHB6yfr5H7rqVg8B2GLtNEmiUZT- email: [email protected]- 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: trueschema:type: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/Order"- meta:- "$ref": "#/components/schemas/PaginationMeta"+ "$ref": "#/components/schemas/Country"+ required:+ - data'401':- description: unauthorized - authentication required+ description: unauthorizedcontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/customers":- post:- summary: Register a new customer+ "/api/v3/store/countries/{iso}":+ get:+ summary: Get a countrytags:- - Customers+ - Internationalizationsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- responses:- '201':- description: registration successful- content:- application/json:- example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFiNjcyN2RlLTE4ZmYtNDA4Ny05YTBiLWRkYWM4MWQ1MGVmYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMjQzOTUzfQ.tyQZduHlN6j52kHMKfD6S1fBqonkEtcUgUfIwBBXgas- user:- id: cus_UkLWZg9DAJ- email: [email protected]- 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: trueschema:- "$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 foundcontent: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 foundschema:"$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- email:- type: string- format: email- example: [email protected]- 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:- - password- "/api/v3/store/customer":- get:- summary: Get current customer profile+ "/api/v3/store/cart/coupon_codes":+ post:+ summary: Apply coupon codetags:- - Customers+ - Cartsecurity:- 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: javascriptlabel: 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: Authorizationin: header- required: true- description: Bearer JWT token+ required: false+ description: Bearer token for authenticated customersschema:type: string- - name: fields- in: query+ - name: x-spree-token+ in: headerrequired: 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: stringresponses:- '200':- description: profile found+ '201':+ description: coupon code applied (gift card)content:application/json:example:- id: cus_UkLWZg9DAJ- email: [email protected]- 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+ email: [email protected]+ 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_EfhxLZ9ck8firstname: Johnlastname: Doefull_name: John Doe- address1: 106 Lovely Street+ address1: 95 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -3127,16 +2964,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_117- state_abbr: STATE_ABBR_117+ state_text: STATE_ABBR_106+ state_abbr: STATE_ABBR_106quick_checkout: false- state_name: STATE_NAME_117- default_shipping_address:- id: addr_UkLWZg9DAJ+ state_name: STATE_NAME_106+ ship_address:+ id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 105 Lovely Street+ address1: 96 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -3144,30 +2981,50 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_116- state_abbr: STATE_ABBR_116+ state_text: STATE_ABBR_107+ state_abbr: STATE_ABBR_107quick_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: falseschema:- "$ref": "#/components/schemas/Customer"- '401':- description: unauthorized - invalid token+ "$ref": "#/components/schemas/Cart"+ '422':+ description: invalid coupon codecontent: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 codetags:- - Customers+ - Cartsecurity:- 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: javascriptlabel: 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: Authorizationin: header+ required: false+ description: Bearer token for authenticated customers+ schema:+ type: string+ - name: id+ in: pathrequired: 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 accessschema:type: stringresponses:'200':- description: profile updated+ description: coupon code removedcontent:application/json:example:- id: cus_UkLWZg9DAJ- email: [email protected]- 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+ email: [email protected]+ 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_EfhxLZ9ck8firstname: Johnlastname: Doefull_name: John Doe- address1: 108 Lovely Street+ address1: 103 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -3257,133 +3184,49 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_119- state_abbr: STATE_ABBR_119+ state_text: STATE_ABBR_114+ state_abbr: STATE_ABBR_114quick_checkout: false- state_name: STATE_NAME_119- default_shipping_address:- id: addr_UkLWZg9DAJ+ state_name: STATE_NAME_114+ ship_address:+ id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 107 Lovely Street+ address1: 104 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'phone: 555-555-0199company: 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- example: [email protected]- 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 cartcontent: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 cardstags:- Customerssecurity:- api_key: []bearer_auth: []- description: Returns all gift cards for the authenticated customer+ description: Returns all saved credit cards for the authenticated customerx-codeSamples:- lang: javascriptlabel: 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: stringresponses:'200':- description: gift cards found+ description: credit cards foundcontent: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: 1limit: 25@@ -3466,7 +3300,7 @@ paths:data:type: arrayitems:- "$ref": "#/components/schemas/GiftCard"+ "$ref": "#/components/schemas/CreditCard"meta:"$ref": "#/components/schemas/PaginationMeta"'401':@@ -3479,15 +3313,15 @@ paths:message: Authentication requiredschema:"$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 cardtags:- Customerssecurity:- api_key: []bearer_auth: []- description: Returns a gift card by its ID+ description: Returns a saved credit card by its IDx-codeSamples:- lang: javascriptlabel: 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: stringresponses:'200':- description: gift card found+ description: credit card foundcontent: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 foundcontent:application/json:example:error:code: record_not_found- message: Gift card not found+ message: Credit card not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{order_id}/line_items":- post:- summary: Add item to cart+ delete:+ summary: Delete a credit cardtags:- - Cart+ - Customerssecurity:- 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 accountx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header- required: false- description: Bearer token for authenticated customers+ required: trueschema:type: string- - name: order_id+ - name: idin: pathrequired: true- description: Order ID or numberschema: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-keyin: header+ required: true+ schema:+ type: string+ - name: fields+ in: queryrequired: 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-keyin: 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: trueschema:type: stringresponses:- '201':- description: item added with metadata+ '200':+ description: orders listedcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R153037447- state: cart- checkout_steps:- - address- - delivery- - payment- - complete- token: do8ruoWJqGJMxXMHGeGiE2LoEYXu8eZa7e6- email: [email protected]- 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+ email: [email protected]+ 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: unauthorizedcontent:application/json:example:error:- code: order_not_found- message: Order not found+ code: authentication_required+ message: Authentication requiredschema:"$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 ordertags:- - Cart+ - Customersecurity:- 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: javascriptlabel: 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: Authorizationin: header- required: false- schema:- type: string- - name: order_id- in: pathrequired: trueschema:type: string- name: idin: pathrequired: true- description: Line item ID- schema:- type: string- - name: x-spree-order-token- in: header- required: false+ description: Order prefixed IDschema:type: stringresponses:'200':- description: metadata updated on line item+ description: order foundcontent:application/json:example:id: or_UkLWZg9DAJ- number: R599053352- state: cart- checkout_steps:- - address- - delivery- - complete- token: ELfSXoFpKiCeBLWD1Uuy9TYUgSfJnEkR7GN- email: [email protected]+ number: R094723322+ email: [email protected]special_instructions:currency: USDlocale: en- item_count: 0- state_lock_version: 1+ item_count: 1shipment_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 397255- slug: product-397255+ name: Product 341755+ slug: product-341755options_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_GROUNDpayments: []bill_address:id: addr_EfhxLZ9ck8firstname: Johnlastname: Doefull_name: John Doe- address1: 148 Lovely Street+ address1: 129 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -3918,38 +3850,49 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_159- state_abbr: STATE_ABBR_159+ state_text: STATE_ABBR_140+ state_abbr: STATE_ABBR_140quick_checkout: false- state_name: STATE_NAME_159+ state_name: STATE_NAME_140ship_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_141schema:"$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 customertags:- - Cart+ - Customerssecurity:- api_key: []- bearer_auth: []- description: Removes a line item from the order+ description: Creates a new customer account and returns a JWT tokenx-codeSamples:- lang: javascriptlabel: 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: trueschema: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: stringresponses:- '200':- description: line item removed, returns updated order+ '201':+ description: registration successfulcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R705024898- state: cart- checkout_steps:- - address- - delivery- - complete- token: 4vfbWYeTWTeRjhtnr62wgGGtbfZFq88rJxF- email: [email protected]- 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+ email: [email protected]+ 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 takencontent: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 takenschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/locales":+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ email:+ type: string+ format: email+ example: [email protected]+ 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:+ - password+ "/api/v3/store/customer":get:- summary: List supported locales+ summary: Get current customer profiletags:- - Internationalization+ - Customerssecurity:- api_key: []- description: Returns locales supported by the store (derived from markets)+ bearer_auth: []+ description: Returns the profile of the currently authenticated customerx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer JWT token+ schema:+ type: string- name: fieldsin: queryrequired: false@@ -4101,43 +4034,105 @@ paths:type: stringresponses:'200':- description: locales found+ description: profile foundcontent:application/json:example:- data:- - code: de- name: de- - code: en- name: English (US)+ id: cus_UkLWZg9DAJ+ email: [email protected]+ 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_146schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Locale"- required:- - data+ "$ref": "#/components/schemas/Customer"'401':- description: unauthorized+ description: unauthorized - invalid tokencontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/markets":- get:- summary: List markets+ patch:+ summary: Update current customer profiletags:- - Markets+ - Customerssecurity:- 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 customerx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema: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: trueschema:type: stringresponses:'200':- description: markets found+ description: profile updatedcontent: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+ email: [email protected]+ 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_148schema:- type: object- properties:- data:- type: array- required:- - data- '401':- description: unauthorized+ "$ref": "#/components/schemas/Customer"+ '422':+ description: validation errorcontent: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 blankschema:"$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+ example: [email protected]+ 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 producttags:- - 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 tokenschema:type: stringresponses:'200':- description: market found+ description: file downloaded+ content:+ application/json: {}+ '403':+ description: download link expired or limit exceededcontent: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 invalidschema:- type: object+ "$ref": "#/components/schemas/ErrorResponse"+ application/octet-stream:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"'404':- description: market not found+ description: digital link not foundcontent: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 foundschema:"$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 cardstags:- - Markets+ - Customerssecurity:- 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 customerx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: country- in: query+ - name: Authorization+ in: headerrequired: 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: fieldsin: queryrequired: false@@ -4347,52 +4393,66 @@ paths:type: stringresponses:'200':- description: market resolved+ description: gift cards foundcontent: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: unauthorizedcontent:application/json:example:error:- code: record_not_found- message: Country not found+ code: authentication_required+ message: Authentication requiredschema:"$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 cardtags:- - Markets+ - Customerssecurity:- 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 IDx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: market_id+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: idin: pathrequired: true- description: Market prefixed IDschema:type: string- name: fields@@ -4426,37 +4492,49 @@ paths:type: stringresponses:'200':- description: countries found+ description: gift card foundcontent: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 carttags:- - Markets+ - Cartsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: market_id- in: path- required: true- description: Market prefixed ID+ - name: Authorization+ in: header+ required: false+ description: Bearer token for authenticated customersschema: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 accessschema:type: string- - name: fields- in: query+ - name: Idempotency-Key+ in: headerrequired: 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: stringresponses:- '200':- description: country found+ '201':+ description: item added with metadatacontent: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+ email: [email protected]+ 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 foundcontent:application/json:example:error:- code: record_not_found- message: Country not found+ code: variant_not_found+ message: Variant not foundschema:"$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 quantitytags:- - Orders+ - Cartsecurity:- 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 cartx-codeSamples:- lang: javascriptlabel: 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: idin: pathrequired: true- description: Order ID (prefixed) or order number+ description: Line item IDschema:type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: 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: stringresponses:'200':- description: order found (guest with token)+ description: metadata updated on line itemcontent:application/json:example:- id: or_gbHJdmfrXB- number: R940809780+ id: cart_UkLWZg9DAJ+ number: R467731208state: cartcheckout_steps:- address- delivery- - payment- complete- token: VKHJYstcpDPxeEnBaMYwSvSiM3nXWPojae9- email:+ token: XmefX8ayavKS3bKQeYx57guiYpJMBRcHoXM+ email: [email protected]special_instructions:currency: USDlocale: 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_UkLWZg9DAJquantity: 1currency: USD- name: Product 443663- slug: product-443663+ name: Product 487545+ slug: product-487545options_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_EfhxLZ9ck8firstname: Johnlastname: Doefull_name: John Doe- address1: 163 Lovely Street+ address1: 175 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -4703,49 +4864,38 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_174- state_abbr: STATE_ABBR_174+ state_text: STATE_ABBR_186+ state_abbr: STATE_ABBR_186quick_checkout: false- state_name: STATE_NAME_174+ state_name: STATE_NAME_186ship_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_175payment_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 carttags:- - Checkout+ - Cartsecurity:- api_key: []bearer_auth: []- description: Updates order attributes like email, special instructions, or addresses+ description: Removes a line item from the cartx-codeSamples:- lang: javascriptlabel: 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: trueschema:type: string- - name: x-spree-order-token- in: header- required: false- schema:- type: string- - name: Idempotency-Key+ - name: x-spree-tokenin: headerrequired: false- description: Unique key for request idempotency. Duplicate requests with the- same key return the cached response.schema:type: stringresponses:'200':- description: order updated with metadata+ description: line item removed, returns updated cartcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R463665774+ id: cart_UkLWZg9DAJ+ number: R770244240state: cartcheckout_steps:- address- delivery- - payment- complete- token: StutsTbAPhZaKLCy3UbnxWejcoK1gaQzXw8- email: [email protected]+ token: 2wDhy4RHwbhhSD3voBxYTt5x8VmEtrDTweh+ email: [email protected]special_instructions:currency: USDlocale: en- item_count: 1+ item_count: 0state_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_EfhxLZ9ck8firstname: Johnlastname: Doefull_name: John Doe- address1: 184 Lovely Street+ address1: 178 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -4927,157 +4986,190 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_195- state_abbr: STATE_ABBR_195+ state_text: STATE_ABBR_189+ state_abbr: STATE_ABBR_189quick_checkout: false- state_name: STATE_NAME_195+ state_name: STATE_NAME_189ship_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_196payment_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: unauthorizedcontent:application/json:example:error:- code: access_denied- message: You are not authorized to access this page.+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- 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:- - variant_id- "/api/v3/store/orders/{id}/next":- patch:- summary: Advance to next checkout step+ "/api/v3/store/markets/{id}":+ get:+ summary: Get a markettags:- - Checkout+ - Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: false- schema:- type: string- name: idin: pathrequired: 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: queryrequired: 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: stringresponses:'200':- description: order advanced+ description: market foundcontent:application/json:example:- id: or_gbHJdmfrXB- number: R872065977- state: address- checkout_steps:- - address- - delivery- - payment- - complete- token: DMW6AkxApqY2i3C5y1ExYVgX3yk2EDUNdvD- email: [email protected]- 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: trueschema:- "$ref": "#/components/schemas/Order"- '422':- description: cannot advance - validation errors+ type: object+ '404':+ description: market not foundcontent: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 countrytags:- - Checkout+ - Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: queryrequired: 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: headerrequired: trueschema:type: string- - name: x-spree-order-token- in: header- required: false+ - name: market_id+ in: path+ required: true+ description: Market prefixed IDschema:type: string- - name: Idempotency-Key- in: header+ - name: fields+ in: queryrequired: 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: stringresponses:'200':- description: order advanced+ description: countries foundcontent:application/json:example:- id: or_gbHJdmfrXB- number: R076286330- state: payment- checkout_steps:- - address- - delivery- - payment- - complete- token: haEJssNxc12QAR3dRYeS7ZHdqfwXArRd4e6- email: [email protected]- 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: trueschema:- "$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 ordertags:- - Checkout+ - Orderssecurity:- 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: javascriptlabel: 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: Authorizationin: headerrequired: false+ description: Bearer token for authenticated customersschema:type: string- name: idin: pathrequired: true+ description: Order prefixed IDschema:type: string- - name: x-spree-order-token- in: header- required: false- schema:- type: string- - name: Idempotency-Key+ - name: x-spree-tokenin: headerrequired: false- description: Unique key for request idempotency. Duplicate requests with the- same key return the cached response.+ description: Order token for guest accessschema:type: stringresponses:'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- email: [email protected]+ id: or_UkLWZg9DAJ+ number: R286057069+ email: [email protected]special_instructions:currency: USDlocale: enitem_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_UkLWZg9DAJquantity: 1currency: USD- name: Product 591606- slug: product-591606+ name: Product 526850+ slug: product-526850options_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: H90765027023state: pending- tracking:+ tracking: U10000tracking_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_UkLWZg9DAJname: UPS Groundcode: UPS_GROUNDstock_location:id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_219- name: Candie Toy+ state_abbr: STATE_ABBR_197+ name: Toni Hesseladdress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'country_iso: UScountry_name: United States of America- state_text: STATE_ABBR_219+ state_text: STATE_ABBR_197shipping_rates:- - id: shpr_EfhxLZ9ck8+ - id: shpr_gbHJdmfrXBshipping_method_id: shpm_UkLWZg9DAJname: UPS Groundselected: true@@ -5649,49 +5605,13 @@ paths:id: shpm_UkLWZg9DAJname: UPS Groundcode: 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_UkLWZg9DAJfirstname: Johnlastname: Doefull_name: John Doe- address1: 212 Lovely Street+ address1: 186 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -5699,16 +5619,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_223- state_abbr: STATE_ABBR_223+ state_text: STATE_ABBR_197+ state_abbr: STATE_ABBR_197quick_checkout: false- state_name: STATE_NAME_223+ state_name: STATE_NAME_197ship_address:- id: addr_OIJLhNcSbf+ id: addr_gbHJdmfrXBfirstname: Johnlastname: Doefull_name: John Doe- address1: 213 Lovely Street+ address1: 187 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -5716,34 +5636,25 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_224- state_abbr: STATE_ABBR_224+ state_text: STATE_ABBR_198+ state_abbr: STATE_ABBR_198quick_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_198schema:"$ref": "#/components/schemas/Order"- '422':- description: cannot complete+ '404':+ description: incomplete order not accessiblecontent: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 methodstags:@@ -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: javascriptlabel: 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: Authorizationin: headerrequired: false+ description: Bearer token for authenticated customersschema:type: string- - name: order_id- in: path- required: true- schema:- type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: false+ description: Order token for guest accessschema:type: stringresponses:@@ -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 sessiontags:@@ -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. StripePaymentIntent, 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 customersschema: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-tokenin: headerrequired: falsedescription: Order token for guest access@@ -5888,8 +5770,7 @@ paths:- name: Idempotency-Keyin: headerrequired: 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: stringresponses:@@ -5901,13 +5782,13 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_c3f5b9f7bac3e180e6ca9e52+ external_id: bogus_939206b9e39cf38a11c26a57external_data:- client_secret: bogus_secret_7a9472fcff4f3952+ client_secret: bogus_secret_f4c6242151dd9228customer_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_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -5919,16 +5800,6 @@ paths:session_required: trueschema:"$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 gatewayrequired:- payment_method_id- "/api/v3/store/orders/{order_id}/payment_sessions/{id}":+ "/api/v3/store/checkout/payment_sessions/{id}":parameters:- name: x-spree-api-keyin: header@@ -5962,19 +5833,13 @@ paths:description: Bearer token for authenticated customersschema:type: string- - name: order_id- in: path- required: true- description: Order ID or number- schema:- type: string- name: idin: pathrequired: truedescription: Payment session IDschema:type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: falsedescription: 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_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_336d5c5b9c794137ab1abedc+ external_id: bogus_bc82c2673de64ed729f48e41external_data:client_secret: secret_123customer_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_UkLWZg9DAJorder_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_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_7852464e9e675ece9c58a135+ external_id: bogus_f316a00803e0c9e1401ae1c3external_data:client_secret: secret_123customer_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_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -6106,7 +5971,7 @@ paths:external_data:type: objectdescription: 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-keyin: header@@ -6119,19 +5984,13 @@ paths:description: Bearer token for authenticated customersschema:type: string- - name: order_id- in: path- required: true- description: Order ID or number- schema:- type: string- name: idin: pathrequired: truedescription: Payment session IDschema:type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: falsedescription: 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-Keyin: headerrequired: 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: stringresponses:@@ -6179,13 +6037,13 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_4549bc3eab40446299163180+ external_id: bogus_62e29b242af47209c88c5c5fexternal_data:client_secret: secret_123customer_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_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -6265,11 +6123,11 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_3d2fa5f1f03bda163c29a912- external_client_secret: bogus_seti_secret_74ba16f4d510ce3e+ external_id: bogus_seti_01a4dd0b5363cfafaa72ac6e+ external_client_secret: bogus_seti_secret_16408d9c954c43f8external_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_UkLWZg9DAJpayment_source_id:payment_source_type:@@ -6366,12 +6224,12 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_bcc8c5aa477a9c34899e35b1- external_client_secret: seti_secret_ffcead150899cf16e5b4301a+ external_id: seti_test_a011106e2f58cb1c542cb4d1+ external_client_secret: seti_secret_0b2f92f40bd0afbbf7044da3external_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_UkLWZg9DAJpayment_source_id:payment_source_type:@@ -6444,12 +6302,12 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_5d5f199c34c93bcb73eb3431- external_client_secret: seti_secret_b3c37c1c53c57b970fcb8818+ external_id: seti_test_66940b447b5069ab23b8d9fe+ external_client_secret: seti_secret_ed8707996cca86b59bc6b1e7external_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_UkLWZg9DAJpayment_source_id: card_UkLWZg9DAJpayment_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 paymentstags:@@ -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: javascriptlabel: 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: stringresponses:'200':- description: payments found+ description: payments listedcontent:application/json:example:@@ -6532,11 +6389,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: PZB8DYTD+ number: PJP8HO3Uamount: '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_cardsource_id: card_UkLWZg9DAJsource:@@ -6550,30 +6407,20 @@ paths:gateway_payment_profile_id:payment_method:id: pm_UkLWZg9DAJ- name: Credit Card+ name: Checkdescription:- 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 paymenttags:@@ -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-tokenin: headerrequired: falsedescription: 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_UkLWZg9DAJstate: checkoutresponse_code:- number: P5W30ZLT+ number: PL969YAGamount: '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_UkLWZg9DAJname: Checkdescription: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 paymentrequired:- 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 648748description: |-- 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-648748meta_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: truein_stock: falsebackorderable: true@@ -6910,18 +6665,18 @@ paths:price_list_id:original_price:- id: prod_gbHJdmfrXB- name: Product 802302+ name: Product 654485description: |-- 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-654485meta_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: truein_stock: falsebackorderable: true@@ -7027,19 +6782,18 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 916887+ name: Product 767469description: |-- 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-767469meta_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: truein_stock: falsebackorderable: true@@ -7186,148 +6940,46 @@ paths:type: stringdescription: Default sort option IDtotal_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 keycontent:application/json:example:error:- code: order_not_found- message: Order not found+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{order_id}/shipments/{id}":+ "/api/v3/store/checkout/shipments":get:- summary: Get a shipment+ summary: List shipmentstags:- Checkoutsecurity:- 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-keyin: header@@ -7339,83 +6991,57 @@ paths:required: falseschema: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-tokenin: headerrequired: falsedescription: Order token for guest accessschema:type: string- - name: expand- in: query- required: false- description: Expand shipping_rates- schema:- type: stringresponses:'200':- description: shipment found+ description: shipments foundcontent: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_UkLWZg9DAJname: UPS Groundcode: 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 shipmenttags:@@ -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: javascriptlabel: 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: falseschema:type: string- - name: order_id- in: path- required: true- schema:- type: string- name: idin: pathrequired: truedescription: Shipment IDschema:type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: falsedescription: Order token for guest access@@ -7470,27 +7092,25 @@ paths:type: stringresponses:'200':- description: shipping rate selected, returns updated order+ description: shipping rate selected, returns updated cartcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R113462108+ id: cart_UkLWZg9DAJ+ number: R486934809state: deliverycheckout_steps:- address- delivery- payment- complete- token: oH5zJdWjEiE1WzuMXb3kSFhynrUmjUHWE3g- email: [email protected]+ token: cFrQenShmVNV7uTV2ETsHJQGn1PWq1wbvt6+ email: [email protected]special_instructions:currency: USDlocale: enitem_count: 1state_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1233123- slug: product-1233123+ name: Product 105702+ slug: product-105702options_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: H42723789632state: pendingtracking: U10000tracking_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_UkLWZg9DAJname: UPS Groundcode: UPS_GROUNDstock_location:id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_333- name: Mechelle Ledner+ state_abbr: STATE_ABBR_273+ name: Lizeth Bashirianaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'country_iso: UScountry_name: United States of America- state_text: STATE_ABBR_333+ state_text: STATE_ABBR_273shipping_rates:- id: shpr_UkLWZg9DAJshipping_method_id: shpm_UkLWZg9DAJ@@ -7584,7 +7203,7 @@ paths:firstname: Johnlastname: Doefull_name: John Doe- address1: 314 Lovely Street+ address1: 254 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -7592,16 +7211,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_335- state_abbr: STATE_ABBR_335+ state_text: STATE_ABBR_275+ state_abbr: STATE_ABBR_275quick_checkout: false- state_name: STATE_NAME_335+ state_name: STATE_NAME_275ship_address:id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 315 Lovely Street+ address1: 255 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -7609,13 +7228,13 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_336- state_abbr: STATE_ABBR_336+ state_text: STATE_ABBR_276+ state_abbr: STATE_ABBR_276quick_checkout: false- state_name: STATE_NAME_336+ state_name: STATE_NAME_276payment_methods: []schema:- "$ref": "#/components/schemas/Order"+ "$ref": "#/components/schemas/Cart"'404':description: shipping rate not foundcontent:@@ -7635,19 +7254,19 @@ paths:properties:selected_shipping_rate_id:type: string- example: shprt_abc123+ example: shpr_abc123description: Shipping rate ID to selectrequired:- 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 credittags:- Checkoutsecurity:- api_key: []bearer_auth: []- description: Applies store credit to the order+ description: Applies store credit to the current cart during checkout.x-codeSamples:- lang: javascriptlabel: 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: trueschema:type: string- - name: order_id- in: path- required: true- schema:- type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: falseschema:@@ -7686,8 +7300,7 @@ paths:- name: Idempotency-Keyin: headerrequired: 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: stringresponses:@@ -7696,23 +7309,21 @@ paths:content:application/json:example:- id: or_UkLWZg9DAJ- number: R418869961+ id: cart_UkLWZg9DAJ+ number: R769411673state: cartcheckout_steps:- address- delivery- payment- complete- token: MeADhwL96G5Zsy36KqthCP1mE9GawvfuuXw- email: [email protected]+ token: 6kgCjWuw9VxQ4SuvK3KaBi3L5fF5sxoAiud+ email: [email protected]special_instructions:currency: USDlocale: enitem_count: 1state_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1254911- slug: product-1254911+ name: Product 1072748+ slug: product-1072748options_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: H32477969001state: pendingtracking: U10000tracking_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_UkLWZg9DAJname: UPS Groundcode: UPS_GROUNDstock_location:id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_341- name: Kimberlee Dach+ state_abbr: STATE_ABBR_281+ name: Mendy Kossaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'country_iso: UScountry_name: United States of America- state_text: STATE_ABBR_341+ state_text: STATE_ABBR_281shipping_rates:- id: shpr_UkLWZg9DAJshipping_method_id: shpm_UkLWZg9DAJ@@ -7804,12 +7414,12 @@ paths:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJstate: checkout- response_code: 1-SC-20260311144635483353- number: PGMMUC9Z+ response_code: 1-SC-20260311201657780014+ number: PNEWMSZ6amount: '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_creditsource_id: credit_UkLWZg9DAJsource:@@ -7832,7 +7442,7 @@ paths:firstname: Johnlastname: Doefull_name: John Doe- address1: 322 Lovely Street+ address1: 262 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -7840,16 +7450,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_343- state_abbr: STATE_ABBR_343+ state_text: STATE_ABBR_283+ state_abbr: STATE_ABBR_283quick_checkout: false- state_name: STATE_NAME_343+ state_name: STATE_NAME_283ship_address:id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 323 Lovely Street+ address1: 263 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -7857,10 +7467,10 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_344- state_abbr: STATE_ABBR_344+ state_text: STATE_ABBR_284+ state_abbr: STATE_ABBR_284quick_checkout: false- state_name: STATE_NAME_344+ state_name: STATE_NAME_284payment_methods:- id: pm_UkLWZg9DAJname: Store Credit@@ -7868,7 +7478,7 @@ paths:type: Spree::PaymentMethod::StoreCreditsession_required: falseschema:- "$ref": "#/components/schemas/Order"+ "$ref": "#/components/schemas/Cart"'422':description: no store credit availablecontent:@@ -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: javascriptlabel: 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: trueschema:type: string- - name: order_id- in: path- required: true- schema:- type: string- - name: x-spree-order-token+ - name: x-spree-tokenin: headerrequired: falseschema:@@ -7938,23 +7543,21 @@ paths:content:application/json:example:- id: or_UkLWZg9DAJ- number: R176406903+ id: cart_UkLWZg9DAJ+ number: R023223592state: cartcheckout_steps:- address- delivery- payment- complete- token: o6HCgycDeUUk4qM1xsQcHX3XBynYmZ2eRLC- email: [email protected]+ token: G1Sdq5jhpBeq29pYqvnq3Jcd1mxJ7fseXb8+ email: [email protected]special_instructions:currency: USDlocale: enitem_count: 1state_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_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 127583- slug: product-127583+ name: Product 1096204+ slug: product-1096204options_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: H82284414826state: pendingtracking: U10000tracking_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_UkLWZg9DAJname: UPS Groundcode: UPS_GROUNDstock_location:id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_349- name: Melaine Beier+ state_abbr: STATE_ABBR_289+ name: Marcelene Smithamaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'country_iso: UScountry_name: United States of America- state_text: STATE_ABBR_349+ state_text: STATE_ABBR_289shipping_rates:- id: shpr_UkLWZg9DAJshipping_method_id: shpm_UkLWZg9DAJ@@ -8048,7 +7650,7 @@ paths:firstname: Johnlastname: Doefull_name: John Doe- address1: 330 Lovely Street+ address1: 270 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -8056,16 +7658,16 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_351- state_abbr: STATE_ABBR_351+ state_text: STATE_ABBR_291+ state_abbr: STATE_ABBR_291quick_checkout: false- state_name: STATE_NAME_351+ state_name: STATE_NAME_291ship_address:id: addr_VqXmZF31wYfirstname: Johnlastname: Doefull_name: John Doe- address1: 331 Lovely Street+ address1: 271 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -8073,13 +7675,13 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_352- state_abbr: STATE_ABBR_352+ state_text: STATE_ABBR_292+ state_abbr: STATE_ABBR_292quick_checkout: false- state_name: STATE_NAME_352+ state_name: STATE_NAME_292payment_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_UkLWZg9DAJname: 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: falseis_private: truemeta:@@ -8218,9 +7820,9 @@ paths:example:id: wl_gbHJdmfrXBname: 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: falseis_private: trueschema:@@ -8316,9 +7918,9 @@ paths:example:id: wl_UkLWZg9DAJname: 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: falseis_private: trueschema:@@ -8380,9 +7982,9 @@ paths:example:id: wl_UkLWZg9DAJname: 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: falseis_private: trueschema:@@ -8494,18 +8096,18 @@ paths:variant_id: variant_gbHJdmfrXBwishlist_id: wl_UkLWZg9DAJquantity: 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_gbHJdmfrXBproduct_id: prod_gbHJdmfrXB- sku: SKU-149+ sku: SKU-130is_master: trueoptions_text: ''track_inventory: trueimage_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: truein_stock: false@@ -8859,6 +8461,138 @@ components:required:- idx-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+ - 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: trueCategory:type: objectproperties:@@ -9720,17 +9454,8 @@ components:type: stringnumber:type: string- state:- type: string- checkout_steps:- type: array- items:- type: string- token:- type: stringemail:type: string- nullable: truespecial_instructions:type: stringnullable: true@@ -9741,8 +9466,6 @@ components:nullable: trueitem_count:type: number- state_lock_version:- type: numbershipment_state:type: stringnullable: 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- 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_methodsx-typelizer: truePaymentMethod:type: objectdiff --git a/docs/developer/sdk/authentication.mdx b/docs/developer/sdk/authentication.mdxindex 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({email: '[email protected]',}, 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.mdxindex 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 cartconst 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({email: '[email protected]',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.mdxindex 2842ad24b8..a1a0267273 100644--- a/docs/developer/sdk/store/payments.mdx+++ b/docs/developer/sdk/store/payments.mdx@@ -3,13 +3,15 @@ title: Payments & Shippingdescription: 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 creditsmetadata: { // 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 totalexternal_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.mdxindex 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.```typescriptimport {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.+```typescriptimport {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 Sessionsdiff --git a/docs/snippets/store-api/auth-guest-cart.mdx b/docs/snippets/store-api/auth-guest-cart.mdxindex 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.tsindex 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.tsindex 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, PaymentMethodtype 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.tsindex 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.tsindex 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.mdindex 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 | nullasync function handleAddItem(formData: FormData) {'use server';@@ -127,23 +127,23 @@ Server actions handle mutations and auth-dependent reads. They automatically man```typescriptimport { 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); // Cartawait clearCart();```### Checkout+All checkout functions operate on the current cart implicitly (via the cart cookie).+```typescriptimport {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).+```typescriptimport { 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 creditsmetadata: { // 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).+```typescriptimport {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:```typescriptimport 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.tsindex 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-fataldiff --git a/packages/next/src/actions/cart.ts b/packages/next/src/actions/cart.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 convenienceexport 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.tsindex 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.tsindex 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.tsindex 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 = {email: '[email protected]',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.tsindex 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.tsindex 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 defaultsconst 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.mdindex 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 itemsconst 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:```typescriptclient.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) // Checkoutclient.customers.create(params) // Registrationclient.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 neededconst 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({email: '[email protected]',}, 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 creditsmetadata: { // 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 totalexternal_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```typescriptimport type {StoreProduct,+ StoreCart,StoreOrder,StoreVariant,StoreCategory,@@ -617,6 +656,7 @@ import type {// All responses are fully typedconst 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 parametersdiff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 } })+ ),+// Carthttp.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 > Addresseshttp.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 Cardshttp.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 Cardshttp.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 Sessionshttp.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.tsindex 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.tsindex 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,optsdiff --git a/packages/sdk/tests/payments.test.ts b/packages/sdk/tests/payments.test.tsindex 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.lockindex ae5b5b91cb..98772f5e07 100644--- a/server/Gemfile.lock+++ b/server/Gemfile.lock@@ -11,7 +11,7 @@ GITPATHremote: ../spree/adminspecs:- spree_admin (5.4.0.beta5)+ spree_admin (5.4.0.beta6)active_link_tobreadcrumbs_on_rails (~> 4.1)chartkick (~> 5.0)@@ -23,7 +23,7 @@ PATHmapkick-rb (~> 0.1)pagy (~> 43.0)ruby-oembed (~> 0.18)- spree (>= 5.4.0.beta5)+ spree (>= 5.4.0.beta6)stimulus-railstailwindcss-rails (>= 4.0)tailwindcss-ruby (>= 4.0)@@ -33,22 +33,22 @@ PATHPATHremote: ../spree/emailsspecs:- spree_emails (5.4.0.beta5)- spree (>= 5.4.0.beta5)+ spree_emails (5.4.0.beta6)+ spree (>= 5.4.0.beta6)PATHremote: ../spreespecs:- 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-onacts_as_list (>= 0.8)@@ -1122,12 +1122,12 @@ CHECKSUMSsimplecov-cobertura (3.1.0) sha256=6d7f38aa32c965ca2174b2e5bd88cb17138eaf629518854976ac50e628925dc5simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246simplecov_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=71725dafe45319a2be1bd2b564a416afe8029af8e18ac703bdb835e09553e1dfspree_i18n (5.3.2) sha256=03b805235ca156644951f6bc3d07cbe43d0aa01134c4a27e3f3304011956f79bspree_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.rbnew file mode 100644index 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+enddiff --git a/spree/api/app/controllers/concerns/spree/api/v3/order_concern.rb b/spree/api/app/controllers/concerns/spree/api/v3/order_concern.rbdeleted file mode 100644index 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-enddiff --git a/spree/api/app/controllers/concerns/spree/api/v3/order_lock.rb b/spree/api/app/controllers/concerns/spree/api/v3/order_lock.rbindex 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 Spreeprivatedef with_order_lock- order = @order || @parent+ order = @order || @parent || @cartorder.with_lock do# Persist increment within the transaction so reloads inside yield see the new versiondiff --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.rbnew file mode 100644index 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+enddiff --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.rbsimilarity index 64%rename from spree/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rbrename to spree/api/app/controllers/spree/api/v3/store/cart/items_controller.rbindex 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 Spreemodule Apimodule V3module Store- module Orders- class LineItemsController < ResourceController- include Spree::Api::V3::OrderConcern+ module Cart+ class ItemsController < Store::BaseController+ include Spree::Api::V3::CartResolvableinclude 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/itemsdef createwith_order_lock doresult = 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)elserender_service_error(result.error, code: ERROR_CODES[:insufficient_stock])endendend- # PATCH /api/v3/store/orders/:order_id/line_items/:id+ # PATCH /api/v3/store/cart/items/:iddef updatewith_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_cartelserender_service_error(result.error, code: ERROR_CODES[:invalid_quantity])endelsif @line_item.changed?@line_item.save!- render_order+ render_cartelse- render_order+ render_cartendendend- # DELETE /api/v3/store/orders/:order_id/line_items/:id+ # DELETE /api/v3/store/cart/items/:iddef destroywith_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_cartendend- protected+ private- def parent_association- :line_items- enddef 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_paramsparams.permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])enddiff --git a/spree/api/app/controllers/spree/api/v3/store/cart_controller.rb b/spree/api/app/controllers/spree/api/v3/store/cart_controller.rbindex 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 Spreemodule V3module Storeclass CartController < Store::BaseController- include Spree::Api::V3::OrderConcern+ include Spree::Api::V3::CartResolvablebefore_action :require_authentication!, only: [:associate]@@ -22,7 +22,7 @@ module Spreeif result.success?@cart = result.value- render json: serialize_resource(@cart), status: :created+ render_cart(status: :created)elserender_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! neededdef 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)+ endend# PATCH /api/v3/store/cart/associate@@ -47,18 +62,12 @@ module Spreeresult = Spree.cart_associate_service.call(guest_order: @cart, user: current_user, guest_only: true)if result.success?- render json: serialize_resource(@cart)+ render_cartelserender_service_error(result.error.to_s)endend- protected-- def serializer_class- Spree.api.order_serializer- end-privatedef 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)endendenddiff --git a/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbsimilarity index 74%rename from spree/api/app/controllers/spree/api/v3/store/orders/payment_sessions_controller.rbrename to spree/api/app/controllers/spree/api/v3/store/checkout/payment_sessions_controller.rbindex 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 Spreemodule Apimodule V3module 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_sessionsdef createpayment_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 Spreeendend- # GET /api/v3/store/orders/:order_id/payment_sessions/:id+ # GET /api/v3/store/checkout/payment_sessions/:iddef showrender json: serialize_resource(@payment_session)end- # PATCH /api/v3/store/orders/:order_id/payment_sessions/:id+ # PATCH /api/v3/store/checkout/payment_sessions/:iddef update@payment_session.payment_method.update_payment_session(payment_session: @payment_session,@@ -47,7 +46,7 @@ module Spreeendend- # PATCH /api/v3/store/orders/:order_id/payment_sessions/:id/complete+ # PATCH /api/v3/store/checkout/payment_sessions/:id/completedef complete@payment_session.payment_method.complete_payment_session(payment_session: @payment_session,@@ -63,14 +62,6 @@ module Spreeprotected- def parent_association- :payment_sessions- end-- def model_class- Spree::PaymentSession- end-def serializer_classSpree.api.payment_session_serializerend@@ -86,7 +77,11 @@ module Spreeprivatedef 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_hendendenddiff --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.rbsimilarity index 61%rename from spree/api/app/controllers/spree/api/v3/store/orders/payments_controller.rbrename to spree/api/app/controllers/spree/api/v3/store/checkout/payments_controller.rbindex 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 Spreemodule Apimodule V3module 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 createpayment_method = current_store.payment_methods.find_by_prefix_id!(params[:payment_method_id])@@ -53,8 +35,6 @@ module Spreemetadata: params[:metadata].present? ? params[:metadata].to_unsafe_h : {})- authorize!(:update, @parent, order_token)-if @payment.saverender json: serialize_resource(@payment), status: :createdelse@@ -62,18 +42,27 @@ module Spreeendend- 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::Paymentenddef serializer_classSpree.api.payment_serializerend- 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!(*)endendenddiff --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.rbnew file mode 100644index 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+enddiff --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.rbsimilarity index 69%rename from spree/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rbrename to spree/api/app/controllers/spree/api/v3/store/checkout/store_credits_controller.rbindex 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 Spreemodule Apimodule V3module Store- module Orders+ module Checkoutclass StoreCreditsController < Store::BaseController- include Spree::Api::V3::OrderConcern+ include Spree::Api::V3::CartResolvableinclude Spree::Api::V3::OrderLockbefore_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_creditsdef createwith_order_lock doresult = Spree.checkout_add_store_credit_service.call(- order: @parent,+ order: @cart,amount: params[:amount].try(:to_f))if result.success?- render_order+ render_cartelserender_service_error(result.error)endendend- # DELETE /api/v3/store/orders/:order_id/store_credits+ # DELETE /api/v3/store/checkout/store_creditsdef destroywith_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_cartelserender_service_error(result.error)enddiff --git a/spree/api/app/controllers/spree/api/v3/store/checkout_controller.rb b/spree/api/app/controllers/spree/api/v3/store/checkout_controller.rbnew file mode 100644index 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+enddiff --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.rbindex 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 Spreeenddef scope- super.for_store(current_store)+ super.for_store(current_store).completeendendenddiff --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.rbdeleted file mode 100644index 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-enddiff --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.rbdeleted file mode 100644index 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-enddiff --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.rbdeleted file mode 100644index 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-enddiff --git a/spree/api/app/controllers/spree/api/v3/store/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders_controller.rbindex 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 Spreemodule Apimodule V3module 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_hend- # 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+ endenddef serializer_classSpree.api.order_serializerend- 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']endendenddiff --git a/spree/api/app/serializers/spree/api/v3/cart_serializer.rb b/spree/api/app/serializers/spree/api/v3/cart_serializer.rbnew file mode 100644index 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+enddiff --git a/spree/api/app/serializers/spree/api/v3/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/order_serializer.rbindex 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 Spreemodule Apimodule 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 Spreetotal: :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 Spreemany :payments, resource: Spree.api.payment_serializerone :bill_address, resource: Spree.api.address_serializerone :ship_address, resource: Spree.api.address_serializer-- many :payment_methods, resource: Spree.api.payment_method_serializerendendenddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 5acf84faa5..09fc0723f8 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -7,9 +7,6 @@ Spree::Core::Engine.add_routes dopost 'auth/refresh', to: 'auth#refresh'post 'auth/oauth/callback', to: 'auth#oauth_callback'- # Customer registration- resources :customers, only: [:create]-# Marketsresources :markets, only: [:index, :show] docollection do@@ -33,46 +30,46 @@ Spree::Core::Engine.add_routes doresources :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' dopatch :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' domember dopatch :completeendend- 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 resourcesnamespace :customer, path: 'customer' do+ resources :orders, only: [:index, :show]resources :addresses, only: [:index, :show, :create, :update, :destroy] domember dopatch :mark_as_defaultendend- resources :orders, only: [:index]resources :credit_cards, only: [:index, :show, :destroy]resources :gift_cards, only: [:index, :show]resources :payment_setup_sessions, only: [:create, :show] dodiff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 4886e0b67d..07e41156af 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -99,6 +99,7 @@ module Spreeimage_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.rbindex 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 doit 'does not apply to GET requests' docart = create(:order, store: store)- request.headers['x-spree-order-token'] = cart.token+ request.headers['x-spree-token'] = cart.tokenrequest.headers['Idempotency-Key'] = idempotency_keyget :showdiff --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.rbsimilarity index 61%rename from spree/api/spec/controllers/spree/api/v3/store/orders/coupon_codes_controller_spec.rbrename to spree/api/spec/controllers/spree/api/v3/store/cart/coupon_codes_controller_spec.rbindex 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 dorender_viewsinclude_context 'API v3 Store'@@ -10,7 +10,6 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :contbefore dorequest.headers['X-Spree-Api-Key'] = api_key.tokenrequest.headers['Authorization'] = "Bearer #{jwt_token}"- request.headers['x-spree-order-token'] = order.tokenenddescribe 'POST #create' do@@ -18,20 +17,20 @@ RSpec.describe Spree::Api::V3::Store::Orders::CouponCodesController, type: :contlet!(: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_')endit '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)endit '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: :contorder.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: :contlet!(: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_')endit '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: :contlet!(: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_')endit 'returns error for expired gift card' dogift_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: :contit 'returns error for redeemed gift card' dogift_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: :contendit '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)endend- 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' dolet(:guest_order) { create(:order_with_line_items, store: store, user: nil) }let!(:promotion) { create(:promotion_with_item_adjustment, code: 'GUEST10', stores: [store]) }before dorequest.headers['Authorization'] = nil- request.headers['x-spree-order-token'] = guest_order.token+ request.headers['x-spree-token'] = guest_order.tokenend- 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: :contendit '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)endend- 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)endendenddiff --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.rbnew file mode 100644index 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+enddiff --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.rbindex 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 doenddescribe 'GET #show' do- context 'with x-spree-order-token header' do+ context 'with x-spree-token header' dolet(: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' doget :show@@ -168,7 +168,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doendit 'returns not found for invalid token' do- request.headers['x-spree-order-token'] = 'invalid_token'+ request.headers['x-spree-token'] = 'invalid_token'get :showexpect(response).to have_http_status(:not_found)@@ -177,7 +177,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doit 'returns not found for completed order token' docompleted_order = create(:completed_order_with_totals, store: store)- request.headers['x-spree-order-token'] = completed_order.token+ request.headers['x-spree-token'] = completed_order.tokenget :showexpect(response).to have_http_status(:not_found)@@ -187,7 +187,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doit 'returns not found for other store cart' doother_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.tokenget :showexpect(response).to have_http_status(:not_found)@@ -244,7 +244,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doendcontext 'without authentication' do- it 'returns not found without order_token or JWT' do+ it 'returns not found without cart_token or JWT' doget :showexpect(response).to have_http_status(:not_found)@@ -266,7 +266,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller docontext 'response structure' dolet(: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' doget :show@@ -311,8 +311,8 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller dorequest.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.tokenpatch :associateexpect(response).to have_http_status(:ok)@@ -321,7 +321,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doendit 'updates cart email to users email' do- request.headers['x-spree-order-token'] = guest_cart.token+ request.headers['x-spree-token'] = guest_cart.tokenpatch :associateexpect(response).to have_http_status(:ok)@@ -333,7 +333,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doship = 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.tokenpatch :associateexpect(response).to have_http_status(:ok)@@ -345,7 +345,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doit 'allows re-associating cart already owned by current user' doguest_cart.update!(user: user)- request.headers['x-spree-order-token'] = guest_cart.token+ request.headers['x-spree-token'] = guest_cart.tokenpatch :associateexpect(response).to have_http_status(:ok)@@ -353,7 +353,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doendit 'returns not found for invalid token' do- request.headers['x-spree-order-token'] = 'invalid_token'+ request.headers['x-spree-token'] = 'invalid_token'patch :associateexpect(response).to have_http_status(:not_found)@@ -370,7 +370,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doit 'returns not found for completed order' docompleted_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.tokenpatch :associateexpect(response).to have_http_status(:not_found)@@ -381,7 +381,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doother_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.tokenpatch :associateexpect(response).to have_http_status(:not_found)@@ -393,7 +393,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller doother_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.tokenpatch :associateexpect(response).to have_http_status(:not_found)@@ -402,7 +402,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller docontext 'without JWT authentication' doit 'returns unauthorized' do- request.headers['x-spree-order-token'] = guest_cart.token+ request.headers['x-spree-token'] = guest_cart.tokenpatch :associateexpect(response).to have_http_status(:unauthorized)@@ -414,7 +414,7 @@ RSpec.describe Spree::Api::V3::Store::CartController, type: :controller dobefore { 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.tokenpatch :associateexpect(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.rbnew file mode 100644index 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+enddiff --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.rbsimilarity index 59%rename from spree/api/spec/controllers/spree/api/v3/store/orders/payment_sessions_controller_spec.rbrename to spree/api/spec/controllers/spree/api/v3/store/checkout/payment_sessions_controller_spec.rbindex 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 dorender_viewsinclude_context 'API v3 Store'@@ -22,10 +22,7 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentSessionsController, type: :describe 'POST #create' doit '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' dopost :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)' dolet(: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')endendcontext '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')endendenddescribe 'GET #show' doit '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' doit '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')endit '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')endendenddescribe 'PATCH #update' doit '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' doit '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.rbsimilarity index 60%rename from spree/api/spec/controllers/spree/api/v3/store/orders/payments_controller_spec.rbrename to spree/api/spec/controllers/spree/api/v3/store/checkout/payments_controller_spec.rbindex 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 dorender_viewsinclude_context 'API v3 Store'@@ -15,8 +15,8 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :controlenddescribe '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 :indexexpect(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: :controlendit 'includes payment method information' do- get :index, params: { order_id: order.to_param }+ get :indexexpect(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)' dolet(: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 :indexexpect(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 :indexexpect(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')endendenddescribe 'GET #show' doit '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: :controlcontext 'error handling' doit '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')endit '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')endendend@@ -104,17 +84,16 @@ RSpec.describe Spree::Api::V3::Store::Orders::PaymentsController, type: :controllet(: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_presentexpect(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)endit '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: :controlit 'creates a payment with metadata' dopost :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: :controlit 'rejects session-required payment methods' dobogus_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: :controlunavailable_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')endit '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)' dolet(: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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbindex 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: :controlinclude_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 dorequest.headers['X-Spree-Api-Key'] = api_key.token@@ -31,7 +31,7 @@ RSpec.describe Spree::Api::V3::Store::Customer::OrdersController, type: :controlit 'does not return orders from other stores' doother_store = create(:store)- create(:order_with_line_items, user: user, store: other_store)+ create(:completed_order_with_totals, user: user, store: other_store)get :indexdiff --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.rbdeleted file mode 100644index 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-enddiff --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.rbdeleted file mode 100644index 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-enddiff --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.rbdeleted file mode 100644index 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-enddiff --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.rbdeleted file mode 100644index 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-enddiff --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.rbindex 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 doenddescribe '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' dobefore do@@ -22,7 +22,6 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller doexpect(response).to have_http_status(:ok)expect(json_response['number']).to eq(order.number)- expect(json_response['state']).to eq(order.state)endit 'returns order with expected attributes' do@@ -33,11 +32,11 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller doendend- 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.tokenget :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 doendit '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')endit 'returns not found without token' doget :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')endend@@ -65,202 +62,25 @@ RSpec.describe Spree::Api::V3::Store::OrdersController, type: :controller dorequest.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_presentendit '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)endend-endenddiff --git a/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb b/spree/api/spec/integration/spree/api/v3/store/cart_spec.rbindex 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.yamproduces '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.DESCsdk_example <<~JS@@ -56,10 +56,11 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yamresponse '201', 'cart created (guest)' dolet(:'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_presentexpect(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.yamlet(:'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.yamlet(:'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.yamsecurity [api_key: [], bearer_auth: []]description <<~DESCReturns 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.DESCsdk_example <<~JS@@ -185,18 +186,19 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yamparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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)' dolet(: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.yamlet(:'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.yamendendend++ 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+ endendpath '/api/v3/store/cart/associate' do@@ -250,19 +277,20 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yamparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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' dolet(: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.yamlet(: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.yamlet(: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.yamresponse '404', 'cart not found' dolet(:'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.yamlet(: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.rbnew file mode 100644index 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+enddiff --git a/spree/api/spec/integration/spree/api/v3/store/checkout_spec.rb b/spree/api/spec/integration/spree/api/v3/store/checkout_spec.rbnew file mode 100644index 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++enddiff --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.rbindex 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' doinclude_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' dopost 'Apply coupon code' dotags '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.DESCsdk_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/sparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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/slet!(: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)endend@@ -60,10 +58,9 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/slet!(: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/sresponse '422', 'invalid coupon code' dolet(:'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/sexpect(data['error']).to be_presentendend-- 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!- endendend- path '/api/v3/store/orders/{order_id}/coupon_codes/{id}' do+ path '/api/v3/store/cart/coupon_codes/{id}' dodelete 'Remove coupon code' dotags '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/sparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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' dolet!(: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) doorder.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)endend- response '404', 'coupon code not found on order' do+ response '422', 'coupon code not found on cart' dolet(:'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.rbindex 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-referencinclude_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 <<~JSconst orders = await client.customer.orders.list({- page: 1,- limit: 25,- }, {bearerToken: '<token>',})JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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)endend- response '401', 'unauthorized - authentication required' do+ response '401', 'unauthorized' dolet(:'x-spree-api-key') { api_key.token }let(:'Authorization') { '' }@@ -63,4 +47,52 @@ RSpec.describe 'Customer Orders API', type: :request, swagger_doc: 'api-referencendendend++ 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+ endenddiff --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.rbindex 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' doinclude_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/stolet!(: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' dopost 'Add item to cart' dotags '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/stoparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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' dolet(: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/stolet(: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/storesponse '404', 'variant not found' dolet(:'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!- endendend- path '/api/v3/store/orders/{order_id}/line_items/{id}' do+ path '/api/v3/store/cart/items/{id}' dopatch 'Update line item quantity' dotags 'Cart'consumes 'application/json'@@ -110,7 +95,7 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/stodescription '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/stoparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: 'Authorization', in: :header, type: :string, required: false- parameter name: :order_id, in: :path, type: :string, required: trueparameter 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: falseparameter 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' dolet(:'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/storesponse '200', 'metadata updated on line item' dolet(:'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/stoexpect(line_item.reload.metadata).to include('engraving' => 'J.D.')endend-enddelete 'Remove line item from cart' dotags '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>',})JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: 'Authorization', in: :header, type: :string, required: false- parameter name: :order_id, in: :path, type: :string, required: trueparameter 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' dolet(:'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_emptydata = JSON.parse(response.body)+ expect(data['id']).to start_with('cart_')expect(data['number']).to eq(order.number)endend@@ -196,7 +177,6 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/storesponse '404', 'line item not found' dolet(:'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.rbindex 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.yinclude_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}' doget 'Get an order' dotags '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 <<~JSconst order = await client.orders.get('or_abc123', {- expand: 'line_items,shipments',- }, {bearerToken: '<token>',})JSparameter 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')endend- 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)endend- 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' dolet(:'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' dolet(: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.rbindex 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' doinclude_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' doget 'List available payment methods' dotags '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>',})JSparameter 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' dolet(:'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-referencexpect(data['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefixed_id)endend-- 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!- endendendenddiff --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.rbindex 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' doinclude_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) docreate(:bogus_payment_session,@@ -16,16 +15,16 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referenexternal_data: { 'client_secret' => 'secret_123' })end- path '/api/v3/store/orders/{order_id}/payment_sessions' do+ path '/api/v3/store/checkout/payment_sessions' dopost 'Create payment session' dotags '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-referenparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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-referenexpect(data['payment_method_id']).to eq(payment_method.prefixed_id)endend-- 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!- endendend- path '/api/v3/store/orders/{order_id}/payment_sessions/{id}' do+ path '/api/v3/store/checkout/payment_sessions/{id}' doparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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-referendescription '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-referendescription '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-referenendend- path '/api/v3/store/orders/{order_id}/payment_sessions/{id}/complete' do+ path '/api/v3/store/checkout/payment_sessions/{id}/complete' doparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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-referendescription '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' dolet(:'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.rbindex 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' doinclude_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' doget 'List payments' dotags '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')+ endlet(:'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)endend-- 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!- endendpost 'Create payment' do@@ -67,21 +51,23 @@ RSpec.describe 'Payments API', type: :request, swagger_doc: 'api-reference/storedescription '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/storeendresponse '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.rbindex 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' doinclude_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' dotags '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>',})JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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' dolet(:'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/storexpect(data['data'].size).to be >= 1endend-- 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!- endendend- 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}' dopatch 'Select shipping rate for shipment' dotags '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/storparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: 'Authorization', in: :header, type: :string, required: false- parameter name: :order_id, in: :path, type: :string, required: trueparameter 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' dolet(: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)endend@@ -147,10 +85,8 @@ RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/storresponse '404', 'shipping rate not found' dolet(:'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.rbindex 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' doinclude_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' dotags '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>',})JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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: falseparameter 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_creditend- 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' dolet(:'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>',})JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter 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: falseresponse '200', 'store credit removed' dolet(:'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!enddiff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rbindex 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` headerfor guest access to that specific order.## Response Formatdiff --git a/spree/core/app/models/concerns/spree/user_methods.rb b/spree/core/app/models/concerns/spree/user_methods.rbindex 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 Spreehas_many :promotion_rule_users, class_name: 'Spree::PromotionRuleUser', foreign_key: :user_id, dependent: :destroyhas_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: :destroyhas_many :wishlists, class_name: 'Spree::Wishlist', foreign_key: :user_id, dependent: :destroydiff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rbindex 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: :storehas_many :checkouts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :storehas_many :orders, class_name: 'Spree::Order'has_many :line_items, through: :orders, class_name: 'Spree::LineItem'