Docs
Storefront API
Carts

Storefront Carts

Manage cart operations and data on BigCommerce-hosted storefronts. To work with headless storefronts, use the GraphQL Storefront API.

The REST Storefront API uses CORS (opens in a new tab) headers for authentication, and therefore has no required scopes. You do not need to send any BigCommerce-specific tokens with your requests to these endpoints.

For info about authenticating BigCommerce APIs, see Authentication and Example Requests.

Get a Cart

GET /carts

Request

Returns a Cart.

Note

  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • include in query - array

    To return product options add one of the following include:

    lineItems.physicalItems.options: The Cart returns an abbreviated result. Use this to return physical items product options. Can also be used in a /POST to have the extended Cart object return.

    lineItems.digitalItems.options: The Cart returns an abbreviated result. Use this to return digital items product options. Can also be used in a /POST to have the extended Cart object return.

    lineItems.digitalItems.options,lineItems.physicalItems.options: The Cart returns an abbreviated result. Use this to return digital and physical options. Can also be used in a /POST to have the extended Cart object return.

    Type: array[string]

    Allowed: lineItems.physicalItems.options | lineItems.digitalItems.options

example

const options = {
method: 'GET',
headers: {Accept: 'application/json', 'Content-Type': 'application/json'}
};

fetch('https://yourstore.example.com/api/storefront/carts', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));

Response

Body

array | application/json

  • id    string

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

  • customerId    integer

    ID of the customer to which the cart belongs.

  • currency    object

    This will always be the same between cart and checkout.

  • isTaxIncluded    boolean

    Whether this item is taxable.

  • baseAmount    number

    Cost of cart’s contents, before applying discounts.

  • discountAmount    number

    Order based discounted amount only - Coupon discounts and product based discounts are excluded.

  • cartAmount    number

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

  • coupons    array[object]

  • discounts    array[object]

  • lineItems    object

  • createdTime    string

    Time when the cart was created.

  • updatedTime    string

    Time when the cart was last updated.

  • locale    string

    Locale of the cart.

  • version    integer

    The current version of the cart increments with each successful update. You can use it to enable optimistic concurrency control for subsequent updates.
    Example: 1

Example

[
{
"id": "770ded29-da45-4ee0-abc6-883e83c0e5ed",
"customerId": 0,
"email": "",
"currency": {
"name": "US Dollars",
"code": "USD",
"symbol": "$",
"decimalPlaces": 2
},
"isTaxIncluded": false,
"baseAmount": 246,
"discountAmount": 0,
"cartAmount": 221.4,
"coupons": [],
"discounts": [
{
"id": "a83dea21-d757-47a2-a06a-73cf6a983746",
"discountedAmount": 24.6
}
],
"lineItems": {
"physicalItems": [
{
"id": "a83dea21-d757-47a2-a06a-73cf6a983746",
"parentId": 6,
"variantId": 193,
"productId": 230,
"sku": "sku123-VA",
"name": "options test",

Create a Cart

POST /carts

Request

Creates a Cart.

Note

  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • include in query - array

    To return product options add one of the following include:

    lineItems.physicalItems.options: The Cart returns an abbreviated result. Use this to return physical items product options. Can also be used in a /POST to have the extended Cart object return.

    lineItems.digitalItems.options: The Cart returns an abbreviated result. Use this to return digital items product options. Can also be used in a /POST to have the extended Cart object return.

    lineItems.digitalItems.options,lineItems.physicalItems.options: The Cart returns an abbreviated result. Use this to return digital and physical options. Can also be used in a /POST to have the extended Cart object return.

    Type: array[string]

    Allowed: lineItems.physicalItems.options | lineItems.digitalItems.options

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

application/json
Cart object used in create cart requests.
Any of:

  • lineItems    array[]
    required

  • locale    string

    With Text Modifier

    {
    "lineItems": [
    {
    "quantity": 2,
    "productId": 230,
    "optionSelections": [
    {
    "optionId": 10,
    "optionValue": "Some Text Value"
    }
    ]
    }
    ],
    "locale": "en"
    }

    With Gift Wrapping

    {
    "lineItems": [
    {
    "quantity": 2,
    "productId": 230,
    "optionSelections": [
    {
    "optionId": 10,
    "optionValue": "Some Text Value"
    }
    ],
    "giftWrapping": {
    "wrapTogether": true,
    "wrapDetails": [
    {
    "id": 1,
    "message": "Happy Birthday"
    }
    ]
    }
    }
    ],
    "locale": "en"
    }

    Response

    Post Carts Response

    Body

    object | application/json
    Cart object used in REST Storefront API cart responses.

    • id      string

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

    • customerId      integer

      ID of the customer to which the cart belongs.

    • currency      object

      This will always be the same between cart and checkout.

    • isTaxIncluded      boolean

      Whether this item is taxable.

    • baseAmount      number

      Cost of cart’s contents, before applying discounts.

    • discountAmount      number

      Order based discounted amount only - Coupon discounts and product based discounts are excluded.

    • cartAmount      number

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

    • coupons      array[object]

    • discounts      array[object]

    • lineItems      object

    • createdTime      string

      Time when the cart was created.

    • updatedTime      string

      Time when the cart was last updated.

    • locale      string

      Locale of the cart.

    • version      integer

      The current version of the cart increments with each successful update. You can use it to enable optimistic concurrency control for subsequent updates.
      Example: 1

    Example

    {
    "id": "string",
    "customerId": 0,
    "email": "string",
    "currency": {
    "code": "string",
    "decimalPlaces": 2,
    "name": "US Dollar",
    "symbol": "$"
    },
    "isTaxIncluded": true,
    "baseAmount": 0,
    "discountAmount": 0,
    "cartAmount": 0,
    "coupons": [
    {
    "code": "string",
    "couponType": 0,
    "discountedAmount": 0,
    "displayName": "$1.00 off total order",
    "id": "string"
    }
    ],
    "discounts": [
    {
    "discountedAmount": 0,
    "id": "string"
    }
    ],
    "lineItems": {
    "customItems": [],
    "digitalItems": [
    {
    "options": [
    {
    "name": "string",

    Delete a Cart

    DELETE /carts/{cartId}

    Request

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

    Note

    • Substitute your storefront domain for yourstore.example.com.
    • The Send a Test Request feature is not currently supported for this endpoint.

    Parameters

    • store_domain in path - string
    • cartId in path - string
      required
      This cartʼs unique ID.
    • Accept in header with default of application/json - string
      required
      The MIME type of the response body.

    example

    const options = {
    method: 'DELETE',
    headers: {Accept: 'application/json', 'Content-Type': 'application/json'}
    };

    fetch('https://yourstore.example.com/api/storefront/carts/[cartId]', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

    Response

    No Content

    See something you can improve? Edit this file on GitHub

    Did you find what you were looking for?
    OverviewGet a Cart