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.

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.

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}

Several example request bodies follow:

{
  "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"
}

Customer support

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

{
  "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.

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{{cartId}}/redirect_urls
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.

{
  "cart_url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?action=load&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
  "checkout_url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
  "embedded_checkout_url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b"
}

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.

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts?include=redirect_urls
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.

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.

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.

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 https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{{cartId}}/items/{{itemId}}
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 https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{{cartId}}
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

• Learn how to move from cart to checkout

Resources

• End-to-End Guide: Headless Checkout Flow with REST Management APIs
• REST Management API: Carts
• REST Storefront API: Carts
• Persistent Cart (opens in a new tab)