> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # 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. > **Note** > > #### 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](/developer/api-reference/rest/admin/management/carts) lets you create carts for both existing and guest customers. To create a cart, send a request to the [Create a cart](/developer/api-reference/rest/admin/management/carts/carts-single/create-cart) endpoint. **`Create a cart`** ```http title="Create a cart" showLineNumbers={false} 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: #### With option selections 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`** ```json title="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" } ``` #### Minimal detail **`Example request body: Create a cart`** ```json title="Example request body: Create a cart" { "channel_id": 1, "line_items": [ { "quantity": 1, "product_id": 80, "variant_id": 64 } ] } ``` #### With currency, locale **`Example request body: Create a cart`** ```json title="Example request body: Create a cart" { "customer_id": 0, "line_items": [], "custom_items": [ { "sku": "custom-item-sku", "name": "table", "quantity": 1, "list_price": 30, "gift_wrapping": { "wrap_together": true, "wrap_details": [ { "id": 0, "message": "Happy Birthday" } ] } } ], "gift_certificates": [ { "name": "Tobi Day", "theme": "Birthday", "amount": 1, "quantity": 1, "sender": { "name": "Brandi Tyler", "email": "Brandi.Tyler@mail.com" }, "recipient": { "name": "Tobi Day", "email": "Tobi.Day@mail.com" }, "message": "Happy Birthday" } ], "channel_id": 1, "currency": { "code": "usd" }, "locale": "en-US" } ``` > **Note** > > #### Locale format > > The locale field supports language, script, and region codes in the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format. > **Note** > > #### Custom item images > > Images are not supported for custom items. Although the API accepts an `image_url` field, the image does not display on the storefront. ## Customer support To create a cart for an existing customer, include the `customer_id` in your request body. **`Example request body: existing customer`** ```json title="Example request body: existing customer" showLineNumbers={false} { "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 [Storefront Checkout API](/developer/api-reference/rest/storefront/checkouts). ## 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](/developer/api-reference/rest/admin/management/carts/redirects/create-cart-redirect-url) endpoint. Use the `id` returned with the [Create a cart](/developer/api-reference/rest/admin/management/carts/carts-single/create-cart) response for the `cartId` path parameter. **`Create cart redirect URL`** ```http title="Create cart redirect URL" showLineNumbers={false} 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](/developer/docs/admin/checkout-and-cart/checkout-sdk) to embed the BigCommerce-hosted checkout into a headless site using an iFrame. **`Example response: Create cart redirect URL`** ```json title="Example response: Create cart redirect URL" showLineNumbers={false} { "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](/developer/api-reference/rest/admin/management/carts/carts-single/create-cart) endpoint by appending the `include=redirect_urls` query parameter to the request URL. **`Create a cart`** ```http title="Create a cart" showLineNumbers={false} 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](/developer/api-reference/rest/admin/management/carts/carts-single/create-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](/developer/docs/storefront/guides/customer-authentication/customer-login) to manage the redirection flow. > **Note** > > #### API account notes > > The Customer Login API requires **app API credentials**. To learn more, see the articles on the [Customer Login API](/developer/docs/storefront/guides/customer-authentication/customer-login#api-account-notes) and [Authentication](/developer/docs/overview/api-fundamentals/api-accounts#user-generated-jwts). The Customer Login API requires your application to generate a JWT, then send it as a path parameter of the [Send login token](/developer/api-reference/rest/admin/authentication-apis/customer-login-api/login-token/get-customer-login) 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](/developer/docs/storefront/guides/customer-authentication/customer-login#customer-login-jwt-payload-reference). | Field Name | Type | Description | | :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------- | | `iss` | string | The API account client ID. | | `store_hash` | string | The subject store hash. | | `channel_id` | integer | The `channel_id` of the subject storefront. Required for this use case; see [Channel ID is mandatory](#channel-id-is-mandatory). | | `customer_id` | integer | The ID of the shopper you associated with the cart. | | `redirect_to` | string | One of the redirect URLs you generated per the section on [Redirecting to checkout](#redirecting-to-checkout). | A successful call to the [Send login token](/developer/api-reference/rest/admin/authentication-apis/customer-login-api/login-token/get-customer-login) 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. > **Note** > > #### 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](/developer/docs/admin/checkout-and-cart/embedded-checkout), create the Customer Login JWT, then pass the full URL for a call to the [Send login token](/developer/api-reference/rest/admin/authentication-apis/customer-login-api/login-token/get-customer-login) 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](/developer/api-reference/rest/admin/management/carts/items/delete-cart-line-item) endpoint, passing the associated `cartId` and `itemId` as path parameters. **`Delete a line item`** ```http title="Delete a line item" showLineNumbers={false} 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](/developer/api-reference/rest/admin/management/carts/carts-single/delete-cart) endpoint. **`Delete a cart`** ```http title="Delete a cart" showLineNumbers={false} 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](/developer/docs/storefront/headless/cart-and-checkout/checkout) ## Resources * [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/developer/docs/storefront/headless/end-to-end-guides/rest-management) * [REST Management API: Carts](/developer/api-reference/rest/admin/management/carts) * [REST Storefront API: Carts](/developer/api-reference/rest/storefront/carts) * [Persistent Cart](https://support.bigcommerce.com/s/article/Persistent-Cart)