Docs
Storefront API
Carts
Cart Items

Cart Items

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

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

  • 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

    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.

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

    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

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

      • optionSelections        array[object]

      • quantity        number
        required

        Quantity of this item.

      • giftWrapping        object or null

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

    • 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

      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.

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

      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

      Body

      object | application/json

      • 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

      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.

      • 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

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