Cart, Checkout & Orders - Spree Commerce documentation

The Store API is split into two resource groups:

Carts — managing shopping carts, items, coupon codes, checkout flow (addresses, delivery, payments, completion)
Orders — retrieving completed orders

All cart and checkout endpoints require a cartId as the first argument.

Carts

Create & Retrieve

// Create a new cart
const cart = await client.carts.create();

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

// List carts
const carts = await client.carts.list();

// Delete a cart
await client.carts.delete(cartId, { spreeToken: cart.token });

// Associate guest cart with authenticated user
// (after user logs in, assign the guest cart to their account — carts are not merged)
await client.carts.associate(cartId, {
  token: jwtToken,         // User's JWT token
  spreeToken: cart.token,  // Guest cart token
});

Items

const options = { spreeToken: cart.token };

// Add item
await client.carts.items.create(cartId, {
  variant_id: 'var_123',
  quantity: 2,
}, options);

// Update item quantity
await client.carts.items.update(cartId, lineItemId, {
  quantity: 3,
}, options);

// Remove item
await client.carts.items.delete(cartId, lineItemId, options);

Discount Codes

const options = { spreeToken: cart.token };

// Apply a discount code
await client.carts.discountCodes.apply(cartId, 'SAVE20', options);

// Remove a discount code
await client.carts.discountCodes.remove(cartId, 'SAVE20', options);

Gift Cards

// Apply a gift card (reduces amount_due, not total)
const cart = await client.carts.giftCards.apply(cartId, 'GC-ABCD-1234', options);

// Remove a gift card (ID from cart.gift_card.id)
await client.carts.giftCards.remove(cartId, 'gc_abc123', options);

A gift card pays as much of the total as its balance allows, and its share keeps up when delivery, discounts or tax change the total. A cart can use a gift card or store credit, not both.

Fees and Duties

A cart may carry charges that are neither a product price nor tax: gift wrapping, a handling charge, a cash-on-delivery surcharge, or an import duty on a cross-border order. Each is a fee on the cart, and the storefront should show every one of them before the customer pays.

const cart = await client.carts.get(cartId, options);

cart.fees.forEach((fee) => {
  fee.label;          // "Import duty"
  fee.kind;           // "duty"
  fee.display_amount; // "$12.00"
  fee.line_item_id;   // set when the fee is for one item, otherwise null
});

cart.display_fee_total; // "$17.00"

kind is one of surcharge, handling, gift_wrap, cod, payment or duty. Fees are already part of total, so list them as their own lines between the subtotal and the total; never add them on top. A duty fee is a customs charge and is not taxed, which is why it is worth showing under its own label rather than folding it into a generic “fees” line. Fees are written by the merchant or by an integration, never by the customer; there is no Store API endpoint to create one.

Checkout

Update Cart

await client.carts.update(cartId, {
  email: 'customer@example.com',
  shipping_address: {
    first_name: 'John',
    last_name: 'Doe',
    address1: '123 Main St',
    city: 'New York',
    postal_code: '10001',
    phone: '+1 555 123 4567',
    country_code: 'US',
    state_code: 'NY',
  },
  billing_address_id: 'addr_xxx', // Or use existing address by ID
}, { spreeToken: cart.token });

Complete Checkout

import { isOrderGroup } from '@spree/sdk';

const result = await client.carts.complete(cartId, { spreeToken: cart.token });

Completing a cart usually returns one order. In a marketplace, a cart holding several sellers’ goods divides into one order per seller, and the response is the order group that ties them together: one purchase, one payment, combined totals, and the per-seller orders in orders. Use isOrderGroup to tell the two apart:

if (isOrderGroup(result)) {
  // One purchase, shown to the customer under the group's number and total.
  console.log(result.number, result.display_total);
  // How it will arrive: one order per seller, each with its own items and delivery.
  result.orders.forEach((order) => console.log(order.number, order.items));
} else {
  console.log(result.number, result.display_total);
}

A storefront that never sells through more than one seller always gets an order back, but checking costs nothing and keeps the confirmation page working if sellers are added later.

Fulfillments

Fulfillments are included in the cart response — there is no separate list endpoint.

const options = { spreeToken: cart.token };

// Access fulfillments from the cart response
const cart = await client.carts.get(cartId, options);
const fulfillments = cart.fulfillments;

// Select a delivery rate
await client.carts.fulfillments.update(cartId, fulfillmentId, {
  selected_delivery_rate_id: 'rate_xxx',
}, options);

Store Credits

const options = { spreeToken: cart.token };

// Apply store credit (applies maximum available by default)
await client.carts.storeCredits.apply(cartId, undefined, options);

// Apply specific amount of store credit
await client.carts.storeCredits.apply(cartId, 25.00, options);

// Remove store credit from order
await client.carts.storeCredits.remove(cartId, options);

Store credit is a balance, not one of the cart’s payment_methods: apply it here, then collect whatever amount_due is left with a payment method. It can’t be combined with a gift card on the same cart.

Totals

The cart and order responses break the amount the customer pays into these totals. Each has a raw string value and a display_ twin formatted in the cart’s currency.

item_total — the products, before anything else
delivery_total — the selected delivery rates
discount_total — promotions and discount codes, as a negative amount
fee_total — every fee on the cart, duties included
tax_total — tax on items, delivery and taxable fees
total — what the order costs: items, delivery, fees and tax, less discounts
store_credit_total / gift_card_total — store credit or gift card value applied against the total
amount_due — what is left to pay after store credit and gift cards
covered_by_store_credit — boolean, whether the order is fully covered by store credit
gift_card — associated gift card (if applicable)

Orders

Get a Completed Order

const order = await client.orders.get('or_xxx', { // prefixed order ID (or the cart ID)
  expand: ['items', 'fulfillments'],
}, { spreeToken: cart.token });

List Orders (Authenticated Customer)

const orders = await client.customer.orders.list({}, { token });

​Carts

​Create & Retrieve

​Items

​Discount Codes

​Gift Cards

​Fees and Duties

​Checkout

​Update Cart

​Complete Checkout

​Fulfillments

​Store Credits

​Totals

​Orders

​Get a Completed Order

​List Orders (Authenticated Customer)