BigCommerce Carts (Single) API

openapi: 3.2.0
info:
  title: BigCommerce Carts Carts (Single) API
  version: ''
  description: 'Create a cart using BigCommerce cart logic.


    Manage settings related to carts.'
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Carts (Single)
paths:
  /carts:
    parameters:
    - $ref: '#/components/parameters/Accept'
    post:
      description: "Creates a **Cart**. \n\n**Required Fields**\n\n|Field|Details|\n|-|-|\n|`line_item`|Specifies a line item.| \n|`custom_items`|Specifies a custom item. Only required if adding a custom item to the cart.|\n|`gift_certificates`|Specifies a gift certificate. Only required if adding a gift certificate to the cart.|\n\n**Usage Notes**\n\n* A **cart** `id` (UUID) is returned in the response.\n* A **cart** `id` is the same as a **checkout** `id`.\n* A cart can be created by adding an existing **catalog item** or a **custom item**.\n* Carts are valid for **30 days** from the **last modification** (this includes creating the cart or editing the cart).\n* If a product has modifiers, use the `option_selections` array to describe the **modifier** selection(s).\n* The format and data type of a cart’s `option_value` are defined by the `value_data` object of a product’s [variant option value](/docs/rest-catalog/product-variant-options/values), [modifier value](/docs/rest-catalog/product-modifiers/values), or a combination of both.\n* Redirect URLs can only be generated from carts that were created using the **REST Management API**. \n* To get cart `redirect_urls` in the response, append the following query parameter to the request URL: `include=redirect_urls`. Redirect URLs point to either a shared checkout domain or a channel-specific domain, depending on the storefront configuration.\n* To restore a cart that was created by a shopper or through a Storefront API, first recreate the cart using the **REST Management API**.\n* To get cart `promotions` in the response, append the following query parameter to the request URL: `include=promotions.banners`."
      parameters:
      - name: include
        in: query
        description: '* `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts.

          * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request.

          * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request.

          * `promotions.banners`: Returns a list of eligible banners.'
        schema:
          type: string
          enum:
          - redirect_urls
          - line_items.physical_items.options
          - line_items.digital_items.options
          - promotions.banners
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartCreatePostData'
            examples:
              Simple Product:
                summary: Creating a cart by adding a simple product without option selections.
                value:
                  customer_id: 0
                  line_items:
                  - quantity: 2
                    product_id: 126
                    list_price: 5
                    name: calendar
                  channel_id: 1
                  currency:
                    code: USD
                  locale: en-US
              Cart with a variant:
                summary: Creating a cart with a product that can be specified purely by a variant, without any other required options.
                value:
                  customer_id: 0
                  line_items:
                  - quantity: 2
                    product_id: 118
                    list_price: 25
                    variant_id: 140
                    name: قميص
                    option_selections:
                    - option_id: 125
                      option_value: 127
                      name: بحجم
                      value: صغير
                  channel_id: 1
                  currency:
                    code: JOD
                  locale: ar-JO
              Cart with date option:
                summary: Creating a cart using a date option.
                value:
                  line_items:
                  - quantity: 1
                    product_id: 128
                    variant_id: 144
                    option_selections:
                    - option_id: 147
                      option_value: '{“día”:”01”, “mes”:”02”, “año”:”2020”}'
                      name: calendario
                      value: 2023
                  currency:
                    code: MXN
                  locale: es-MX
              Cart with variant, a checkbox, and a pick list modifier:
                summary: Creating a cart with a variant, a checkbox, and an added picklist modifier.
                value:
                  customer_id: 0
                  line_items:
                  - quantity: 1
                    variant_id: 141
                    product_id: 118
                    list_price: 30
                    name: shirt
                    option_selections:
                    - name: Color
                      value: Red
                      option_id: 133
                      option_value: 149
                    - name: Add a $5 Donation
                      value: 'No'
                      option_id: 126
                      option_value: 129
                  channel_id: 1
                  currency:
                    code: AUD
                  locale: en-AU
              Custom item:
                summary: Creating a cart using a custom item.
                value:
                  customer_id: 0
                  line_items: []
                  custom_items:
                  - sku: custom-item-sku
                    name: table
                    quantity: 1
                    list_price: 30
                    gift_wrapping:
                      wrap_together: true
                      wrap_details:
                      - id: 0
                        message: Happy Birthday
                  gift_certificates:
                  - name: Tobi Day
                    theme: birthday.html
                    amount: 1
                    quantity: 1
                    sender:
                      name: Brandi Tyler
                      email: Brandi.Tyler@mail.com
                    recipient:
                      name: Tobi Day
                      email: Tobi.Day@mail.com
                    message: Happy Birthday
                  channel_id: 1
                  currency:
                    code: usd
                  locale: en-US
        description: ''
        required: true
        x-examples:
          Simple Product:
            line_items:
            - quantity: 5
              product_id: 191
          Create a Cart with a Variant:
            line_items:
            - quantity: 2
              product_id: 107
              variant_id: 185
          Create a Cart using Date Option:
            line_items:
            - quantity: 5
              product_id: 191
              variant_id: 185
              option_selections:
              - option_id: 440
                option_value: 1743570000
          With a Variant of Checkbox and Picklist:
            line_items:
            - quantity: 1
              product_id: 77
              option_selections:
              - option_id: 120
                option_value: 69
              - option_id: 121
                option_value: 10
              - option_id: 124
                option_value: 106
              - option_id: 122
                option_value: Hello
              - option_id: 123
                option_value: 104
          Custom Item:
            custom_items:
            - sku: abc-123
              name: Custom Product
              quantity: 1
              list_price: 10
          Options Selections:
            line_items:
            - quantity: 5
              product_id: 118
              variant_id: 115
              option_selections:
              - option_id: 121
                option_value: 10
                name: Size
                nameId: 125
                value: Small
                valueId: 125
      tags:
      - Carts (Single)
      responses:
        '201':
          $ref: '#/components/responses/CartResponse'
      summary: BigCommerce Create a Cart
      operationId: createCart
  /carts/{cartId}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/cartId'
    get:
      description: Returns a storeʼs *Cart*.
      parameters:
      - name: include
        in: query
        description: '* `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts.

          * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request.

          * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request.

          * `promotions.banners`: Returns a list of eligible banners.'
        schema:
          type: string
          enum:
          - redirect_urls
          - line_items.physical_items.options
          - line_items.digital_items.options
          - promotions.banners
      tags:
      - Carts (Single)
      responses:
        '200':
          $ref: '#/components/responses/CartResponse'
        '404':
          description: Cart not found.
      summary: BigCommerce Get a Cart
      operationId: getCart
    put:
      description: 'Updates a *Cartʼs* `customer_id`.


        **Notes**


        Changing the *Cart* `customer_id` will remove any promotions or shipping calculations on the *Cart*. These are tied to the customer depending on cart conditions and any customer groups. '
      parameters:
      - name: include
        in: query
        description: '* `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts.

          * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request.

          * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request.

          * `promotions.banners`: Returns a list of eligible banners.'
        schema:
          type: string
          enum:
          - redirect_urls
          - line_items.physical_items.options
          - line_items.digital_items.options
          - promotions.banners
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartUpdatePutRequestData'
            example:
              customer_id: 5
        required: true
      tags:
      - Carts (Single)
      responses:
        '201':
          $ref: '#/components/responses/CartResponse'
      summary: BigCommerce Update Customer ID
      operationId: updateCart
    delete:
      description: Deletes a *Cart*. Once a *Cart* has been deleted it can’t be recovered.
      tags:
      - Carts (Single)
      responses:
        '204':
          description: ''
      summary: BigCommerce Delete a Cart
      operationId: deleteCart
