BigCommerce
Storefront API
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.

  • include in query with default of lineItems.digitalItems.options,lineItems.physicalItems.options - string

    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.

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

Body

object | application/json

Cart object used in add items requests.

One of:
  • lineItems
    array[object]
    required

One of:
  • lineItems
    array[object]
    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
  • cartId in path - string - required

    This cart's unique ID.

  • itemId in path - string - required

    This item's ID.

  • include in query with default of lineItems.digitalItems.options,lineItems.physicalItems.options - string

    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.

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

Body

object | application/json
One of:
  • lineItem
    object
    required

    Any of:
    • productId
      number
      required

      ID of the product.

    • quantity
      number
      required

      Quantity of this item.

    • giftWrapping
      object

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

One of:
  • lineItem
    object
    required

    Any of:
    • productId
      number
      required

      ID of the product.

    • quantity
      number
      required

      Quantity of this item.

    • giftWrapping
      object

      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 item to delete.

  • include in query with default of lineItems.digitalItems.options,lineItems.physicalItems.options - string

    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.

    Allowed values: lineItems.physicalItems.options | lineItems.digitalItems.options | lineItems.digitalItems.options,lineItems.physicalItems.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?