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.
Several example request bodies follow:
With option selections
Minimal detail
With currency, locale
To create a cart with option selections, include an option_id and option_value for each selection. Make sure to specify a locale.
Locale format
The locale field supports language, script, and region codes in the ISO-639 standard format.
Customer support
To create a cart for an existing customer, include the customer_id in your request body.
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.
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.
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.
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.
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.
Clearing the cart
To clear the cart, send a request to the Delete a cart endpoint.
In practice, removing all cart items also essentially deletes the cart.