components:
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
    cartId:
      name: cartId
      in: path
      description: The identifier of a specific cart.
      required: true
      schema:
        type: string
        format: UUID
  schemas:
    AppliedCoupon:
      title: Applied Coupon
      type: object
      description: '|Type `int`|Type Name|

        |-|-|

        |`0`|`per_item_discount`|

        |`1`|`percentage_discount`|

        |`2`|`per_total_discount`|

        |`3`|`shipping_discount`|

        |`4`|`free_shipping`|

        |`5`|`promotion`|'
      x-internal: false
      properties:
        code:
          description: The coupon code.
          type: string
        id:
          description: The coupon ID. (read-only)
          type: string
          readOnly: true
        coupon_type:
          description: 'Key name to identify the type of coupon.


            type 0: per_item_discount

            type 1: percentage_discount

            type 2: per_total_discount

            type 3: shipping_discount

            type 4: free_shipping

            type 5: promotion'
          type: string
          enum:
          - '0'
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          readOnly: true
        discounted_amount:
          description: The discounted amount applied within a given context.
          type: number
          format: double
          readOnly: true
      required:
      - code
    Cart_Full:
      description: A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.
      type: object
      title: Cart_Full
      x-internal: false
      properties:
        id:
          description: Cart ID, provided after creating a cart with a POST request.
          type: string
          format: UUID
        parent_id:
          type: string
          description: Bundled items will have the ID of their parent item.
        customer_id:
          description: ID of the customer to which the cart belongs.
          type: integer
        email:
          description: The cart’s email. This is the same email that is used in the billing address.
          type: string
        currency:
          type: object
          description: The currency. This is the same for both the cart and its subsequent checkout.
          title: Currency
          properties:
            code:
              type: string
              format: ISO-4217
              description: The [transactional currency](/docs/rest-management/currencies#definitions) code for the cart, formatted as an [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) string.
              example: usd
        tax_included:
          type: boolean
        base_amount:
          type: number
          description: Sum of cart line-item amounts before cart-level discounts, coupons, or taxes.
        discount_amount:
          type: number
          description: Order-based discounted amount only - Excludes coupon discounts and product-based discounts.
        cart_amount:
          type: number
          description: Sum of cart line-item amounts minus cart-level discounts and coupons. This amount includes taxes (where applicable).
        coupons:
          type: array
          items:
            $ref: '#/components/schemas/AppliedCoupon'
        discounts:
          type: array
          items:
            type: object
            title: Applied Discount
            description: "Example as part of a cart response:\n\n```\n  \"discounts\": [\n    {\n      \"id\": 2,\n      \"discounted_amount\": 2\n    },\n    {\n      \"id\": \"coupon\",\n      \"discounted_amount\": 0.42\n    }\n  ]\n```"
            properties:
              id:
                type: string
                description: ID of the applied discount.
                example: coupon
              discounted_amount:
                type: number
                description: The discounted amount.
        line_items:
          $ref: '#/components/schemas/LineItemsGet'
        created_time:
          type: string
          format: ISO-8601
          description: Time when the cart was created.
        updated_time:
          type: string
          format: ISO-8601
          description: Time when the cart was last updated.
        channel_id:
          type: integer
          description: The channel ID. If no channel is specified, defaults to 1.
        locale:
          type: string
          description: Locale of the cart. Accepts strings of format `xx` or `xx-YY`. Uses the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format.
          format: ISO-639
        promotions:
          type: object
          description: This is available only when "include=promotions.banners" is presented in the URL.
          properties:
            banners:
              title: Banner
              type: object
              properties:
                id:
                  description: ID of the promotion.
                  type: string
                type:
                  description: Type of the banner.
                  type: string
                page:
                  description: An array of the locations where the banner will display.
                  type: array
                  items:
                    type: string
                text:
                  description: Text of the banner.
                  type: string
    ItemDigitalGet:
      allOf:
      - title: Base Item
        properties:
          id:
            type: string
            description: The line-item ID.
            example: 6e193ce6-f327-4dcc-b75e-72cf6738525e
          variant_id:
            type: number
            description: The ID of the variant. Required in the /PUT or /POST request if the product has variants.
            example: 358
          product_id:
            type: number
            description: The ID of the product. Required in a /POST request.
            example: 12
          sku:
            type: string
            example: SMGREEN
            description: SKU of the variant.
          name:
            type: string
            description: The item’s product name.
            example: T-Shirt
          url:
            description: The product URL.
            type: string
            format: uri
            example: http://your-store-url.mybigcommerce.com/your-product/
          quantity:
            type: number
            example: 5
            description: Quantity of this item in the cart.
          is_taxable:
            type: boolean
            example: false
            description: Boolean value that specifies whether the item is taxable.
          image_url:
            type: string
            format: uri
            example: https://pathtoproductimage/ProductDefault.png
            description: Image of the product or variant.
          discounts:
            type: array
            items:
              type: object
              title: Applied Discount
              description: "Example as part of a cart response:\n\n```\n  \"discounts\": [\n    {\n      \"id\": 2,\n      \"discounted_amount\": 2\n    },\n    {\n      \"id\": \"coupon\",\n      \"discounted_amount\": 0.42\n    }\n  ]\n```"
              properties:
                id:
                  oneOf:
                  - type: string
                  - type: number
                discounted_amount:
                  type: number
                  description: The discounted amount.
          coupons:
            oneOf:
            - type: number
            - type: array
              items:
                type: object
                title: Applied Coupon
                properties:
                  id:
                    type: integer
                    example: 6
                    description: ID of the coupon.
                  code:
                    type: string
                    example: KV56053388J
                    description: The coupon code. Required in a /POST request.
                  name:
                    type: string
                    example: Percentage off
                    description: Name given to the coupon in the control panel.
                  discountType:
                    type: integer
                    description: 'The discount type.

                      - type 0: per_item_discount

                      - type 1: percentage_discount

                      - type 2: per_total_discount

                      - type 3: shipping_discount

                      - type 4: free_shipping

                      '
                    example: 3
                    enum:
                    - 0
                    - 1
                    - 2
                    - 3
                    - 4
                  discountAmount:
                    type: integer
                    description: The amount of the discount based on the coupon. For example, 3 percent off will show a 3.
                    example: 3
                  expiresDate:
                    type: integer
                    example: 0
                    description: Returns 0 if no expiration date has been set.
                  totalDiscount:
                    type: number
                    example: 4.19
                    description: The total amount of all discounts applied to the cart.
                required:
                - code
          discount_amount:
            type: number
            description: The total value of all discounts applied to this item. This includes coupons and cart-level discounts.
            example: 4
          coupon_amount:
            type: number
            description: The total value of all coupons applied to this item.
          original_price:
            type: number
            description: An item’s original price is the same as the product default price in the admin panel.
          list_price:
            type: number
            description: The net item price before discounts and coupons. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel.
          sale_price:
            type: number
            description: Item’s price after all discounts are applied. (The final price before tax calculation.)
          extended_list_price:
            type: number
            description: List price of the item multiplied by the quantity.
          extended_sale_price:
            type: number
            description: Sale price of the item multiplied by the quantity.
          options:
            description: The list of selected options for this product.
            type: array
            items:
              type: object
              title: Product Option
              properties:
                name:
                  type: string
                  description: The product option name; for example, Color or Size.
                nameId:
                  type: number
                  description: The product option identifier.
                value:
                  type: string
                  description: The product option value; for example, Red or Medium.
                valueId:
                  type: number
                  description: The product option value identifier in number format.
                  example: 128
      - properties:
          download_file_urls:
            description: URLs to download all product files.
            type: array
            items:
              type: string
              format: url
          download_page_url:
            description: The URL for the combined downloads page.
            type: string
            format: url
          download_size:
            description: Specifies the combined download size of all files in human-readable style; for example, `30MB`.
            type: string
      type: object
      title: ''
      description: ''
    ItemCustomGet:
      type: object
      title: Item Custom
      description: 'Add a custom item to the shopperʼs cart.


        * Custom items are not added to the catalog.

        * The price should be set to match the store settings for taxes.'
      x-internal: false
      properties:
        id:
          type: string
          description: ID of the custom item.
        sku:
          type: string
          description: SKU of the custom item.
        name:
          type: string
          description: Name of the item.
        quantity:
          type: string
        list_price:
          type: string
          description: Specifies the price of the item. This value can include or exclude tax, depending on the store setup.
    LineItemsGet:
      title: LineItemsGet
      type: object
      properties:
        physical_items:
          type: array
          items:
            $ref: '#/components/schemas/ItemPhysicalGet'
        digital_items:
          type: array
          items:
            $ref: '#/components/schemas/ItemDigitalGet'
        gift_certificates:
          type: array
          items:
            $ref: '#/components/schemas/ItemGiftCertificateGet'
        custom_items:
          type: array
          items:
            $ref: '#/components/schemas/ItemCustomGet'
      description: '`GET`'
    cart_PostCustomItem:
      type: array
      title: Custom item
      x-internal: false
      items:
        type: object
        properties:
          sku:
            type: string
          name:
            type: string
            minLength: 1
            maxLength: 250
          quantity:
            type: number
          list_price:
            type: number
      x-examples:
        example-1:
        - sku: string
          name: string
          quantity: 0
          list_price: 0
    cart_PostModifier:
      type: object
      title: Item with modifier
      properties:
        quantity:
          type: number
        product_id:
          type: number
        list_price:
          type: number
          description: Optional price override.
        name:
          type: string
          description: Optionally, provide a value to override the product name.
        option_selections:
          type: array
          description: Needed for Catalog V2.
          items:
            type: object
            properties:
              option_id:
                type: integer
              option_value:
                type: integer
              name:
                type: string
                description: Override for the selected option or modifier name.
              value:
                type: string
                description: Override for the selected option value.
              nameId:
                type: integer
              valueId:
                type: integer
      required:
      - quantity
      - product_id
      description: Product with a modifier.
      x-internal: false
      x-examples:
        example-1:
        - quantity: 0
          product_id: 0
          list_price: 0
          name: string
          option_selections:
          - option_id: 0
            option_value: 0
            name: string
            value: string
            name_id: 0
            value_id: 0
    ItemGiftCertificateGet:
      type: object
      title: Item Gift Certificate
      x-internal: false
      properties:
        id:
          type: string
        name:
          type: string
          description: Name provided for the gift certificate that will appear in the control panel.
        theme:
          type: string
          description: The theme of the gift certificate. The following options are available:`birthday.html`, `boy.html`, `celebration.html`, `christmas.html`, `general.html`, and `girl.html`.
        amount:
          type: number
          description: Value must be between 1.00 and 1,000.00 in the store’s default currency.
        is_taxable:
          type: boolean
        sender:
          title: Contact Entity
          type: object
          properties:
            name:
              type: string
            email:
              type: string
        recipient:
          title: Contact Entity
          type: object
          properties:
            name:
              type: string
            email:
              type: string
        message:
          type: string
          description: The message included in the gift certificate is limited to 200 characters.
    CartUpdatePutRequestData:
      type: object
      properties:
        customer_id:
          type: integer
      title: Cart Update Put Request Data
      x-internal: false
    ItemPhysicalGet:
      allOf:
      - type: object
        title: Base Item
        properties:
          id:
            type: string
            description: The line-item ID.
            example: 6e193ce6-f327-4dcc-b75e-72cf6738525e
          variant_id:
            type: number
            description: The ID of the variant. Required in the /PUT or /POST request if the product has variants.
            example: 358
          product_id:
            type: number
            description: The ID of the product. Required in a /POST request.
            example: 12
          sku:
            type: string
            example: SMGREEN
            description: SKU of the variant.
          name:
            type: string
            description: The item’s product name.
            example: T-Shirt
          weight:
            type: number
            description: The weight is displayed here if the item has a custom dimension.
            example: 1.2
          dimensions:
            type: object
            properties:
              height:
                type: number
                description: The height is displayed here if the item has a custom dimension.
                example: 2
              width:
                type: number
                description: The width is displayed here if the item has a custom dimension.
                example: 2.1
              depth:
                type: number
                description: The depth is displayed here if the item has a custom dimension.
                example: 2.2
          url:
            description: The product URL.
            type: string
            format: uri
            example: http://your-store-url.mybigcommerce.com/your-product/
          quantity:
            type: number
            example: 5
            description: Quantity of this item in the cart.
          is_taxable:
            type: boolean
            example: false
            description: Boolean value that specifies whether the item is taxable.
          image_url:
            type: string
            format: uri
            example: https://pathtoproductimage/ProductDefault.png
            description: Image of the product or variant.
          discounts:
            type: array
            items:
              type: object
              title: Applied Discount
              description: "Example as part of a cart response:\n\n```\n  \"discounts\": [\n    {\n      \"id\": 2,\n      \"discounted_amount\": 2\n    },\n    {\n      \"id\": \"coupon\",\n      \"discounted_amount\": 0.42\n    }\n  ]\n```"
              properties:
                id:
                  oneOf:
                  - type: string
                  - type: number
                discounted_amount:
                  type: number
                  description: The discounted amount.
          coupons:
            oneOf:
            - type: number
            - type: array
              items:
                type: object
                title: Applied Coupon
                properties:
                  id:
                    type: integer
                    example: 6
                    description: ID of the coupon.
                  code:
                    type: string
                    example: KV56053388J
                    description: The coupon code. Required in a /POST request.
                  name:
                    type: string
                    example: Percentag

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-carts-single-api-openapi.yml