Create Cart

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, modifier value, 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.

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](/developer/api-reference/rest/admin/catalog/product-variant-options/values), [modifier value](/developer/api-reference/rest/admin/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`.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Carts	modify	`store_cart`
Carts	read-only	`store_cart_read_only`
Information & Settings	modify	`store_v2_information`
Information & Settings	read-only	`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.

Query parameters

includelist of enumsOptional

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.

* `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.

Allowed values:

Request

Examples:

Creating a cart by adding a simple product (a product without option selections).
Creating a cart with a variant. This works when a product can be specified purely by a variant, without any other required options.
Creating a cart using a date option. The API supports timestamps, “option_value”: 1743570000, and dates as an object literal, “option_value”: {“day”:”01”, “month”:”02”, “year”:”2020”}.
Creating a cart with a variant, a checkbox, and a picklist modifier added.
Creating a cart using a custom item.

**Examples:** 1. Creating a cart by adding a simple product (a product without option selections). 2. Creating a cart with a variant. This works when a product can be specified purely by a variant, without any other required options. 3. Creating a cart using a date option. The API supports timestamps, “option_value”: 1743570000, and dates as an object literal, “option_value”: {“day”:”01”, “month”:”02”, “year”:”2020”}. 4. Creating a cart with a variant, a checkbox, and a picklist modifier added. 5. Creating a cart using a custom item.

customer_idintegerOptional

line_itemslist of objectsOptional

custom_itemslist of objectsOptional

gift_certificateslist of objectsOptional

channel_idintegerOptional

The Channel ID. If no channel is specified, defaults to 1.

currencyobjectOptional

localestringOptionalformat: "ISO-639"

The locale of the cart. Accepts strings of format xx or xx-YY. Uses the ISO-639 standard format.

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.

Response

dataobject

A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

metaobject

Response metadata.

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, modifier value, 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.

1	import requests
2
3	url = "https://api.bigcommerce.com/stores/store_hash/v3/carts"
4
5	payload = {
6	"customer_id": 0,
7	"line_items": [
8	{
9	"quantity": 2,
10	"product_id": 118,
11	"list_price": 25,
12	"variant_id": 140,
13	"name": "قميص",
14	"option_selections": [
15	{
16	"option_id": 125,
17	"option_value": 127,
18	"name": "بحجم",
19	"value": "صغير"
20	}
21	]
22	}
23	],
24	"channel_id": 1,
25	"currency": { "code": "JOD" },
26	"locale": "ar-JO"
27	}
28	headers = {
29	"X-Auth-Token": "<apiKey>",
30	"Content-Type": "application/json"
31	}
32
33	response = requests.post(url, json=payload, headers=headers)
34
35	print(response.json())

1	{
2	"data": {
3	"id": "string",
4	"customer_id": 1,
5	"channel_id": 1,
6	"email": "string",
7	"currency": {
8	"code": "usd"
9	},
10	"tax_included": true,
11	"base_amount": 1.1,
12	"discount_amount": 1.1,
13	"manual_discount_amount": 1.1,
14	"cart_amount": 1.1,
15	"coupons": [
16	{
17	"code": "string",
18	"id": "string",
19	"coupon_type": "0",
20	"discounted_amount": 1.1,
21	"display_name": "20% Off"
22	}
23	],
24	"discounts": [
25	{
26	"id": "coupon",
27	"discounted_amount": 1.1
28	}
29	],
30	"line_items": {
31	"physical_items": [
32	{
33	"variant_id": 358,
34	"product_id": 12,
35	"quantity": 5,
36	"id": "6e193ce6-f327-4dcc-b75e-72cf6738525e",
37	"parent_id": "string",
38	"sku": "SMGREEN",
39	"name": "T-Shirt",
40	"url": "http://your-store-url.mybigcommerce.com/your-product/",
41	"taxable": false,
42	"image_url": "https://pathtoproductimage/ProductDefault.png",
43	"discounts": [
44	{
45	"id": "string",
46	"discounted_amount": 1.1
47	}
48	],
49	"coupons": 1.1,
50	"discount_amount": 4,
51	"coupon_amount": 1.1,
52	"original_price": 1.1,
53	"list_price": 1.1,
54	"sale_price": 1.1,
55	"extended_list_price": 1.1,
56	"extended_sale_price": 1.1,
57	"is_require_shipping": false,
58	"is_mutable": true,
59	"added_by_promotion": false,
60	"gift_wrapping": {
61	"name": "Gift Wrap 1",
62	"message": "Happy Birthday!",
63	"amount": 1.99
64	}
65	}
66	],
67	"digital_items": [
68	{
69	"id": "6e193ce6-f327-4dcc-b75e-72cf6738525e",
70	"parent_id": "string",
71	"variant_id": 358,
72	"product_id": 12,
73	"sku": "SMGREEN",
74	"name": "T-Shirt",
75	"url": "http://your-store-url.mybigcommerce.com/your-product/",
76	"quantity": 5,
77	"taxable": false,
78	"image_url": "https://pathtoproductimage/ProductDefault.png",
79	"discounts": [
80	{
81	"id": "string",
82	"discounted_amount": 1.1
83	}
84	],
85	"coupons": 1.1,
86	"discount_amount": 4,
87	"coupon_amount": 1.1,
88	"original_price": 1.1,
89	"list_price": 1.1,
90	"sale_price": 1.1,
91	"extended_list_price": 1.1,
92	"extended_sale_price": 1.1,
93	"is_require_shipping": false,
94	"is_mutable": true,
95	"added_by_promotion": false,
96	"download_file_urls": [
97	"string"
98	],
99	"download_page_url": "string",
100	"download_size": "string"
101	}
102	],
103	"gift_certificates": [
104	{
105	"id": "string",
106	"name": "string",
107	"theme": "string",
108	"amount": 1.1,
109	"taxable": true,
110	"sender": {
111	"name": "string",
112	"email": "string"
113	},
114	"recipient": {
115	"name": "string",
116	"email": "string"
117	},
118	"message": "string"
119	}
120	],
121	"custom_items": [
122	{
123	"id": "string",
124	"sku": "string",
125	"name": "string",
126	"quantity": "string",
127	"list_price": "string",
128	"extended_list_price": 1.1,
129	"image_url": "https://pathtoproductimage/ProductDefault.png"
130	}
131	]
132	},
133	"created_time": "string",
134	"updated_time": "string",
135	"locale": "string",
136	"promotions": {
137	"banners": {
138	"id": "string",
139	"type": "string",
140	"page": [
141	"string"
142	],
143	"text": "string"
144	}
145	},
146	"version": 1
147	},
148	"meta": {}
149	}

Authentication

OAuth scopes

Authentication header

Further reading

Query parameters

Request

Response

OAuth scopes

Authentication header

Further reading