BigCommerce Carts is a leading e-commerce platform that provides users with a powerful and user-friendly shopping cart solution. With BigCommerce Carts, businesses can easily create and customize their online store, add products, and manage orders and inventory with ease. The platform is designed to be scalable and versatile, allowing businesses of all sizes to grow and succeed in the competitive online marketplace.
openapi: 3.0.3
info:
title: BigCommerce Carts
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: [email protected]
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: Batch Metafields
- name: Carts (Single)
- name: Items
- name: Metafields
- name: Redirects - Cart Redirect URLs
- name: Settings
paths:
/carts:
parameters:
- $ref: '#/components/parameters/Accept'
post:
description: >-
Creates a **Cart**.
**Required Fields**
|Field|Details|
|-|-|
|`line_item`|Specifies a line item.|
|`custom_items`|Specifies a custom item. Only required if adding a
custom item to the cart.|
|`gift_certificates`|Specifies a gift certificate. Only required if
adding a gift certificate to the cart.|
**Usage Notes**
* A **cart** `id` (UUID) is returned in the response.
* A **cart** `id` is the same as a **checkout** `id`.
* A cart can be created by adding an existing **catalog item** or a
**custom item**.
* Carts are valid for **30 days** from the **last modification** (this
includes creating the cart or editing the cart).
* If a product has modifiers, use the `option_selections` array to
describe the **modifier** selection(s).
* 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.
* Redirect URLs can only be generated from carts that were created using
the **REST Management API**.
* 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.
* To restore a cart that was created by a shopper or through a
Storefront API, first recreate the cart using the **REST Management
API**.
* 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: [email protected]
recipient:
name: Tobi Day
email: [email protected]
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}/items:
parameters:
- $ref: '#/components/parameters/cartId'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ContentType'
post:
description: >-
Adds line item to the *Cart*.
**Usage Notes**
To add a custom item use `custom_items`.
Overriding a product’s `list_price` will make that item ineligible for
V3 product level promotions.
If a product has modifiers, omit the `variant_id` and instead use the
`option_selections` array to describe both the **variant** and the
**modifier** selections.
Please note that this API endpoint is not concurrent safe, meaning
multiple simultaneous requests could result in unexpected and
inconsistent results.
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Cart_Line_Item_Update_Post'
examples:
Example 1:
value:
line_items:
- quantity: 2
product_id: 77
list_price: 12.5
option_selections:
- option_id: 8
option_value: 'Yes'
gift_certificates:
- name: Happy Birthday
theme: birthday.html
amount: 50
quantity: 1
sender:
name: Jane Does
email: [email protected]
recipient:
name: Jane Does
email: [email protected]
message: Happy Birthday Jane!
'Example 2: Custom Item':
value:
custom_items:
- sku: abc-123
name: Custom Product
quantity: 1
list_price: 10
required: true
tags:
- Items
responses:
'201':
$ref: '#/components/responses/CartResponse'
summary: BigCommerce Add Cart Line Items
operationId: addCartLineItems
/carts/{cartId}/redirect_urls:
parameters:
- $ref: '#/components/parameters/cartId'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ContentType'
post:
description: >-
Creates a **Cart** redirect URL for redirecting a shopper to an already
created cart using the `cartId`.
**Usage Notes**
* Redirect URLs can also be created with **Create a Cart** requests by
appending `include=redirect_urls`.
* A **Carts** redirect URL may only be used once.
* Redirect URLs point to either a shared checkout domain or a
channel-specific domain, depending on the storefront configuration.
* Once a redirect URL has been visited, it will be invalidated and
cannot be used again.
* If your application requires URLs to be visited more than once,
consider generating a fresh one each time you need to restore a cart,
and redirecting to the URL from your own application.
* Redirect URLs can be generated only from carts that were created using
the **REST Management API**.
* To restore a cart that was created on the storefront, either by a
shopper or a Storefront API, first recreate the cart using the **REST
Management API**.
* When redirecting the shopper, you can add a set of `query_params` to
the URL. The `query_params` feature allows passing additional
information to the redirect URL.
tags:
- Redirects - Cart Redirect URLs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Redirect_urls_Post'
responses:
'201':
$ref: '#/components/responses/CartRedirectResponse'
summary: BigCommerce Create Cart Redirect URL
operationId: createCartRedirectURL
/carts/{cartId}/items/{itemId}:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/cartId'
- name: itemId
in: path
required: true
schema:
type: string
format: number
put:
description: >-
Updates an existing, single line item in the *Cart*.
**Notes**
Currently, only updating `list_price` and `quantity` are supported.
Updating a product’s `list_price` will make that item ineligible for V3
product-level promotions.
If the product has modifiers, omit the `variant_id` and instead use the
`option_selections` array to describe both the **variant** and the
**modifier** selections.
If 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** endpoint.
`custom_items` cannot be updated via the API at this time. To update
your cart, add a new updated custom item and delete the outdated one. If
your cart contains only one line item, perform the add operation before
the delete operation.
Deleting all line items from the cart will invalidate the cart.
Please note that this API endpoint is not concurrent safe, meaning
multiple simultaneous requests could result in unexpected and
inconsistent results.
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/Cart_Line_Item_Update_Put'
required: true
tags:
- Items
responses:
'200':
$ref: '#/components/responses/CartResponse'
summary: BigCommerce Update Cart Line Item
operationId: updateCartLineItem
delete:
description: |-
Deletes a *Cart* line item.
**Notes**
Removing the last `line_item` in the *Cart* deletes the *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:
- Items
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/Cart_Full'
examples:
response:
value:
data:
id: bc218c65-7a32-4ab7-8082-68730c074d02
customer_id: 11
email: ''
currency:
code: USD
tax_included: false
base_amount: 189.75
discount_amount: 0
cart_amount: 212.81
coupons: []
line_items:
physical_items:
- id: 6e193ce6-f327-4dcc-b75e-72cf6738525e
parent_id: {}
variant_id: 362
product_id: 191
sku: ''
name: Openhouse No. 3
url: >-
http://id30h7ohwf.mybigcommerce.com/all/openhouse-no-3/
quantity: 5
taxable: true
image_url: >-
https://cdn8.bigcommerce.com/s-id30h7ohwf/products/191/images/475/openhousevol3_1024x1024__59692__16355.1534344544.330.500.jpg?c=2
discounts: []
coupons: []
discount_amount: 0
coupon_amount: 0
original_price: 27.95
list_price: 27.95
sale_price: 27.95
extended_list_price: 139.75
extended_sale_price: 139.75
is_require_shipping: true
options:
- name: Add a $5 Donation
nameId: 82
value: 'No'
valueId: 186
digital_items: []
custom_items:
- extended_list_price: 5.99
id: 78239b69-1952-4c35-9d58-ea30158b4e39
list_price: 5.99
name: Rope Toy
quantity: 1
sku: ROPE-TOY
gift_certificates:
- id: 6e38bbc2-8873-472c-a452-8bd4aaea5d3a
name: Happy Birthday
theme: birthday.html
amount: 50
quantity: 1
taxable: false
sender:
name: Jane Does
email: [email protected]
recipient:
name: Jane Does
email: [email protected]
message: Happy Birthday Jane!
created_time: '2018-09-17T14:27:39.000Z'
updated_time: '2018-09-17T14:53:40.000Z'
meta: {}
'204':
description: >-
If the action’s result is an empty cart, the cart is automatically
deleted.
summary: BigCommerce Delete Cart Line Item
operationId: deleteCartLineItem
/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
/carts/settings:
parameters:
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get Global Cart Settings
description: Returns the global cart settings of a store.
operationId: getGlobalCartSettings
tags:
- Settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalCartSettingsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: BigCommerce Update Global Cart Settings
description: Update the global cart settings of a store.
parameters:
- $ref: '#/components/parameters/ContentType'
tags:
- Settings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalCartSettingsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalCartSettingsResponse'
'400':
description: Bad Request. Input is invalid.
content:
application/json:
schema:
description: ''
type: object
properties:
status:
type: number
title:
type: string
minLength: 1
type:
type: string
minLength: 1
detail:
type: string
minLength: 1
example:
status: 400
title: Input is invalid
type: >-
https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
detail: Syntax error
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: updateGlobalCartSettings
/carts/settings/channels/{channel_id}:
parameters:
- $ref: '#/components/parameters/Accept'
- name: channel_id
description: The channel ID of the settings overrides.
in: path
required: true
schema:
type: integer
get:
summary: BigCommerce Get Channel Cart Settings
description: Returns the per-channel overrides for the cart settings of a store.
tags:
- Settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelCartSettingsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getChannelCartSettings
put:
summary: BigCommerce Update Channel Cart Settings
description: Update the per-channel overrides for the cart settings of a store.
tags:
- Settings
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelCartSettingsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelCartSettingsResponse'
'400':
description: Bad Request. Input is invalid.
content:
application/json:
schema:
description: ''
type: object
properties:
status:
type: number
title:
type: string
minLength: 1
type:
type: string
minLength: 1
detail:
type: string
minLength: 1
example:
status: 400
title: Input is invalid
type: >-
https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
detail: Syntax error
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: updateChannelCartSettings
/carts/{cart_id}/metafields:
parameters:
- $ref: '#/components/parameters/cart_id'
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get Cart Metafields
tags:
- Metafields
description: Get a cart's metafields.
operationId: getCartMetafields
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/MetafieldKeyParam'
- $ref: '#/components/parameters/MetafieldNamespaceParam'
- $ref: '#/components/parameters/DirectionParam'
responses:
'200':
description: |
An array of metafields and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/MetafieldResponse'
'409':
description: >
The `Metafield` conflicts with another `Metafield`. This can result
from duplicate unique key combinations of the appʼs client id,
namespace, key, resource_type, and resource_id.
content:
application/json:
schema:
$ref: '#/components/sche
# --- truncated at 32 KB (132 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/carts-openapi-original.yml