openapi: 3.0.0
info:
title: BigCommerce Abandoned Cart Emails Carts (Single) 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: 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:
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.
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
CartUpdatePutRequestData:
type: object
properties:
customer_id:
type: integer
title: Cart Update Put Request Data
x-internal: false
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`'
CartCreatePostData:
type: object
title: Cart Create Post Data
x-internal: false
properties:
customer_id:
type: integer
line_items:
type: array
items:
anyOf:
- $ref: '#/components/schemas/cart_PostVariant'
- $ref: '#/components/schemas/cart_PostModifier'
custom_items:
$ref: '#/components/schemas/cart_PostCustomItem'
gift_certificates:
type: array
items:
type: object
title: Line Item Gift Certificate Request Data
properties:
name:
type: string
description: Given name for the gift certificate line item.
theme:
type: string
description: The theme of the gift certificate.
enum:
- birthday.html
- boy.html
- celebration.html
- christmas.html
- general.html
- girl.html
amount:
type: number
minimum: 1
maximum: 1000
quantity:
type: integer
minimum: 1
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
maximum: 200
description: Message shown to recipient, as provided by sender.
required:
- name
- theme
- amount
- quantity
- sender
- recipient
channel_id:
type: integer
description: The Channel ID. If no channel is specified, defaults to 1.
currency:
type: object
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. This code is required when multi-currency is enabled. Passing a non-transactional display currency will result in a `400` error.
example: usd
locale:
type: string
description: The 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
example: en-US
description: ''
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
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.
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: ''
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
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_PostVariant:
type: object
title: Item with variant
x-internal: false
properties:
quantity:
type: number
product_id:
type: number
list_price:
type: number
description: Optional price override.
variant_id:
type: number
description: Variant ID. Exists only in Catalog V3.
name:
type: string
description: Optionally, provide a value to override the product name.
g
# --- 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