Custom headless storefronts
Cart and checkout
Managing carts

Managing Carts

This article explains how to use the Carts API to create and manage carts. It also discusses how to redirect shoppers from headless storefronts to BigCommerce-hosted cart and checkout pages.

Locale support

The Carts API supports selling in different markets by allowing locale-based overrides for product details. Supply a cart's locale and add option_selections to the cart's line items to configure alternative product names, option names, and modifier values. The Carts API stores the locale and makes it available to the Checkout and Orders APIs.

Creating a cart

The Carts API lets you create carts for both existing and guest customers.

To create a cart, send a request to the Create a cart endpoint.

Create a cart
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

Several example request bodies follow:

To create a cart with option selections, include an option_id and option_value for each selection. Make sure to specify a locale.

Example request body: option selections
  "customer_id": 0,
  "line_items": [
      "quantity": 2,
      "product_id": 118,
      "list_price": 25,
      "variant_id": 140,
      "name": "قميص",
      "option_selections": [
          "option_id": 125,
          "option_value": 127,
          "name": "بحجم",
          "value": "صغير"
  "channel_id": 1,
  "currency": {
    "code": "JOD"
  "locale": "ar-JO"

Locale format

The locale field supports language, script, and region codes in the ISO-639 standard (opens in a new tab) format.

Customer support

To create a cart for an existing customer, include the customer_id in your request body.

Example request body: existing customer
  "channel_id": 1,
  "customer_id": 1,
  "line_items": [
      "quantity": 1,
      "product_id": 80,
      "variant_id": 64
  "locale": "en-us"

Guest cart

Guest carts assume the shopper is not a customer and is not signing in or creating an account during checkout. You can handle guest carts by displaying the cart data to the customer and then moving them to checkout using the Checkouts API.

Redirecting to checkout

A cart redirect URL redirects a shopper to a BigCommerce hosted checkout page. You can only generate a cart redirect URL from a cart created using the Carts API.

Using the Create a cart redirect URL endpoint

To generate a cart redirect URL, send a request to the Create cart redirect URL endpoint. Use the id returned with the Create a cart response for the cartId path parameter.

Create cart redirect URL
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

The response will contain cart_url and checkout_url properties. Use these URLs to redirect the customer to the BigCommerce-hosted cart or checkout pages. You can use the embedded_checkout_url with the Checkout SDK to embed the BigCommerce-hosted checkout into a headless site using an iFrame.

Example response: Create cart redirect URL
  "cart_url": "",
  "checkout_url": "",
  "embedded_checkout_url": ""

Using Create a cart with the include query parameter

It is possible to generate a redirect URL when creating a cart using the Create a cart endpoint by appending the include=redirect_urls query parameter to the request URL.

Create a cart
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
  // request body

Signing customers in before redirecting

Registered customers have personally-identifiable information, or PII, saved in their accounts. If you passed a customer_id in the Create a cart request, send the customer to a sign-in page before redirecting them to cart or checkout pages. You can use the Customer Login API to manage the redirection flow.

API account notes

The Customer Login API requires app API credentials. To learn more, see the articles on the Customer Login API and Authentication.

The Customer Login API requires your application to generate a JWT, then send it as a path parameter of the Send login token endpoint.

The following table is a reference for the specifics of JWT claims in the context of this use case. For a complete listing of payload claims, both required and optional, see the Customer Login API JWT payload reference.

Field NameTypeDescription
issstringThe API account client ID.
store_hashstringThe subject store hash.
channel_idintegerThe channel_id of the subject storefront. Required for this use case; see Channel ID is mandatory.
customer_idintegerThe ID of the shopper you associated with the cart.
redirect_tostringOne of the redirect URLs you generated per the section on Redirecting to checkout.

A successful call to the Send login token endpoint will redirect the user to the supplied relative URL. If you're calling the Customer Login API server-side, pass the redirect along to the frontend.

Channel ID is mandatory

The Customer Login JWT must include a channel_id property. If you omit the channel_id, CORS checks will fail and the checkout will not load.

If you are using Embedded Checkout, create the Customer Login JWT, then pass the full URL for a call to the Send login token endpoint to the Checkout SDK. The SDK will sign the customer in, then redirect them to the Embedded Checkout iFrame.

Deleting a line item

To delete a line item from a cart, send a request to the Delete cart line item endpoint, passing the associated cartId and itemId as path parameters.

Delete a line item
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

Clearing the cart

To clear the cart, send a request to the Delete a cart endpoint.

Delete a cart
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

In practice, removing all cart items also essentially deletes the cart.

Next step


Did you find what you were looking for?