BigCommerce
Management API
Carts
Carts Single

Carts

Create a Cart

POST /carts

Request

Creates a Cart.

Required Fields

FieldDetails
line_itemSpecifies a line item.
custom_itemsSpecifies a custom item. Only required if adding a custom item to the cart.
gift_certificatesSpecifies a gift certificate. Only required if adding a gift certificate to the cart.

Usage Notes

  • A cart id (UUID) is returned in the response.
  • A cart id is the same as a checkout id.
  • A cart can be created by adding an existing catalog item or a custom item.
  • Carts are valid for 30 days from the last modification (this includes creating the cart or editing the cart).
  • If a product has modifiers, use the option_selections array to describe the modifier selection(s).
  • The format and data type of a cart’s option_value are defined by the value_data object of a product’s variant option value, modifier value, or a combination of both.
  • Redirect URLs can only be generated from carts that were created using the REST Management API.
  • To get cart redirect_urls in the response, append the following query parameter to the request URL: include=redirect_urls. Redirect URLs point to either a shared checkout domain or a channel-specific domain, depending on the storefront configuration.
  • To restore a cart that was created by a shopper or through a Storefront API, first recreate the cart using the REST Management API.
  • To get cart promotions in the response, append the following query parameter to the request URL: include=promotions.banners.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • include in query - array
    • redirect_urls: Create a direct link to a cart. This can be used for the /POST request for carts.
    • line_items.physical_items.options: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request.
    • line_items.digital_items.options: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request.
    • promotions.banners: Returns a list of eligible banners.
  • Content-Type in header with default of application/json - string
    required

Examples:

  1. Creating a cart by adding a simple product (a product without option selections).
  2. Creating a cart with a variant. This works when a product can be specified purely by a variant, without any other required options.
  3. Creating a cart using a date option. The API supports timestamps, “option_value”: 1743570000, and dates as an object literal, “option_value”: {“day”:”01”, “month”:”02”, “year”:”2020”}.
  4. Creating a cart with a variant, a checkbox, and a picklist modifier added.
  5. Creating a cart using a custom item.

Body

object | application/json

  • customer_id    integer

  • line_items    array[]

  • custom_items    array[object]

  • gift_certificates    array[object]

  • channel_id    integer

    The Channel ID. If no channel is specified, defaults to 1.

  • currency    object

  • locale    string

    The locale of the cart. Accepts strings of format xx or xx-YY. Uses the ISO-639 standard format.

    Example: en-US

Simple Product

Cart with a variant

Cart with date option

Cart with variant, a checkbox, and a pick list modifier

Custom item

Cart with file upload options

Response

Body

object | application/json

A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • id    string

    Cart ID, provided after creating a cart with a POST request.

  • parent_id    string

    Bundled items will have the ID of their parent item.

  • customer_id    integer

    ID of the customer to which the cart belongs.

  • email    string

    The cart’s email. This is the same email that is used in the billing address.

  • currency    object

    The currency. This is the same for both the cart and its subsequent checkout.

  • tax_included    boolean

  • base_amount    number

    Sum of cart line-item amounts before cart-level discounts, coupons, or taxes.

  • discount_amount    number

    Order-based discounted amount only - Excludes coupon discounts and product-based discounts.

  • cart_amount    number

    Sum of cart line-item amounts minus cart-level discounts and coupons. This amount includes taxes (where applicable).

  • coupons    array[object]

  • discounts    array[object]

  • line_items    object

    GET

  • created_time    string

    Time when the cart was created.

  • updated_time    string

    Time when the cart was last updated.

  • channel_id    integer

    The channel ID. If no channel is specified, defaults to 1.

  • locale    string

    Locale of the cart. Accepts strings of format xx or xx-YY. Uses the ISO-639 standard format.

  • promotions    object

    This is available only when "include=promotions.banners" is presented in the URL.

Get a Cart

GET /carts/{cartId}

Request

Returns a storeʼs Cart.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • cartId in path - string
    required

    The identifier of a specific cart.

  • include in query - array
    • redirect_urls: Create a direct link to a cart. This can be used for the /POST request for carts.
    • line_items.physical_items.options: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request.
    • line_items.digital_items.options: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request.
    • promotions.banners: Returns a list of eligible banners.

example

Response

Body

object | application/json

A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • id    string

    Cart ID, provided after creating a cart with a POST request.

  • parent_id    string

    Bundled items will have the ID of their parent item.

  • customer_id    integer

    ID of the customer to which the cart belongs.

  • email    string

    The cart’s email. This is the same email that is used in the billing address.

  • currency    object

    The currency. This is the same for both the cart and its subsequent checkout.

  • tax_included    boolean

  • base_amount    number

    Sum of cart line-item amounts before cart-level discounts, coupons, or taxes.

  • discount_amount    number

    Order-based discounted amount only - Excludes coupon discounts and product-based discounts.

  • cart_amount    number

    Sum of cart line-item amounts minus cart-level discounts and coupons. This amount includes taxes (where applicable).

  • coupons    array[object]

  • discounts    array[object]

  • line_items    object

    GET

  • created_time    string

    Time when the cart was created.

  • updated_time    string

    Time when the cart was last updated.

  • channel_id    integer

    The channel ID. If no channel is specified, defaults to 1.

  • locale    string

    Locale of the cart. Accepts strings of format xx or xx-YY. Uses the ISO-639 standard format.

  • promotions    object

    This is available only when "include=promotions.banners" is presented in the URL.

Update Customer ID

PUT /carts/{cartId}

Request

Updates a Cartʼs customer_id.

Notes

Changing the Cart customer_id will remove any promotions or shipping calculations on the Cart. These are tied to the customer depending on cart conditions and any customer groups.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • include in query - array
    • redirect_urls: Create a direct link to a cart. This can be used for the /POST request for carts.
    • line_items.physical_items.options: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request.
    • line_items.digital_items.options: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request.
    • promotions.banners: Returns a list of eligible banners.
  • Content-Type in header with default of application/json - string
    required

Body

object | application/json

  • customer_id    integer

example

Response

Body

object | application/json

A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • id    string

    Cart ID, provided after creating a cart with a POST request.

  • parent_id    string

    Bundled items will have the ID of their parent item.

  • customer_id    integer

    ID of the customer to which the cart belongs.

  • email    string

    The cart’s email. This is the same email that is used in the billing address.

  • currency    object

    The currency. This is the same for both the cart and its subsequent checkout.

  • tax_included    boolean

  • base_amount    number

    Sum of cart line-item amounts before cart-level discounts, coupons, or taxes.

  • discount_amount    number

    Order-based discounted amount only - Excludes coupon discounts and product-based discounts.

  • cart_amount    number

    Sum of cart line-item amounts minus cart-level discounts and coupons. This amount includes taxes (where applicable).

  • coupons    array[object]

  • discounts    array[object]

  • line_items    object

    GET

  • created_time    string

    Time when the cart was created.

  • updated_time    string

    Time when the cart was last updated.

  • channel_id    integer

    The channel ID. If no channel is specified, defaults to 1.

  • locale    string

    Locale of the cart. Accepts strings of format xx or xx-YY. Uses the ISO-639 standard format.

  • promotions    object

    This is available only when "include=promotions.banners" is presented in the URL.

Delete a Cart

DELETE /carts/{cartId}

Request

Deletes a Cart. Once a Cart has been deleted it can’t be recovered.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • cartId in path - string
    required

    The identifier of a specific cart.

example

Response

Did you find what you were looking for?
Delete All MetafieldsCreate a Cart