Spree Commerce Checkout / Shipments API
The Checkout / Shipments API from Spree Commerce — 2 operation(s) for checkout / shipments.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Checkout / Shipments 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 / Shipments
paths:
/api/v2/storefront/checkout/select_shipping_method:
patch:
description: 'Selects shipping method for Shipment(s).
To generate shipments you first need to fetch shipping rates via
[Get Shipping Rates](/api-reference/storefront/checkout-shipments/list-shipping-rates) endpoint'
operationId: select-shipping-method
responses:
'200':
$ref: '#/components/responses/Cart'
'404':
$ref: '#/components/responses/404NotFound'
'422':
$ref: '#/components/responses/422UnprocessableEntity'
security:
- orderToken: []
- bearerAuth: []
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
shipping_method_id:
type: string
description: ID of the selected Shipping Method
shipment_id:
type: string
description: ID of the selected Shipment. If not supplied it will try to set selected shipping method for all shipments
required:
- shipping_method_id
examples:
Set shippng method for all shipments:
value:
shipping_method_id: '1'
Set shipping method for specific shipment:
value:
shipping_method_id: '1'
shipment_id: '1'
description: ''
parameters:
- $ref: '#/components/parameters/CartIncludeParam'
- $ref: '#/components/parameters/SparseFieldsCart'
summary: Selects shipping method for shipment(s)
tags:
- Checkout / Shipments
/api/v2/storefront/checkout/shipping_rates:
get:
description: 'Returns a list of available shipping rates for the checkout.
Shipping rates are grouped against shipments. Each checkout can have multiple shipments. Some products are in stock and will be shipped immediately, while others might be back-ordered and sent later.'
tags:
- Checkout / Shipments
operationId: shipping-rates
responses:
'200':
$ref: '#/components/responses/Shipment'
'404':
$ref: '#/components/responses/404NotFound'
security:
- orderToken: []
- bearerAuth: []
summary: List Shipping Rates
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'
ShipmentIncludes:
x-internal: false
title: Shipment Includes
allOf:
- $ref: '#/components/schemas/ShippingRate'
- $ref: '#/components/schemas/StockLocation'
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
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: ''
StockLocation:
title: Stock Location
type: object
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: stock_location
attributes:
type: object
properties:
name:
type: string
example: Main Warehouse
required:
- id
- type
- attributes
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
ShippingRate:
type: object
title: Shipping Rate
description: ''
x-internal: false
properties:
id:
type: string
example: '1'
nullable: true
type:
type: string
default: shipping_rate
attributes:
type: object
properties:
name:
type: string
example: USPS Ground
selected:
type: boolean
example: true
cost:
type: string
example: '10.0'
description: Price of the service without discounts applied
tax_amount:
type: string
example: '0.0'
description: Eligible tax for service (if any)
shipping_method_id:
type: integer
example: 1
description: ID of a Shipping Method. You will need this for the Checkout Update action
final_price:
type: string
example: '10.0'
description: Price to be presented for the Customer
display_cost:
type: string
example: $10.00
display_final_price:
type: string
example: $10.00
display_tax_amount:
type: string
example: $0.00
free:
type: boolean
example: true
description: Indicates if the Shipping Rate is free, eg. when Free shipping promo applied to Cart
relationships:
type: object
properties:
shipping_method:
type: object
description: Shipping method for which this shipping rate belongs to
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'
nullable: true
depth:
type: string
example: '10'
nullable: true
is_master:
type: boolean
description: Indicates if Variant is the master Variant
options_text:
type: string
example: 'Size: small, Color: red'
options:
type: array
items:
type: object
properties:
name:
type: string
value:
type: string
presentation:
type: string
purchasable:
type: boolean
description: Indicates if Variant is in stock or backorderable
in_stock:
type: boolean
description: Indicates if Variant is in stock
backorderable:
type: boolean
relationships:
type: object
properties:
product:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
images:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
option_values:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
Payment:
title: Payment
type: object
description: ''
x-internal: false
properties:
id:
type: string
type:
type: string
default: payment
attributes:
type: object
properties:
amount:
type: string
default: '200.57'
response_code:
type: integer
default: 192
number:
type: string
default: PV7B4YH0
cvv_response_code:
type: integer
default: 200
cvv_response_message:
type: string
default: authorized
payment_method_id:
type: integer
default: 1
payment_method_name:
type: string
default: Credit Card
state:
type: string
default: paid
relationships:
type: object
properties:
source:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
payment_method:
type: object
properties:
data:
$ref: '#/components/schemas/Relation'
required:
- id
- type
- attributes
- relationships
responses:
404NotFound:
description: 404 Not Found - Resource not found.
content:
application/vnd.api+json:
schema:
properties:
error:
typ
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/openapi/spree-checkout-shipments-api-openapi.yml