Docs
Management API
Carts
Carts Single

Carts (Single)

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

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • 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.
    Type: array[string]

    Allowed: redirect_urls | line_items.physical_items.options | line_items.digital_items.options | promotions.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

{
"customer_id": 0,
"line_items": [
{
"quantity": 2,
"product_id": 126,
"list_price": 5,
"name": "calendar"
}
],
"channel_id": 1,
"currency": {
"code": "USD"
},
"locale": "en-US"
}

Cart with a variant

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

Cart with date option

{
"line_items": [
{
"quantity": 1,
"product_id": 128,
"variant_id": 144,
"option_selections": [
{
"option_id": 147,
"option_value": "{“día”:”01”, “mes”:”02”, “año”:”2020”}",
"name": "calendario",
"value": 2023
}
]
}
],
"currency": {
"code": "MXN"
},
"locale": "es-MX"
}

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

{
"customer_id": 0,
"line_items": [
{
"quantity": 1,
"variant_id": 141,
"product_id": 118,
"list_price": 30,
"name": "shirt",
"option_selections": [
{
"name": "Color",
"value": "Red",
"option_id": 133,
"option_value": 149
},
{
"name": "Add a $5 Donation",
"value": "No",
"option_id": 126,
"option_value": 129
}
]
}
],
"channel_id": 1,
"currency": {
"code": "AUD"
},
"locale": "en-AU"
}

Custom item

{
"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": 10,
"quantity": 1,
"sender": {
"name": "Brandi Tyler",
"email": "Brandi.Tyler@mail.com"
},
"recipient": {

Cart with file upload options

{
"customer_id": 0,
"line_items": [
{
"quantity": 1,
"product_id": 104,
"option_selections": [
{
"option_id": 116,
"option_value": {
"originalName": "cs_marking_logo_0.jpeg",
"temporaryPath": "488_a430fe0afaf236bef64635c53f9a26ae.jpeg"
}
}
]
}
]
}

Response

Body

object | application/json

  • data    object

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

  • meta    object

    Response metadata.

Get a Cart

GET /carts/{cartId}

Request

Returns a storeʼs Cart.

Authentication

  • X-Auth-Token in header

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.
    Type: array[string]

    Allowed: redirect_urls | line_items.physical_items.options | line_items.digital_items.options | promotions.banners

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/carts/[cartId]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    object

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

  • meta    object

    Response metadata.

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.

To prevent lost updates due to concurrent requests overriding changes made by others, it is recommended to enable optimistic concurrency control by including the version field in the request payload. If the provided version does not match the version on the server, a conflict error will be returned, which the client can handle accordingly.

Authentication

  • X-Auth-Token in header

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.
    Type: array[string]

    Allowed: redirect_urls | line_items.physical_items.options | line_items.digital_items.options | promotions.banners

  • Content-Type in header with default of application/json - string
    required

Body

object | application/json

  • customer_id    integer

  • version    integer

    The cart version that you expect to apply the updates. If the provided version doesn't match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.
    Example: 1

example

{
"customer_id": 5,
"version": 1
}

Response

Body

object | application/json

  • data    object

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

  • meta    object

    Response metadata.

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

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

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/carts/[cartId]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

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