BigCommerce
BigCommerce Cart API

The Cart API from BigCommerce — 2 operation(s) for cart.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Emails Cart API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  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: Cart
paths:
  /carts:
    get:
      tags:
      - Cart
      summary: BigCommerce Get a Cart
      description: "Returns a *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: getCart
      parameters:
      - $ref: '#/components/parameters/include'
      responses:
        '200':
          $ref: '#/components/responses/getCarts'
    post:
      tags:
      - Cart
      summary: BigCommerce Create a Cart
      description: "Creates a *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: createCart
      parameters:
      - $ref: '#/components/parameters/include'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestCart'
            examples:
              With Text Modifier:
                value:
                  lineItems:
                  - quantity: 2
                    productId: 230
                    optionSelections:
                    - optionId: 10
                      optionValue: Some Text Value
                  locale: en
              With Gift Wrapping:
                value:
                  lineItems:
                  - quantity: 2
                    productId: 230
                    optionSelections:
                    - optionId: 10
                      optionValue: Some Text Value
                    giftWrapping:
                      wrapTogether: true
                      wrapDetails:
                      - id: 1
                        message: Happy Birthday
                  locale: en
        required: true
      responses:
        '200':
          $ref: '#/components/responses/postCarts'
      x-codegen-request-body-name: cartData
  /carts/{cartId}:
    delete:
      tags:
      - Cart
      summary: BigCommerce Delete a Cart
      description: "Deletes a *Cart*. Once a *Cart* has been deleted it can not be recovered.\n\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: deleteCart
      parameters:
      - name: cartId
        in: path
        description: This cart's unique ID.
        required: true
        schema:
          type: string
          format: UUID
      responses:
        '204':
          description: No Content
