Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added Addresses Mark as Default API (#13590)

Damian Legawiec909d52719da5
diff --git a/.github/workflows/spelling_lint.yml b/.github/workflows/spelling_lint.yml
index 838a773c5c..dc50148e63 100644
--- a/.github/workflows/spelling_lint.yml
+++ b/.github/workflows/spelling_lint.yml
@@ -31,4 +31,4 @@ jobs:
- name: Install
run: 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' -error
diff --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.rb
index 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 Spree
module Customer
class AddressesController < ResourceController
prepend_before_action :require_authentication!
+ before_action :set_resource, only: [:show, :update, :destroy, :mark_as_default]
# POST /api/v3/store/customer/addresses
def create
@@ -20,6 +21,24 @@ module Spree
end
end
+ # 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/:id
def update
result = Spree.address_update_service.call(
diff --git a/backend/engines/api/config/routes.rb b/backend/engines/api/config/routes.rb
index 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 do
namespace :customer, path: 'customer' do
get '/', 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
+ end
resources :credit_cards, only: [:index, :show, :destroy]
resources :gift_cards, only: [:index, :show]
end
diff --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.rb
index 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: :cont
end
end
+ 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' do
it 'deletes the address' do
expect {
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.rb
index 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/stor
end
end
end
+
+ 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
+ end
end
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 9b7c0322b4..a4792a6319 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -40,256 +40,17 @@ info:
```
version: v3
paths:
- "/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
- 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
- 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
- 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 cart
tags:
- - Coupon Codes
+ - Cart
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.
+ 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-key
in: header
@@ -299,32 +60,26 @@ paths:
- name: Authorization
in: header
required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
+ description: Bearer JWT token for authenticated customers
schema:
type: string
- name: order_token
in: query
required: false
- description: Order token for guest access
+ description: Order token for guest checkout
schema:
type: string
responses:
- '201':
- description: coupon code applied (gift card)
+ '200':
+ description: cart found (guest)
content:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R565584986
+ number: R908760653
state: cart
- token: dKpSWdbd57LMbvnj3zKq35skoosb1Dyfa1q
+ token: XQYajpzkbaMsp4KPNSjRFPaKQEUM616mXns
special_instructions:
currency: USD
item_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 found
content:
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 found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- code:
- type: string
- example: SAVE10
- description: Coupon code or gift card code to apply
- required:
- - code
- "/api/v3/store/orders/{order_id}/coupon_codes/{id}":
- delete:
- summary: Remove coupon code
+ "/api/v3/store/cart/associate":
+ patch:
+ summary: Associate guest cart with authenticated user
tags:
- - Coupon Codes
+ - Cart
security:
- 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-key
in: header
@@ -405,49 +173,43 @@ paths:
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
+ 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_token
in: query
required: false
- description: Order token for guest access
+ description: Order token (alternative to header)
schema:
type: string
responses:
'404':
- description: coupon code not found on order
+ description: cart belongs to another user
content:
application/json:
example:
error:
- code: record_not_found
- message: Order promotion not found
+ code: order_not_found
+ message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
'200':
- description: coupon code removed
+ description: cart associated successfully
content:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R220533920
+ number: R342807255
state: cart
- token: jwg5nhPb8w8cGLjPcfXX86XjnDUopGv37VC
+ token: tJzSrEsVuHqepWuAqyj94RZCFCSVFJDyQ76
special_instructions:
currency: USD
item_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 required
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/taxonomies/{id}":
- get:
- summary: Get a taxonomy
+ "/api/v3/store/wishlists/{id}":
+ patch:
+ summary: Update a wishlist
tags:
- - Taxonomies
+ - Wishlists
security:
- api_key: []
- description: Returns a single taxonomy with its taxon tree
+ bearer_auth: []
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: id
- in: path
+ - name: Authorization
+ in: header
required: true
- description: Taxonomy ID (prefixed)
schema:
type: string
- - name: includes
- in: query
- required: false
- description: Include taxons
+ - name: id
+ in: path
+ required: true
schema:
type: string
responses:
'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 updated
content:
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: true
schema:
- "$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 wishlist
tags:
- - Shipments
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Returns all shipments associated with the order
parameters:
- name: x-spree-api-key
in: header
@@ -639,100 +352,24 @@ paths:
type: string
- name: Authorization
in: header
- required: false
+ required: true
schema:
type: string
- - name: order_id
+ - name: id
in: path
required: true
schema:
type: string
- - name: token
- in: query
- required: false
- description: Order token for guest access
- schema:
- type: string
responses:
- '200':
- description: shipments found
- content:
- application/json:
- example:
- data:
- - id: ship_UkLWZg9DAJ
- number: 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 deleted
get:
- summary: Get a shipment
+ summary: Get a wishlist
tags:
- - Shipments
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Returns details of a specific shipment
parameters:
- name: x-spree-api-key
in: header
@@ -741,93 +378,53 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- schema:
- type: string
- - name: order_id
- in: path
required: true
schema:
type: string
- name: id
in: path
required: true
- description: Shipment ID
- schema:
- type: string
- - name: token
- in: query
- required: false
- description: Order token for guest access
schema:
type: string
- name: includes
in: query
required: false
- description: Include shipping_rates
+ description: Include wished_items
schema:
type: string
responses:
- '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 found
content:
application/json:
example:
error:
code: record_not_found
- message: Shipment not found
+ message: Wishlist not found
schema:
"$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 wishlist
tags:
- - Shipments
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Selects a shipping rate for the shipment
parameters:
- name: x-spree-api-key
in: header
@@ -836,10 +433,10 @@ paths:
type: string
- name: Authorization
in: header
- required: false
+ required: true
schema:
type: string
- - name: order_id
+ - name: wishlist_id
in: path
required: true
schema:
@@ -847,194 +444,148 @@ paths:
- 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
responses:
- '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 found
content:
application/json:
example:
error:
code: record_not_found
- message: Shipping rate not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- selected_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 wishlist
tags:
- - Authentication
+ - Wishlists
security:
- api_key: []
- description: Creates a new customer account and returns a JWT token
+ bearer_auth: []
+ description: Adds a variant to the wishlist
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
responses:
- '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 added
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE3NTkyOH0.vfcRB9L23UqJgvOaSuA5Ze3KwXZlAHVRtLo4SM6p3c4
- user:
- id: cus_UkLWZg9DAJ
- 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: object
properties:
- email:
- type: string
- format: email
- password:
- type: string
- minLength: 6
- example: password123
- password_confirmation:
- type: string
- example: password123
- first_name:
- type: string
- example: John
- last_name:
+ variant_id:
type: string
- example: Doe
+ example: variant_abc123
+ quantity:
+ type: integer
+ example: 1
required:
- - email
- - password
- "/api/v3/store/auth/login":
+ - variant_id
+ "/api/v3/store/wishlists":
post:
- summary: Login
+ summary: Create a wishlist
tags:
- - Authentication
+ - Wishlists
security:
- api_key: []
- description: Authenticates a customer with email/password and returns a JWT
- token
+ bearer_auth: []
+ description: Creates a new wishlist for the customer
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
responses:
- '200':
- description: login successful
+ '201':
+ description: wishlist created
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE3NTkyOH0.vfcRB9L23UqJgvOaSuA5Ze3KwXZlAHVRtLo4SM6p3c4
- user:
- id: cus_UkLWZg9DAJ
- 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: true
schema:
- "$ref": "#/components/schemas/AuthResponse"
- '401':
- description: missing API key
+ "$ref": "#/components/schemas/StoreWishlist"
+ '422':
+ description: validation error
content:
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 blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -1043,29 +594,25 @@ paths:
schema:
type: object
properties:
- provider:
- type: string
- example: email
- description: 'Authentication provider (default: email)'
- email:
- type: string
- format: email
- password:
+ name:
type: string
- example: password123
+ example: Birthday Ideas
+ is_private:
+ type: boolean
+ example: true
+ is_default:
+ type: boolean
+ example: false
required:
- - email
- - password
- "/api/v3/store/auth/refresh":
- post:
- summary: Refresh token
+ - name
+ get:
+ summary: List wishlists
tags:
- - Authentication
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Generates a new JWT token for the authenticated user
+ description: Returns all wishlists for the authenticated customer
parameters:
- name: x-spree-api-key
in: header
@@ -1075,30 +622,53 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: per_page
+ in: query
+ required: false
+ schema:
+ type: integer
responses:
'200':
- description: token refreshed
+ description: wishlists found
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE3NTkyOX0.T9UcZGb5SxlKWa3tXYppxwfv0c0Tqe9_RfAYMOWw9dU
- user:
- id: cus_UkLWZg9DAJ
- 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: unauthorized
content:
application/json:
example:
@@ -1107,44 +677,38 @@ paths:
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/taxons/{id}":
+ "/api/v3/store/taxonomies":
get:
- summary: Get a taxon
+ summary: List taxonomies
tags:
- - Taxons
+ - Taxonomies
security:
- api_key: []
- description: Returns a single taxon by permalink or prefix ID
+ 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: 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: false
schema:
- type: string
+ type: integer
+ - name: per_page
+ in: query
+ required: false
+ schema:
+ type: integer
- name: includes
in: query
required: false
- description: Include associations (children, products, parent)
+ description: Include root taxon
schema:
type: string
responses:
- '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
content:
@@ -1156,124 +720,119 @@ paths:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'200':
- description: taxon found by permalink
+ description: taxonomies found
content:
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: id
in: path
required: true
- description: Line item ID
+ description: Taxonomy ID (prefixed)
schema:
type: string
- - name: order_token
+ - name: includes
in: query
required: false
+ description: Include taxons
schema:
type: string
responses:
'200':
- description: line item updated
+ description: taxonomy found
content:
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_OIJLhNcSbf
schema:
- "$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 addresses
tags:
- - Line Items
+ - Addresses
security:
- api_key: []
bearer_auth: []
- description: Removes a line item from the order
+ description: Returns all addresses in the customer address book
parameters:
- name: x-spree-api-key
in: header
@@ -1282,47 +841,108 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- schema:
- type: string
- - name: order_id
- in: path
required: true
schema:
type: string
- - name: id
- in: path
- required: true
+ - name: page
+ in: query
+ required: false
schema:
- type: string
- - name: order_token
+ type: integer
+ - name: per_page
in: query
required: false
schema:
- type: string
+ type: integer
responses:
- '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: unauthorized
content:
application/json:
example:
error:
- code: line_item_not_found
- message: Line item not found
+ code: authentication_required
+ message: Authentication required
schema:
"$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 address
tags:
- - Line Items
+ - Addresses
security:
- api_key: []
bearer_auth: []
- description: Adds a variant to the order. Creates a new line item or increases
- quantity if variant already in cart.
+ description: Adds a new address to the customer address book
parameters:
- name: x-spree-api-key
in: header
@@ -1331,152 +951,199 @@ paths:
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 or number
- schema:
- type: string
- - name: order_token
- in: query
- required: false
- description: Order token for guest access
schema:
type: string
responses:
- '404':
- description: order not found
+ '201':
+ description: address created
content:
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_51
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '201':
- description: line item created
+ "$ref": "#/components/schemas/StoreAddress"
+ '422':
+ description: validation error
content:
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 blank
schema:
- "$ref": "#/components/schemas/StoreLineItem"
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- 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 states
required:
- - 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 default
tags:
- - Store
+ - Addresses
security:
- 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 customer
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: store found
+ description: address marked as default
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-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_57
schema:
- "$ref": "#/components/schemas/StoreStore"
- '401':
- description: unauthorized - invalid API key
+ "$ref": "#/components/schemas/StoreAddress"
+ '422':
+ description: invalid kind parameter
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: invalid_request
+ message: kind must be billing or shipping
schema:
"$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 address
tags:
- - Orders
+ - Addresses
security:
- api_key: []
bearer_auth: []
- description: Returns a paginated list of orders for the authenticated customer
parameters:
- name: x-spree-api-key
in: header
@@ -1488,103 +1155,51 @@ paths:
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: 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: true
schema:
type: string
responses:
'200':
- description: orders found
+ description: address found
content:
application/json:
example:
- data:
- - id: or_UkLWZg9DAJ
- number: R920944376
- state: cart
- token: FRbB5nvtLdaUzzgZKoyC1hFscC3P1ynBi48
- 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_66
schema:
- 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 found
content:
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 address
tags:
- - Orders
+ - Addresses
security:
- 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-key
in: header
@@ -1593,64 +1208,89 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- description: Bearer JWT token (optional - for authenticated customers)
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
schema:
type: string
responses:
- '201':
- description: cart created (guest)
+ '200':
+ description: address updated
content:
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_72
schema:
- 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 found
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: record_not_found
+ message: Address not found
schema:
"$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: R379134890
state: cart
- token: f6RLcPBgfpR62dsS8Fz9C6449EsebvqfuMv
+ token: ho3jgjKZXVnnVyVgG7sUBFtvPtXL3a8zFGn
special_instructions:
currency: USD
item_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: R502200759
state: cart
- token: HvPSYphQaqYsd6D32FjFMFvVunKQsQTEGYx
+ token: vyHT8ez2ugRVV1ZRhQkuypz9R7YvHQZE7w8
special_instructions:
currency: USD
item_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_UkLWZg9DAJ
name: Store Credit
@@ -1849,10 +1489,10 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R579308003
+ number: R493155655
state: payment
- token: jtU8mPj9Wg7m4Nc3nZD4fJSdsbv7hsJVPtN
+ token: CWSQBZar4J6AWaN28M8gzBLAWYcPs5vQtjg
special_instructions:
currency: USD
item_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 cart
tags:
- Orders
security:
- 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-key
in: header
@@ -1898,38 +1539,29 @@ paths:
- name: Authorization
in: header
required: 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: string
responses:
- '200':
- description: order completed
+ '201':
+ description: cart created (authenticated)
content:
application/json:
example:
id: or_gbHJdmfrXB
- number: R622128321
- state: complete
- token: mh1j4g8cwF7WTeuCZAnEu6EroS7MbVT8qpm
+ number: R130962790
+ state: cart
+ token: 1nM9hfybFbcur9qMdTgevQevG4SsQDC9SCf
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: 1nM9hfybFbcur9qMdTgevQevG4SsQDC9SCf
schema:
- "$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 key
content:
application/json:
example:
error:
- code: order_already_completed
- message: No payment found
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{id}/next":
- patch:
- summary: Advance to next checkout step
+ get:
+ summary: List orders
tags:
- Orders
security:
- 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 customer
parameters:
- name: x-spree-api-key
in: header
@@ -1983,77 +1613,106 @@ paths:
type: string
- name: Authorization
in: header
- required: false
+ required: true
schema:
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 state
schema:
type: string
- - name: order_token
+ - name: q[completed_at_gte]
in: query
required: false
+ description: Filter by completion date (after)
schema:
type: string
responses:
'200':
- description: order advanced
- content:
- application/json:
- example:
- id: or_gbHJdmfrXB
- number: R801853052
- state: address
- token: TXY29NH58suQwkmJAZ8tGECtD367vEFu1UQ
- 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 found
content:
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
+ 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 required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{id}":
- get:
- summary: Get an order
+ "/api/v3/store/orders/{id}/complete":
+ patch:
+ summary: Complete the order
tags:
- Orders
security:
- 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-key
in: header
@@ -2068,51 +1727,43 @@ paths:
- 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: string
responses:
- '404':
- description: not found - order belongs to another user
+ '422':
+ description: cannot complete
content:
application/json:
example:
error:
- code: order_not_found
- message: Order not found
+ code: order_already_completed
+ message: No payment found
schema:
"$ref": "#/components/schemas/ErrorResponse"
'200':
- description: order found (authenticated)
+ description: order completed
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R281415027
- state: cart
- token: U3K88PGLb7mdwroDwhcdvU2v8PuBYjJTyvZ
+ id: or_gbHJdmfrXB
+ number: R647140788
+ state: complete
+ token: Yr2X4aRYjfLExzdprSQ1SjxkenorGCmknak
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"
+ 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::Bogus
schema:
"$ref": "#/components/schemas/StoreOrder"
+ "/api/v3/store/orders/{id}":
patch:
summary: Update an order
tags:
@@ -2167,10 +1827,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R301256028
+ number: R498676948
state: cart
- token: uLSqFe4UePgQMDe7fozpKRXmMgUQh1HJBog
+ token: ZrxK7b4eJwNK62He9tdpNS5mmTJUoQcM1YD
special_instructions: Leave at door
currency: USD
item_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: string
example: CA
- "/api/v3/store/countries":
get:
- summary: List checkout countries
+ summary: Get an order
tags:
- - Countries
+ - Orders
security:
- 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-key
in: header
required: true
schema:
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: string
responses:
'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
+ 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 user
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: order_not_found
+ message: Order not found
schema:
"$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 step
tags:
- - Countries
+ - Orders
security:
- 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 flow
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: iso
+ - name: Authorization
+ in: header
+ required: false
+ schema:
+ type: string
+ - name: id
in: path
required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE", "CA")
+ schema:
+ type: string
+ - name: order_token
+ in: query
+ required: false
schema:
type: string
responses:
- '404':
- description: country not found
+ '200':
+ description: order advanced
content:
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
+ 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 found
content:
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 found
content:
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 countries
tags:
- - Wishlists
+ - Countries
security:
- api_key: []
- bearer_auth: []
+ description: Returns countries available for checkout from the store checkout
+ zone
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- - name: includes
- in: query
- required: false
- description: Include wished_items
- schema:
- type: string
responses:
'200':
- description: wishlist found
+ description: countries found
content:
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: en
schema:
- "$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: unauthorized
content:
application/json:
example:
error:
- code: record_not_found
- message: Wishlist not found
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- delete:
- summary: Delete a wishlist
+ "/api/v3/store/store":
+ get:
+ summary: Get current store
tags:
- - Wishlists
+ - Store
security:
- api_key: []
- bearer_auth: []
+ description: Returns information about the current store based on the API key
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: 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 code
tags:
- - Wishlists
+ - Coupon Codes
security:
- api_key: []
bearer_auth: []
+ description: Removes a previously applied coupon code from the order.
parameters:
- name: x-spree-api-key
in: header
@@ -2579,117 +2343,549 @@ paths:
type: string
- name: Authorization
in: header
- required: true
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: id
+ - name: order_id
in: path
required: 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 access
schema:
type: string
responses:
'200':
- description: wishlist updated
+ description: coupon code removed
content:
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
+ 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
+ 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: object
properties:
- 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 product
tags:
- - Wishlists
+ - Products
security:
- api_key: []
- bearer_auth: []
- description: Creates a new wishlist for the customer
+ description: Returns a single product by slug or prefix ID
parameters:
- name: x-spree-api-key
in: header
required: 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-key
in: header
required: 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 string
schema:
type: string
responses:
- '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 key
content:
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 required
schema:
"$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 key
content:
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 methods
tags:
- - Wishlists
+ - Payment Methods
security:
- 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 state
parameters:
- name: x-spree-api-key
in: header
@@ -2698,19 +2894,19 @@ paths:
type: string
- name: Authorization
in: header
- required: true
+ required: false
schema:
type: string
- - name: page
- in: query
- required: false
+ - name: order_id
+ in: path
+ required: true
schema:
- type: integer
- - name: per_page
+ type: string
+ - name: order_token
in: query
required: false
schema:
- type: integer
+ type: string
responses:
'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 required
schema:
"$ref": "#/components/schemas/ErrorResponse"
'200':
- description: wishlists found
+ description: payment methods found
content:
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::Bogus
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/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 quantity
tags:
- - Wishlists
+ - Line Items
security:
- api_key: []
bearer_auth: []
- description: Adds a variant to the wishlist
+ description: Updates the quantity of a line item in the cart
parameters:
- name: x-spree-api-key
in: header
@@ -2771,84 +2969,131 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ schema:
+ type: string
+ - name: order_id
+ in: path
required: true
schema:
type: string
- - name: wishlist_id
+ - name: id
in: path
required: true
+ description: Line item ID
+ schema:
+ type: string
+ - name: order_token
+ in: query
+ required: false
schema:
type: string
responses:
- '201':
- description: item added
+ '200':
+ description: line item updated
content:
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: object
properties:
- variant_id:
- type: string
- example: variant_abc123
quantity:
type: integer
- example: 1
+ minimum: 1
+ example: 5
required:
- - variant_id
- "/api/v3/store/cart/associate":
- patch:
- summary: Associate guest cart with authenticated user
+ - quantity
+ delete:
+ summary: Remove line item from cart
tags:
- - Cart
+ - Line Items
security:
- 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-key
in: header
@@ -2857,461 +3102,348 @@ paths:
type: string
- name: Authorization
in: header
- required: true
- description: Bearer JWT token (required)
+ required: false
+ description: Bearer token for authenticated customers
schema:
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 number
schema:
type: string
- name: order_token
in: query
required: false
- description: Order token (alternative to header)
+ description: Order token for guest access
schema:
type: string
responses:
'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 found
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: variant_not_found
+ message: Variant not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- '200':
- description: cart associated successfully
+ '201':
+ description: line item created
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R972232618
- state: cart
- token: 1ejBzeKGHSHNdgsZBHoLbvSG1W75B1TFGS3
- 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: Register
tags:
- - Cart
+ - Authentication
security:
- 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 token
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
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: string
responses:
- '200':
- description: cart found (authenticated)
+ '422':
+ description: email already taken
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R380109999
- state: cart
- token: qsA2EsWMoWchgSSJwVtbBE5Jh9NRp73YTUz
- 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 taken
schema:
- 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 successful
content:
application/json:
example:
- error:
- code: order_not_found
- message: Order not found
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImV4cCI6MTc3MTE4NDg3NH0.HeqmGqikQqAzGFp00HBHKajvzp7HlZTgALg1emsN_nU
+ user:
+ id: cus_UkLWZg9DAJ
+ 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
+ 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:
+ - email
+ - password
+ "/api/v3/store/auth/refresh":
+ post:
+ summary: Refresh token
tags:
- - Digitals
+ - Authentication
security:
- 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 user
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: token
- in: path
+ - name: Authorization
+ in: header
required: true
- description: Digital link token
+ description: Bearer token
schema:
type: string
responses:
- '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 refreshed
content:
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
+ 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 token
content:
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 required
schema:
"$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: Login
tags:
- - Addresses
+ - Authentication
security:
- api_key: []
- bearer_auth: []
+ description: Authenticates a customer with email/password and returns a JWT
+ token
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
responses:
+ '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 successful
content:
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
+ 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: object
properties:
- 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
+ password:
type: string
- example: Los Angeles
+ example: password123
+ required:
+ - email
+ - password
+ "/api/v3/store/digitals/{token}":
get:
- summary: Get an address
+ summary: Download a digital product
tags:
- - Addresses
+ - Digitals
security:
- 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-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
+ - name: token
in: path
required: true
+ description: Digital link token
schema:
type: string
responses:
- '200':
- description: address found
+ '404':
+ description: digital link not found
content:
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 found
schema:
- "$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 key
content:
application/json:
example:
error:
- code: record_not_found
- message: Address not found
+ code: invalid_token
+ message: Valid API key required
schema:
"$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 exceeded
content:
application/json:
example:
error:
- code: record_not_found
- message: Address not found
+ code: digital_link_expired
+ message: Download link expired or invalid
schema:
"$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 profile
tags:
- - Addresses
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Adds a new address to the customer address book
+ description: Updates the profile of the currently authenticated customer
parameters:
- name: x-spree-api-key
in: header
@@ -3320,32 +3452,86 @@ paths:
type: string
- name: Authorization
in: 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
+ 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_244
schema:
- "$ref": "#/components/schemas/StoreAddress"
+ "$ref": "#/components/schemas/StoreCustomer"
'422':
description: validation error
content:
@@ -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 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:
+ email:
- can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
@@ -3377,58 +3551,36 @@ paths:
schema:
type: object
properties:
- firstname:
+ first_name:
type: string
example: John
- lastname:
+ last_name:
type: string
example: Doe
- address1:
- type: string
- example: 123 Main St
- address2:
+ email:
type: string
- example: Apt 4B
- city:
+ format: email
+ password:
type: string
- example: New York
- zipcode:
+ example: newpassword123
+ password_confirmation:
type: string
- example: '10001'
+ example: newpassword123
+ accepts_email_marketing:
+ type: boolean
+ example: true
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 states
- required:
- - firstname
- - lastname
- - address1
- - city
- - zipcode
- - country_iso
get:
- summary: List customer addresses
+ summary: Get current customer profile
tags:
- - Addresses
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Returns all addresses in the customer address book
+ description: Returns the profile of the currently authenticated customer
parameters:
- name: x-spree-api-key
in: header
@@ -3438,45 +3590,52 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer JWT token
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: per_page
- in: query
- required: false
- schema:
- type: integer
responses:
+ '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 found
content:
application/json:
example:
- data:
- - id: addr_EfhxLZ9ck8
+ id: cus_UkLWZg9DAJ
+ 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_gbHJdmfrXB
firstname: John
lastname: Doe
full_name: John Doe
- address1: 245 Lovely Street
+ address1: 239 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
company: 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_UkLWZg9DAJ
firstname: John
lastname: Doe
full_name: John Doe
- address1: 244 Lovely Street
+ address1: 238 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -3484,14 +3643,15 @@ paths:
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
+ state_text: STATE_ABBR_248
+ state_abbr: STATE_ABBR_248
+ state_name: STATE_NAME_248
+ default_billing_address:
+ id: addr_gbHJdmfrXB
firstname: John
lastname: Doe
full_name: John Doe
- address1: 243 Lovely Street
+ address1: 239 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -3499,38 +3659,27 @@ paths:
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
- 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_248
schema:
- "$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 order
responses:
- '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 found
content:
@@ -3578,11 +3717,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PBB3PIAM
+ number: PKVGMSI0
amount: '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_UkLWZg9DAJ
name: 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 payment
tags:
- 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 found
content:
@@ -3650,11 +3789,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PKXQ827O
+ number: P8SGVUWG
amount: '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_UkLWZg9DAJ
name: Credit Card
@@ -3662,41 +3801,56 @@ paths:
type: Spree::Gateway::Bogus
schema:
"$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 taxon
tags:
- - Products
+ - Taxons
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.
+ description: Returns a single taxon by permalink or prefix ID
parameters:
- name: x-spree-api-key
in: header
required: 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)
+ - 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: includes
in: query
required: false
- description: Filter by name containing string
+ description: Include associations (children, products, parent)
schema:
type: string
responses:
+ '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: unauthorized
content:
application/json:
example:
@@ -3706,322 +3860,244 @@ paths:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'200':
- description: filters retrieved successfully
+ description: taxon found by prefix ID
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
- 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: false
schema:
- 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 order
tags:
- - Products
+ - Shipments
security:
- api_key: []
- description: Returns a single product by slug or prefix ID
+ bearer_auth: []
+ description: Returns all shipments associated with the order
parameters:
- name: x-spree-api-key
in: header
required: true
- description: Publishable API key
schema:
type: string
- - name: id
+ - name: Authorization
+ in: header
+ required: false
+ schema:
+ type: string
+ - name: order_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: includes
+ - name: token
in: query
required: false
- description: Comma-separated associations to include
+ description: Order token for guest access
schema:
type: string
responses:
'404':
- description: draft product not visible
+ description: order not found
content:
application/json:
example:
error:
- code: record_not_found
- message: Product not found
+ code: order_not_found
+ message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
'200':
- description: product found by slug
+ description: shipments found
content:
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 shipment
tags:
- - Products
+ - Shipments
security:
- api_key: []
- description: Returns a paginated list of active products for the current store
+ bearer_auth: []
+ description: Selects a shipping rate for the shipment
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
+ - name: Authorization
+ in: header
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
+ type: string
+ - name: order_id
+ in: path
+ required: true
schema:
type: string
- - name: q[taxons_id_eq]
- in: query
- required: false
- description: Filter by taxon ID
+ - name: id
+ in: path
+ required: true
+ description: Shipment ID
schema:
type: string
- - name: includes
+ - name: token
in: query
required: false
- description: Comma-separated associations to include (variants, images, taxons,
- option_types)
+ description: Order token for guest access
schema:
type: string
responses:
- '200':
- description: products found
+ '404':
+ description: shipping rate not found
content:
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 found
schema:
- 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 selected
content:
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_GROUND
schema:
- "$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_id
get:
- summary: List available payment methods
+ summary: Get a shipment
tags:
- - Payment Methods
+ - Shipments
security:
- 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 shipment
parameters:
- name: x-spree-api-key
in: header
@@ -4038,56 +4114,77 @@ paths:
required: true
schema:
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: includes
in: query
required: false
+ description: Include shipping_rates
schema:
type: string
responses:
- '401':
- description: unauthorized
+ '404':
+ description: shipment not found
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: record_not_found
+ message: Shipment not found
schema:
"$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 found
content:
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_GROUND
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/StoreShipment"
servers:
- url: http://{defaultHost}
variables:
@@ -5192,6 +5289,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/StoreOptionValue"
+ digital_links:
+ type: array
+ items:
+ "$ref": "#/components/schemas/StoreDigitalLink"
x-typelizer: true
required:
- id
@@ -5219,6 +5320,7 @@ components:
- created_at
- updated_at
- option_values
+ - digital_links
StoreMetafield:
type: object
properties:
diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md
index 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 Changes
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 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.ts
index 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 },
+ }),
},
/**