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

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

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

    With Gift Wrapping

    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

    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

    Response

    No Content

    See something you can improve? Edit this file on GitHub

    Did you find what you were looking for?