components:
  schemas:
    requestLineItemGiftCertificateRecipient:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    responseCartLineItemsPhysicalItemGiftWrapping:
      title: Gift Wrapping
      type: object
      properties:
        amount:
          type: number
          description: Gift-wrapping price per product.
          format: float
        message:
          type: string
        name:
          type: string
          description: Name of the gift-wrapping option.
      nullable: true
      x-internal: false
    responseCartLineItemsDigitalItems:
      title: Item Digital
      allOf:
      - $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0'
      x-internal: false
    responseCartLineItemsCustomItems:
      title: Item Custom
      type: object
      properties:
        extendedListPrice:
          type: integer
          readOnly: true
        id:
          type: string
          description: ID of the custom item
          readOnly: true
          example: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff
        listPrice:
          type: integer
          description: Price of the item. With or without tax depending on your stores set up.
          readOnly: true
          example: 10
        name:
          type: string
          description: Name of the custom item.
          readOnly: true
          example: Custom Item Name
        quantity:
          type: integer
          readOnly: true
          example: 1
        sku:
          type: string
          description: SKU of the custom item.
          readOnly: true
          example: SM-456
      description: '**Read Only**


        This will return in the Cart Response if the Cart was created using the [REST Management API](/docs/rest-management/carts). A custom item can only be added to a cart using the REST Management API.'
      x-internal: false
    responseCartCurrency:
      title: Currency
      type: object
      properties:
        code:
          type: string
          description: 'ISO-4217 currency code. (See: http://en.wikipedia.org/wiki/ISO_4217.)'
          format: ISO-4217
      description: This will always be the same between cart and checkout.
      x-go-gen-location: models
      x-internal: false
    responseCartLineItemsGiftCertificatesSender:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    responseCartLineItemsItemsPhysicalItemsItems:
      title: Item Physical
      allOf:
      - $ref: '#/components/schemas/responseCartBaseItem'
      - $ref: '#/components/schemas/responseCartLineItemsItemsPhysicalItemsItemsAllOf1'
      x-internal: false
    responseCartCoupons:
      title: Response Cart Coupons
      type: array
      items:
        required:
        - code
        type: object
        properties:
          code:
            type: string
            description: The coupon code.
          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: float
          id:
            type: string
            description: The coupon ID.
      x-internal: false
    responseCartLineItemsItemsPhysicalItemsItemsAllOf0OptionsItems:
      title: Product Option
      type: object
      properties:
        name:
          type: string
          description: The product option name. For example, Color or Size
        nameId:
          type: number
          description: The product option identifier. It is the same as the `optionId` used in the request.
          example: 125
        value:
          type: string
          description: The product option value. For example, Red or Medium
        valueId:
          type: number
          description: The product option value identifier. It is the same as the `optionValue` used in the request.
          example: 127
      x-internal: false
    responseCartLineItemsItemsPhysicalItemsItemsAllOf1:
      type: object
      properties:
        giftWrapping:
          $ref: '#/components/schemas/responseCartLineItemsPhysicalItemGiftWrapping'
        isShippingRequired:
          type: boolean
          description: Whether this item requires shipping to a physical address.
      x-internal: false
    responseCartBaseItem:
      title: Base Item
      type: object
      properties:
        options:
          type: array
          description: The list of selected options for this product.
          items:
            $ref: '#/components/schemas/responseCartLineItemsItemsPhysicalItemsItemsAllOf0OptionsItems'
        brand:
          type: string
          description: The products brand
        couponAmount:
          type: number
          description: The total value of all coupons applied to this item.
        discountAmount:
          type: number
          description: The total value of all discounts applied to this item (excluding coupon).
          format: float
        discounts:
          $ref: '#/components/schemas/responseCartDiscounts'
        extendedListPrice:
          type: number
          description: Item's list price multiplied by the quantity.
        extendedSalePrice:
          type: number
          description: Item's sale price multiplied by the quantity.
        id:
          type: string
          description: The line-item ID.
          example: '4'
        imageUrl:
          type: string
          description: URL of an image of this item, accessible on the internet.
          format: uri
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        listPrice:
          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.
        originalPrice:
          type: number
          description: An item’s original price is the same as the product default price in the admin panel.
        name:
          type: string
          description: The item's product name.
        parentId:
          type: number
          description: The product is part of a bundle such as a product pick list, then the parentId or the main product id will populate.
          example: 6
        productId:
          type: number
          description: ID of the product.
        quantity:
          type: number
          description: Quantity of this item.
        salePrice:
          type: number
          description: Item's price after all discounts are applied. (The final price before tax calculation.)
        sku:
          type: string
          description: SKU of the variant.
        url:
          type: string
          description: The product URL.
          format: uri
        variantId:
          type: number
          description: ID of the variant.
          example: 7
      required:
      - quantity
      x-internal: false
    responseCartLineItemsDigitalItemsAllOf0DiscountsItems:
      title: Applied Discount
      type: object
      properties:
        discountedAmount:
          type: number
          description: The discounted amount applied within a given context.
          format: float
        id:
          type: number
          description: ID of the applied discount.
      x-internal: false
    requestPostOrPutGiftWrapping:
      title: Gift Wrapping Request Data
      required:
      - wrapTogether
      - wrapDetails
      type: object
      nullable: true
      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
    requestCart:
      title: Create Cart Request Object
      description: Cart object used in create cart requests.
      oneOf:
      - properties:
          lineItems:
            type: array
            items:
              $ref: '#/components/schemas/requestCartPostLineItem'
          locale:
            type: string
        required:
        - lineItems
      - properties:
          giftCertificates:
            type: array
            items:
              $ref: '#/components/schemas/requestLineItemGiftCertificate'
          locale:
            type: string
        required:
        - giftCertificates
      - properties:
          lineItems:
            type: array
            items:
              $ref: '#/components/schemas/requestCartPostLineItem'
          giftCertificates:
            $ref: '#/components/schemas/requestLineItemGiftCertificate'
          locale:
            type: string
        required:
        - lineItems
        - giftCertificates
      type: object
      x-internal: false
    responseCartLineItems:
      title: Response Line Items Object
      type: object
      properties:
        customItems:
          type: array
          items:
            $ref: '#/components/schemas/responseCartLineItemsCustomItems'
        digitalItems:
          type: array
          description: Array of `ItemDigital` objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsDigitalItems'
        giftCertificates:
          type: array
          description: Array of `ItemGiftCertificate` objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsGiftCertificates'
        physicalItems:
          type: array
          description: Array of `ItemPhysical` objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsItemsPhysicalItemsItems'
      x-internal: false
    responseCartLineItemsGiftCertificates:
      title: Item Gift Certificate
      required:
      - amount
      - recipient
      - sender
      - theme
      type: object
      properties:
        amount:
          type: number
          description: Value must be between 1.00 and 1,000.00 in the storeʼs default currency.
        id:
          type: string
          description: ID of this gift certificate.
        isTaxable:
          type: boolean
          description: Whether or not the gift certificate is taxable.
        message:
          type: string
          description: Message that will be sent to the gift certificate's recipient. Limited to 200 characters.
        name:
          type: string
          description: GiftCertificate-provided name that will appear in the control panel.
        recipient:
          $ref: '#/components/schemas/responseCartLineItemsGiftCertificatesRecipient'
        sender:
          $ref: '#/components/schemas/responseCartLineItemsGiftCertificatesSender'
        theme:
          type: string
          description: Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.
      x-internal: false
    responseCartLineItemsGiftCertificatesRecipient:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    requestCartPostLineItem:
      title: Line Item Request Data
      anyOf:
      - properties:
          productId:
            type: number
            description: ID of the product.
          quantity:
            type: number
            description: Quantity of this item.
          giftWrapping:
            $ref: '#/components/schemas/requestPostOrPutGiftWrapping'
        required:
        - productId
        - quantity
        title: Simple product
      - properties:
          productId:
            type: number
            description: ID of the product.
          quantity:
            type: number
            description: Quantity of this item.
          variantId:
            type: number
            description: ID of the variant.
          giftWrapping:
            $ref: '#/components/schemas/requestPostOrPutGiftWrapping'
        required:
        - productId
        - quantity
        - variantId
        title: Product with a variant
      x-examples:
        example-1:
          productId: 0
          quantity: 0
      x-internal: false
      type: object
    responseCartDiscounts:
      title: responseCartDiscounts
      type: array
      items:
        type: object
        properties:
          discountedAmount:
            type: number
            description: The discounted amount applied within a given context.
            format: float
          id:
            type: string
            description: ID of the applied discount.
      x-internal: false
    requestLineItemGiftCertificateSender:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    requestLineItemGiftCertificate:
      title: Line Item Gift Certificate Request Data
      required:
      - amount
      - name
      - quantity
      - recipient
      - sender
      - theme
      type: object
      properties:
        amount:
          maximum: 1000
          minimum: 1
          type: number
          description: Gift-certificate amount.
        message:
          type: string
          description: Message shown to recipient, as provided by sender.
        name:
          type: string
          description: Name assigned to this gift-certificate line item.
        quantity:
          minimum: 1
          type: integer
          description: Quantity of this item.
        recipient:
          $ref: '#/components/schemas/requestLineItemGiftCertificateRecipient'
        sender:
          $ref: '#/components/schemas/requestLineItemGiftCertificateSender'
        theme:
          type: string
          description: Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.
      x-internal: false
    responseCartLineItemsDigitalItemsAllOf0OptionsItems:
      title: Product Option
      type: object
      properties:
        name:
          type: string
          description: The product option name. For example, Color or Size
        nameId:
          type: number
          description: 'The product option identifier. It is the same as the `optionId` used in the request. '
          example: 125
        value:
          type: string
          description: The product option value. For example, Red or Medium
        valueId:
          type: number
          description: The product option value identifier. It is the same as the `optionValue` used in the request.
          example: 127
      x-internal: false
    responseCartLineItemsDigitalItemsAllOf0:
      title: Base Item
      required:
      - quantity
      type: object
      properties:
        options:
          type: array
          description: The list of selected options for this product.
          items:
            $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0OptionsItems'
        brand:
          type: string
          description: The products brand
        couponAmount:
          type: number
          description: The total value of all coupons applied to this item.
        discountAmount:
          type: number
          description: The total value of all discounts applied to this item (excluding coupon).
          format: float
        discounts:
          type: array
          description: List of discounts applied to this item, as an array of AppliedDiscount objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0DiscountsItems'
        extendedListPrice:
          type: number
          description: Item's list price multiplied by the quantity.
        extendedSalePrice:
          type: number
          description: Item's sale price multiplied by the quantity.
        id:
          type: string
          description: The line-item ID.
          example: '4'
        imageUrl:
          type: string
          description: URL of an image of this item, accessible on the internet.
          format: uri
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        listPrice:
          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.
        originalPrice:
          type: number
          description: An item’s original price is the same as the product default price in the admin panel.
        name:
          type: string
          description: The item's product name.
        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.
          example: '6'
        productId:
          type: number
          description: ID of the product.
        quantity:
          type: number
          description: Quantity of this item.
        salePrice:
          type: number
          description: Item's price after all discounts are applied. (The final price before tax calculation.)
        sku:
          type: string
          description: SKU of the variant.
        url:
          type: string
          description: The product URL.
          format: uri
        variantId:
          type: number
          description: ID of the variant.
          example: 7
      x-internal: false
    responseCart:
      description: Cart object used in REST Storefront API cart responses.
      title: Cart Read
      type: object
      properties:
        id:
          type: string
          description: Cart ID, provided after creating a cart with a POST.
          format: UUID
        customerId:
          type: integer
          description: ID of the customer to which the cart belongs.
        email:
          type: string
          description: The cart's email. This is the same email that is used in the billing address
        currency:
          $ref: '#/components/schemas/responseCartCurrency'
        isTaxIncluded:
          type: boolean
          description: Whether this item is taxable.
        baseAmount:
          type: number
          description: Cost of cart’s contents, before applying discounts.
        discountAmount:
          type: number
          description: Order based discounted amount only - Coupon discounts and product based discounts are excluded.
          format: float
        cartAmount:
          type: number
          description: Sum of line-items amounts, minus cart-level discounts and coupons. This amount includes taxes (where applicable).
        coupons:
          $ref: '#/components/schemas/responseCartCoupons'
        discounts:
          $ref: '#/components/schemas/responseCartDiscounts'
        lineItems:
          $ref: '#/components/schemas/responseCartLineItems'
        createdTime:
          type: string
          description: Time when the cart was created.
          format: ISO-8601
        updatedTime:
          type: string
          description: Time when the cart was last updated.
          format: ISO-8601
        locale:
          type: string
          description: Locale of the cart.
      x-internal: false
  responses:
    postCarts:
      description: Post Carts Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/responseCart'
          examples:
            Example:
              value:
                id: string
                customerId: 0
                email: string
                currency:
                  code: string
                isTaxIncluded: true
                baseAmount: 0
                discountAmount: 0
                cartAmount: 0
                coupons:
                - code: string
                  couponType: 0
                  discountedAmount: 0
                  id: string
                discounts:
                - discountedAmount: 0
                  id: string
                lineItems:
                  customItems: []
                  digitalItems:
                  - options:
                    - name: string
                      nameId: 0
                      value: string
                      valueId: 0
                    brand: string
                    couponAmount: 0
                    discountAmount: 0
                    discounts:
                    - discountedAmount: 0
                      id: 0
                    extendedListPrice: 0
                    extendedSalePrice: 0
                    id: '4'
                    imageUrl: http://example.com
                    isTaxable: true
                    listPrice: 0
                    originalPrice: 0
                    name: string
                    parentId: '6'
                    productId: 0
                    quantity: 0
                    salePrice: 0
                    sku: string
                    url: http://example.com
                    variantId: 7
                  giftCertificates:
                  - amount: 0
                    id: string
                    isTaxable: true
                    message: string
                    name: string
                    recipient:
                      email: user@example.com
                      name: string
                    sender:
                      email: user@example.com
                      name: string
                    theme: string
                  physicalItems:
                  - options:
                    - name: string
                      nameId: 0
                      value: string
                      valueId: 0
                    brand: string
                    couponAmount: 0
                    discountAmount: 0
                    discounts:
                    - discountedAmount: 0
                      id: string
                    extendedListPrice: 0
                    extendedSalePrice: 0
                    id: '4'
                    imageUrl: http://example.com
                    isTaxable: true
                    listPrice: 0
                    originalPrice: 0
                    name: string
                    parentId: 6
                    productId: 0
                    quantity: 0
                    salePrice: 0
                    sku: string
                    url: http://example.com
                    variantId: 7
                    giftWrapping:
                      amount: 0
                      message: string
                      name: string
                    isShippingRequired: true
                createdTime: string
                updatedTime: string
                locale: string
    getCarts:
      description: ''
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/responseCart'
          examples:
            Example:
              value:
              - id: 770ded29-da45-4ee0-abc6-883e83c0e5ed
                customerId: 0
                email: ''
                currency:
                  name: US Dollars
                  code: USD
                  symbol: $
                  decimalPlaces: 2
                isTaxIncluded: false
                baseAmount: 246
                discountAmount: 0
                cartAmount: 221.4
                coupons: []
                discounts:
                - id: a83dea21-d757-47a2-a06a-73cf6a983746
                  discountedAmount: 24.6
                lineItems:
                  physicalItems:
                  - id: a83dea21-d757-47a2-a06a-73cf6a983746
                    parentId: 6
                    variantId: 193
                    productId: 230
                    sku: sku123-VA
                    name: options test
                    url: https://store.example.com/options-test/
                    quantity: 2
                    brand: BigCommerce
                    isTaxable: true
                    imageUrl: https://cdn11.bigcommerce.com/r-3b68d717e18793df0b51c71e16bc24664ad18b7c/themes/ClassicNext/images/ProductDefault.gif
                    discounts:
                    - id: string
                      discountedAmount: 24.6
                    discountAmount: 24.6
                    couponAmount: 0
                    originalPrice: 130
                    listPrice: 123
                    salePrice: 110.7
                    extendedListPrice: 246
                    extendedSalePrice: 221.4
                    isShippingRequired: true
                    type: physical
                    isMutable: true
                    giftWrapping: null
                  digitalItems: []
                  giftCertificates: []
                  customItems: []
                createdTime: '2021-03-04T14:17:50+00:00'
                updatedTime: '2021-03-04T14:17:50+00:00'
                locale: en
  parameters:
    include:
      name: include
      in: query
      description: Include product options in specified line item types.
      schema:
        type: string
        enum:
        - lineItems.physicalItems.options
        - lineItems.digitalItems.options
        - lineItems.digitalItems.options,lineItems.physicalItems.options
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        | Information & Settings  | read-only  | `store_v2_information_read_only`|

        | Information & Settings  | modify     | `store_v2_information`          |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header
BigCommerce Cart API

Documentation

Specifications

Other Resources

OpenAPI Specification
