BigCommerce
Storefront API
Carts
Cart Items

Storefront Carts

Add Cart Line Items

POST /carts/{cartId}/items

Request

Adds a line items to the Cart.

Notes

  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.
  • Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results.

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.

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

    The MIME type of the request 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

Body

application/json

Cart object used in add items requests.

Any of:

  • lineItems    array[]
    required

    With Option Selections

    With Gift Wrapping

    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.

    • email      string

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

    • 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.

    example-1

    Update Cart Line Item

    PUT /carts/{cartId}/items/{itemId}

    Request

    Updates a Cart line item. Updates an existing, single line item quantity and the price of custom items in a cart.

    If a modified product or variant needs to be changed or updated, you can remove and re-add the product to the cart with the correct variants using the Delete Cart Line Item and the Add Cart Line Items endpoints. You can also use carts mutations that are part of the GraphQL Storefront API.

    Notes

    • Substitute your storefront domain for yourstore.example.com.
    • The Send a Test Request feature is not currently supported for this endpoint.
    • Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results.

    Parameters

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

      The MIME type of the request body.

    Body

    application/json
    Any of:

    • lineItem
      required

      Any of:

      • productId        number
        required

        ID of the product.

      • quantity        number
        required

        Quantity of this item.

      • giftWrapping        object or null

        if passing null, it will remove the current gift wrapping for the item

      Variant Item

      Custom Item

      With Gift Wrapping

      With null Gift Wrapping (will delete current gift wrapping)

      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.

      • email        string

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

      • 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.

      Example

      Delete Cart Line Item

      DELETE /carts/{cartId}/items/{itemId}

      Request

      Deletes a Cart line item.

      Removing the last line_item in the Cart deletes the 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
      • cartId in path - string
        required

        This cartʼs unique ID.

      • itemId in path - string
        required

        The ID of the subject item.

      • 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

      NOTE: Discounted line items are re-evaluated on cart actions and may be automatically added back to your cart with a new line item ID to satisfy promotional requirements.

      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.

      • email        string

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

      • 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.

      Example

      Did you find what you were looking for?
      Update Cart CurrencyAdd Cart Line Items