Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 28 ยท Checkout and Commerce Services

Carts and the Checkout API

Create carts on the server, send shoppers to checkout with redirect URLs, and use the Checkout API for consignments, coupons and discounts, step by step.

Every sale passes through a cart and a checkout. BigCommerce exposes both as APIs, which is what makes custom buying experiences possible: a headless storefront that builds carts from its own pages, a sales tool that prepares a cart for a customer, or an app that applies a special deal. This lesson covers two API families. The Carts API creates and changes carts. The Checkout API takes a cart through shipping, billing, coupons and, finally, order creation.

The calls to BigCommerce are shown read-only, because the lesson cannot reach a store. The runnable parts are Node.js stand-ins: a cart and discount calculator that uses integer money and a small in-memory model of the cart-to-order flow. The calculator is our own code. It teaches the arithmetic and rules you must understand, but your store's real totals come from BigCommerce, never from your own code. Design background is in Cart Design, Building a Promotions Engine and Pricing Models, which this lesson does not repeat.

Two kinds of cart API

There are two ways to work with a cart, and they have different jobs:

  • The Storefront Cart API runs in the shopper's browser, on the store's own domain, with the shopper's session. Theme JavaScript and headless front ends use it (or the GraphQL cart operations from GraphQL Storefront API) to add and remove items. It needs no access token, because the cart belongs to the session.
  • The Server-to-Server Carts API (/v3/carts) runs in your back end with an access token. You use it when your server creates a cart for someone: a quote tool, a "reorder" button, an app that builds bundles.

The server-side API needs an API account with the appropriate Carts scope; see API Accounts, Tokens and Scopes.

Creating a cart and sending the shopper to checkout

A cart is created with line items. Each line names a product and a quantity, and variants are chosen with variant_id or option selections (read-only):

Terminal
curl -X POST "$BC_API_BASE/v3/carts" \
  -H "X-Auth-Token: $BC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": 1,
    "line_items": [
      { "product_id": 118, "variant_id": 210, "quantity": 2 }
    ]
  }'

The response contains the cart id and the cart's computed amounts. Notice what you do not send: prices. The platform looks up the price from the catalog, applies price lists, bulk pricing and discount rules for that customer, and returns the result. (A line item can carry a price override for special cases such as quotes, but it is a powerful feature; use it only when you must, and never let a browser choose the number.)

To hand the cart to a shopper, create redirect URLs (read-only):

Terminal
curl -X POST "$BC_API_BASE/v3/carts/$CART_ID/redirect_urls" \
  -H "X-Auth-Token: $BC_ACCESS_TOKEN"

The response includes URLs for the cart page, the checkout page and an embedded checkout. You send the shopper's browser to one of them, and the store picks up the cart. These URLs are meant to be used right away; do not save them for later, and read the current documentation for expiry and single-use rules. If the cart was created for a customer id, the redirect can carry that identity into the store session, which is why the URL must be treated like a credential and never logged or shared.

sequenceDiagram
    participant S as Your server
    participant B as BigCommerce API
    participant U as Shopper browser
    S->>B: POST /v3/carts (line items)
    B-->>S: cart id and amounts
    S->>B: POST /v3/carts/{id}/redirect_urls
    B-->>S: cart, checkout and embedded checkout URLs
    S-->>U: HTTP redirect to the checkout URL
    U->>B: continues in the store checkout

Your server builds the cart, and the shopper's browser finishes in the store's checkout.

The Checkout API

A cart becomes a checkout when you start working with shipping and payment details. The Checkout API (/v3/checkouts/{checkoutId}; the checkout id equals the cart id) gives you a combined view: items, consignments, coupons, taxes and the grand total. The main steps (read-only):

  1. GET /v3/checkouts/{id} to read the checkout, including its current totals.
  2. POST /v3/checkouts/{id}/consignments to add a shipping address and the items going there. The response lists the available shipping options for that consignment.
  3. PUT /v3/checkouts/{id}/consignments/{consignmentId} to select one of the shipping options.
  4. POST /v3/checkouts/{id}/billing-address to set the billing address and email.
  5. POST /v3/checkouts/{id}/coupons with a coupon code to apply a discount.
  6. POST /v3/checkouts/{id}/orders to create an order from the checkout. After that, the shopper pays, either through the store's checkout or through a payment flow you build with the Payments API.

