Add Items to Cart
POST/v2/carts/:cartID/items
Add Product to Cart
Adding a Product to Cart is the most common Cart action. If you want to add any custom products or promotions, you need to do that as a separate action.
Dynamic Bundles
A bundle is a purchasable product that is composed of a combination of two or more products that you want to sell together. You can create multiple components within a bundle. Each component can have one or more options. Each option is a product and a quantity. You can configure minimum and/or maximum values for the number of product options in a component that your shoppers can select. For example, you can enable a shopper to select 1 or more product options from a list of 10. These are called dynamic bundles.
Your dynamic bundles are displayed in your published catalogs.
- Use the configure a shopper endpoint to allow shoppers to make their selections from a bundle.
- In the response of the configure a shopper, the
bundle_configurationobject contains the bundle selections a shopper has made. - In the add a product to cart request, use the
bundle_configurationobject to add the customers selections to a cart.
"bundle_configuration": {
"selected_options": {
"games": {
"d7b79eb8-19d8-45ea-86ed-2324a604dd9c": 1
},
"toys": {
"0192ccdd-6d33-4898-87d7-c4d87f2bf8ea": 1,
"1aea6f97-f0d9-452c-b3c1-7fb5629ead82": 1
}
}
}
When a cart is checked out, the options a shopper selected are added to the order. See order items.
Personalized Products
You can allow shoppers to personalize their goods by adding custom text inputs to products directly. This feature is particularly useful for customizable items, such as personalized T-shirts or greeting cards. You can use this functionality by leveraging the custom_inputs attribute, and defining the details and validation rules for the custom text.
First, you must configure a custom_inputs attribute when creating a new product or updating an existing product. Once you have defined your custom inputs on a product, you must configure the custom inputs in your orders.
For example, you may sell T-shirts that can have personalized text on the front and back of the shirt.
{
"data": {
"type": "product",
"attributes": {
"custom_inputs": {
"front": {
"name": "T-Shirt Front",
"validation_rules": [
{
"type": "string",
"options": {
"max_length": 50
}
}
],
"required": false
},
"back": {
"name": "T-Shirt Back",
"validation_rules": [
{
"type": "string",
"options": {
"max_length": 50
}
}
],
"required": false
}
}
}
}
}
If the same product has different custom_inputs attributes, then these are added as separate items in a cart.
The custom_inputs attribute is stored in the cart item and the text for custom_input must not exceed 255 characters in length. When a cart is checked out, the custom_inputs attribute becomes part of the order.
Limitations on Usage of custom_inputs with Specific Promotion Types
When you add products to a cart with custom_inputs, there are certain limitations on usage of the custom_inputs with the following promotion types:
- For Free Gift Promotions, you can add
custom_inputsto gift items. - For Fixed Bundle Discount Promotions, the promotion applies as long as the cart contains the bundle SKUs even when there are different
custom_inputs. - For X for Y Discount Promotion and X for amount discount promotion, the promotion applies when there are two SKUs with the same
custom_inputs. The promotion does not apply when there are differentcustom_inputsand the SKUs are in different line items.
- Any requests to add a product to cart returns the collection of cart items.
- Tax items may optionally be added with the product. Only administrators with client credentials are able to do this. If included, they replace any existing taxes on the product.
- The cart currency is set when the first item is added to the cart.
- The product being added to the cart requires a price in the same currency as the other items in the cart. The API returns a 400 error if a price is not defined in the correct currency.
- A cart can contain a maximum of 100 unique items. Items include products, custom items, tax items, and promotions.
- There are a number of actions that happen to your inventory when checking out and paying for an order. For more information, see the Inventory documentation.
Including Resources
When you make an Add Product to Cart request to the catalog-view service, you can obtain details of the component products. If you include the optional parameter include=component_products in the request, the response will include details for each component product.
When a bundle with selected component products is added to a cart, the cart displays both the bundle pricing and component product IDs.
The response example is returned with a new field called component_products under bundle_configuration, which is a list of component products that the user has selected for dynamic bundles.
| Parameter | Required | Description |
|---|---|---|
component_products | Optional | The component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle. |
main_image | Optional | The main images associated with a product. |
files | Optional | Any files associated with a product. |
"bundle_configuration": {
"selected_options": {
"mixed-shirts": {
"16a6cc14-6ebb-4156-9973-e6a0f92f5731": 3,
"55037cc5-f382-4039-95c6-1e04ac0351d3": 2,
"standard-shirts"
"70f1c9d2-c580-4839-bd6c-a0a9b91d5159": 5
}
},
"component_products": [
{
"id": "16a6cc14-6ebb-4156-9973-e6a0f92f5731",
"type": "product",
"attributes": {
"name": "Red T-shirt",
"description": "Standard red t-shirt.",
"slug": "red-t-shirt-slug",
"sku": "red-t-shirt-sku",
"status": "live",
"commodity_type": "physical"
},
"meta": {
"display_price": {
"without_tax": {
"amount": 500,
"currency": "USD",
"formatted": "$5.00"
}
}
}
},
{
"id": "55037cc5-f382-4039-95c6-1e04ac0351d3",
"type": "product",
"attributes": {
"name": "Blue T-shirt",
"description": "Standard blue t-shirt.",
"slug": "blue-t-shirt-slug",
"sku": "blue-t-shirt-sku",
"status": "live",
"commodity_type": "physical"
},
"meta": {
"display_price": {
"without_tax": {
"amount": 500,
"currency": "USD",
"formatted": "$5.00"
}
}
}
},
{
"id": "70f1c9d2-c580-4839-bd6c-a0a9b91d5159",
"type": "product",
"attributes": {
"name": "White T-shirt",
"description": "Standard white t-shirt.",
"slug": "white-t-shirt-slug",
"sku": "white-t-shirt-sku",
"status": "live",
"commodity_type": "physical"
},
"meta": {
"display_price": {
"without_tax": {
"amount": 500,
"currency": "USD",
"formatted": "$5.00"
}
}
}
}
]
}
See Including Resources.
Add Subscription to Cart
To add a subscription to your cart, you need to provide the ID of the subscription offering and the ID of the plan within that offering that you want to subscribe to.
{
{
"data": {
"id": "5b9be99f-1c94-4ddd-9718-81adab0cc3e0",
"type": "subscription_item",
"quantity": 1,
"subscription_configuration": {
"plan": "40010dde-2f38-489b-8b3f-14a13cbfb431"
}
}
}
The price of the subscription item in the cart reflects the cost of the subscription's initial billing period. Once the cart has been checked out and the order paid for, the subscription will be automatically created in the subscriptions service.
Add Custom Item to Cart
You can add a custom item to the cart when you don't manage things like shipping, taxes and inventory in Commerce.
For Shipping Groups, once you have created a cart shipping group, you need to link it to the cart items. This is important, because it is necessary to associate items with shipping groups in order to include shipping groups in the corresponding cart, order, and totals.
- Custom Cart Items are available through implicit authentication. Ensure that you always check each order has the correct details for each item, most importantly, price.
Add Promotion to Cart
You can use the Promotions API to apply discounts to your cart as a special cart item type. Any requests to add a product to cart will return a collection of cart items.
There are certain limitations on usage of the custom_inputs attribute with some promotion types. See Limitations on Usage of custom_inputs with Specific Promotion Types.
To remove promotion from the cart via the promotion code, see Delete Promotion Code from Cart.
Re-order
From a shopper’s order history, they can add the items from a previous order into their carts. Shoppers can add items regardless of past order status, such as incomplete or not paid. For more information, see Orders.
- Any requests to add an item to cart return a collection of cart items.
- A cart can contain a maximum of 100 unique items. Items include products, custom items, and promotions.
- When a shopper creates a cart and re-orders items from an order with properties such as custom attributes, custom discounts, and payment intent ID, these properties will remain unchanged in the original cart.
- Custom items do not exist in catalogs, and therefore cannot be reordered.
Merging Carts
A shopper can have multiple carts, and the system may automatically merge items from an anonymous cart into the shopper's registered cart when they sign in. For example, if a shopper has an existing cart with items A, B and C, and later adds items D and E while not signed in, the system can merge these carts when the shopper signs in. After the carts merge, the cart contains items A, B, C, D and E.
If any items are duplicated from the anonymous cart to the registered cart, their quantities are incremented accordingly. For example, if a shopper's existing cart with items A, B and C, and they later add two more A items and one B item while not signed in, the system will merge the carts when the shopper signs in. The existing cart will now contain three A items, two B items, and one C item.
When the system merges items from one cart into another cart, properties such as custom attributes, custom discounts, and payment intent ID will remain unchanged in the original cart.
Best Practices
We recommend to include a unique sku code within the request body while adding custom items to carts. If the same sku is used for multiple products, they are merged into a single line item.
For example, if a cart consists of the following items:
product-1with quantity 1 and sku code assku-1product-2with quantity 1 and sku code assku-1product-3with quantity 1 and sku code assku-2.
The following response is returned where it combines all products with the same sku codes into a single line item, while products with a unique sku codes are represented as separate items:
{
"data": [
{
"id": "c58760f4-8889-4719-b34d-be1f1d11ae59",
"type": "custom_item",
"name": "product-1",
"description": "My first custom item!",
"sku": "sku-1",
"slug": "",
"image": {
"mime_type": "",
"file_name": "",
"href": ""
},
"quantity": 2,
"manage_stock": false,
"unit_price": {
"amount": 20000,
"currency": "USD",
"includes_tax": true
},
"value": {
"amount": 40000,
"currency": "USD",
"includes_tax": true
},
"links": {},
"meta": {
"display_price": {
"with_tax": {
"unit": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.00"
},
"value": {
"amount": 40000,
"currency": "USD",
"formatted": "$400.00"
}
},
"without_tax": {
"unit": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.00"
},
"value": {
"amount": 40000,
"currency": "USD",
"formatted": "$400.00"
}
},
"tax": {
"unit": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
},
"value": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
}
},
"discount": {
"unit": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
},
"value": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
}
},
"without_discount": {
"unit": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.00"
},
"value": {
"amount": 40000,
"currency": "USD",
"formatted": "$400.00"
}
}
},
"timestamps": {
"created_at": "2023-05-02T16:28:11Z",
"updated_at": "2023-05-02T16:28:18Z"
}
}
}
Request
Responses
- 200
- 401