BigCommerce Checkout Cart Items API

openapi: 3.2.0
info:
  title: BigCommerce Storefront Checkouts Checkout Cart Items API
  description: "Manage checkout operations and data using front-end JavaScript on BigCommerce\nStencil-powered storefronts.\n\nFor info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts).\n    \nFor info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication)."
  version: ''
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://{store_domain}/api/storefront
  variables:
    store_domain:
      default: your_store.example.com
      description: The [URL authority](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#authority) of the storefront.
tags:
- name: Checkout Cart Items
paths:
  /checkouts/{checkoutId}/carts/{cartId}/items/{itemId}:
    put:
      tags:
      - Checkout Cart Items
      summary: BigCommerce Update a Line Item
      description: "Updates a *Checkout Line Item*. Updates an existing, single line item in the cart.\n\nIf a variant needs to be changed or updated, the product will need to be removed and re-added to the cart with the correct variants using the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoint or the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront).\n\n> #### Notes\n> * Substitute your storefront domain for `yourstore.example.com`. \n> * The Send a Test Request feature is not currently supported for this endpoint.  \n> * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results."
      operationId: updateCheckoutLineItem
      parameters:
      - name: checkoutId
        in: path
        required: true
        schema:
          type: string
      - name: cartId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cart_Put'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_Full'
              example:
                id: 29eb9b44-8f33-4e4a-9429-d0e8e24641ed
                cart:
                  id: 29eb9b44-8f33-4e4a-9429-d0e8e24641ed
                  customerId: 18
                  email: dwaynecole@testing.com
                  currency:
                    name: US Dollars
                    code: USD
                    symbol: $
                    decimalPlaces: 2
                  isTaxIncluded: true
                  baseAmount: 7.95
                  discountAmount: 0
                  cartAmount: 7.95
                  coupons: []
                  discounts:
                  - id: 243c9ca2-22b4-417a-8b09-b3fc05778b52
                    discountedAmount: 0
                  lineItems:
                    physicalItems:
                    - id: 243c9ca2-22b4-417a-8b09-b3fc05778b52
                      parentId: {}
                      variantId: 345
                      productId: 174
                      sku: ''
                      name: 1L Le Parfait Jar
                      url: https://{store_domain}/all/1l-le-parfait-jar/
                      quantity: 1
                      brand: OFS
                      isTaxable: true
                      imageUrl: https://cdn11.bigcommerce.com/s-{store_hash}/products/174/images/425/leparfaitmedium3_1024x1024_1024x1024__37756__81924.1534344526.330.500.jpg?c=2
                      discounts: []
                      discountAmount: 0
                      couponAmount: 0
                      originalPrice: 7.95
                      listPrice: 7.95
                      salePrice: 7.95
                      extendedListPrice: 7.95
                      extendedSalePrice: 7.95
                      isShippingRequired: true
                      giftWrapping: {}
                      addedByPromotion: false
                    digitalItems: []
                    giftCertificates: []
                    customItems: []
                  createdTime: '2019-01-10T17:18:00+00:00'
                  updatedTime: '2019-01-10T17:19:47+00:00'
                billingAddress:
                  id: 5c377ead301c2
                  firstName: Dwayne
                  lastName: Cole
                  email: dwaynecole@testing.com
                  company: ''
                  address1: Mauna Kea Access Rd
                  address2: ''
                  city: Hilo
                  stateOrProvince: Hawaii
                  stateOrProvinceCode: HI
                  country: United States
                  countryCode: US
                  postalCode: '96720'
                  phone: '8081234567'
                  customFields: []
                consignments:
                - id: 5c377ead30ac1
                  shippingCost: 8
                  handlingCost: 0
                  couponDiscounts: []
                  discounts: []
                  lineItemIds:
                  - 243c9ca2-22b4-417a-8b09-b3fc05778b52
                  selectedShippingOption:
                    id: d09e05c0-3788-44df-a1bb-b6d3afdf6841
                    type: shipping_byweight
                    description: Ship by Weight
                    imageUrl: ''
                    cost: 8
                    transitTime: ''
                  address:
                    firstName: Dwayne
                    lastName: Cole
                    email: dwaynecole@testing.com
                    company: ''
                    address1: Mauna Kea Access Rd
                    address2: ''
                    city: Hilo
                    stateOrProvince: Hawaii
                    stateOrProvinceCode: HI
                    country: United States
                    countryCode: US
                    postalCode: '96720'
                    phone: '8081234567'
                    customFields: []
                orderId: null
                shippingCostTotal: 8
                shippingCostBeforeDiscount: 8
                handlingCostTotal: 0
                taxTotal: 1.22
                coupons: []
                taxes:
                - name: Tax
                  amount: 1.22
                subtotal: 7.95
                grandTotal: 15.95
                giftCertificates: []
                createdTime: '2019-01-10T17:18:00+00:00'
                updatedTime: '2019-01-10T17:19:47+00:00'
                customerMessage: ''
      x-codegen-request-body-name: body
    delete:
      tags:
      - Checkout Cart Items
      summary: BigCommerce Delete a Line Item
      description: "Deletes a *Line Item* from the *Cart*.\n\n> #### Note\n> * Substitute your storefront domain for `yourstore.example.com`. \n> * The Send a Test Request feature is not currently supported for this endpoint.  "
      operationId: deleteCheckoutLineItem
      parameters:
      - name: checkoutId
        in: path
        required: true
        schema:
          type: string
      - name: cartId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkout_Full'
              example:
                id: b6fbd994-61a8-4f25-9167-6ec10489c448
                cart:
                  id: b6fbd994-61a8-4f25-9167-6ec10489c448
                  customerId: 11
                  email: janedoe@example.com
                  currency:
                    name: US Dollars
                    code: USD
                    symbol: $
                    decimalPlaces: 2
                  isTaxIncluded: false
                  baseAmount: 119.93
                  discountAmount: 0
                  cartAmount: 112.93
                  coupons:
                  - id: 1
                    code: S2549JM0Y
                    displayName: $5.00 off the order total
                    couponType: per_total_discount
                    discountedAmount: 5
                  discounts:
                  - id: 69791a88-85c9-4c19-8042-e537621e8a55
                    discountedAmount: 2.59
                  - id: ba2c619d-e6b4-48c2-8809-d88e424ed450
                    discountedAmount: 1.06
                  - id: c72d6651-978d-45e5-881b-c2bb5f7ff1d5
                    discountedAmount: 2.12
                  - id: 6477a4a1-02cf-4287-8bf2-fd043bdd5234
                    discountedAmount: 0.8
                  - id: 871f1f56-4c88-43c3-a6e5-0a647d83d6ac
                    discountedAmount: 0.43
                  lineItems:
                    physicalItems:
                    - id: 69791a88-85c9-4c19-8042-e537621e8a55
                      parentId: {}
                      variantId: 364
                      productId: 184
                      sku: SMA-RED
                      name: Canvas Laundry Cart
                      url: https://{store_domain}/all/canvas-laundry-cart/
                      quantity: 1
                      isTaxable: true
                      imageUrl: https://cdn8.bigcommerce.com/s-id30h7ohwf/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.330.500.jpg?c=2
                      discounts:
                      - id: total-coupon
                        discountedAmount: 0.59
                      - id: 2
                        discountedAmount: 2
                      discountAmount: 2
                      couponAmount: 0
                      originalPrice: 17.99
                      listPrice: 15.99
                      salePrice: 13.99
                      extendedListPrice: 15.99
                      extendedSalePrice: 13.99
                      isShippingRequired: true
                      giftWrapping: {}
                      addedByPromotion: false
                    - id: ba2c619d-e6b4-48c2-8809-d88e424ed450
                      parentId: {}
                      variantId: 341
                      productId: 170
                      sku: ''
                      name: Ceramic Measuring Spoons
                      url: https://{store_domain}/all/ceramic-measuring-spoons/
                      quantity: 1
                      isTaxable: true
                      imageUrl: https://cdn8.bigcommerce.com/s-id30h7ohwf/products/170/images/411/measuringsquares2_1024x1024__07108__95421.1534344522.330.500.jpg?c=2
                      discounts:
                      - id: total-coupon
                        discountedAmount: 1.06
                      discountAmount: 0
                      couponAmount: 0
                      originalPrice: 25
                      listPrice: 25
                      salePrice: 25
                      extendedListPrice: 25
                      extendedSalePrice: 25
                      isShippingRequired: true
                      giftWrapping: {}
                      addedByPromotion: false
                    - id: c72d6651-978d-45e5-881b-c2bb5f7ff1d5
                      parentId: {}
                      variantId: 376
                      productId: 158
                      sku: SKU-A0C8A203
                      name: Chambray Towel
                      url: https://{store_domain}/all/chambray-towel/
                      quantity: 1
                      isTaxable: true
                      imageUrl: https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.330.500.jpg?c=2
                      discounts:
                      - id: total-coupon
                        discountedAmount: 2.12
                      discountAmount: 0
                      couponAmount: 0
                      originalPrice: 49.99
                      listPrice: 49.99
                      salePrice: 49.99
                      extendedListPrice: 49.99
                      extendedSalePrice: 49.99
                      isShippingRequired: true
                      giftWrapping: {}
                      addedByPromotion: false
                    digitalItems:
                    - id: 6477a4a1-02cf-4287-8bf2-fd043bdd5234
                      parentId: {}
                      variantId: 360
                      productId: 189
                      name: Gather Journal Issue 7 - Digital
                      url: https://{store_domain}/all/gather-journal-issue-7/
                      quantity: 1
                      isTaxable: true
                      imageUrl: https://cdn8.bigcommerce.com/s-id30h7ohwf/products/189/images/465/gather_1024x1024__17195__82620.1534344540.330.500.jpg?c=2
                      discounts:
                      - id: total-coupon
                        discountedAmount: 0.8
                      discountAmount: 0
                      couponAmount: 0
                      originalPrice: 18.95
                      listPrice: 18.95
                      salePrice: 18.95
                      extendedListPrice: 18.95
                      extendedSalePrice: 18.95
                      isShippingRequired: false
                      type: digital
                    giftCertificates:
                    - id: 871f1f56-4c88-43c3-a6e5-0a647d83d6ac
                      name: $10.00 Gift Certificate
                      theme: Celebration
                      amount: 10
                      taxable: false
                      sender:
                        name: Jane Doe
                        email: janedoe@example.com
                      recipient:
                        name: John Doe
                        email: johndoe@example.com
                      message: Thank you!
                      type: giftCertificate
                  createdTime: '2018-09-18T15:48:26+00:00'
                  updatedTime: '2018-09-18T16:59:45+00:00'
                billingAddress:
                  id: 5ba11e4a10fb5
                  firstName: Jane
                  lastName: Doe
                  email: janedoe@example.com
                  company: ''
                  address1: 123 Main Street
                  address2: ''
                  city: Austin
                  stateOrProvince: Texas
                  stateOrProvinceCode: TX
                  country: United States
                  countryCode: US
                  postalCode: '78751'
                  phone: '1234567890'
                  customFields:
                  - fieldId: field_25
                    fieldValue: Leave in backyard
                consignments:
                - id: 5ba121929619b
                  shippingCost: 69.94
                  handlingCost: 0
                  couponDiscounts: []
                  discounts: []
                  lineItemIds:
                  - 69791a88-85c9-4c19-8042-e537621e8a55
                  - ba2c619d-e6b4-48c2-8809-d88e424ed450
                  - c72d6651-978d-45e5-881b-c2bb5f7ff1d5
                  selectedShippingOption:
                    id: bb3c818f-17ce-46fe-9475-65933095da0d
                    type: shipping_upsready
                    description: UPS® (UPS Next Day Air®)
                    imageUrl: ''
                    cost: 69.94
                    transitTime: 1 business day
                  address:
                    firstName: Jane
                    lastName: Doe
                    email: janedoe@example.com
                    company: ''
                    address1: 123 Main Street
                    address2: ''
                    city: Austin
                    stateOrProvince: Texas
                    stateOrProvinceCode: TX
                    country: United States
                    countryCode: US
                    postalCode: '78751'
                    phone: '1234567890'
                    customFields:
                    - fieldId: field_25
                      fieldValue: Leave in backyard
                orderId: null
                shippingCostTotal: 69.94
                shippingCostBeforeDiscount: 69.94
                handlingCostTotal: 0
                taxTotal: 28.62
                coupons:
                - id: 1
                  code: S2549JM0Y
                  displayName: $5.00 off the order total
                  couponType: 2
                  discountedAmount: 5
                taxes:
                - name: Store Tax
                  amount: 28.62
                subtotal: 117.93
                grandTotal: 211.49
                giftCertificates: []
                createdTime: '2018-09-18T15:48:26+00:00'
                updatedTime: '2018-09-18T16:59:45+00:00'
                customerMessage: Thank you, BigCommerce
components:
  schemas:
    CartCoupon:
      title: Cart Coupon
      required:
      - code
      type: object
      properties:
        id:
          type: integer
          description: The coupon ID.
        code:
          type: string
          description: the coupon code
        displayName:
          type: string
          description: The coupon title based on different types provided in control panel section.
        couponType:
          type: string
          description: Key name to identify the type of coupon.
          enum:
          - per_item_discount
          - percentage_discount
          - per_total_discount
          - shipping_discount
          - free_shipping
          - promotion
        discountedAmount:
          type: number
          description: The discounted amount applied within a given context.
          format: double
      x-internal: false
    cartLineItemPut:
      title: cartLineItemPut
      type: object
      properties:
        quantity:
          type: number
          description: ''
          format: double
        productId:
          type: number
          description: ''
          format: double
        variantId:
          type: number
          description: ''
          format: double
        giftWrapping:
          $ref: '#/components/schemas/cartLineItemGiftWrapping_Put'
      x-internal: false
    PickupOption:
      type: object
      title: Pickup Option
      description: An option that represents a location where customers can pick up items.
      properties:
        pickupMethodId:
          type: integer
    consignmentAvailableShippingOptions:
      title: consignmentAvailableShippingOptions
      allOf:
      - $ref: '#/components/schemas/consignmentShippingOption_Base'
      - type: object
        properties:
          isRecommended:
            type: boolean
            description: Is this shipping method the recommended shipping option or not.
          additionalDescription:
            type: string
      x-internal: false
    cartLineItemGiftWrapping_Put:
      title: Gift Wrapping Request Data
      required:
      - wrapTogether
      - wrapDetails
      type:
      - object
      - 'null'
      description: if passing null, it will remove the current gift wrapping for the item
      properties:
        wrapTogether:
          type: boolean
          description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually.
          example: true
        wrapDetails:
          type: array
          description: "Details for the gift wrapping option selected. This can be specified for each line item or together based on wrapTogether value.\nIf wrapTogether is false, each element in the wrapDetails array determines each item's specific wrapping. \n(e.g if this line item has 6 quantity, you can pass at maximum 6 elements for the array to spefified each one's wrapping)  \nIf wrapTogether is true, we will only use 1st element in the wrapDetails array to determine what to be wrapped"
          items:
            type: object
            required:
            - id
            properties:
              id:
                type: integer
                description: Identifier of the gift wrapping option selected.
                example: 0
              message:
                type: string
                description: Custom gift message.
                example: Happy Birthday
    consignmentShippingOption_Base:
      title: consignmentShippingOption_Base
      type: object
      properties:
        description:
          type: string
          description: Read only.
          readOnly: true
        id:
          type: string
          description: ''
        type:
          type: string
          description: Specifies the type of shipping option; for example, flat rate, UPS, etc.
        imageUrl:
          type: string
          description: ''
        cost:
          type: number
          description: ''
          format: double
        transitTime:
          type: string
          description: An estimate of the arrival time.
      x-internal: false
    contactEntity:
      title: contactEntity
      type: object
      properties:
        name:
          type: string
          description: ''
        email:
          type: string
          description: ''
      description: Model for sender and receiver objects.
      x-internal: false
    CheckoutCoupon:
      title: Checkout Coupon
      required:
      - code
      type: object
      properties:
        id:
          type: integer
          description: The coupon ID.
        code:
          type: string
          description: the coupon code
        displayName:
          type: string
          description: The coupon title based on different types provided in control panel section.
        couponType:
          type: integer
          description: '|Type `int`|Type Name|

            |-|-|

            |`0`|`per_item_discount`|

            |`1`|`percentage_discount`|

            |`2`|`per_total_discount`|

            |`3`|`shipping_discount`|

            |`4`|`free_shipping`|

            |`5`|`promotion`|'
        discountedAmount:
          type: number
          description: The discounted amount applied within a given context.
          format: double
      x-internal: false
    cartLineItemGiftCertificate_Put:
      title: cartLineItemGiftCertificate_Put
      required:
      - amount
      - quantity
      - recipient
      - sender
      - theme
      type: object
      properties:
        theme:
          type: string
          description: Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.
        amount:
          maximum: 1000
          minimum: 1
          type: number
          description: ''
          format: double
        sender:
          $ref: '#/components/schemas/contactEntity'
        recipient:
          $ref: '#/components/schemas/contactEntity'
        message:
          type: string
          description: Message shown to recipient, as provided by sender.
        quantity:
          type: number
          description: ''
          format: double
      x-internal: false
    checkoutCart:
      title: checkoutCart
      type: object
      properties:
        id:
          type: string
          description: Cart ID, provided after creating a cart with a POST.
          format: uuid
        customer_id:
          type: integer
          description: ID of the customer to which the cart belongs.
          format: int32
        email:
          type: string
          description: The cartʼs email. This is the same email that is used in the billing address.
        currency:
          title: Currency
          type: object
          properties:
            name:
              type: string
              description: The currency name.
            code:
              type: string
              description: 'ISO-4217 currency code. (See: http://en.wikipedia.org/wiki/ISO_4217.)'
            symbol:
              type: string
              description: The currency symbol.
            decimalPlaces:
              type: number
              description: The number of decimal places for the currency. For example, the USD currency has two decimal places.
              format: double
          description: The currency in which prices are displayed; the store default currency.
        isTaxIncluded:
          type: boolean
          description: Boolean representing whether tax information is included.
        baseAmount:
          type: number
          description: Cost of cart’s contents, before applying discounts.
          format: double
        discountAmount:
          type: number
          description: Discounted amount.
          format: double
        cartAmount:
          type: number
          description: Sum of line-items amounts, minus cart-level discounts and coupons. This amount includes taxes, where applicable.
          format: double
        coupons:
          type: array
          description: ''
          items:
            $ref: '#/components/schemas/CartCoupon'
        discounts:
          type: array
          description: ''
          items:
            title: Applied Discount
            type: object
            properties:
              name:
                type: string
                description: The name provided by the merchant.
              discountedAmount:
                type: number
                description: The discounted amount applied within a given context.
                format: double
        lineItems:
          type: object
          description: ''
          items:
            title: Line Item
            required:
            - digitalItems
            - physicalItems
            type: object
            properties:
              physicalItems:
                type: array
                description: ''
                items:
                  title: Item Physical
                  required:
                  - quantity
                  type: object
                  properties:
                    id:
                      type: string
                      description: The line-item ID.
                    parentId:
                      type: string
                      description: The product is part of a bundle such as a product pick list, then the parentId or the main product ID will populate.
                    variantId:
                      type: integer
                      description: ID of the variant.
                    productId:
                      type: integer
                      description: ID of the product.
                    sku:
                      type: string
                      description: SKU of the variant.
                    name:
                      type: string
                      description: The itemʼs product name.
                    url:
                      type: string
                      description: The product URL.
                    quantity:
                      type: number
                      description: Quantity of this item.
                      format: double
                    isTaxable:
                      type: boolean
                      description: Whether the item is taxable.
                    imageUrl:
                      type: string
                      description: A publicly-accessible URL for an image of this item.
                    discounts:
                      type: array
                      description: A list of discounts applied to this item, as an array of AppliedDiscount objects.
                      items:
                        title: Applied Discount
                        type: object
                        properties:
                          name:
                            type: string
                            description: The name provided by the merchant.
                          discountedAmount:
                            type: number
                            description: The discounted amount applied within a given context.
                            format: double
                    discountAmount:
                      type: number
                      description: The total value of all discounts applied to this item (excluding coupon).
                      format: double
                    couponAmount:
                      type: number
                      description: The total value of all coupons applied to this item.
                      format: double
                    listPrice:
                      type: number
                      description: The item’s list price, as quoted by the manufacturer or distributor.
                      format: double
                    salePrice:
                      type: number
                      description: The itemʼs price after all discounts are applied. The final price before tax calculation.
                      format: double
                    extendedListPrice:
                      type: number
                      description: The itemʼs list price multiplied by the quantity.
                      format: double
                    extendedSalePrice:
                      type: number
                      description: The itemʼs sale price multiplied by the quantity.
                      format: double
                    comparisonPrice:
                      type: number
                      description: The itemʼs comparison price
                    extendedComparisonPrice:
                      type: number
                      description: The itemʼs comparison price multiplied by the quantity.
                    type:
                      type: string
                      description: the product type - physical or digital
                    addedByPromotion:
                      type: boolean
                      description: If the item was added automatically by a promotion, such as a coupon or buy one, get one.
                    isShippingRequired:
                      type: boolean
                      description: Whether this item requires shipping to a physical address.
                    isMutable:
                      type: boolean
                      description: ''
                    giftWrapping:
                      title: Gift Wrapping
                      type: object
                      properties:
                        name:
                          type: string
                          description: ''
                        message:
                          type: string
                          description: ''
                        amount:
                          type: number
                          description: ''
                          format: double
              digitalItems:
                type: array
                description: ''
                items:
                  title: Item Digital
                  required:
                  - quantity
                  type: object
                  properties:
                    id:
                      type: string
                      description: The line-item ID.
                    parentId:
                      type: string
                      description: Bundled items will have their parentʼs item ID.
                    variantId:
                      type: number
                      description: ID of the variant.
                      format: double
                    productId:
                      type: number
                      description: ID of the product.
                      format: double
                    sku:
                      type: string
                      description: SKU of the variant.
                    name:
                      type: string
                      description: The itemʼs product name.
                    url:
                      type: string
                      description: The product URL.
                    quantity:
                      type: number
                      description: Quantity of this item.
                      format: double
                  

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-checkout-cart-items-api-openapi.yml