A consignment is a group of items that ship to one address by one method. An order that ships to two addresses has two consignments. If everything goes to one place, there is just one, and it is easy to forget that the concept exists until you build a multi-address flow. The order lifecycle that follows creation is described in Orders, Customers and the V2/V3 Split and Order Lifecycle.

flowchart LR
    A["Cart"] --> B["Consignment<br/>(address + items)"]
    B --> C["Shipping option chosen"]
    C --> D["Billing address"]
    D --> E["Coupons applied"]
    E --> F["Order created"]
    F --> G["Payment"]

A checkout moves from a bare cart to a complete order step by step.

Coupons and discounts

Discounts come from several sources. Coupon codes and automatic promotions are configured by the merchant in the control panel, or through the Promotions API (the newer, rule-based system) and the older coupon endpoints. Which one to use depends on the store and the features you need; check the current docs, since promotions have been evolving. Whichever system created them, the discount shows up in the checkout response as an amount on the checkout and per line item, and the coupon is listed with its code and type.

Two practices matter for developers:

  • Let the platform calculate. Applying a coupon is a POST of the code; the platform decides whether it is valid, whether the cart meets the minimum, and what the discount is. If the code is invalid, you get an error response, and you show a friendly message.
  • Think in line allocations. A cart-level discount (such as 10% off) is spread across line items for tax and refund purposes. Totals must add up to the cent, which is why money is stored as integers; see Money as Integers.

A cart and discount calculator

The stand-in below models the arithmetic. It computes the subtotal in cents, applies a percent or fixed coupon with a minimum spend, never lets a discount exceed the subtotal, allocates the discount across lines with the largest-remainder method so that the parts sum exactly, and handles a free-shipping coupon. It does not do taxes, price lists or stacking rules; real stores have those, and the real platform is the authority.

Node.js Cart totals with coupons and exact allocation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check the results. The cart subtotal is $63.49. With 10% off, the discount is 634.9 cents rounded to 635, and the allocation across the three lines ($2.40, $2.00 and $1.95) adds up to exactly that. The fixed coupon asks for $100 off but is capped at the subtotal so that the total can never go negative (the shipping charge remains). The below-minimum coupon is rejected with a note, and the free-shipping coupon only changes the shipping amount.

A model of the cart-to-order flow

The second stand-in mimics the Checkout API state machine: you cannot create an order until the checkout has items, a shipping address and chosen option, a billing address and an email. This is the same discipline the real API enforces, and building your own flows is easier when you see the guards. All data is in memory; the shapes echo the real resources (cart id, consignments, coupons) but are simplified.

Node.js Guards in a checkout flow

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first two attempts fail with a list of what is missing, the bad option is rejected, and the last call succeeds once everything is filled in. In a real integration, handle the same cases by reading error responses and showing the shopper what to fix.

Practical advice

  • Create carts on the server only when you need to. For ordinary browsing, the storefront or GraphQL cart is simpler and safer.
  • Never trust totals sent from a browser. Re-read the cart or checkout from the API before you act on a price.
  • Make order creation idempotent in your own system, for example by recording which of your own records have already produced an order; see Idempotency. A retry after a timeout must not create two orders.
  • Treat redirect URLs as secrets, and use them promptly.
  • Read the order flow with the shopper's experience in mind: Checkout Flow explains why each step exists.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a server not send item prices when it creates a cart?

    The cart is priced by the platform. Price overrides exist for special cases, but sending your own prices by default risks wrong or manipulated totals.
  2. 2. What is a consignment?

    Consignments split an order by destination and method. A single-address order has one consignment.
  3. 3. Why can a fixed-amount coupon not make the cart total negative?

    A sensible discount engine caps the discount at the subtotal, so the customer never has the store owe them money for items.
  4. 4. How should you treat the redirect URLs returned for a cart?

    Redirect URLs carry the cart (and possibly the customer's identity) into the store, so they are sensitive and meant for immediate use.

Summary

  • The Storefront Cart API serves browsers; the Server-to-Server Carts API (/v3/carts) serves your back end with an access token.
  • You create a cart from line items, let the platform price it, and send the shopper onward with redirect URLs.
  • The Checkout API adds consignments, shipping options, billing, coupons and finally creates the order.
  • Coupons and promotions are applied by posting a code; the platform validates it and returns the discount, which is allocated over line items.
  • Use integer money, cap discounts and never trust browser-supplied totals.
  • The calculator and flow model are stand-ins for learning the rules; the live platform is the authority.

Next: Customizing Checkout and the Checkout SDK