The Cart resource can hold product data, product variants, quantity, price, and other metadata to be used to generate a checkout token and capture an order. This feature comes equipped with multiple intuitive endpoints to help develop a seamless shopping cart experience.
Retrieve cart
In order to start adding products to your cart, you'll need to first create a cart. When you first call the method
retrieve()
using GET v1/carts
, it will automatically create a cart for you if a cart does not exist yet or a current
cart will be retrieved if the cart_id
is passed in as an argument. Commerce.js tracks the current cart ID using a
cookie.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.retrieve().then((cart) => console.log(cart));
Example request using cURL:
curl -X GET \
-G "https://api.chec.io/v1/carts" \
-H "X-Authorization: {key}"
Method | Description |
---|---|
retrieve() |
Get the cart object, including contents |
Cart has a lifetime of 30 days once they've been created. After that time they will automatically be cleared.
For more information, refer to the full response of the cart object.
Refresh cart
The refresh()
method uses GET v1/carts
to create a new cart and update the stored cart ID in Commerce.js.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.refresh().then((cart) => console.log(cart));
Method | Description |
---|---|
refresh() |
Request a new cart ID |
For more information, refer to the full response for requesting a new cart.
Add to cart
The add()
method uses POST v1/carts/{cart_id}
to add a product to cart. You will need the ID of the product you want
to add, e.g. prod_05389st98t49h
.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.add('prod_R4OANwRqklvYL8', 5).then((response) => console.log(response));
Example request using cURL:
curl -X POST \
"https://api.chec.io/v1/carts/cart_2Jwr9yJAeN4VlP" \
-H "X-Authorization: {key}" \
-H "Content-Type: application/json" \
-d '{"id":"prod_R4OANwRqklvYL8","quantity":5}'
Method | Description |
---|---|
add(productId, quantity, variantData) |
Add an item to the cart |
If you'd like to specify variant information during this call, you can do so by providing a third argument which may be one of the following:
- A specific variant ID (string)
- An object which maps variant group IDs to variant option IDs
Example request adding a variant to cart using a specific variant ID:
commerce.cart.add('prod_R4OANwRqklvYL8', 5, 'vrnt_KE50NKbjqKNwdg');
Example request adding a variant to cart by specifying variant groups and options:
commerce.cart.add('prod_R4OANwRqklvYL8', 5, {
'vgrp_NqKE50ap1ldgBL': 'optn_NqKE50y601ldgB',
// ... any other group -> options here
});
The structure of the variants request arguments in these examples were changed with our 2021-03-31 release. See our release notes for more information, including backwards compatibility suggestions.
When you add a product to cart, the response you get back contains the updated cart object, and each product in the cart has been assigned a "line item ID".
For more information, refer to the full response for adding an item to the cart.
Update cart
The update()
method uses PUT v1/carts/{cart_id}/items/{line_item_id}
to update the quantity or variant for the line
item ID in the cart.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.update('item_7RyWOwmK5nEa2V', { quantity: 5 }).then(response => console.log(response));
Example request using cURL:
curl -X PUT \
"https://api.chec.io/v1/carts/cart_2Jwr9yJAeN4VlP/items/item_7RyWOwmK5nEa2V" \
-H "X-Authorization: {key}" \
-H "Content-Type: application/json" \
-d '{"quantity": 5}'
Method | Description |
---|---|
update(lineItemId, data) |
Update an existing item in the cart |
For more information, refer to the full response for updating the cart line item.
Get cart contents
The contents()
method uses GET v1/carts/{cart_id}/items
to return the contents and items of the cart.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.contents().then((items) => console.log(items));
Example request using cURL:
curl -X GET \
-G "https://api.chec.io/v1/carts/cart_2Jwr9yJAeN4VlP/items" \
-H "X-Authorization: {key}" \
Method | Description |
---|---|
contents() |
Get the contents of the cart |
For more information, refer to the full response for getting the cart contents.
Remove from cart
The remove()
method uses DELETE v1/carts/{cart_id}/items/{line_item_id}
to remove a specific line item from the
cart.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.remove('item_7RyWOwmK5nEa2V').then((response) => console.log(response));
Example request using cURL:
curl -X DELETE \
"https://api.chec.io/v1/carts/cart_2Jwr9yJAeN4VlP/items/item_7RyWOwmK5nEa2V" \
-H "X-Authorization: {key}" \
Method | Description |
---|---|
remove(lineItemId) |
Remove a line item from the cart |
For more information, refer to the full response for removing items from the cart.
Delete cart
The delete()
method uses DELETE v1/carts/{cart_id}
to delete a cart entirely.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.delete().then((response) => console.log(response));
Example request using cURL:
curl -X DELETE \
"https://api.chec.io/v1/carts/cart_2Jwr9yJAeN4VlP" \
-H "X-Authorization: {key}"
Method | Description |
---|---|
delete() |
Delete the entire cart |
For more information, refer to the full response for deleting the cart.
Empty cart
The empty()
method uses DELETE v1/carts/{cart_id}/items
to clear the contents of the current cart. This is different
from the .refresh()
method in that it empties the current cart but does not create a new cart.
Example request using Commerce.js:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.empty().then((response) => console.log(response));
Example request using cURL:
curl -X DELETE \
"https://api.chec.io/v1/carts/cart_2Jwr9yJAeN4VlP/items" \
-H "X-Authorization: {token}" \
Method | Description |
---|---|
empty() |
Clear the cart contents but cart is not deleted |
For more information, refer to the full response for emptying the cart's contents.
Retrieve cart ID
The id()
method returns the cart identifier being used in the current request, or null if there is no stored cart ID.
Example request:
import Commerce from '@chec/commerce.js';
const commerce = new Commerce('{your_public_key}');
commerce.cart.id().then((cartId) => console.log(cartId));