BigCommerce Storefront Carts is a feature-rich platform that allows businesses to easily create and customize their online store shopping cart. With a simple drag-and-drop interface, users can design a seamless and visually appealing shopping experience for customers. This tool also provides various payment options, shipping methods, and tax calculation capabilities to streamline the checkout process.
openapi: 3.0.1
info:
version: Storefront
title: BigCommerce Storefront Carts
description: >-
Manage cart operations and data using frontend JavaScript on BigCommerce
Stencil-powered storefronts.
For info about API accounts, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts).
For info about authenticating BigCommerce APIs, see [Authentication and
Example
Requests](/docs/start/authentication#same-origin-cors-authentication).
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
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: Cart
- name: Cart Currency
- name: Cart Items
paths:
/carts:
get:
tags:
- Cart
summary: BigCommerce Get a Cart
description: >-
Returns a *Cart*.
> #### Note
> * Substitute your storefront domain for `yourstore.example.com`.
> * 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*.
> #### Note
> * Substitute your storefront domain for `yourstore.example.com`.
> * 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.
> #### Note
> * Substitute your storefront domain for `yourstore.example.com`.
> * 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
/carts/{cartId}/items:
post:
tags:
- Cart Items
summary: BigCommerce Add Cart Line Items
description: >-
Adds a line items to the *Cart*.
> #### Notes
> * Substitute your storefront domain for `yourstore.example.com`.
> * The Send a Test Request feature is not currently supported for this
endpoint.
> * Please note that this API endpoint is not concurrent safe, meaning
multiple simultaneous requests could result in unexpected and
inconsistent results.
operationId: addCartLineItem
parameters:
- name: cartId
in: path
description: This cart's unique ID.
required: true
schema:
type: string
format: UUID
- name: include
in: query
description: >-
To return product options add one of the following include:
`lineItems.physicalItems.options`: The Cart returns an abbreviated
result. Use this to return physical items product options. Can also
be used in a /POST to have the extended Cart object return.
`lineItems.digitalItems.options`: The Cart returns an abbreviated
result. Use this to return digital items product options. Can also
be used in a /POST to have the extended Cart object return.
`lineItems.digitalItems.options,lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return digital
and physical options. Can also be used in a /POST to have the
extended Cart object return.
schema:
type: string
default: lineItems.digitalItems.options,lineItems.physicalItems.options
enum:
- lineItems.physicalItems.options
- lineItems.digitalItems.options
- lineItems.digitalItems.options,lineItems.physicalItems.options
responses:
'200':
$ref: '#/components/responses/postCartsItems'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LineItemsRequest'
examples:
With Option Selections:
value:
lineItems:
- quantity: 2
productId: 230
variantId: 124
optionSelections:
- optionId: 10
optionValue: 117
- optionId: 11
optionValue: 125
With Gift Wrapping:
value:
lineItems:
- quantity: 2
productId: 230
variantId: 124
giftWrapping:
wrapTogether: true
wrapDetails:
- id: 1
message: Happy Birthday
description: ''
/carts/{cartId}/items/{itemId}:
put:
tags:
- Cart Items
summary: BigCommerce Update Cart Line Item
description: >-
Updates a *Cart* line item. Updates an existing, single line item
quantity and the price of custom items in a cart.
If a modified product or variant needs to be changed or updated, you can
remove and re-add the product to the cart with the correct variants
using the [Delete Cart Line
Item](/docs/rest-storefront/carts/cart-items#delete-cart-line-item) and
the [Add Cart Line
Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items)
endpoints. You can also use carts mutations that are part of the
[GraphQL Storefront
API](/docs/storefront/cart-checkout/guide/graphql-storefront).
> #### Notes
> * Substitute your storefront domain for `yourstore.example.com`.
> * The Send a Test Request feature is not currently supported for this
endpoint.
> * Please note that this API endpoint is not concurrent safe, meaning
multiple simultaneous requests could result in unexpected and
inconsistent results.
operationId: updateCartLineItem
parameters:
- name: cartId
in: path
description: This cart's unique ID.
required: true
schema:
type: string
format: UUID
- name: itemId
in: path
description: This item's ID.
required: true
schema:
type: string
format: number
- name: include
in: query
description: >-
To return product options add one of the following include:
`lineItems.physicalItems.options`: The Cart returns an abbreviated
result. Use this to return physical items product options. Can also
be used in a /POST to have the extended Cart object return.
`lineItems.digitalItems.options`: The Cart returns an abbreviated
result. Use this to return digital items product options. Can also
be used in a /POST to have the extended Cart object return.
`lineItems.digitalItems.options,lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return digital
and physical options. Can also be used in a /POST to have the
extended Cart object return.
schema:
type: string
default: lineItems.digitalItems.options,lineItems.physicalItems.options
enum:
- lineItems.physicalItems.options
- lineItems.digitalItems.options
- lineItems.digitalItems.options,lineItems.physicalItems.options
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/requestLineItemPut'
examples:
Variant Item:
value:
lineItem:
productId: 229
variantId: 191
quantity: 10
locale: en
Custom Item:
value:
lineItem:
productId: 118
variantId: 140
quantity: 10
optionSelections:
- optionId: 125
optionValue: 127
locale: en
With Gift Wrapping:
value:
lineItem:
quantity: 2
productId: 230
variantId: 124
giftWrapping:
wrapTogether: true
wrapDetails:
- id: 1
message: Happy Birthday
With null Gift Wrapping (will delete current gift wrapping):
value:
lineItem:
quantity: 2
productId: 230
variantId: 124
giftWrapping:
required: true
responses:
'200':
$ref: '#/components/responses/putCartsItems'
x-codegen-request-body-name: lineItem
delete:
tags:
- Cart Items
summary: BigCommerce Delete Cart Line Item
description: >-
Deletes a *Cart* line item.
Removing the last `line_item` in the *Cart* deletes the *Cart*.
> #### Note
> * Substitute your storefront domain for `yourstore.example.com`.
> * The Send a Test Request feature is not currently supported for this
endpoint.
operationId: deleteCartLineItem
parameters:
- name: cartId
in: path
description: This cart's unique ID.
required: true
schema:
type: string
format: UUID
- name: itemId
in: path
description: The ID of the item to delete.
required: true
schema:
type: string
format: number
- name: include
in: query
description: >-
To return product options add one of the following include:
`lineItems.physicalItems.options`: The Cart returns an abbreviated
result. Use this to return physical items product options. Can also
be used in a /POST to have the extended Cart object return.
`lineItems.digitalItems.options`: The Cart returns an abbreviated
result. Use this to return digital items product options. Can also
be used in a /POST to have the extended Cart object return.
`lineItems.digitalItems.options,lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return digital
and physical options. Can also be used in a /POST to have the
extended Cart object return.
schema:
type: string
default: lineItems.digitalItems.options,lineItems.physicalItems.options
enum:
- lineItems.physicalItems.options
- lineItems.digitalItems.options
- lineItems.digitalItems.options,lineItems.physicalItems.options
responses:
'200':
$ref: '#/components/responses/deleteCartsItems'
/carts/{cartId}/currency:
post:
tags:
- Cart Currency
summary: BigCommerce Update Cart Currency
description: >-
Update currency of the *Cart*.
Promotions and gift certificates that don't apply to the new currency
will be removed from your cart.
You cannot update the cart currency if the draft order cart or the cart
contains a manual discount.
> #### Note
> * Substitute your storefront domain for `yourstore.example.com`.
> * The Send a Test Request feature is not currently supported for this
endpoint.
operationId: updateCartCurrency
parameters:
- name: cartId
in: path
description: This cart's unique ID.
required: true
schema:
type: string
format: UUID
responses:
'200':
$ref: '#/components/responses/getCarts'
'400':
description: Bad request. Authentication Required.
'404':
description: Currency not found
'422':
description: Missing or invalid data
requestBody:
content:
application/json:
schema:
title: Cart Currency Request Data
required:
- currencyCode
type: object
properties:
currencyCode:
type: string
description: currency code
x-internal: false
description: ''
components:
schemas:
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
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
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
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
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
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
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.
If wrapTogether is false, each element in the wrapDetails array
determines each item's specific wrapping.
(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)
If 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
LineItemsRequest:
title: requestLineItems
oneOf:
- properties:
lineItems:
type: array
items:
$ref: '#/components/schemas/requestCartPostLineItem'
required:
- lineItems
- properties:
giftCertificates:
type: array
items:
$ref: '#/components/schemas/requestLineItemGiftCertificate'
required:
- giftCertificates
- properties:
lineItems:
type: array
items:
$ref: '#/components/schemas/requestCartPostLineItem'
giftCertificates:
$ref: '#/components/schemas/requestLineItemGiftCertificate'
required:
- lineItems
- giftCertificates
type: object
description: Cart object used in add items requests.
x-internal: false
requestLineItemPut:
title: requestLineItemPut
oneOf:
- properties:
lineItem:
$ref: '#/components/schemas/requestCartPostLineItem'
required:
- lineItem
title: Line item
- properties:
giftCertificates:
$ref: '#/components/schemas/requestLineItemGiftCertificate'
required:
- giftCertificates
title: Gift certificate item
- properties:
lineItem:
$ref: '#/components/schemas/requestCartPostLineItem'
giftCertificates:
$ref: '#/components/schemas/requestLineItemGiftCertificate'
required:
- lineItem
- giftCertificates
title: line & gift certificate items
description: ''
type: object
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
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
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
responseCartLineItemsDigitalItems:
title: Item Digital
allOf:
- $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0'
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
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
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
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
responseCartLineItemsGiftCertificatesSender:
title: Contact Entity
type: object
properties:
email:
type: string
description: Contact's email address.
format:
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/storefront-carts-openapi-original.yml