Spree Commerce Checkout API
The Checkout API from Spree Commerce — 2 operation(s) for checkout.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Checkout API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: hello@spreecommerce.org
description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n"
version: v3
servers:
- url: http://{defaultHost}
variables:
defaultHost:
default: localhost:3000
tags:
- name: Checkout
paths:
/api/v2/storefront/checkout:
patch:
description: The Update Checkout endpoint allows you to manage the typical stages of an e-commerce checkout system.
tags:
- Checkout
operationId: update-checkout
responses:
'200':
$ref: '#/components/responses/Cart'
'404':
$ref: '#/components/responses/404NotFound'
'422':
$ref: '#/components/responses/422UnprocessableEntity'
security:
- orderToken: []
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CartIncludeParam'
summary: Update Checkout
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
order:
type: object
properties:
email:
type: string
example: john@snow.org
bill_address_attributes:
$ref: '#/components/schemas/AddressPayload'
ship_address_attributes:
$ref: '#/components/schemas/AddressPayload'
shipments_attributes:
type: array
items:
type: object
properties:
id:
type: string
example: '3'
description: The Shipment `id`
selected_shipping_rate_id:
type: string
example: '10'
description: The Shipping Rate `id`
required:
- id
- selected_shipping_rate_id
payments_attributes:
type: array
items:
type: object
properties:
payment_method_id:
type: string
example: '1'
description: The `id` of the Payment Method
source_attributes:
type: object
properties:
gateway_payment_profile_id:
type: string
month:
type: number
year:
type: number
cc_type:
type: string
name:
type: string
required:
- payment_method_id
- source_attributes
examples:
Add Customer Details:
value:
order:
email: john@snow.org
bill_address_attributes:
firstname: John
lastname: Snow
address1: 7735 Old Georgetown Road
city: Bethesda
phone: '3014445002'
zipcode: '20814'
state_name: MD
country_iso: US
ship_address_attributes:
firstname: John
lastname: Snow
address1: 7735 Old Georgetown Road
city: Bethesda
phone: '3014445002'
zipcode: '20814'
state_name: MD
country_iso: US
Add Shipping Rates:
value:
order:
shipments_attributes:
- id: '1'
selected_shipping_rate_id: '1'
Add a Payment:
value:
order:
payments_attributes:
- payment_method_id: '1'
source_attributes:
gateway_payment_profile_id: ABC123
cc_type: visa
last_digits: '1111'
month: 10
year: 2022
name: John Doe
description: '##### Add Customer Details
Adding customer details is achieved by passing the customer-related attributes shown in the corresponding request body example.
##### Add Shipping Rates
To add shipping rates, you will need a shipment associated with the checkout. If you do not have any shipments follow the steps below:
1. First, ensure your cart has items added via the **Add an Item to Cart** endpoint.
2. Next, ensure the checkout has a shipping address set, you can set this by running the *Add Customer Details* example above.
3. Next run the **Advance Checkout** endpoint, this will create shipments for the items in the cart and users shipping destination.
Use the **List Shipping Rates** endpoint to find the shipments and shipping rates available for this checkout. Note the shipment `id` and shipping_rate `id`; use these values to populate your request body.
##### Add a Payment
To add a payment method, you must find the available payment methods by running the **List Payment Methods** endpoint, each payment method has its own set of source attribute requirements. In the example shown, we have used the source attributes for a card payment.
Pass the `payment_method_id` and `source_attribute` hash containing the required attributes for the selected payment method.'
/api/v2/storefront/checkout/validate_order_for_payment:
post:
description: 'Validate an order before placing it. It will respond with an error when:
- cart was changed
- any order item is out of stock
- any order item is discontinued'
operationId: validate-order-payment
responses:
'200':
$ref: '#/components/responses/Cart'
'422':
$ref: '#/components/responses/CartWithErrors'
security:
- orderToken: []
- bearerAuth: []
parameters:
- in: query
name: skip_state
description: Set to `true` if the check for cart changes should be skipped
schema:
type: boolean
- $ref: '#/components/parameters/CartIncludeParam'
- $ref: '#/components/parameters/SparseFieldsCart'
summary: Validate order payment
tags:
- Checkout
components:
schemas:
LineItem:
title: Line Item
type: object
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: line_item
attributes:
type: object
properties:
name:
type: string
example: Sample product
quantity:
type: integer
example: 1
slug:
type: string
example: sample-product
options_text:
type: string
example: 'Size: small, Color: red'
price:
type: string
example: '125.0'
description: Price of Product per quantity
currency:
type: string
example: USD
display_price:
type: string
example: $125.00
description: Price of Product per quantity
total:
type: string
example: '250.0'
description: Total price of Line Item including adjastments, promotions and taxes
display_total:
type: string
example: $250.00
description: Total price of Line Item including adjastments, promotions and taxes
adjustment_total:
type: string
example: '10.0'
description: TBD
display_adjustment_total:
type: string
example: $10.00
description: TBD
additional_tax_total:
type: string
example: '5.0'
display_additional_tax_total:
type: string
example: $5.00
discounted_amount:
type: string
example: '125.0'
display_discounted_amount:
type: string
example: $125.00
pre_tax_amount:
type: string
example: '125.0'
display_pre_tax_amount:
type: string
example: $125.00
promo_total:
type: string
example: '-5.0'
display_promo_total:
type: string
included_tax_total:
type: string
example: '0.0'
description: Taxes included in the price, eg. VAT
display_inluded_tax_total:
type: string
example: $0.00
compare_at_amount:
type: string
example: '290.99'
description: Compare at price of the Line Item
display_compare_at_amount:
type: string
example: $290.99
description: Display compare at price of the Line Item
public_metadata:
type: object
example:
recommended_by_us: true
description: The public metadata for the Line Item.
relationships:
type: object
properties:
variant:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
digital_links:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
description: ''
Timestamp:
type: string
format: date-time
example: '2020-02-16T07:14:54.617Z'
x-internal: false
title: Time Stamp
x-examples:
example-1: '2020-02-16T07:14:54.617Z'
Error:
x-internal: false
title: Error
type: object
properties:
error:
type: string
Promotion:
type: object
title: Promotion
properties:
id:
type: string
example: '1'
type:
type: string
default: promotion
attributes:
type: object
properties:
name:
type: string
example: 10% Discount
description:
type: string
example: Super discount for you
amount:
type: string
example: '-10.0'
display_amount:
type: string
example: -$10.00
code:
type: string
example: BLK-FRI
required:
- id
- type
- attributes
x-internal: false
AddressPayload:
example:
firstname: John
lastname: Snow
address1: 7735 Old Georgetown Road
address2: 2nd Floor
city: Bethesda
phone: '3014445002'
zipcode: '20814'
state_name: MD
country_iso: US
type: object
x-internal: false
title: ''
x-examples: {}
description: ''
properties:
firstname:
type: string
lastname:
type: string
address1:
type: string
description: Street address
address2:
type: string
description: Additional address information, floor no etc
city:
type: string
description: City, town
phone:
type: string
zipcode:
type: string
description: Valid zipcode, will be validated against the selected Country
state_name:
type: string
description: State/region/province 2 letter abbreviation
country_iso:
type: string
description: Country ISO (2-chars) or ISO3 (3-chars) code. [List of all codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
company:
type: string
example: Paper Street Soap Co.
description: Company name
label:
type: string
example: Work
description: The internal name for this address (Work, Home)
required:
- firstname
- lastname
- address1
- city
- country_iso
Cart:
description: The Cart provides a central place to collect information about an order, including line items, adjustments, payments, addresses, and shipments. [Read more in Spree docs](/developer/core-concepts/orders)
type: object
title: Cart
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: cart
attributes:
type: object
properties:
number:
type: string
example: R123456789
description: Used as the **{order_number}** value in the URI to identify a completed order.
token:
type: string
example: eL0nVxe1Aum-Qr9-UkryPA1633360128076
description: Used for authorizing actions through the `X-Spree-Order-Token` API Key.
item_total:
type: string
example: '19.99'
subtotal_cents:
type: integer
example: 1999
store_credit_total_cents:
type: integer
example: 0
total:
type: string
example: '29.99'
total_cents:
type: integer
example: 2999
total_minus_store_credits:
type: string
example: '29.99'
total_minus_store_credits_cents:
type: integer
example: 2999
ship_total:
type: string
example: '5.0'
ship_total_cents:
type: integer
example: 500
adjustment_total:
type: string
example: '10.0'
created_at:
$ref: '#/components/schemas/Timestamp'
updated_at:
$ref: '#/components/schemas/Timestamp'
completed_at:
type: string
format: date-time
nullable: true
included_tax_total:
type: string
example: '5.00'
additional_tax_total:
type: string
example: '5.0'
display_additional_tax_total:
type: string
example: $5.00
tax_total:
type: string
example: '10.0'
tax_total_cents:
type: integer
example: 1000
currency:
type: string
example: USD
state:
type: string
example: cart
enum:
- cart
- address
- delivery
- payment
- confirm
- complete
description: "State of the Cart in the Checkout flow. Please see <a href=\"/developer/core-concepts/orders#the-order-state-machine\">\n The Order State machine\n</a> for a full list with description."
email:
type: string
format: email
example: spree@example.com
nullable: true
display_item_total:
type: string
example: $19.99
display_ship_total:
type: string
example: $19.99
display_adjustment_total:
type: string
example: $10.00
display_included_tax_total:
type: string
example: $5.00
promo_total:
type: string
example: '-10.0'
promo_total_cents:
type: integer
example: -1000
display_promo_total:
type: string
example: -$10.00
item_count:
type: number
description: Total quantity number of all items added to the Cart
example: 2
minimum: 0
special_instructions:
type: string
example: Please wrap it as a gift
description: Message added by the Customer
nullable: true
display_total:
type: string
example: $29.99
display_total_minus_store_credits:
type: string
example: $29.99
pre_tax_item_amount:
type: string
example: '17.00'
display_pre_tax_item_amount:
type: string
example: $17.00
pre_tax_total:
type: string
example: '20.00'
display_tax_total:
type: string
example: $10.00
display_pre_tax_total:
type: string
example: $20.00
shipment_state:
type: string
enum:
- pending
- backorder
- canceled
- partial
- ready
- shipped
- null
description: "Overall state of the Shipments. Please see <a href=\"/developer/core-concepts/orders#order-shipment-states-1\">\n Order Shipments states\n</a> for a full list with description."
nullable: true
payment_state:
type: string
enum:
- balance_due
- credit_owed
- failed
- paid
- void
- null
description: "Overall state of the Payments. Please see <a href=\"/developer/core-concepts/orders#order-payment-states\">\n Order Payments states\n</a> for a full list with description."
nullable: true
relationships:
type: object
properties:
line_items:
type: object
description: ''
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
variants:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
promotions:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
payments:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
shipments:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
user:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
billing_address:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
shipping_address:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
DigitalLink:
title: Digital Link
type: object
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: digital_link
attributes:
type: object
properties:
token:
type: string
example: Gn6srBmmR4KrWy73LRtrBKYw
relationships:
type: object
properties:
line_item:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
description: Digital links are accessible in the order includes line_items.digital_links
CartIncludes:
x-internal: false
title: Cart Includes
anyOf:
- $ref: '#/components/schemas/LineItem'
- $ref: '#/components/schemas/Promotion'
- $ref: '#/components/schemas/Variant'
- $ref: '#/components/schemas/Payment'
- $ref: '#/components/schemas/User'
- $ref: '#/components/schemas/Shipment'
- $ref: '#/components/schemas/DigitalLink'
- $ref: '#/components/schemas/Product'
description: ''
Relation:
type: object
nullable: true
properties:
id:
type: string
type:
type: string
required:
- id
- type
x-internal: false
description: ''
Shipment:
type: object
title: Shipment
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: shipment
attributes:
type: object
properties:
number:
type: string
example: H121354
description: Unique Shipment identifier
free:
type: boolean
description: Indicates if the Shipping Rate is free, eg. when Free shipping promo applied to Cart
final_price:
type: string
example: '10.0'
description: Price to be presented for the Customer
display_final_price:
type: string
example: $10.00
tracking_url:
type: string
example: https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels=4123412434%2C
description: Tracking URL to the service provider website
nullable: true
state:
type: string
example: shipped
enum:
- pending
- ready
- shipped
- canceled
description: "Status of the Shipment. For a list of all available statuses please refer: <a href=\"/developer/core-concepts/shipments\" target=\"_blank\" rel=\"noopener\">\n Shipment section in Spree Guides\n</a>"
shipped_at:
type: string
format: date-time
example: '2021-01-02 13:42:12'
description: Date when Shipment was being sent from the warehouse
nullable: true
relationships:
type: object
properties:
stock_location:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
shipping_rates:
type: object
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
User:
type: object
title: User
description: ' '
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: user
attributes:
type: object
properties:
email:
type: string
example: spree@example.com
first_name:
type: string
example: John
last_name:
type: string
example: Doe
selected_locale:
type: string
example: fr
store_credits:
type: number
example: 150.75
completed_orders:
type: number
example: 3
description: Number of placed Orders by this User
tags:
type: array
items:
type: string
description: List of tags associated with the user
public_metadata:
type: object
example:
user_segment: supplier
description: The public metadata for this User
relationships:
type: object
properties:
default_billing_address:
type: object
description: Default billing address associated with this Account
properties:
data:
$ref: '#/components/schemas/Relation'
default_shipping_address:
type: object
description: Default shipping address associated with this Account
properties:
data:
$ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
Product:
type: object
title: Product
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: product
attributes:
type: object
properties:
name:
type: string
example: Example product
description:
type: string
example: Example description
nullable: true
available_on:
type: string
example: '2012-10-17T03:43:57Z'
nullable: true
slug:
type: string
example: example-product
price:
type: string
example: '15.99'
nullable: true
currency:
type: string
example: USD
display_price:
type: string
example: $15.99
nullable: true
purchasable:
type: boolean
description: Indicates if any of Variants are in stock or backorderable
in_stock:
type: boolean
description: Indicates if any of Variants are in stock
backorderable:
type: boolean
description: Indicates if any of Variants are backeorderable
meta_description:
type: string
example: Example product
nullable: true
meta_keywords:
type: string
example: example, product
nullable: true
updated_at:
$ref: '#/components/schemas/Timestamp'
sku:
type: string
example: 9238-WS
available:
type: boolean
compare_at_price:
type: string
example: '49.99'
nullable: true
display_compare_at_price:
type: string
example: $49.99
nullable: true
localized_slugs:
type: object
description: Provides product's slugs in other locales
tags:
type: array
items:
type: string
description: List of tags associated with the product
labels:
type: array
items:
type: string
description: List of labels associated with the product
relationships:
type: object
properties:
variants:
type: object
description: List of Product Variants, excluding Master Variant
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
option_types:
type: object
description: List of Product Option Types
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
product_properties:
type: object
description: List of Product Properties
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
taxons:
type: object
description: List of Taxons associated with this Product
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
images:
type: object
description: List of Images associated with this Product
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
default_variant:
type: object
description: The default Variant for this product
properties:
data:
$ref: '#/components/schemas/Relation'
primary_variant:
type: object
description: The Primary Variant for this product
properties:
data:
$ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
Variant:
title: Variant
description: 'Variant records track the individual variants of a Product. Variants are of two types: master variants and normal variants.'
x-examples: {}
type: object
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: variant
attributes:
type: object
properties:
sku:
type: string
example: SKU-1001
price:
type: string
example: '15.99'
currency:
type: string
example: USD
display_price:
type: string
example: $15.99
weight:
type: string
example: '10'
nullable: true
height:
type: string
example: '10'
nullable: true
width:
type: string
example: '10'
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/openapi/spree-checkout-api-openapi.yml