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
Added Addresses Mark as Default API (#13590)
Damian Legawiec909d52719da5
diff --git a/.github/workflows/spelling_lint.yml b/.github/workflows/spelling_lint.ymlindex 838a773c5c..dc50148e63 100644--- a/.github/workflows/spelling_lint.yml+++ b/.github/workflows/spelling_lint.yml@@ -31,4 +31,4 @@ jobs:- name: Installrun: wget -O - -q https://git.io/misspell | sh -s -- -b .- name: Misspell- run: git ls-files --empty-directory | grep -v "vendor/" | xargs ./misspell -i 'aircrafts,devels,invertions' -error+ run: git ls-files --empty-directory | grep -v "vendor/" | grep -v "docs/api-reference/store.yaml" | xargs ./misspell -i 'aircrafts,devels,invertions' -errordiff --git a/backend/engines/api/app/controllers/spree/api/v3/store/customer/addresses_controller.rb b/backend/engines/api/app/controllers/spree/api/v3/store/customer/addresses_controller.rbindex 3a7c783ba1..9c6d0de332 100644--- a/backend/engines/api/app/controllers/spree/api/v3/store/customer/addresses_controller.rb+++ b/backend/engines/api/app/controllers/spree/api/v3/store/customer/addresses_controller.rb@@ -5,6 +5,7 @@ module Spreemodule Customerclass AddressesController < ResourceControllerprepend_before_action :require_authentication!+ before_action :set_resource, only: [:show, :update, :destroy, :mark_as_default]# POST /api/v3/store/customer/addressesdef create@@ -20,6 +21,24 @@ module Spreeendend+ # PATCH /api/v3/store/customer/addresses/:id/mark_as_default+ def mark_as_default+ kind = params[:kind].to_s++ unless %w[billing shipping].include?(kind)+ return render_error(+ code: ERROR_CODES[:invalid_request],+ message: 'kind must be billing or shipping',+ status: :unprocessable_content+ )+ end++ attribute = kind == 'billing' ? :bill_address_id : :ship_address_id+ current_user.update!(attribute => @resource.id)++ render json: serialize_resource(@resource.reload)+ end+# PATCH /api/v3/store/customer/addresses/:iddef updateresult = Spree.address_update_service.call(diff --git a/backend/engines/api/config/routes.rb b/backend/engines/api/config/routes.rbindex 34415d0df0..5674c49b0e 100644--- a/backend/engines/api/config/routes.rb+++ b/backend/engines/api/config/routes.rb@@ -51,7 +51,11 @@ Spree::Core::Engine.add_routes donamespace :customer, path: 'customer' doget '/', to: 'account#show'patch '/', to: 'account#update'- resources :addresses, only: [:index, :show, :create, :update, :destroy]+ resources :addresses, only: [:index, :show, :create, :update, :destroy] do+ member do+ patch :mark_as_default+ end+ endresources :credit_cards, only: [:index, :show, :destroy]resources :gift_cards, only: [:index, :show]enddiff --git a/backend/engines/api/spec/controllers/spree/api/v3/store/customer/addresses_controller_spec.rb b/backend/engines/api/spec/controllers/spree/api/v3/store/customer/addresses_controller_spec.rbindex 999c5881f4..e48081bec0 100644--- a/backend/engines/api/spec/controllers/spree/api/v3/store/customer/addresses_controller_spec.rb+++ b/backend/engines/api/spec/controllers/spree/api/v3/store/customer/addresses_controller_spec.rb@@ -174,6 +174,67 @@ RSpec.describe Spree::Api::V3::Store::Customer::AddressesController, type: :contendend+ describe 'PATCH #mark_as_default' do+ it 'sets address as default billing address' do+ patch :mark_as_default, params: { id: address.prefixed_id, kind: 'billing' }++ expect(response).to have_http_status(:ok)+ expect(user.reload.bill_address_id).to eq(address.id)+ end++ it 'sets address as default shipping address' do+ patch :mark_as_default, params: { id: address.prefixed_id, kind: 'shipping' }++ expect(response).to have_http_status(:ok)+ expect(user.reload.ship_address_id).to eq(address.id)+ end++ it 'returns the address' do+ patch :mark_as_default, params: { id: address.prefixed_id, kind: 'billing' }++ expect(json_response['id']).to eq(address.prefixed_id)+ end++ context 'with invalid kind' do+ it 'returns error' do+ patch :mark_as_default, params: { id: address.prefixed_id, kind: 'invalid' }++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['code']).to eq('invalid_request')+ end+ end++ context 'with missing kind' do+ it 'returns error' do+ patch :mark_as_default, params: { id: address.prefixed_id }++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['code']).to eq('invalid_request')+ end+ end++ context 'when address belongs to another user' do+ let(:other_user) { create(:user) }+ let(:other_address) { create(:address, user: other_user) }++ it 'returns not found' do+ patch :mark_as_default, params: { id: other_address.prefixed_id, kind: 'billing' }++ expect(response).to have_http_status(:not_found)+ end+ end++ context 'without authentication' do+ before { request.headers['Authorization'] = nil }++ it 'returns unauthorized' do+ patch :mark_as_default, params: { id: address.prefixed_id, kind: 'billing' }++ expect(response).to have_http_status(:unauthorized)+ end+ end+ end+describe 'DELETE #destroy' doit 'deletes the address' doexpect {diff --git a/backend/engines/api/spec/integration/spree/api/v3/store/addresses_spec.rb b/backend/engines/api/spec/integration/spree/api/v3/store/addresses_spec.rbindex cf84360cd8..a43b800bb5 100644--- a/backend/engines/api/spec/integration/spree/api/v3/store/addresses_spec.rb+++ b/backend/engines/api/spec/integration/spree/api/v3/store/addresses_spec.rb@@ -206,4 +206,63 @@ RSpec.describe 'Addresses API', type: :request, swagger_doc: 'api-reference/storendendend++ path '/api/v3/store/customer/addresses/{id}/mark_as_default' do+ patch 'Mark address as default' do+ tags 'Addresses'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Sets the address as the default billing or shipping address for the customer'++ 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+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ kind: { type: :string, enum: %w[billing shipping], example: 'billing',+ description: 'Address kind: billing or shipping' }+ },+ required: ['kind']+ }++ response '200', 'address marked as default' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:id) { address.to_param }+ let(:body) { { kind: 'billing' } }++ schema '$ref' => '#/components/schemas/StoreAddress'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(address.prefixed_id)+ expect(user.reload.bill_address_id).to eq(address.id)+ end+ end++ response '422', 'invalid kind parameter' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:id) { address.to_param }+ let(:body) { { kind: 'invalid' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end++ response '404', 'address not found' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:id) { 'non-existent' }+ let(:body) { { kind: 'billing' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ endenddiff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 9b7c0322b4..a4792a6319 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -40,256 +40,17 @@ info:```version: v3paths:- "/api/v3/store/customer":- patch:- summary: Update current customer profile- tags:- - Customers- security:- - api_key: []- bearer_auth: []- description: Updates the profile of the currently authenticated customer- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- schema:- type: string- responses:- '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"- '200':- description: profile updated- content:- application/json:- example:- id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Updated- last_name: Name- created_at: '2026-02-14T17:18:36.585Z'- updated_at: '2026-02-14T17:18:36.885Z'- addresses:- - id: addr_gbHJdmfrXB- firstname: John- lastname: Doe- full_name: John Doe- address1: 4 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_4- state_abbr: STATE_ABBR_4- state_name: STATE_NAME_4- - id: addr_UkLWZg9DAJ- firstname: John- lastname: Doe- full_name: John Doe- address1: 3 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_3- state_abbr: STATE_ABBR_3- state_name: STATE_NAME_3- default_billing_address:- id: addr_gbHJdmfrXB- firstname: John- lastname: Doe- full_name: John Doe- address1: 4 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_4- state_abbr: STATE_ABBR_4- state_name: STATE_NAME_4- default_shipping_address:- id: addr_UkLWZg9DAJ- firstname: John- lastname: Doe- full_name: John Doe- address1: 3 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_3- state_abbr: STATE_ABBR_3- state_name: STATE_NAME_3- schema:- "$ref": "#/components/schemas/StoreCustomer"- 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+ "/api/v3/store/cart":get:- summary: Get current customer profile- tags:- - Customers- security:- - api_key: []- bearer_auth: []- description: Returns the profile of the currently authenticated customer- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer JWT token- schema:- type: string- responses:- '200':- description: profile found- content:- application/json:- example:- id: cus_UkLWZg9DAJ- email: [email protected]- first_name: German- last_name: Purdy- created_at: '2026-02-14T17:18:37.168Z'- updated_at: '2026-02-14T17:18:37.465Z'- addresses:- - id: addr_gbHJdmfrXB- firstname: John- lastname: Doe- full_name: John Doe- address1: 6 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_6- state_abbr: STATE_ABBR_6- state_name: STATE_NAME_6- - id: addr_UkLWZg9DAJ- firstname: John- lastname: Doe- full_name: John Doe- address1: 5 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_5- state_abbr: STATE_ABBR_5- state_name: STATE_NAME_5- default_billing_address:- id: addr_gbHJdmfrXB- firstname: John- lastname: Doe- full_name: John Doe- address1: 6 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_6- state_abbr: STATE_ABBR_6- state_name: STATE_NAME_6- default_shipping_address:- id: addr_UkLWZg9DAJ- firstname: John- lastname: Doe- full_name: John Doe- address1: 5 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_5- state_abbr: STATE_ABBR_5- state_name: STATE_NAME_5- schema:- "$ref": "#/components/schemas/StoreCustomer"- '401':- description: unauthorized - no token- content:- application/json:- example:- error:- code: authentication_required- message: Authentication required- schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{order_id}/coupon_codes":- post:- summary: Apply coupon code+ summary: Get current carttags:- - Coupon Codes+ - Cartsecurity:- 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.+ Returns the current shopping cart (incomplete order).+ Authenticate via JWT token for logged-in users or via order_token parameter for guests.parameters:- name: x-spree-api-keyin: header@@ -299,32 +60,26 @@ paths:- name: Authorizationin: headerrequired: false- description: Bearer token for authenticated customers- schema:- type: string- - name: order_id- in: path- required: true- description: Order ID+ description: Bearer JWT token for authenticated customersschema:type: string- name: order_tokenin: queryrequired: false- description: Order token for guest access+ description: Order token for guest checkoutschema:type: stringresponses:- '201':- description: coupon code applied (gift card)+ '200':+ description: cart found (guest)content:application/json:example:id: or_UkLWZg9DAJ- number: R565584986+ number: R908760653state: cart- token: dKpSWdbd57LMbvnj3zKq35skoosb1Dyfa1q- email: [email protected]+ token: XQYajpzkbaMsp4KPNSjRFPaKQEUM616mXns+ email: [email protected]special_instructions:currency: USDitem_count: 1@@ -347,56 +102,69 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-02-14T17:18:39.107Z'- updated_at: '2026-02-14T17:18:39.283Z'- payment_methods:- - id: pm_UkLWZg9DAJ- name: Store Credit- description:- type: Spree::PaymentMethod::StoreCredit+ created_at: '2026-02-14T19:47:06.333Z'+ updated_at: '2026-02-14T19:47:06.457Z'+ line_items:+ - id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ name: Product 25146+ slug: product-25146+ 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-02-14T19:47:06.406Z'+ updated_at: '2026-02-14T19:47:06.406Z'+ compare_at_amount:+ thumbnail_url:+ option_values: []+ digital_links: []+ payment_methods: []schema:- "$ref": "#/components/schemas/StoreOrder"- '404':- description: order not found- content:- application/json:- example:- error:- code: order_not_found- message: Order not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- '422':- description: invalid coupon code+ type: object+ allOf:+ - "$ref": "#/components/schemas/StoreOrder"+ - type: object+ properties:+ token:+ type: string+ '404':+ description: no cart foundcontent:application/json:example:error:- code: processing_error- message: The coupon code you entered doesn't exist. Please try again.+ code: order_not_found+ message: Order not foundschema:"$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/cart/associate":+ patch:+ summary: Associate guest cart with authenticated usertags:- - Coupon Codes+ - Cartsecurity:- api_key: []bearer_auth: []- description: Removes a previously applied coupon code from the order.+ description: |+ Associates a guest cart with the currently authenticated user.+ Requires both JWT authentication and an order token.+ The order must not be completed and must not belong to another user.parameters:- name: x-spree-api-keyin: header@@ -405,49 +173,43 @@ paths:type: string- name: Authorizationin: header- required: false- description: Bearer token for authenticated customers- schema:- type: string- - name: order_id- in: pathrequired: true- description: Order ID+ description: Bearer JWT token (required)schema:type: string- - name: id- in: path- required: true- description: Order promotion ID+ - name: x-spree-order-token+ in: header+ required: false+ description: Order token (can also be passed as query param)schema:type: string- name: order_tokenin: queryrequired: false- description: Order token for guest access+ description: Order token (alternative to header)schema:type: stringresponses:'404':- description: coupon code not found on order+ description: cart belongs to another usercontent:application/json:example:error:- code: record_not_found- message: Order promotion not found+ code: order_not_found+ message: Order not foundschema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: coupon code removed+ description: cart associated successfullycontent:application/json:example:id: or_UkLWZg9DAJ- number: R220533920+ number: R342807255state: cart- token: jwg5nhPb8w8cGLjPcfXX86XjnDUopGv37VC- email: [email protected]+ token: tJzSrEsVuHqepWuAqyj94RZCFCSVFJDyQ76+ email: [email protected]special_instructions:currency: USDitem_count: 1@@ -470,167 +232,118 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-02-14T17:18:42.089Z'- updated_at: '2026-02-14T17:18:42.293Z'+ created_at: '2026-02-14T19:47:07.230Z'+ updated_at: '2026-02-14T19:47:07.345Z'+ line_items:+ - id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ name: Product 43960+ slug: product-43960+ 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-02-14T19:47:07.293Z'+ updated_at: '2026-02-14T19:47:07.293Z'+ compare_at_amount:+ thumbnail_url:+ option_values: []+ digital_links: []payment_methods: []- schema:- "$ref": "#/components/schemas/StoreOrder"- "/api/v3/store/taxonomies":- get:- summary: List taxonomies- tags:- - Taxonomies- security:- - api_key: []- description: Returns a list of taxonomies (category hierarchies) for the current- store- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: page- in: query- required: false- schema:- type: integer- - name: per_page- in: query- required: false- schema:- type: integer- - name: includes- in: query- required: false- description: Include root taxon- schema:- type: string- responses:- '200':- description: taxonomies found- content:- application/json:- example:- data:- - id: txnmy_UkLWZg9DAJ- name: Categories- position: 1- created_at: '2026-02-14T17:18:35.511Z'- updated_at: '2026-02-14T17:18:35.530Z'- root_id: txn_UkLWZg9DAJ- - id: txnmy_gbHJdmfrXB- name: Brands- position: 2- created_at: '2026-02-14T17:18:35.531Z'- updated_at: '2026-02-14T17:18:35.539Z'- root_id: txn_gbHJdmfrXB- - id: txnmy_EfhxLZ9ck8- name: Collections- position: 3- created_at: '2026-02-14T17:18:35.540Z'- updated_at: '2026-02-14T17:18:35.653Z'- root_id: txn_EfhxLZ9ck8- - id: txnmy_VqXmZF31wY- name: taxonomy_1- position: 4- created_at: '2026-02-14T17:18:42.303Z'- updated_at: '2026-02-14T17:18:42.312Z'- root_id: txn_OIJLhNcSbf- - id: txnmy_uw2YK1rnl0- name: taxonomy_2- position: 5- created_at: '2026-02-14T17:18:42.313Z'- updated_at: '2026-02-14T17:18:42.322Z'- root_id: txn_AXs1igzRC6- meta:- page: 1- limit: 25- count: 5- pages: 1- from: 1- to: 5- in: 5- previous:- next:schema:type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/StoreTaxonomy"- meta:- "$ref": "#/components/schemas/PaginationMeta"+ allOf:+ - "$ref": "#/components/schemas/StoreOrder"+ - type: object+ properties:+ token:+ type: string'401':- description: unauthorized+ description: unauthorized - JWT requiredcontent: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/taxonomies/{id}":- get:- summary: Get a taxonomy+ "/api/v3/store/wishlists/{id}":+ patch:+ summary: Update a wishlisttags:- - Taxonomies+ - Wishlistssecurity:- api_key: []- description: Returns a single taxonomy with its taxon tree+ bearer_auth: []parameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: id- in: path+ - name: Authorization+ in: headerrequired: true- description: Taxonomy ID (prefixed)schema:type: string- - name: includes- in: query- required: false- description: Include taxons+ - name: id+ in: path+ required: trueschema:type: stringresponses:'200':- description: taxonomy found- content:- application/json:- example:- id: txnmy_VqXmZF31wY- name: taxonomy_7- position: 4- created_at: '2026-02-14T17:18:42.689Z'- updated_at: '2026-02-14T17:18:42.699Z'- root_id: txn_OIJLhNcSbf- schema:- "$ref": "#/components/schemas/StoreTaxonomy"- '404':- description: taxonomy from other store+ description: wishlist updatedcontent:application/json:example:- error:- code: record_not_found- message: Taxonomy not found+ id: wl_UkLWZg9DAJ+ name: Updated Name+ token: pTjuUq7zGXbr1e8srB3e6f1x+ created_at: '2026-02-14T19:47:10.212Z'+ updated_at: '2026-02-14T19:47:10.305Z'+ is_default: false+ is_private: trueschema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{order_id}/shipments":- get:- summary: List shipments for an order+ "$ref": "#/components/schemas/StoreWishlist"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Updated Name+ is_private:+ type: boolean+ example: true+ is_default:+ type: boolean+ example: false+ delete:+ summary: Delete a wishlisttags:- - Shipments+ - Wishlistssecurity:- api_key: []bearer_auth: []- description: Returns all shipments associated with the orderparameters:- name: x-spree-api-keyin: header@@ -639,100 +352,24 @@ paths:type: string- name: Authorizationin: header- required: false+ required: trueschema:type: string- - name: order_id+ - name: idin: pathrequired: trueschema:type: string- - name: token- in: query- required: false- description: Order token for guest access- schema:- type: stringresponses:- '200':- description: shipments found- content:- application/json:- example:- data:- - id: ship_UkLWZg9DAJ- number: H55430180322- state: pending- tracking: U10000- tracking_url:- cost: '100.0'- display_cost: "$100.00"- shipped_at:- created_at: '2026-02-14T17:18:43.910Z'- updated_at: '2026-02-14T17:18:43.933Z'- shipping_method:- id: shpm_UkLWZg9DAJ- name: UPS Ground- code: UPS_GROUND- stock_location:- id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_31- name: Rosy Feil- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_iso: US- country_name: United States of America- state_text: STATE_ABBR_31- 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/StoreShipment"- meta:- "$ref": "#/components/schemas/PaginationMeta"- '404':- description: order not found- content:- application/json:- example:- error:- code: order_not_found- message: Order not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{order_id}/shipments/{id}":+ '204':+ description: wishlist deletedget:- summary: Get a shipment+ summary: Get a wishlisttags:- - Shipments+ - Wishlistssecurity:- api_key: []bearer_auth: []- description: Returns details of a specific shipmentparameters:- name: x-spree-api-keyin: header@@ -741,93 +378,53 @@ paths:type: string- name: Authorizationin: header- required: false- schema:- type: string- - name: order_id- in: pathrequired: trueschema:type: string- name: idin: pathrequired: true- description: Shipment ID- schema:- type: string- - name: token- in: query- required: false- description: Order token for guest accessschema:type: string- name: includesin: queryrequired: false- description: Include shipping_rates+ description: Include wished_itemsschema:type: stringresponses:- '200':- description: shipment found- content:- application/json:- example:- id: ship_UkLWZg9DAJ- number: H41372378538- state: pending- tracking: U10000- tracking_url:- cost: '100.0'- display_cost: "$100.00"- shipped_at:- created_at: '2026-02-14T17:18:45.368Z'- updated_at: '2026-02-14T17:18:45.396Z'- shipping_method:- id: shpm_UkLWZg9DAJ- name: UPS Ground- code: UPS_GROUND- stock_location:- id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_39- name: Valene Halvorson- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_iso: US- country_name: United States of America- state_text: STATE_ABBR_39- 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- schema:- "$ref": "#/components/schemas/StoreShipment"'404':- description: shipment not found+ description: wishlist not foundcontent:application/json:example:error:code: record_not_found- message: Shipment not found+ message: Wishlist not foundschema:"$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Select shipping rate for shipment+ '200':+ description: wishlist found+ content:+ application/json:+ example:+ id: wl_UkLWZg9DAJ+ name: My Wishlist+ token: efJEmea94PawydeiJh9JR99b+ created_at: '2026-02-14T19:47:12.162Z'+ updated_at: '2026-02-14T19:47:12.162Z'+ is_default: false+ is_private: true+ schema:+ "$ref": "#/components/schemas/StoreWishlist"+ "/api/v3/store/wishlists/{wishlist_id}/items/{id}":+ delete:+ summary: Remove item from wishlisttags:- - Shipments+ - Wishlistssecurity:- api_key: []bearer_auth: []- description: Selects a shipping rate for the shipmentparameters:- name: x-spree-api-keyin: header@@ -836,10 +433,10 @@ paths:type: string- name: Authorizationin: header- required: false+ required: trueschema:type: string- - name: order_id+ - name: wishlist_idin: pathrequired: trueschema:@@ -847,194 +444,148 @@ paths:- name: idin: pathrequired: true- description: Shipment ID- schema:- type: string- - name: token- in: query- required: false- description: Order token for guest accessschema:type: stringresponses:- '200':- description: shipping rate selected- content:- application/json:- example:- id: ship_UkLWZg9DAJ- number: H80762433143- state: pending- tracking: U10000- tracking_url:- cost: '100.0'- display_cost: "$100.00"- shipped_at:- created_at: '2026-02-14T17:18:46.837Z'- updated_at: '2026-02-14T17:18:46.889Z'- shipping_method:- id: shpm_UkLWZg9DAJ- name: UPS Ground- code: UPS_GROUND- stock_location:- id: sloc_UkLWZg9DAJ- state_abbr: STATE_ABBR_47- name: Darla Windler- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_iso: US- country_name: United States of America- state_text: STATE_ABBR_47- 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- schema:- "$ref": "#/components/schemas/StoreShipment"+ '204':+ description: item removed'404':- description: shipping rate not found+ description: item not foundcontent:application/json:example:error:code: record_not_found- message: Shipping rate not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- selected_shipping_rate_id:- type: string- example: shprt_abc123- description: Shipping rate ID to select- required:- - selected_shipping_rate_id- "/api/v3/store/auth/register":+ message: Wished item not found+ "/api/v3/store/wishlists/{wishlist_id}/items":post:- summary: Register+ summary: Add item to wishlisttags:- - Authentication+ - Wishlistssecurity:- api_key: []- description: Creates a new customer account and returns a JWT token+ bearer_auth: []+ description: Adds a variant to the wishlistparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: wishlist_id+ in: path+ required: true+ schema:+ type: stringresponses:- '422':- description: email already taken- content:- application/json:- example:- error:- code: validation_error- message: Email has already been taken- details:- email:- - has already been taken- schema:- "$ref": "#/components/schemas/ErrorResponse"'201':- description: registration successful+ description: item addedcontent:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE3NTkyOH0.vfcRB9L23UqJgvOaSuA5Ze3KwXZlAHVRtLo4SM6p3c4- user:- id: cus_UkLWZg9DAJ- email: [email protected]- first_name: John- last_name: Doe- created_at: '2026-02-14T17:18:48.141Z'- updated_at: '2026-02-14T17:18:48.141Z'- addresses: []- default_billing_address:- default_shipping_address:+ id: wi_gbHJdmfrXB+ variant_id: variant_gbHJdmfrXB+ wishlist_id: wl_UkLWZg9DAJ+ quantity: 1+ created_at: '2026-02-14T19:47:14.280Z'+ updated_at: '2026-02-14T19:47:14.280Z'+ variant:+ id: variant_gbHJdmfrXB+ product_id: prod_gbHJdmfrXB+ sku: SKU-14+ is_master: true+ options_text: ''+ track_inventory: true+ image_count: 0+ created_at: '2026-02-14T19:47:14.208Z'+ updated_at: '2026-02-14T19:47:14.240Z'+ thumbnail:+ purchasable: true+ in_stock: false+ backorderable: true+ weight: 0.0+ height:+ width:+ depth:+ price:+ id: price_gbHJdmfrXB+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ option_values: []schema:- "$ref": "#/components/schemas/AuthResponse"+ "$ref": "#/components/schemas/StoreWishedItem"requestBody:content:application/json:schema:type: objectproperties:- 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:+ variant_id:type: string- example: Doe+ example: variant_abc123+ quantity:+ type: integer+ example: 1required:- - password- "/api/v3/store/auth/login":+ - variant_id+ "/api/v3/store/wishlists":post:- summary: Login+ summary: Create a wishlisttags:- - Authentication+ - Wishlistssecurity:- api_key: []- description: Authenticates a customer with email/password and returns a JWT- token+ bearer_auth: []+ description: Creates a new wishlist for the customerparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: stringresponses:- '200':- description: login successful+ '201':+ description: wishlist createdcontent:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE3NTkyOH0.vfcRB9L23UqJgvOaSuA5Ze3KwXZlAHVRtLo4SM6p3c4- user:- id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Corrina- last_name: Bernhard- created_at: '2026-02-14T17:18:48.417Z'- updated_at: '2026-02-14T17:18:48.417Z'- addresses: []- default_billing_address:- default_shipping_address:+ id: wl_gbHJdmfrXB+ name: Birthday Ideas+ token: gpEV78fdp4HbbTWgMHWKktDh+ created_at: '2026-02-14T19:47:15.000Z'+ updated_at: '2026-02-14T19:47:15.000Z'+ is_default: false+ is_private: trueschema:- "$ref": "#/components/schemas/AuthResponse"- '401':- description: missing API key+ "$ref": "#/components/schemas/StoreWishlist"+ '422':+ description: validation errorcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blankschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -1043,29 +594,25 @@ paths:schema:type: objectproperties:- provider:- type: string- example: email- description: 'Authentication provider (default: email)'- email:- type: string- format: email- example: [email protected]- password:+ name:type: string- example: password123+ example: Birthday Ideas+ is_private:+ type: boolean+ example: true+ is_default:+ type: boolean+ example: falserequired:- - password- "/api/v3/store/auth/refresh":- post:- summary: Refresh token+ - name+ get:+ summary: List wishliststags:- - Authentication+ - Wishlistssecurity:- api_key: []bearer_auth: []- description: Generates a new JWT token for the authenticated user+ description: Returns all wishlists for the authenticated customerparameters:- name: x-spree-api-keyin: header@@ -1075,30 +622,53 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer tokenschema:type: string+ - name: page+ in: query+ required: false+ schema:+ type: integer+ - name: per_page+ in: query+ required: false+ schema:+ type: integerresponses:'200':- description: token refreshed+ description: wishlists foundcontent:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE3NTkyOX0.T9UcZGb5SxlKWa3tXYppxwfv0c0Tqe9_RfAYMOWw9dU- user:- id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Wenona- last_name: Jaskolski- created_at: '2026-02-14T17:18:49.790Z'- updated_at: '2026-02-14T17:18:49.790Z'- addresses: []- default_billing_address:- default_shipping_address:+ data:+ - id: wl_UkLWZg9DAJ+ name: My Wishlist+ token: Habm2oifceLMh9SfxyNC1baP+ created_at: '2026-02-14T19:47:16.233Z'+ updated_at: '2026-02-14T19:47:16.233Z'+ is_default: false+ is_private: true+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:schema:- "$ref": "#/components/schemas/AuthResponse"+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StoreWishlist"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"'401':- description: missing or invalid token+ description: unauthorizedcontent:application/json:example:@@ -1107,44 +677,38 @@ paths:message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/taxons/{id}":+ "/api/v3/store/taxonomies":get:- summary: Get a taxon+ summary: List taxonomiestags:- - Taxons+ - Taxonomiessecurity:- api_key: []- description: Returns a single taxon by permalink or prefix ID+ description: Returns a list of taxonomies (category hierarchies) for the current+ storeparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: id- in: path- required: true- description: Taxon permalink (e.g., categories/clothing/shirts) or prefix- ID (e.g., taxon_abc123)+ - name: page+ in: query+ required: falseschema:- type: string+ type: integer+ - name: per_page+ in: query+ required: false+ schema:+ type: integer- name: includesin: queryrequired: false- description: Include associations (children, products, parent)+ description: Include root taxonschema:type: stringresponses:- '404':- description: taxon not found- content:- application/json:- example:- error:- code: record_not_found- message: Taxon not found- schema:- "$ref": "#/components/schemas/ErrorResponse"'401':description: unauthorizedcontent:@@ -1156,124 +720,119 @@ paths:schema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: taxon found by permalink+ description: taxonomies foundcontent:application/json:example:- id: txn_AXs1igzRC6- name: taxon_13- permalink: taxonomy-24/taxon-13- position: 0- depth: 1- meta_title:- meta_description:- meta_keywords:- children_count: 1- created_at: '2026-02-14T17:18:50.533Z'- updated_at: '2026-02-14T17:18:50.552Z'- parent_id: txn_OIJLhNcSbf- taxonomy_id: txnmy_VqXmZF31wY- description: ''- description_html: ''- image_url:- square_image_url:- is_root: false- is_child: true- is_leaf: false- schema:- "$ref": "#/components/schemas/StoreTaxon"- "/api/v3/store/orders/{order_id}/line_items/{id}":- patch:- summary: Update line item quantity- tags:- - Line Items- security:- - api_key: []- bearer_auth: []- description: Updates the quantity of a line item in the cart- 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:+ data:+ - id: txnmy_UkLWZg9DAJ+ name: Categories+ position: 1+ created_at: '2026-02-14T19:47:04.996Z'+ updated_at: '2026-02-14T19:47:05.018Z'+ root_id: txn_UkLWZg9DAJ+ - id: txnmy_gbHJdmfrXB+ name: Brands+ position: 2+ created_at: '2026-02-14T19:47:05.020Z'+ updated_at: '2026-02-14T19:47:05.028Z'+ root_id: txn_gbHJdmfrXB+ - id: txnmy_EfhxLZ9ck8+ name: Collections+ position: 3+ created_at: '2026-02-14T19:47:05.029Z'+ updated_at: '2026-02-14T19:47:05.138Z'+ root_id: txn_EfhxLZ9ck8+ - id: txnmy_VqXmZF31wY+ name: taxonomy_4+ position: 4+ created_at: '2026-02-14T19:47:17.093Z'+ updated_at: '2026-02-14T19:47:17.105Z'+ root_id: txn_OIJLhNcSbf+ - id: txnmy_uw2YK1rnl0+ name: taxonomy_5+ position: 5+ created_at: '2026-02-14T19:47:17.106Z'+ updated_at: '2026-02-14T19:47:17.115Z'+ root_id: txn_AXs1igzRC6+ meta:+ page: 1+ limit: 25+ count: 5+ pages: 1+ from: 1+ to: 5+ in: 5+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StoreTaxonomy"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ "/api/v3/store/taxonomies/{id}":+ get:+ summary: Get a taxonomy+ tags:+ - Taxonomies+ security:+ - api_key: []+ description: Returns a single taxonomy with its taxon tree+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:type: string- name: idin: pathrequired: true- description: Line item ID+ description: Taxonomy ID (prefixed)schema:type: string- - name: order_token+ - name: includesin: queryrequired: false+ description: Include taxonsschema:type: stringresponses:'200':- description: line item updated+ description: taxonomy foundcontent:application/json:example:- id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 5- name: Product 135213- slug: product-135213- options_text: ''- price: '19.99'- display_price: "$19.99"- total: '99.95'- display_total: "$99.95"- 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: '99.95'- display_pre_tax_amount: "$99.95"- discounted_amount: '99.95'- display_discounted_amount: "$99.95"- display_compare_at_amount: "$0.00"- created_at: '2026-02-14T17:18:51.320Z'- updated_at: '2026-02-14T17:18:51.354Z'- compare_at_amount:- thumbnail_url:- option_values: []+ id: txnmy_VqXmZF31wY+ name: taxonomy_7+ position: 4+ created_at: '2026-02-14T19:47:17.246Z'+ updated_at: '2026-02-14T19:47:17.256Z'+ root_id: txn_OIJLhNcSbfschema:- "$ref": "#/components/schemas/StoreLineItem"- requestBody:- content:- application/json:- schema:- type: object- properties:- quantity:- type: integer- minimum: 1- example: 5- required:- - quantity- delete:- summary: Remove line item from cart+ "$ref": "#/components/schemas/StoreTaxonomy"+ '404':+ description: taxonomy not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Taxonomy not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/customer/addresses":+ get:+ summary: List customer addressestags:- - Line Items+ - Addressessecurity:- api_key: []bearer_auth: []- description: Removes a line item from the order+ description: Returns all addresses in the customer address bookparameters:- name: x-spree-api-keyin: header@@ -1282,47 +841,108 @@ paths:type: string- name: Authorizationin: header- required: false- schema:- type: string- - name: order_id- in: pathrequired: trueschema:type: string- - name: id- in: path- required: true+ - name: page+ in: query+ required: falseschema:- type: string- - name: order_token+ type: integer+ - name: per_pagein: queryrequired: falseschema:- type: string+ type: integerresponses:- '404':- description: line item not found+ '200':+ description: addresses found+ content:+ application/json:+ example:+ data:+ - id: addr_EfhxLZ9ck8+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 47 Lovely Street+ address2: Northwest+ city: Herndon+ zipcode: '35005'+ phone: 555-555-0199+ company: Company+ country_name: NAME_7+ country_iso: I7+ state_text: STATE_ABBR_45+ state_abbr: STATE_ABBR_45+ state_name: STATE_NAME_45+ - id: addr_gbHJdmfrXB+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 46 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_47+ state_abbr: STATE_ABBR_47+ state_name: STATE_NAME_47+ - id: addr_UkLWZg9DAJ+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 45 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_46+ state_abbr: STATE_ABBR_46+ state_name: STATE_NAME_46+ 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/StoreAddress"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ '401':+ description: unauthorizedcontent:application/json:example:error:- code: line_item_not_found- message: Line item not found+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- '204':- description: line item removed- "/api/v3/store/orders/{order_id}/line_items":post:- summary: Add item to cart+ summary: Create an addresstags:- - Line Items+ - Addressessecurity:- 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 new address to the customer address bookparameters:- name: x-spree-api-keyin: header@@ -1331,152 +951,199 @@ paths:type: string- name: Authorizationin: header- required: false- description: Bearer token for authenticated customers- schema:- type: string- - name: order_id- in: pathrequired: true- description: Order ID or number- schema:- type: string- - name: order_token- in: query- required: false- description: Order token for guest accessschema:type: stringresponses:- '404':- description: order not found+ '201':+ description: address createdcontent:application/json:example:- error:- code: order_not_found- message: Order not found+ id: addr_VqXmZF31wY+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 123 Main St+ address2:+ city: New York+ zipcode: '10001'+ phone: "+1 555 123 4567"+ company:+ country_name: NAME_9+ country_iso: I9+ state_text: STATE_ABBR_51+ state_abbr: STATE_ABBR_51+ state_name: STATE_NAME_51schema:- "$ref": "#/components/schemas/ErrorResponse"- '201':- description: line item created+ "$ref": "#/components/schemas/StoreAddress"+ '422':+ description: validation errorcontent:application/json:example:- id: li_gbHJdmfrXB- variant_id: variant_gbHJdmfrXB- quantity: 2- name: Product 189863- slug: product-189863- options_text: ''- price: '19.99'- display_price: "$19.99"- total: '39.98'- display_total: "$39.98"- 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: '39.98'- display_pre_tax_amount: "$39.98"- discounted_amount: '39.98'- display_discounted_amount: "$39.98"- display_compare_at_amount: "$0.00"- created_at: '2026-02-14T17:18:54.002Z'- updated_at: '2026-02-14T17:18:54.002Z'- compare_at_amount:- thumbnail_url:- option_values: []+ error:+ code: validation_error+ message: First Name can't be blank, Last Name can't be blank, Address+ can't be blank, City can't be blank, Country can't be blank, and+ Zip Code can't be blank+ details:+ firstname:+ - can't be blank+ lastname:+ - can't be blank+ address1:+ - can't be blank+ city:+ - can't be blank+ country:+ - can't be blank+ zipcode:+ - can't be blankschema:- "$ref": "#/components/schemas/StoreLineItem"+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:schema:type: objectproperties:- variant_id:+ firstname:type: string- example: variant_abc123- description: Variant ID to add- quantity:- type: integer- example: 2- description: 'Quantity to add (default: 1)'+ 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+ description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")+ state_abbr:+ type: string+ example: NY+ description: ISO 3166-2 subdivision code without country prefix+ (e.g., "CA", "NY")+ state_name:+ type: string+ example: New York+ description: State name - for countries without predefined statesrequired:- - variant_id- "/api/v3/store/store":- get:- summary: Get current store+ - firstname+ - lastname+ - address1+ - city+ - zipcode+ - country_iso+ "/api/v3/store/customer/addresses/{id}/mark_as_default":+ patch:+ summary: Mark address as defaulttags:- - Store+ - Addressessecurity:- api_key: []- description: Returns information about the current store based on the API key+ bearer_auth: []+ description: Sets the address as the default billing or shipping address for+ the customerparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: store found+ description: address marked as defaultcontent:application/json:example:- id: store_UkLWZg9DAJ- name: Spree Test Store- url: www.example.com- meta_description: Sample store description.- meta_keywords:- seo_title:- default_currency: USD- code: spree_1- default: true- facebook: spreecommerce- twitter: spreecommerce- instagram: spreecommerce- customer_support_email: [email protected]- default_locale: en- created_at: '2026-02-14T17:18:35.503Z'- updated_at: '2026-02-14T17:18:35.648Z'- default_country_iso: US- supported_currencies:- - USD- - EUR- - GBP- favicon_image_url:- logo_image_url:- social_image_url:- supported_locales:- - en- payment_methods: []+ id: addr_EfhxLZ9ck8+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 59 Lovely Street+ address2: Northwest+ city: Herndon+ zipcode: '35005'+ phone: 555-555-0199+ company: Company+ country_name: NAME_11+ country_iso: I11+ state_text: STATE_ABBR_57+ state_abbr: STATE_ABBR_57+ state_name: STATE_NAME_57schema:- "$ref": "#/components/schemas/StoreStore"- '401':- description: unauthorized - invalid API key+ "$ref": "#/components/schemas/StoreAddress"+ '422':+ description: invalid kind parametercontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: invalid_request+ message: kind must be billing or shippingschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders":+ '404':+ description: address not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Address not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ kind:+ type: string+ enum:+ - billing+ - shipping+ example: billing+ description: 'Address kind: billing or shipping'+ required:+ - kind+ "/api/v3/store/customer/addresses/{id}":get:- summary: List orders+ summary: Get an addresstags:- - Orders+ - Addressessecurity:- api_key: []bearer_auth: []- description: Returns a paginated list of orders for the authenticated customerparameters:- name: x-spree-api-keyin: header@@ -1488,103 +1155,51 @@ paths:required: trueschema:type: string- - name: page- in: query- required: false- schema:- type: integer- - name: per_page- in: query- required: false- schema:- type: integer- - 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)+ - name: id+ in: path+ required: trueschema:type: stringresponses:'200':- description: orders found+ description: address foundcontent:application/json:example:- data:- - id: or_UkLWZg9DAJ- number: R920944376- state: cart- token: FRbB5nvtLdaUzzgZKoyC1hFscC3P1ynBi48- email: [email protected]- special_instructions:- currency: USD- 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"- 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-02-14T17:18:55.231Z'- updated_at: '2026-02-14T17:18:55.370Z'- payment_methods: []- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ id: addr_EfhxLZ9ck8+ 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: NAME_14+ country_iso: I14+ state_text: STATE_ABBR_66+ state_abbr: STATE_ABBR_66+ state_name: STATE_NAME_66schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/StoreOrder"- meta:- "$ref": "#/components/schemas/PaginationMeta"- '401':- description: unauthorized - authentication required+ "$ref": "#/components/schemas/StoreAddress"+ '404':+ description: address not foundcontent:application/json:example:error:- code: authentication_required- message: Authentication required- schema:+ code: record_not_found+ message: Address not found+ schema:"$ref": "#/components/schemas/ErrorResponse"- post:- summary: Create a cart+ patch:+ summary: Update an addresstags:- - Orders+ - Addressessecurity:- api_key: []- description: |- Creates a new order (shopping cart). Can be created by guests or authenticated customers.- Returns an `order_token` that must be used for guest access to the order.+ bearer_auth: []parameters:- name: x-spree-api-keyin: header@@ -1593,64 +1208,89 @@ paths:type: string- name: Authorizationin: header- required: false- description: Bearer JWT token (optional - for authenticated customers)+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: trueschema:type: stringresponses:- '201':- description: cart created (guest)+ '200':+ description: address updatedcontent:application/json:example:- id: or_gbHJdmfrXB- number: R262979595- state: cart- token: PSQqteox8xTXetssoZmoBacxBckedPKGVmV- email:- special_instructions:- currency: USD- item_count: 0- 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-02-14T17:18:58.149Z'- updated_at: '2026-02-14T17:18:58.149Z'- payment_methods: []- order_token: PSQqteox8xTXetssoZmoBacxBckedPKGVmV+ id: addr_EfhxLZ9ck8+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 74 Lovely Street+ address2: Northwest+ city: Los Angeles+ zipcode: '35005'+ phone: 555-555-0199+ company: Company+ country_name: NAME_16+ country_iso: I16+ state_text: STATE_ABBR_72+ state_abbr: STATE_ABBR_72+ state_name: STATE_NAME_72schema:- type: object- allOf:- - "$ref": "#/components/schemas/StoreOrder"- - type: object- properties:- order_token:- type: string- description: Token for guest access to this order- '401':- description: unauthorized - invalid API key+ "$ref": "#/components/schemas/StoreAddress"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ firstname:+ type: string+ example: John+ lastname:+ type: string+ example: Doe+ address1:+ type: string+ example: 456 Oak Ave+ city:+ type: string+ example: Los Angeles+ delete:+ summary: Delete an address+ tags:+ - Addresses+ security:+ - api_key: []+ bearer_auth: []+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ responses:+ '204':+ description: address deleted+ '404':+ description: address not foundcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: record_not_found+ message: Address not foundschema:"$ref": "#/components/schemas/ErrorResponse""/api/v3/store/orders/{order_id}/store_credits":@@ -1690,10 +1330,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R644173136+ number: R379134890state: cart- token: f6RLcPBgfpR62dsS8Fz9C6449EsebvqfuMv- email: [email protected]+ token: ho3jgjKZXVnnVyVgG7sUBFtvPtXL3a8zFGn+ email: [email protected]special_instructions:currency: USDitem_count: 1@@ -1716,8 +1356,8 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-02-14T17:18:58.752Z'- updated_at: '2026-02-14T17:18:58.876Z'+ created_at: '2026-02-14T19:47:24.980Z'+ updated_at: '2026-02-14T19:47:25.095Z'payment_methods: []schema:"$ref": "#/components/schemas/StoreOrder"@@ -1757,10 +1397,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R633382445+ number: R502200759state: cart- token: HvPSYphQaqYsd6D32FjFMFvVunKQsQTEGYx- email: [email protected]+ token: vyHT8ez2ugRVV1ZRhQkuypz9R7YvHQZE7w8+ email: [email protected]special_instructions:currency: USDitem_count: 1@@ -1783,8 +1423,8 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-02-14T17:18:59.467Z'- updated_at: '2026-02-14T17:18:59.963Z'+ created_at: '2026-02-14T19:47:25.677Z'+ updated_at: '2026-02-14T19:47:26.127Z'payment_methods:- id: pm_UkLWZg9DAJname: Store Credit@@ -1849,10 +1489,10 @@ paths:application/json:example:id: or_gbHJdmfrXB- number: R579308003+ number: R493155655state: payment- token: jtU8mPj9Wg7m4Nc3nZD4fJSdsbv7hsJVPtN- email: [email protected]+ token: CWSQBZar4J6AWaN28M8gzBLAWYcPs5vQtjg+ email: [email protected]special_instructions:currency: USDitem_count: 1@@ -1875,20 +1515,21 @@ paths:total: '29.99'display_total: "$29.99"completed_at:- created_at: '2026-02-14T17:19:01.358Z'- updated_at: '2026-02-14T17:19:01.595Z'+ created_at: '2026-02-14T19:47:27.529Z'+ updated_at: '2026-02-14T19:47:27.732Z'payment_methods: []schema:"$ref": "#/components/schemas/StoreOrder"- "/api/v3/store/orders/{id}/complete":- patch:- summary: Complete the order+ "/api/v3/store/orders":+ post:+ summary: Create a carttags:- Orderssecurity:- api_key: []- bearer_auth: []- description: Completes the order (finalizes the purchase)+ description: |+ Creates a new order (shopping cart). Can be created by guests or authenticated customers.+ Returns an `order_token` that must be used for guest access to the order.parameters:- name: x-spree-api-keyin: header@@ -1898,38 +1539,29 @@ paths:- name: Authorizationin: headerrequired: false- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- - name: order_token- in: query- required: false+ description: Bearer JWT token (optional - for authenticated customers)schema:type: stringresponses:- '200':- description: order completed+ '201':+ description: cart created (authenticated)content:application/json:example:id: or_gbHJdmfrXB- number: R622128321- state: complete- token: mh1j4g8cwF7WTeuCZAnEu6EroS7MbVT8qpm- email: [email protected]+ number: R130962790+ state: cart+ token: 1nM9hfybFbcur9qMdTgevQevG4SsQDC9SCf+ email: [email protected]special_instructions:currency: USD- item_count: 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"+ item_count: 0+ 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'@@ -1940,41 +1572,39 @@ 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-02-14T17:19:02.693Z'- created_at: '2026-02-14T17:19:02.296Z'- updated_at: '2026-02-14T17:19:02.693Z'- payment_methods:- - id: pm_UkLWZg9DAJ- name: Check- description:- type: Spree::PaymentMethod::Check- - id: pm_gbHJdmfrXB- name: Credit Card- description:- type: Spree::Gateway::Bogus+ total: '0.0'+ display_total: "$0.00"+ completed_at:+ created_at: '2026-02-14T19:47:29.767Z'+ updated_at: '2026-02-14T19:47:29.767Z'+ payment_methods: []+ order_token: 1nM9hfybFbcur9qMdTgevQevG4SsQDC9SCfschema:- "$ref": "#/components/schemas/StoreOrder"- '422':- description: cannot complete+ type: object+ allOf:+ - "$ref": "#/components/schemas/StoreOrder"+ - type: object+ properties:+ order_token:+ type: string+ '401':+ description: unauthorized - invalid API keycontent:application/json:example:error:- code: order_already_completed- message: No payment found+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{id}/next":- patch:- summary: Advance to next checkout step+ get:+ summary: List orderstags:- Orderssecurity:- api_key: []bearer_auth: []- description: Advances the order to the next state in the checkout flow+ description: Returns a paginated list of orders for the authenticated customerparameters:- name: x-spree-api-keyin: header@@ -1983,77 +1613,106 @@ paths:type: string- name: Authorizationin: header- required: false+ required: trueschema:type: string- - name: id- in: path- required: true+ - name: page+ in: query+ required: false+ schema:+ type: integer+ - name: per_page+ in: query+ required: false+ schema:+ type: integer+ - name: q[state_eq]+ in: query+ required: false+ description: Filter by order stateschema:type: string- - name: order_token+ - name: q[completed_at_gte]in: queryrequired: false+ description: Filter by completion date (after)schema:type: stringresponses:'200':- description: order advanced- content:- application/json:- example:- id: or_gbHJdmfrXB- number: R801853052- state: address- token: TXY29NH58suQwkmJAZ8tGECtD367vEFu1UQ- email: [email protected]- special_instructions:- currency: USD- 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"- 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-02-14T17:19:04.340Z'- updated_at: '2026-02-14T17:19:04.467Z'- payment_methods: []- schema:- "$ref": "#/components/schemas/StoreOrder"- '422':- description: cannot advance - validation errors+ description: orders foundcontent:application/json:example:- error:- code: order_cannot_transition- message: We are unable to calculate shipping rates for the selected- items.+ data:+ - id: or_UkLWZg9DAJ+ number: R156061788+ state: cart+ token: WBFpQ69VtHRV5QftrNmdXvdyZE6f4PiWKJB+ email: [email protected]+ special_instructions:+ currency: USD+ 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"+ 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-02-14T19:47:30.328Z'+ updated_at: '2026-02-14T19:47:30.431Z'+ payment_methods: []+ 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/StoreOrder"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ '401':+ description: unauthorized - authentication required+ content:+ application/json:+ example:+ error:+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{id}":- get:- summary: Get an order+ "/api/v3/store/orders/{id}/complete":+ patch:+ summary: Complete the ordertags:- Orderssecurity:- api_key: []bearer_auth: []- description: Returns a single order by ID or number. Guests must provide order_token.+ description: Completes the order (finalizes the purchase)parameters:- name: x-spree-api-keyin: header@@ -2068,51 +1727,43 @@ paths:- name: idin: pathrequired: true- description: Order ID (prefixed) or order numberschema:type: string- name: order_tokenin: queryrequired: false- description: Order token for guest access- schema:- type: string- - name: includes- in: query- required: false- description: Include associations (line_items, shipments, payments)schema:type: stringresponses:- '404':- description: not found - order belongs to another user+ '422':+ description: cannot completecontent:application/json:example:error:- code: order_not_found- message: Order not found+ code: order_already_completed+ message: No payment foundschema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: order found (authenticated)+ description: order completedcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R281415027- state: cart- token: U3K88PGLb7mdwroDwhcdvU2v8PuBYjJTyvZ- email: [email protected]+ id: or_gbHJdmfrXB+ number: R647140788+ state: complete+ token: Yr2X4aRYjfLExzdprSQ1SjxkenorGCmknak+ email: [email protected]special_instructions:currency: USDitem_count: 1- shipment_state:- payment_state:- item_total: '10.0'- display_item_total: "$10.00"- ship_total: '100.0'- display_ship_total: "$100.00"+ 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'@@ -2123,14 +1774,23 @@ 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-02-14T17:19:08.254Z'- updated_at: '2026-02-14T17:19:08.378Z'- payment_methods: []+ total: '29.99'+ display_total: "$29.99"+ completed_at: '2026-02-14T19:47:32.991Z'+ created_at: '2026-02-14T19:47:32.667Z'+ updated_at: '2026-02-14T19:47:32.991Z'+ payment_methods:+ - id: pm_UkLWZg9DAJ+ name: Check+ description:+ type: Spree::PaymentMethod::Check+ - id: pm_gbHJdmfrXB+ name: Credit Card+ description:+ type: Spree::Gateway::Bogusschema:"$ref": "#/components/schemas/StoreOrder"+ "/api/v3/store/orders/{id}":patch:summary: Update an ordertags:@@ -2167,10 +1827,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R301256028+ number: R498676948state: cart- token: uLSqFe4UePgQMDe7fozpKRXmMgUQh1HJBog- email: [email protected]+ token: ZrxK7b4eJwNK62He9tdpNS5mmTJUoQcM1YD+ email: [email protected]special_instructions: Leave at doorcurrency: USDitem_count: 1@@ -2193,8 +1853,8 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-02-14T17:19:08.952Z'- updated_at: '2026-02-14T17:19:09.088Z'+ created_at: '2026-02-14T19:47:33.567Z'+ updated_at: '2026-02-14T19:47:33.681Z'payment_methods: []schema:"$ref": "#/components/schemas/StoreOrder"@@ -2286,112 +1946,192 @@ paths:state_abbr:type: stringexample: CA- "/api/v3/store/countries":get:- summary: List checkout countries+ summary: Get an ordertags:- - Countries+ - Orderssecurity:- api_key: []- description: Returns countries available for checkout from the store checkout- zone+ bearer_auth: []+ description: Returns a single order by ID or number. Guests must provide order_token.parameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string+ - name: Authorization+ in: header+ required: false+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Order ID (prefixed) or order number+ schema:+ type: string+ - name: order_token+ in: query+ required: false+ description: Order token for guest access+ schema:+ type: string+ - name: includes+ in: query+ required: false+ description: Include associations (line_items, shipments, payments)+ schema:+ type: stringresponses:'200':- description: countries found+ description: order found (authenticated)content:application/json:example:- data:- - iso: DE- iso3: IS32- name: Germany- states_required: false- zipcode_required: true- default_currency: EUR- default_locale: de- - iso: US- iso3: USA- name: United States of America- states_required: true- zipcode_required: true- default_currency: USD- default_locale: en+ id: or_UkLWZg9DAJ+ number: R287925432+ state: cart+ token: 8XBYVGsUXcRj3FE6piEAxExNDnHKaXNUXwi+ email: [email protected]+ special_instructions:+ currency: USD+ 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"+ 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-02-14T19:47:37.497Z'+ updated_at: '2026-02-14T19:47:37.604Z'+ payment_methods: []schema:- type: object- properties:- data:- type: array- items:- type: object- properties:- iso:- type: string- description: ISO 3166-1 alpha-2 code- iso3:- type: string- description: ISO 3166-1 alpha-3 code- name:- type: string- states_required:- type: boolean- zipcode_required:- type: boolean- required:- - iso- - iso3- - name- - states_required- - zipcode_required- required:- - data- '401':- description: unauthorized+ "$ref": "#/components/schemas/StoreOrder"+ '404':+ description: not found - order belongs to another usercontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: order_not_found+ message: Order not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/countries/{iso}":- get:- summary: Get a country with states+ "/api/v3/store/orders/{id}/next":+ patch:+ summary: Advance to next checkout steptags:- - Countries+ - Orderssecurity:- api_key: []- description: Returns a single country by ISO code with its states+ bearer_auth: []+ description: Advances the order to the next state in the checkout flowparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: iso+ - name: Authorization+ in: header+ required: false+ schema:+ type: string+ - name: idin: pathrequired: true- description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE", "CA")+ schema:+ type: string+ - name: order_token+ in: query+ required: falseschema:type: stringresponses:- '404':- description: country not found+ '200':+ description: order advancedcontent:application/json:example:- error:- code: record_not_found- message: Country not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- '200':+ id: or_gbHJdmfrXB+ number: R886784435+ state: address+ token: t1cN9Df8UnTVz5XrAgdVuunQ19ukoUixy7d+ email: [email protected]+ special_instructions:+ currency: USD+ 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"+ 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-02-14T19:47:38.303Z'+ updated_at: '2026-02-14T19:47:38.416Z'+ payment_methods: []+ schema:+ "$ref": "#/components/schemas/StoreOrder"+ '422':+ description: cannot advance - validation errors+ content:+ application/json:+ example:+ error:+ code: order_cannot_transition+ message: We are unable to calculate shipping rates for the selected+ items.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/countries/{iso}":+ get:+ summary: Get a country with states+ tags:+ - Countries+ security:+ - api_key: []+ description: Returns a single country by ISO code with its states+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: iso+ in: path+ required: true+ description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE", "CA")+ schema:+ type: string+ responses:+ '200':description: country foundcontent:application/json:@@ -2443,134 +2183,158 @@ paths:- states_required- zipcode_required- states- "/api/v3/store/wishlists/{wishlist_id}/items/{id}":- delete:- summary: Remove item from wishlist- tags:- - Wishlists- security:- - api_key: []- bearer_auth: []- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: wishlist_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- responses:'404':- description: item not found+ description: country not foundcontent:application/json:example:error:code: record_not_found- message: Wished item not found- '204':- description: item removed- "/api/v3/store/wishlists/{id}":+ message: Country not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/countries":get:- summary: Get a wishlist+ summary: List checkout countriestags:- - Wishlists+ - Countriessecurity:- api_key: []- bearer_auth: []+ description: Returns countries available for checkout from the store checkout+ zoneparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- - name: includes- in: query- required: false- description: Include wished_items- schema:- type: stringresponses:'200':- description: wishlist found+ description: countries foundcontent:application/json:example:- id: wl_UkLWZg9DAJ- name: My Wishlist- token: HcySek6tYYrDX8WAhtnjpBiA- created_at: '2026-02-14T17:19:11.836Z'- updated_at: '2026-02-14T17:19:11.836Z'- is_default: false- is_private: true+ data:+ - iso: DE+ iso3: IS40+ name: Germany+ states_required: false+ zipcode_required: true+ default_currency: EUR+ default_locale: de+ - iso: US+ iso3: USA+ name: United States of America+ states_required: true+ zipcode_required: true+ default_currency: USD+ default_locale: enschema:- "$ref": "#/components/schemas/StoreWishlist"- '404':- description: wishlist not found+ type: object+ properties:+ data:+ type: array+ items:+ type: object+ properties:+ iso:+ type: string+ description: ISO 3166-1 alpha-2 code+ iso3:+ type: string+ description: ISO 3166-1 alpha-3 code+ name:+ type: string+ states_required:+ type: boolean+ zipcode_required:+ type: boolean+ required:+ - iso+ - iso3+ - name+ - states_required+ - zipcode_required+ required:+ - data+ '401':+ description: unauthorizedcontent:application/json:example:error:- code: record_not_found- message: Wishlist not found+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- delete:- summary: Delete a wishlist+ "/api/v3/store/store":+ get:+ summary: Get current storetags:- - Wishlists+ - Storesecurity:- api_key: []- bearer_auth: []+ description: Returns information about the current store based on the API keyparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:- '204':- description: wishlist deleted- patch:- summary: Update a wishlist+ '401':+ description: unauthorized - invalid API key+ content:+ application/json:+ example:+ error:+ code: invalid_token+ message: Valid API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '200':+ description: store found+ content:+ application/json:+ example:+ id: store_UkLWZg9DAJ+ name: Spree Test Store+ url: www.example.com+ meta_description: Sample store description.+ meta_keywords:+ seo_title:+ default_currency: USD+ code: spree_1+ default: true+ facebook: spreecommerce+ twitter: spreecommerce+ instagram: spreecommerce+ customer_support_email: [email protected]+ default_locale: en+ created_at: '2026-02-14T19:47:04.988Z'+ updated_at: '2026-02-14T19:47:05.133Z'+ default_country_iso: US+ supported_currencies:+ - USD+ - EUR+ - GBP+ favicon_image_url:+ logo_image_url:+ social_image_url:+ supported_locales:+ - en+ payment_methods: []+ schema:+ "$ref": "#/components/schemas/StoreStore"+ "/api/v3/store/orders/{order_id}/coupon_codes/{id}":+ delete:+ summary: Remove coupon codetags:- - Wishlists+ - Coupon Codessecurity:- api_key: []bearer_auth: []+ description: Removes a previously applied coupon code from the order.parameters:- name: x-spree-api-keyin: header@@ -2579,117 +2343,549 @@ paths:type: string- name: Authorizationin: header- required: true+ required: false+ description: Bearer token for authenticated customersschema:type: string- - name: id+ - name: order_idin: pathrequired: true+ description: Order ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Order promotion ID+ schema:+ type: string+ - name: order_token+ in: query+ required: false+ description: Order token for guest accessschema:type: stringresponses:'200':- description: wishlist updated+ description: coupon code removedcontent:application/json:example:- id: wl_UkLWZg9DAJ- name: Updated Name- token: vNS49SptMxAmLwYdyfiLAsdo- created_at: '2026-02-14T17:19:13.708Z'- updated_at: '2026-02-14T17:19:13.806Z'- is_default: false- is_private: true+ id: or_UkLWZg9DAJ+ number: R602639899+ state: cart+ token: CaPcQWxujFBSWBDdQxbPVFpVPjvqEsTY2Ef+ email: [email protected]+ special_instructions:+ currency: USD+ 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"+ 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-02-14T19:47:39.780Z'+ updated_at: '2026-02-14T19:47:40.000Z'+ payment_methods: []schema:- "$ref": "#/components/schemas/StoreWishlist"+ "$ref": "#/components/schemas/StoreOrder"+ '404':+ description: coupon code not found on order+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Order promotion not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/orders/{order_id}/coupon_codes":+ post:+ summary: Apply coupon code+ tags:+ - Coupon Codes+ security:+ - api_key: []+ bearer_auth: []+ description: |+ Applies a coupon code to the order. Supports both promotion coupon codes and gift card codes.+ The code is matched case-insensitively.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: false+ description: Bearer token for authenticated customers+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ - name: order_token+ in: query+ required: false+ description: Order token for guest access+ schema:+ type: string+ responses:+ '422':+ description: invalid coupon code+ content:+ application/json:+ example:+ error:+ code: processing_error+ message: The coupon code you entered doesn't exist. Please try again.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '404':+ description: order not found+ content:+ application/json:+ example:+ error:+ code: order_not_found+ message: Order not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '201':+ description: coupon code applied (promotion)+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ number: R848169888+ state: cart+ token: u3JL3vZx8igAt337UDY783FWiSA4oPtTQTx+ email: [email protected]+ special_instructions:+ currency: USD+ 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: "-10.0"+ display_adjustment_total: "-$10.00"+ promo_total: "-10.0"+ display_promo_total: "-$10.00"+ tax_total: '0.0'+ display_tax_total: "$0.00"+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ additional_tax_total: '0.0'+ display_additional_tax_total: "$0.00"+ total: '100.0'+ display_total: "$100.00"+ completed_at:+ created_at: '2026-02-14T19:47:43.301Z'+ updated_at: '2026-02-14T19:47:43.478Z'+ payment_methods: []+ schema:+ "$ref": "#/components/schemas/StoreOrder"requestBody:content:application/json:schema:type: objectproperties:- name:+ code:type: string- example: Updated Name- is_private:- type: boolean- example: true- is_default:- type: boolean- example: false- "/api/v3/store/wishlists":- post:- summary: Create a wishlist+ example: SAVE10+ description: Coupon code or gift card code to apply+ required:+ - code+ "/api/v3/store/products/{id}":+ get:+ summary: Get a producttags:- - Wishlists+ - Productssecurity:- api_key: []- bearer_auth: []- description: Creates a new wishlist for the customer+ description: Returns a single product by slug or prefix IDparameters:- name: x-spree-api-keyin: headerrequired: true+ description: Publishable API key+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Product slug (e.g., ruby-on-rails-tote) or prefix ID (e.g., product_abc123)schema:type: string- - name: Authorization+ - name: includes+ in: query+ required: false+ description: Comma-separated associations to include+ schema:+ type: string+ responses:+ '404':+ description: product not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Product not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '200':+ description: product found by slug+ content:+ application/json:+ example:+ id: prod_UkLWZg9DAJ+ name: Product 623111+ description: |-+ Sed consectetur officiis officia ab rem. Quae amet blanditiis harum eos consectetur. Maxime fugit laborum dicta saepe velit accusantium officia repellendus. Doloremque fugiat architecto quae temporibus odio beatae quo at.+ Facilis amet officia rerum officiis iure assumenda. Repudiandae aut fugiat fuga dolor voluptatum. Id delectus libero illo tenetur.+ Necessitatibus repudiandae saepe quis cum ab. Magni velit rerum eius modi ex saepe eum. Voluptatibus labore delectus velit neque laborum odit. Beatae maiores cumque saepe inventore qui dolores. Tempore odio inventore tenetur vero.+ Dolore architecto atque illo non veritatis earum totam quibusdam. Minima excepturi repudiandae placeat alias temporibus. Pariatur similique velit consequatur quidem ea voluptas mollitia eveniet. Laudantium repudiandae nisi consectetur culpa officiis.+ slug: product-623111+ meta_description:+ meta_keywords:+ variant_count: 1+ available_on: '2025-02-14T19:47:44.835Z'+ created_at: '2026-02-14T19:47:44.852Z'+ updated_at: '2026-02-14T19:47:44.926Z'+ purchasable: true+ in_stock: false+ backorderable: true+ available: true+ default_variant_id: variant_gbHJdmfrXB+ thumbnail_url:+ tags: []+ price:+ id: price_gbHJdmfrXB+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ schema:+ "$ref": "#/components/schemas/StoreProduct"+ "/api/v3/store/products/filters":+ get:+ summary: Get product filters+ tags:+ - Products+ security:+ - api_key: []+ description: |+ Returns available filters for products with their options and counts.+ Use this endpoint to build filter UIs for product listing pages.++ The filters are context-aware - when a taxon_id is provided, only filters+ relevant to products in that taxon are returned.+ parameters:+ - name: x-spree-api-keyin: headerrequired: true+ description: Publishable API key+ schema:+ type: string+ - name: taxon_id+ in: query+ required: false+ description: Scope filters to products in this taxon (prefix ID)+ schema:+ type: string+ - name: q[name_cont]+ in: query+ required: false+ description: Filter by name containing stringschema:type: stringresponses:- '422':- description: validation error+ '200':+ description: filters scoped to taxon+ content:+ application/json:+ example:+ filters:+ - id: price+ type: price_range+ label: Price+ min: 19.99+ max: 19.99+ currency: USD+ - id: availability+ type: availability+ label: availability+ options:+ - id: in_stock+ label: In Stock+ count: 0+ - id: out_of_stock+ label: Out of Stock+ count: 2+ - id: opt_UkLWZg9DAJ+ type: option+ label: Size+ name: size+ options:+ - id: optval_UkLWZg9DAJ+ label: S+ name: small+ position: 1+ count: 1+ - id: taxons+ type: taxon+ label: Category+ options:+ - id: txn_p6klVeMgbn+ label: Shirts+ permalink: taxonomy-22/taxon-7/shirts+ count: 2+ sort_options:+ - id: manual+ label: Manual+ - id: best-selling+ label: Best Selling+ - id: price-low-to-high+ label: Price (low-high)+ - id: price-high-to-low+ label: Price (high-low)+ - id: newest-first+ label: Newest+ - id: oldest-first+ label: Oldest+ - id: name-a-z+ label: Alphabetically, A-Z+ - id: name-z-a+ label: Alphabetically, Z-A+ default_sort: manual+ total_count: 2+ schema:+ type: object+ properties:+ filters:+ type: array+ description: Available filters (price_range, availability, option,+ taxon)+ items:+ type: object+ sort_options:+ type: array+ description: Available sort options+ items:+ type: object+ properties:+ id:+ type: string+ label:+ type: string+ required:+ - id+ - label+ default_sort:+ type: string+ description: Default sort option ID+ total_count:+ type: integer+ description: Total products matching current filters+ required:+ - filters+ - sort_options+ - default_sort+ - total_count+ '401':+ description: unauthorized - invalid or missing API keycontent:application/json:example:error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- '201':- description: wishlist created+ "/api/v3/store/products":+ get:+ summary: List products+ tags:+ - Products+ security:+ - api_key: []+ description: Returns a paginated list of active products for the current store+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ description: Publishable API key+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: 'Page number (default: 1)'+ schema:+ type: integer+ - name: per_page+ in: query+ required: false+ description: 'Number of items per page (default: 25, max: 100)'+ schema:+ type: integer+ - name: q[name_cont]+ in: query+ required: false+ description: Filter by name containing string+ schema:+ type: string+ - name: q[taxons_id_eq]+ in: query+ required: false+ description: Filter by taxon ID+ schema:+ type: string+ - name: includes+ in: query+ required: false+ description: Comma-separated associations to include (variants, images, taxons,+ option_types)+ schema:+ type: string+ responses:+ '401':+ description: unauthorized - invalid or missing API keycontent:application/json:example:- id: wl_gbHJdmfrXB- name: Birthday Ideas- token: jhkGW62wifRNYmKrBiVsc218- created_at: '2026-02-14T17:19:15.124Z'- updated_at: '2026-02-14T17:19:15.124Z'- is_default: false- is_private: true+ error:+ code: invalid_token+ message: Valid API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '200':+ description: products found+ content:+ application/json:+ example:+ data:+ - id: prod_UkLWZg9DAJ+ name: Product 867122+ description: |-+ Minus quo natus unde enim perferendis praesentium corporis. Id fuga modi enim sequi. Officiis temporibus rem ab ipsam.+ Reiciendis inventore voluptates eaque facere officia exercitationem. Accusamus fugiat alias ipsum nemo dicta nobis. Voluptatibus itaque voluptates ipsam omnis.+ slug: product-867122+ meta_description:+ meta_keywords:+ variant_count: 1+ available_on: '2025-02-14T19:47:47.512Z'+ created_at: '2026-02-14T19:47:47.526Z'+ updated_at: '2026-02-14T19:47:47.602Z'+ purchasable: true+ in_stock: false+ backorderable: true+ available: true+ default_variant_id: variant_gbHJdmfrXB+ thumbnail_url:+ tags: []+ price:+ id: price_gbHJdmfrXB+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ - id: prod_gbHJdmfrXB+ name: Product 871397+ description: |-+ Illum saepe explicabo ratione magni. Reprehenderit accusantium deleniti dolores similique. Dignissimos sed vero accusamus assumenda facilis at commodi. Veniam ad atque modi quos animi.+ Repudiandae consequatur facilis sit et magnam quas. Quos ipsa itaque molestias omnis culpa perspiciatis voluptatibus placeat. A enim voluptatibus vitae repellat temporibus ab est eius. Est illum quisquam minus sit ab quam.+ Adipisci facilis illo sapiente reprehenderit aliquam tempora voluptates. Quos quis voluptate dignissimos molestias magni quasi ducimus. Sequi nobis tempora quaerat occaecati ut eligendi blanditiis ipsum.+ slug: product-871397+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on: '2025-02-14T19:47:47.621Z'+ created_at: '2026-02-14T19:47:47.631Z'+ updated_at: '2026-02-14T19:47:47.657Z'+ purchasable: true+ in_stock: false+ backorderable: true+ available: true+ default_variant_id: variant_EfhxLZ9ck8+ thumbnail_url:+ tags: []+ price:+ id: price_EfhxLZ9ck8+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ meta:+ page: 1+ limit: 25+ count: 2+ pages: 1+ from: 1+ to: 2+ in: 2+ previous:+ next:schema:- "$ref": "#/components/schemas/StoreWishlist"- requestBody:- content:- application/json:- schema:- type: object- properties:- name:- type: string- example: Birthday Ideas- is_private:- type: boolean- example: true- is_default:- type: boolean- example: false- required:- - name+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StoreProduct"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ "/api/v3/store/orders/{order_id}/payment_methods":get:- summary: List wishlists+ summary: List available payment methodstags:- - Wishlists+ - Payment Methodssecurity:- api_key: []bearer_auth: []- description: Returns all wishlists for the authenticated customer+ description: Returns payment methods available for the order based on store+ configuration and order stateparameters:- name: x-spree-api-keyin: header@@ -2698,19 +2894,19 @@ paths:type: string- name: Authorizationin: header- required: true+ required: falseschema:type: string- - name: page- in: query- required: false+ - name: order_id+ in: path+ required: trueschema:- type: integer- - name: per_page+ type: string+ - name: order_tokenin: queryrequired: falseschema:- type: integer+ type: stringresponses:'401':description: unauthorized@@ -2718,51 +2914,53 @@ paths:application/json:example:error:- code: authentication_required- message: Authentication required+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: wishlists found+ description: payment methods foundcontent:application/json:example:data:- - id: wl_UkLWZg9DAJ- name: My Wishlist- token: KyximyUTwdPsUoNGByJ3Y2t5- created_at: '2026-02-14T17:19:16.319Z'- updated_at: '2026-02-14T17:19:16.319Z'- is_default: false- is_private: true+ - id: pm_UkLWZg9DAJ+ name: Credit Card+ description:+ type: Spree::Gateway::Bogusmeta:- page: 1- limit: 25count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:schema:type: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/StoreWishlist"+ "$ref": "#/components/schemas/StorePaymentMethod"meta:- "$ref": "#/components/schemas/PaginationMeta"- "/api/v3/store/wishlists/{wishlist_id}/items":- post:- summary: Add item to wishlist+ type: object+ 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"+ "/api/v3/store/orders/{order_id}/line_items/{id}":+ patch:+ summary: Update line item quantitytags:- - Wishlists+ - Line Itemssecurity:- api_key: []bearer_auth: []- description: Adds a variant to the wishlist+ description: Updates the quantity of a line item in the cartparameters:- name: x-spree-api-keyin: header@@ -2771,84 +2969,131 @@ paths:type: string- name: Authorizationin: header+ required: false+ schema:+ type: string+ - name: order_id+ in: pathrequired: trueschema:type: string- - name: wishlist_id+ - name: idin: pathrequired: true+ description: Line item ID+ schema:+ type: string+ - name: order_token+ in: query+ required: falseschema:type: stringresponses:- '201':- description: item added+ '200':+ description: line item updatedcontent:application/json:example:- id: wi_gbHJdmfrXB- variant_id: variant_gbHJdmfrXB- wishlist_id: wl_UkLWZg9DAJ- quantity: 1- created_at: '2026-02-14T17:19:17.066Z'- updated_at: '2026-02-14T17:19:17.066Z'- variant:- id: variant_gbHJdmfrXB- product_id: prod_gbHJdmfrXB- sku: SKU-56- is_master: true- options_text: ''- track_inventory: true- image_count: 0- created_at: '2026-02-14T17:19:17.026Z'- updated_at: '2026-02-14T17:19:17.047Z'- thumbnail:- purchasable: true- in_stock: false- backorderable: true- weight: 0.0- height:- width:- depth:- price:- id: price_gbHJdmfrXB- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:- option_values: []+ id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 5+ name: Product 934666+ slug: product-934666+ options_text: ''+ price: '19.99'+ display_price: "$19.99"+ total: '99.95'+ display_total: "$99.95"+ 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: '99.95'+ display_pre_tax_amount: "$99.95"+ discounted_amount: '99.95'+ display_discounted_amount: "$99.95"+ display_compare_at_amount: "$0.00"+ created_at: '2026-02-14T19:47:50.238Z'+ updated_at: '2026-02-14T19:47:50.269Z'+ compare_at_amount:+ thumbnail_url:+ option_values: []+ digital_links: []schema:- "$ref": "#/components/schemas/StoreWishedItem"+ "$ref": "#/components/schemas/StoreLineItem"requestBody:content:application/json:schema:type: objectproperties:- variant_id:- type: string- example: variant_abc123quantity:type: integer- example: 1+ minimum: 1+ example: 5required:- - variant_id- "/api/v3/store/cart/associate":- patch:- summary: Associate guest cart with authenticated user+ - quantity+ delete:+ summary: Remove line item from carttags:- - Cart+ - Line Itemssecurity:- api_key: []bearer_auth: []- description: |- Associates a guest cart with the currently authenticated user.- Requires both JWT authentication and an order token.- The order must not be completed and must not belong to another user.+ description: Removes a line item from the order+ 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: id+ in: path+ required: true+ schema:+ type: string+ - name: order_token+ in: query+ required: false+ schema:+ type: string+ responses:+ '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"+ '204':+ description: line item removed+ "/api/v3/store/orders/{order_id}/line_items":+ post:+ summary: Add item to cart+ tags:+ - Line Items+ 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.parameters:- name: x-spree-api-keyin: header@@ -2857,461 +3102,348 @@ paths:type: string- name: Authorizationin: header- required: true- description: Bearer JWT token (required)+ required: false+ description: Bearer token for authenticated customersschema:type: string- - name: x-spree-order-token- in: header- required: false- description: Order token (can also be passed as query param)+ - name: order_id+ in: path+ required: true+ description: Order ID or numberschema:type: string- name: order_tokenin: queryrequired: false- description: Order token (alternative to header)+ description: Order token for guest accessschema:type: stringresponses:'404':- description: cart already completed- content:- application/json:- example:- error:- code: order_not_found- message: Order not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- '401':- description: unauthorized - JWT required+ description: variant not foundcontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: variant_not_found+ message: Variant not foundschema:"$ref": "#/components/schemas/ErrorResponse"- '200':- description: cart associated successfully+ '201':+ description: line item createdcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R972232618- state: cart- token: 1ejBzeKGHSHNdgsZBHoLbvSG1W75B1TFGS3- email: [email protected]- special_instructions:- currency: USD- 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"+ id: li_gbHJdmfrXB+ variant_id: variant_gbHJdmfrXB+ quantity: 2+ name: Product 981861+ slug: product-981861+ options_text: ''+ price: '19.99'+ display_price: "$19.99"+ total: '39.98'+ display_total: "$39.98"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-02-14T17:19:18.764Z'- updated_at: '2026-02-14T17:19:18.886Z'- line_items:- - id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1- name: Product 597288- slug: product-597288- 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-02-14T17:19:18.836Z'- updated_at: '2026-02-14T17:19:18.836Z'- compare_at_amount:- thumbnail_url:- option_values: []- payment_methods: []+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ promo_total: '0.0'+ display_promo_total: "$0.00"+ pre_tax_amount: '39.98'+ display_pre_tax_amount: "$39.98"+ discounted_amount: '39.98'+ display_discounted_amount: "$39.98"+ display_compare_at_amount: "$0.00"+ created_at: '2026-02-14T19:47:52.938Z'+ updated_at: '2026-02-14T19:47:52.938Z'+ compare_at_amount:+ thumbnail_url:+ option_values: []+ digital_links: []schema:- type: object- allOf:- - "$ref": "#/components/schemas/StoreOrder"- - type: object- properties:- token:- type: string- "/api/v3/store/cart":- get:- summary: Get current cart+ "$ref": "#/components/schemas/StoreLineItem"+ 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)'+ required:+ - variant_id+ "/api/v3/store/auth/register":+ post:+ summary: Registertags:- - Cart+ - Authenticationsecurity:- api_key: []- bearer_auth: []- description: |- Returns the current shopping cart (incomplete order).- Authenticate via JWT token for logged-in users or via order_token parameter for guests.+ description: Creates a new customer account and returns a JWT tokenparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: false- description: Bearer JWT token for authenticated customers- schema:- type: string- - name: order_token- in: query- required: false- description: Order token for guest checkout- schema:- type: stringresponses:- '200':- description: cart found (authenticated)+ '422':+ description: email already takencontent:application/json:example:- id: or_UkLWZg9DAJ- number: R380109999- state: cart- token: qsA2EsWMoWchgSSJwVtbBE5Jh9NRp73YTUz- email: [email protected]- special_instructions:- currency: USD- 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"- 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-02-14T17:19:21.176Z'- updated_at: '2026-02-14T17:19:21.300Z'- line_items:- - id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1- name: Product 621779- slug: product-621779- 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-02-14T17:19:21.246Z'- updated_at: '2026-02-14T17:19:21.246Z'- compare_at_amount:- thumbnail_url:- option_values: []- payment_methods: []+ error:+ code: validation_error+ message: Email has already been taken+ details:+ email:+ - has already been takenschema:- type: object- allOf:- - "$ref": "#/components/schemas/StoreOrder"- - type: object- properties:- token:- type: string- '404':- description: no cart found+ "$ref": "#/components/schemas/ErrorResponse"+ '201':+ description: registration successfulcontent:application/json:example:- error:- code: order_not_found- message: Order not found+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE4NDg3NH0.HeqmGqikQqAzGFp00HBHKajvzp7HlZTgALg1emsN_nU+ user:+ id: cus_UkLWZg9DAJ+ email: [email protected]+ first_name: John+ last_name: Doe+ created_at: '2026-02-14T19:47:54.212Z'+ updated_at: '2026-02-14T19:47:54.212Z'+ addresses: []+ default_billing_address:+ default_shipping_address:schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/digitals/{token}":- get:- summary: Download a digital product+ "$ref": "#/components/schemas/AuthResponse"+ 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+ required:+ - password+ "/api/v3/store/auth/refresh":+ post:+ summary: Refresh tokentags:- - Digitals+ - Authenticationsecurity:- api_key: []- description: |- Downloads a digital product file using the digital link token.- The token is provided in the order confirmation or digital links list.- Each download increments the access counter. Downloads may be limited by- store settings (number of downloads and/or time-based expiration).+ bearer_auth: []+ description: Generates a new JWT token for the authenticated userparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: token- in: path+ - name: Authorization+ in: headerrequired: true- description: Digital link token+ description: Bearer tokenschema:type: stringresponses:- '404':- description: digital link not found- content:- application/json:- example:- error:- code: record_not_found- message: Digital link not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- application/octet-stream:- schema:- "$ref": "#/components/schemas/ErrorResponse"- '403':- description: download link expired or limit exceeded+ '200':+ description: token refreshedcontent:application/json:example:- error:- code: digital_link_expired- message: Download link expired or invalid- schema:- "$ref": "#/components/schemas/ErrorResponse"- application/octet-stream:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE4NDg3NH0.HeqmGqikQqAzGFp00HBHKajvzp7HlZTgALg1emsN_nU+ user:+ id: cus_UkLWZg9DAJ+ email: [email protected]+ first_name: Coletta+ last_name: Cruickshank+ created_at: '2026-02-14T19:47:54.491Z'+ updated_at: '2026-02-14T19:47:54.491Z'+ addresses: []+ default_billing_address:+ default_shipping_address:schema:- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/AuthResponse"'401':- description: unauthorized - invalid API key+ description: missing or invalid tokencontent:application/json:example:error:- code: invalid_token- message: Valid API key required- schema:- "$ref": "#/components/schemas/ErrorResponse"- application/octet-stream:+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- '200':- description: file downloaded- content:- application/json: {}- "/api/v3/store/customer/addresses/{id}":- patch:- summary: Update an address+ "/api/v3/store/auth/login":+ post:+ summary: Logintags:- - Addresses+ - Authenticationsecurity:- api_key: []- bearer_auth: []+ description: Authenticates a customer with email/password and returns a JWT+ tokenparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:+ '401':+ description: missing API key+ content:+ application/json:+ example:+ error:+ code: invalid_token+ message: Valid API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"'200':- description: address updated+ description: login successfulcontent:application/json:example:- id: addr_EfhxLZ9ck8- firstname: John- lastname: Doe- full_name: John Doe- address1: 224 Lovely Street- address2: Northwest- city: Los Angeles- zipcode: '35005'- phone: 555-555-0199- company: Company- country_name: NAME_42- country_iso: I42- state_text: STATE_ABBR_222- state_abbr: STATE_ABBR_222- state_name: STATE_NAME_222+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE4NDg3NX0.ttEJoVJuekYxHjkoXrwJNZcE_n0r1ycJYcY4W08pJN4+ user:+ id: cus_UkLWZg9DAJ+ email: [email protected]+ first_name: Michal+ last_name: Sawayn+ created_at: '2026-02-14T19:47:55.346Z'+ updated_at: '2026-02-14T19:47:55.346Z'+ addresses: []+ default_billing_address:+ default_shipping_address:schema:- "$ref": "#/components/schemas/StoreAddress"+ "$ref": "#/components/schemas/AuthResponse"requestBody:content:application/json:schema:type: objectproperties:- firstname:- type: string- example: John- lastname:+ provider:type: string- example: Doe- address1:+ example: email+ description: 'Authentication provider (default: email)'+ email:type: string- example: 456 Oak Ave- city:+ format: email+ example: [email protected]+ password:type: string- example: Los Angeles+ example: password123+ required:+ - password+ "/api/v3/store/digitals/{token}":get:- summary: Get an address+ summary: Download a digital producttags:- - Addresses+ - Digitalssecurity:- api_key: []- bearer_auth: []+ description: |+ Downloads a digital product file using the digital link token.+ The token is provided in the order confirmation or digital links list.+ 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id+ - name: tokenin: pathrequired: true+ description: Digital link tokenschema:type: stringresponses:- '200':- description: address found+ '404':+ description: digital link not foundcontent:application/json:example:- id: addr_EfhxLZ9ck8- firstname: John- lastname: Doe- full_name: John Doe- address1: 227 Lovely Street- address2: Northwest- city: Herndon- zipcode: '35005'- phone: 555-555-0199- company: Company- country_name: NAME_43- country_iso: I43- state_text: STATE_ABBR_225- state_abbr: STATE_ABBR_225- state_name: STATE_NAME_225+ error:+ code: record_not_found+ message: Digital link not foundschema:- "$ref": "#/components/schemas/StoreAddress"- '404':- description: address not found+ "$ref": "#/components/schemas/ErrorResponse"+ application/octet-stream:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '401':+ description: unauthorized - invalid API keycontent:application/json:example:error:- code: record_not_found- message: Address not found+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- delete:- summary: Delete an address- tags:- - Addresses- security:- - api_key: []- bearer_auth: []- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- responses:- '204':- description: address deleted- '404':- description: address not found+ application/octet-stream:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '200':+ description: file downloaded+ content:+ application/json: {}+ '403':+ description: download link expired or limit exceededcontent:application/json:example:error:- code: record_not_found- message: Address not found+ code: digital_link_expired+ message: Download link expired or invalidschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/customer/addresses":- post:- summary: Create an address+ application/octet-stream:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/customer":+ patch:+ summary: Update current customer profiletags:- - Addresses+ - Customerssecurity:- api_key: []bearer_auth: []- description: Adds a new address to the customer address book+ description: Updates the profile of the currently authenticated customerparameters:- name: x-spree-api-keyin: header@@ -3320,32 +3452,86 @@ paths:type: string- name: Authorizationin: header- required: true- schema:- type: string- responses:- '201':- description: address created- content:- application/json:- example:- id: addr_VqXmZF31wY- firstname: John- lastname: Doe- full_name: John Doe- address1: 123 Main St- address2:- city: New York- zipcode: '10001'- phone: "+1 555 123 4567"- company:- country_name: NAME_47- country_iso: I47- state_text: STATE_ABBR_237- state_abbr: STATE_ABBR_237- state_name: STATE_NAME_237+ required: true+ schema:+ type: string+ responses:+ '200':+ description: profile updated+ content:+ application/json:+ example:+ id: cus_UkLWZg9DAJ+ email: [email protected]+ first_name: Updated+ last_name: Name+ created_at: '2026-02-14T19:47:59.322Z'+ updated_at: '2026-02-14T19:47:59.621Z'+ addresses:+ - id: addr_gbHJdmfrXB+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 235 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_245+ state_abbr: STATE_ABBR_245+ state_name: STATE_NAME_245+ - id: addr_UkLWZg9DAJ+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 234 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_244+ state_abbr: STATE_ABBR_244+ state_name: STATE_NAME_244+ default_billing_address:+ id: addr_gbHJdmfrXB+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 235 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_245+ state_abbr: STATE_ABBR_245+ state_name: STATE_NAME_245+ default_shipping_address:+ id: addr_UkLWZg9DAJ+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 234 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_244+ state_abbr: STATE_ABBR_244+ state_name: STATE_NAME_244schema:- "$ref": "#/components/schemas/StoreAddress"+ "$ref": "#/components/schemas/StoreCustomer"'422':description: validation errorcontent:@@ -3353,21 +3539,9 @@ paths:example:error:code: validation_error- message: First Name can't be blank, Last Name can't be blank, Address- can't be blank, City can't be blank, Country can't be blank, and- Zip Code can't be blank+ message: Email can't be blankdetails:- firstname:- - can't be blank- lastname:- - can't be blank- address1:- - can't be blank- city:- - can't be blank- country:- - can't be blank- zipcode:+ email:- can't be blankschema:"$ref": "#/components/schemas/ErrorResponse"@@ -3377,58 +3551,36 @@ paths:schema:type: objectproperties:- firstname:+ first_name:type: stringexample: John- lastname:+ last_name:type: stringexample: Doe- address1:- type: string- example: 123 Main St- address2:+ email:type: string- example: Apt 4B- city:+ format: email+ example: [email protected]+ password:type: string- example: New York- zipcode:+ example: newpassword123+ password_confirmation:type: string- example: '10001'+ example: newpassword123+ accepts_email_marketing:+ type: boolean+ example: truephone:type: stringexample: "+1 555 123 4567"- company:- type: string- example: Acme Inc- country_iso:- type: string- example: US- description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")- state_abbr:- type: string- example: NY- description: ISO 3166-2 subdivision code without country prefix- (e.g., "CA", "NY")- state_name:- type: string- example: New York- description: State name - for countries without predefined states- required:- - firstname- - lastname- - address1- - city- - zipcode- - country_isoget:- summary: List customer addresses+ summary: Get current customer profiletags:- - Addresses+ - Customerssecurity:- api_key: []bearer_auth: []- description: Returns all addresses in the customer address book+ description: Returns the profile of the currently authenticated customerparameters:- name: x-spree-api-keyin: header@@ -3438,45 +3590,52 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer JWT tokenschema:type: string- - name: page- in: query- required: false- schema:- type: integer- - name: per_page- in: query- required: false- schema:- type: integerresponses:+ '401':+ description: unauthorized - invalid token+ content:+ application/json:+ example:+ error:+ code: authentication_required+ message: Authentication required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"'200':- description: addresses found+ description: profile foundcontent:application/json:example:- data:- - id: addr_EfhxLZ9ck8+ id: cus_UkLWZg9DAJ+ email: [email protected]+ first_name: Andrew+ last_name: Zemlak+ created_at: '2026-02-14T19:48:00.490Z'+ updated_at: '2026-02-14T19:48:00.781Z'+ addresses:+ - id: addr_gbHJdmfrXBfirstname: Johnlastname: Doefull_name: John Doe- address1: 245 Lovely Street+ address1: 239 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'phone: 555-555-0199company: Company- country_name: NAME_49- country_iso: I49- state_text: STATE_ABBR_243- state_abbr: STATE_ABBR_243- state_name: STATE_NAME_243- - id: addr_gbHJdmfrXB+ country_name: United States of America+ country_iso: US+ state_text: STATE_ABBR_249+ state_abbr: STATE_ABBR_249+ state_name: STATE_NAME_249+ - id: addr_UkLWZg9DAJfirstname: Johnlastname: Doefull_name: John Doe- address1: 244 Lovely Street+ address1: 238 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -3484,14 +3643,15 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_245- state_abbr: STATE_ABBR_245- state_name: STATE_NAME_245- - id: addr_UkLWZg9DAJ+ state_text: STATE_ABBR_248+ state_abbr: STATE_ABBR_248+ state_name: STATE_NAME_248+ default_billing_address:+ id: addr_gbHJdmfrXBfirstname: Johnlastname: Doefull_name: John Doe- address1: 243 Lovely Street+ address1: 239 Lovely Streetaddress2: Northwestcity: Herndonzipcode: '35005'@@ -3499,38 +3659,27 @@ paths:company: Companycountry_name: United States of Americacountry_iso: US- state_text: STATE_ABBR_244- state_abbr: STATE_ABBR_244- state_name: STATE_NAME_244- 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/StoreAddress"- meta:- "$ref": "#/components/schemas/PaginationMeta"- '401':- description: unauthorized- content:- application/json:- example:- error:- code: authentication_required- message: Authentication required+ state_text: STATE_ABBR_249+ state_abbr: STATE_ABBR_249+ state_name: STATE_NAME_249+ default_shipping_address:+ id: addr_UkLWZg9DAJ+ firstname: John+ lastname: Doe+ full_name: John Doe+ address1: 238 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_248+ state_abbr: STATE_ABBR_248+ state_name: STATE_NAME_248schema:- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/StoreCustomer""/api/v3/store/orders/{order_id}/payments":parameters:- name: x-spree-api-key@@ -3558,16 +3707,6 @@ paths:bearer_auth: []description: Returns a list of payments for the specified orderresponses:- '404':- description: order not found- content:- application/json:- example:- error:- code: order_not_found- message: Order not found- schema:- "$ref": "#/components/schemas/ErrorResponse"'200':description: payments foundcontent:@@ -3578,11 +3717,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: PBB3PIAM+ number: PKVGMSI0amount: '110.0'display_amount: "$110.00"- created_at: '2026-02-14T17:19:31.164Z'- updated_at: '2026-02-14T17:19:31.164Z'+ created_at: '2026-02-14T19:48:01.510Z'+ updated_at: '2026-02-14T19:48:01.510Z'payment_method:id: pm_UkLWZg9DAJname: Credit Card@@ -3598,6 +3737,16 @@ paths:"$ref": "#/components/schemas/StorePayment"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""/api/v3/store/orders/{order_id}/payments/{id}":parameters:- name: x-spree-api-key@@ -3626,21 +3775,11 @@ paths:summary: Get paymenttags:- Payments- security:- - api_key: []- bearer_auth: []- description: Returns a single payment by ID- responses:- '404':- description: payment not found- content:- application/json:- example:- error:- code: record_not_found- message: Payment not found- schema:- "$ref": "#/components/schemas/ErrorResponse"+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single payment by ID+ responses:'200':description: payment foundcontent:@@ -3650,11 +3789,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: PKXQ827O+ number: P8SGVUWGamount: '110.0'display_amount: "$110.00"- created_at: '2026-02-14T17:19:32.593Z'- updated_at: '2026-02-14T17:19:32.593Z'+ created_at: '2026-02-14T19:48:02.881Z'+ updated_at: '2026-02-14T19:48:02.881Z'payment_method:id: pm_UkLWZg9DAJname: Credit Card@@ -3662,41 +3801,56 @@ paths:type: Spree::Gateway::Bogusschema:"$ref": "#/components/schemas/StorePayment"- "/api/v3/store/products/filters":+ '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/taxons/{id}":get:- summary: Get product filters+ summary: Get a taxontags:- - Products+ - Taxonssecurity:- api_key: []- description: |- Returns available filters for products with their options and counts.- Use this endpoint to build filter UIs for product listing pages.-- The filters are context-aware - when a taxon_id is provided, only filters- relevant to products in that taxon are returned.+ description: Returns a single taxon by permalink or prefix IDparameters:- name: x-spree-api-keyin: headerrequired: true- description: Publishable API keyschema:type: string- - name: taxon_id- in: query- required: false- description: Scope filters to products in this taxon (prefix ID)+ - name: id+ in: path+ required: true+ description: Taxon permalink (e.g., categories/clothing/shirts) or prefix+ ID (e.g., taxon_abc123)schema:type: string- - name: q[name_cont]+ - name: includesin: queryrequired: false- description: Filter by name containing string+ description: Include associations (children, products, parent)schema:type: stringresponses:+ '404':+ description: taxon not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Taxon not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"'401':- description: unauthorized - invalid or missing API key+ description: unauthorizedcontent:application/json:example:@@ -3706,322 +3860,244 @@ paths:schema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: filters retrieved successfully+ description: taxon found by prefix IDcontent:application/json:example:- filters:- - id: price- type: price_range- label: Price- min: 19.99- max: 19.99- currency: USD- - id: availability- type: availability- label: availability- options:- - id: in_stock- label: In Stock- count: 0- - id: out_of_stock- label: Out of Stock- count: 2- - id: opt_UkLWZg9DAJ- type: option- label: Size- name: size- options:- - id: optval_UkLWZg9DAJ- label: S- name: small- position: 1- count: 1- sort_options:- - id: manual- label: Manual- - id: best-selling- label: Best Selling- - id: price-low-to-high- label: Price (low-high)- - id: price-high-to-low- label: Price (high-low)- - id: newest-first- label: Newest- - id: oldest-first- label: Oldest- - id: name-a-z- label: Alphabetically, A-Z- - id: name-z-a- label: Alphabetically, Z-A- default_sort: manual- total_count: 2+ id: txn_AXs1igzRC6+ name: taxon_23+ permalink: taxonomy-34/taxon-23+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 1+ created_at: '2026-02-14T19:48:04.412Z'+ updated_at: '2026-02-14T19:48:04.427Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: falseschema:- type: object- properties:- filters:- type: array- items:- type: object- description: Available filters (price_range, availability, option,- taxon)- sort_options:- type: array- items:- type: object- properties:- id:- type: string- label:- type: string- required:- - id- - label- description: Available sort options- default_sort:- type: string- description: Default sort option ID- total_count:- type: integer- description: Total products matching current filters- required:- - filters- - sort_options- - default_sort- - total_count- "/api/v3/store/products/{id}":+ "$ref": "#/components/schemas/StoreTaxon"+ "/api/v3/store/orders/{order_id}/shipments":get:- summary: Get a product+ summary: List shipments for an ordertags:- - Products+ - Shipmentssecurity:- api_key: []- description: Returns a single product by slug or prefix ID+ bearer_auth: []+ description: Returns all shipments associated with the orderparameters:- name: x-spree-api-keyin: headerrequired: true- description: Publishable API keyschema:type: string- - name: id+ - name: Authorization+ in: header+ required: false+ schema:+ type: string+ - name: order_idin: pathrequired: true- description: Product slug (e.g., ruby-on-rails-tote) or prefix ID (e.g., product_abc123)schema:type: string- - name: includes+ - name: tokenin: queryrequired: false- description: Comma-separated associations to include+ description: Order token for guest accessschema:type: stringresponses:'404':- description: draft product not visible+ description: order not foundcontent:application/json:example:error:- code: record_not_found- message: Product not found+ code: order_not_found+ message: Order not foundschema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: product found by slug+ description: shipments foundcontent:application/json:example:- id: prod_UkLWZg9DAJ- name: Product 1033316- description: Maiores consequuntur nulla voluptatibus alias dignissimos- dicta ut. Rerum accusamus saepe beatae ab. Expedita delectus blanditiis- animi consectetur dolor. Voluptate aliquid recusandae est laudantium- culpa. Dicta quos ea quaerat vitae consequatur provident.- slug: product-1033316- meta_description:- meta_keywords:- variant_count: 1- available_on: '2025-02-14T17:19:36.044Z'- created_at: '2026-02-14T17:19:36.059Z'- updated_at: '2026-02-14T17:19:36.133Z'- purchasable: true- in_stock: false- backorderable: true- available: true- default_variant_id: variant_gbHJdmfrXB- thumbnail_url:- tags: []- price:- id: price_gbHJdmfrXB- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:+ data:+ - id: ship_UkLWZg9DAJ+ number: H93703696292+ state: pending+ tracking: U10000+ tracking_url:+ cost: '100.0'+ display_cost: "$100.00"+ shipped_at:+ created_at: '2026-02-14T19:48:06.012Z'+ updated_at: '2026-02-14T19:48:06.036Z'+ shipping_method:+ id: shpm_UkLWZg9DAJ+ name: UPS Ground+ code: UPS_GROUND+ stock_location:+ id: sloc_UkLWZg9DAJ+ state_abbr: STATE_ABBR_270+ name: Klara Volkman+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_iso: US+ country_name: United States of America+ state_text: STATE_ABBR_270+ 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:- "$ref": "#/components/schemas/StoreProduct"- "/api/v3/store/products":- get:- summary: List products+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StoreShipment"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ "/api/v3/store/orders/{order_id}/shipments/{id}":+ patch:+ summary: Select shipping rate for shipmenttags:- - Products+ - Shipmentssecurity:- api_key: []- description: Returns a paginated list of active products for the current store+ bearer_auth: []+ description: Selects a shipping rate for the shipmentparameters:- name: x-spree-api-keyin: headerrequired: true- description: Publishable API keyschema:type: string- - name: page- in: query- required: false- description: 'Page number (default: 1)'- schema:- type: integer- - name: per_page- in: query+ - name: Authorization+ in: headerrequired: false- description: 'Number of items per page (default: 25, max: 100)'schema:- type: integer- - name: q[name_cont]- in: query- required: false- description: Filter by name containing string+ type: string+ - name: order_id+ in: path+ required: trueschema:type: string- - name: q[taxons_id_eq]- in: query- required: false- description: Filter by taxon ID+ - name: id+ in: path+ required: true+ description: Shipment IDschema:type: string- - name: includes+ - name: tokenin: queryrequired: false- description: Comma-separated associations to include (variants, images, taxons,- option_types)+ description: Order token for guest accessschema:type: stringresponses:- '200':- description: products found+ '404':+ description: shipping rate not foundcontent:application/json:example:- data:- - id: prod_UkLWZg9DAJ- name: Product 1075048- description: |-- Beatae adipisci sapiente reiciendis quibusdam culpa placeat ad est. At molestiae corrupti dolore eaque quidem excepturi quaerat. Itaque error voluptates aliquid tempora occaecati quam.- Quis atque dolorum dignissimos odio. Libero nam repellendus exercitationem possimus optio. Beatae expedita quisquam quaerat fuga blanditiis. Unde aut corporis quas officia facere debitis.- A voluptatem sunt vero animi repellat. Necessitatibus sapiente cumque sunt ipsam eum. Architecto non qui veritatis doloribus. Exercitationem ex officia consequuntur incidunt.- Sequi reprehenderit cumque animi exercitationem. Quos temporibus mollitia sit quibusdam earum nam eius doloribus. Numquam in eius ab quas libero est.- slug: product-1075048- meta_description:- meta_keywords:- variant_count: 1- available_on: '2025-02-14T17:19:36.445Z'- created_at: '2026-02-14T17:19:36.467Z'- updated_at: '2026-02-14T17:19:36.566Z'- purchasable: true- in_stock: false- backorderable: true- available: true- default_variant_id: variant_gbHJdmfrXB- thumbnail_url:- tags: []- price:- id: price_gbHJdmfrXB- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:- - id: prod_gbHJdmfrXB- name: Product 1083289- description: Cupiditate aperiam consequatur numquam non nulla repudiandae.- Totam rem magni doloremque reiciendis vitae natus. Atque est velit- adipisci dicta voluptas.- slug: product-1083289- meta_description:- meta_keywords:- variant_count: 0- available_on: '2025-02-14T17:19:36.585Z'- created_at: '2026-02-14T17:19:36.597Z'- updated_at: '2026-02-14T17:19:36.634Z'- purchasable: true- in_stock: false- backorderable: true- available: true- default_variant_id: variant_EfhxLZ9ck8- thumbnail_url:- tags: []- price:- id: price_EfhxLZ9ck8- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:- meta:- page: 1- limit: 25- count: 2- pages: 1- from: 1- to: 2- in: 2- previous:- next:+ error:+ code: record_not_found+ message: Shipping rate not foundschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/StoreProduct"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- '401':- description: unauthorized - invalid or missing API key+ "$ref": "#/components/schemas/ErrorResponse"+ '200':+ description: shipping rate selectedcontent:application/json:example:- error:- code: invalid_token- message: Valid API key required+ id: ship_UkLWZg9DAJ+ number: H29726844584+ state: pending+ tracking: U10000+ tracking_url:+ cost: '100.0'+ display_cost: "$100.00"+ shipped_at:+ created_at: '2026-02-14T19:48:07.773Z'+ updated_at: '2026-02-14T19:48:07.851Z'+ shipping_method:+ id: shpm_UkLWZg9DAJ+ name: UPS Ground+ code: UPS_GROUND+ stock_location:+ id: sloc_UkLWZg9DAJ+ state_abbr: STATE_ABBR_278+ name: Victorina Mayer+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_iso: US+ country_name: United States of America+ state_text: STATE_ABBR_278+ 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_GROUNDschema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/orders/{order_id}/payment_methods":+ "$ref": "#/components/schemas/StoreShipment"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ selected_shipping_rate_id:+ type: string+ example: shprt_abc123+ description: Shipping rate ID to select+ required:+ - selected_shipping_rate_idget:- summary: List available payment methods+ summary: Get a shipmenttags:- - Payment Methods+ - Shipmentssecurity:- api_key: []bearer_auth: []- description: Returns payment methods available for the order based on store- configuration and order state+ description: Returns details of a specific shipmentparameters:- name: x-spree-api-keyin: header@@ -4038,56 +4114,77 @@ paths:required: trueschema:type: string- - name: order_token+ - name: id+ in: path+ required: true+ description: Shipment ID+ schema:+ type: string+ - name: token+ in: query+ required: false+ description: Order token for guest access+ schema:+ type: string+ - name: includesin: queryrequired: false+ description: Include shipping_ratesschema:type: stringresponses:- '401':- description: unauthorized+ '404':+ description: shipment not foundcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: record_not_found+ message: Shipment not foundschema:"$ref": "#/components/schemas/ErrorResponse"'200':- description: payment methods found- content:- application/json:- example:- data:- - id: pm_UkLWZg9DAJ- name: Credit Card- description:- type: Spree::Gateway::Bogus- meta:- count: 1- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/StorePaymentMethod"- meta:- type: object- properties:- count:- type: integer- '404':- description: order not found+ description: shipment foundcontent:application/json:example:- error:- code: order_not_found- message: Order not found+ id: ship_UkLWZg9DAJ+ number: H78713691792+ state: pending+ tracking: U10000+ tracking_url:+ cost: '100.0'+ display_cost: "$100.00"+ shipped_at:+ created_at: '2026-02-14T19:48:09.679Z'+ updated_at: '2026-02-14T19:48:09.713Z'+ shipping_method:+ id: shpm_UkLWZg9DAJ+ name: UPS Ground+ code: UPS_GROUND+ stock_location:+ id: sloc_UkLWZg9DAJ+ state_abbr: STATE_ABBR_286+ name: Cayla Kling+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_iso: US+ country_name: United States of America+ state_text: STATE_ABBR_286+ 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_GROUNDschema:- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/StoreShipment"servers:- url: http://{defaultHost}variables:@@ -5192,6 +5289,10 @@ components:type: arrayitems:"$ref": "#/components/schemas/StoreOptionValue"+ digital_links:+ type: array+ items:+ "$ref": "#/components/schemas/StoreDigitalLink"x-typelizer: truerequired:- id@@ -5219,6 +5320,7 @@ components:- created_at- updated_at- option_values+ - digital_linksStoreMetafield:type: objectproperties:diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.mdindex 847a3d0cba..fb76787d1d 100644--- a/packages/sdk/CHANGELOG.md+++ b/packages/sdk/CHANGELOG.md@@ -1,5 +1,11 @@# @spree/sdk+## 0.1.8++### Patch Changes++- Add addresses.markAsDefault() method to set a customer address as default billing or shipping+## 0.1.7### Patch Changesdiff --git a/packages/sdk/package.json b/packages/sdk/package.jsonindex 31341b5157..cdf7872354 100644--- a/packages/sdk/package.json+++ b/packages/sdk/package.json@@ -1,6 +1,6 @@{"name": "@spree/sdk",- "version": "0.1.7",+ "version": "0.1.8","description": "Official TypeScript SDK for Spree Commerce API","type": "module","main": "./dist/index.cjs",diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.tsindex 16be90ce2f..33a3e99f4c 100644--- a/packages/sdk/src/client.ts+++ b/packages/sdk/src/client.ts@@ -785,6 +785,19 @@ export class SpreeClient {*/delete: (id: string, options?: RequestOptions): Promise<void> =>this.request<void>('DELETE', `/customer/addresses/${id}`, options),++ /**+ * Mark an address as default billing or shipping+ */+ markAsDefault: (+ id: string,+ kind: 'billing' | 'shipping',+ options?: RequestOptions+ ): Promise<StoreAddress> =>+ this.request<StoreAddress>('PATCH', `/customer/addresses/${id}/mark_as_default`, {+ ...options,+ body: { kind },+ }),},/**