Skip to main content

​
Overview

An order is the central model connecting a customer to their purchase. It collects line items, addresses, shipments, payments, and adjustments into a single transaction that flows through a checkout state machine from cart to completion. Key relationships:
  • Line Items link orders to Variants (what was purchased)
  • Shipments handle fulfillment from stock locations
  • Payments track payment attempts and their states
  • Adjustments apply taxes, promotions, and shipping costs
  • Addresses store billing and shipping information

​
Order Attributes

The API returns these key fields on every order:
AttributeDescription
numberUnique order number (e.g., R123456789), shown to customers
stateCurrent checkout state (cart, address, delivery, payment, confirm, complete)
emailCustomer’s email address
currencyOrder currency (e.g., USD)
item_countTotal number of items
item_total / display_item_totalSum of line item prices
ship_total / display_ship_totalShipping cost
tax_total / display_tax_totalTotal tax
promo_total / display_promo_totalTotal discount from promotions
adjustment_total / display_adjustment_totalSum of all adjustments (tax + shipping + promos)
total / display_totalFinal order total
payment_statePayment status (balance_due, paid, credit_owed, failed, void)
shipment_stateShipment status (pending, ready, partial, shipped, backorder)
completed_atTimestamp when the order was placed
The display_* fields return formatted strings with currency symbols (e.g., "$15.99").

​
Cart

A cart is simply an order in the cart state. Guest carts are identified by a cart token; authenticated users’ carts are linked to their account. 
// Create a cart
const cart = await client.carts.create()
// cart.token => "abc123" (save this for guest checkout)

// Get existing cart
const cart = await client.carts.get(cartId, { spreeToken: 'xxx' })

// Add an item
const updatedOrder = await client.carts.items.create(cart.id, {
  variant_id: 'var_xxx',
  quantity: 2,
})

// Update quantity
await client.carts.items.update(cart.id, 'li_xxx', {
  quantity: 3,
})

// Remove an item
await client.carts.items.delete(cart.id, 'li_xxx')
Every item mutation returns the full updated order with recalculated totals.

​
Checkout Flow

The checkout is a state machine that advances the order through a series of steps. Each step collects required information before allowing the order to proceed.
1

cart

Customer has items in their cart. This is the starting state.
2

address

Customer provides shipping and billing addresses.
3

delivery

Customer selects a shipping rate for each shipment.
4

payment

Customer provides payment. Skipped if the order is fully covered by store credit.
5

confirm

Customer reviews and confirms the order.
6

complete

Order is placed. completed_at is set and fulfillment begins.
If the order doesn’t meet the requirements for the next state (e.g., missing address), the API returns an error. 
// Set addresses
await client.carts.update(cartId, {
  email: 'john@example.com',
  ship_address: {
    firstname: 'John', lastname: 'Doe',
    address1: '123 Main St', city: 'Los Angeles',
    country_iso: 'US', state_abbr: 'CA', zipcode: '90001',
    phone: '555-0100',
  },
})

// Get shipments and select a shipping rate
const { data: shipments } = await client.carts.shipments.list(cartId)
await client.carts.shipments.update(cartId, shipments[0].id, {
  selected_shipping_rate_id: 'sr_xxx',
})

// Create a payment session (e.g., Stripe)
const session = await client.carts.paymentSessions.create(cartId, {
  payment_method_id: 'pm_xxx',
})
// session.external_data.client_secret => use with Stripe.js

// Complete the payment session after provider confirmation
await client.carts.paymentSessions.complete(cartId, session.id)

// Complete the order
await client.carts.complete(cartId)

​
Coupon Codes

Apply or remove promotional coupon codes during checkout: 
// Apply a coupon
await client.carts.couponCodes.apply(cartId, 'SAVE20')

// Remove a coupon
await client.carts.couponCodes.remove(cartId, 'SAVE20')

​
Order History

Authenticated customers can view their past orders: 
// List past orders
const { data: orders } = await client.customer.orders.list()

// Get a specific order with details
const order = await client.orders.get('or_xxx', {
  expand: ['items', 'shipments', 'payments'],
})

​
Line Items

Line items represent individual products in an order. Each line item links to a Variant and tracks the quantity and price at the time of purchase. When a variant is added to an order, the price is locked on the line item. If the variant’s price changes later, existing orders are unaffected.

​
Adjustments

Adjustments modify an order’s total — promotions decrease it, taxes and shipping increase it. Adjustments can be applied at the order level, the line item level, or the shipment level.

​
Payment States

StateDescription
balance_duePayment total is less than the order total
paidPayment total equals the order total
credit_owedPayment total exceeds the order total (refund pending)
failedMost recent payment attempt failed
voidOrder was canceled and payments voided

​
Shipment States

StateDescription
pendingAll shipments are pending
readyAll shipments are ready to ship
partialAt least one shipment is shipped, others are not
shippedAll shipments have been shipped
backorderSome inventory is on backorder
For more details, see Shipments and Payments.