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 Elastic Path Commerce Cloud.
Personalized Products
You can allow your shoppers to add custom text when adding custom items to their carts. This is useful, for example, if you have a custom item that can be personalized. You can do this using the custom_inputs attribute. The custom_inputs attribute must be an object. For example, you sell greetings cards that can be printed with your shoppers personalized messages.
Once you have defined your custom inputs on a custom item, you must configure the custom inputs in your orders.
For example, you may want to add a gift message to an order, so you have custom inputs for name and message.
{
"custom_inputs": {
"name": {
"name": "Name",
"validation_rules": {
"type": "string"
},
"message": {
"name": "Message",
"validation_rules": {
"type": "string"
}
}
}
}
}
When the custom item is added to the cart, those custom inputs are supplied.
{
"custom_inputs": {
"name": {
"name": "Fred",
"message": "Happy Birthday"
}
}
}
If the same custom item 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 must not exceed 1MB. When a cart is checked out, the custom_inputs attribute becomes part of the order items.
When you add custom items 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 custom item to a cart returns a collection of cart items.
- Tax items may optionally be added with the custom item. Only administrators with client credentials are able to do this. If included, they replace any existing taxes on the custom item.
- A cart can contain a maximum of 100 unique items. Items include products and custom items.
- 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.
POST Add Custom Item to Cart
https://api.moltin.com/v2/carts/:reference/items
Parameters
Path parameters
| Name | Required | Type | Description |
|---|---|---|---|
cartId | Required | string | The system generated ID for the cart that the customer created. |
Headers
| Name | Required | Type | Description |
|---|---|---|---|
X-MOLTIN-CURRENCY | Optional | string | Specifies the currency to be used for the products in the cart. Your site’s default is used if not specified. |
Authorization | Required | string | The Bearer token required to get access to the API. |
Body
| Name | Required | Type | Description |
|---|---|---|---|
tax | Optional | array | A list of tax items to apply to this cart item. |
type | Required | string | custom_item |
name | Required | string | The name of the custom item. |
sku | Optional | string | The SKU code to use for the custom item. See best practices to use the sku code. |
description | Optional | string | A description of the custom item. |
quantity | Required | integer | The amount of custom items to add to cart. |
price.amount | Required | integer | The unit price of the custom item. |
price.includes_tax | Optional | boolean | true if relevant taxes have been included in the price, false if not. Defaults to true |
custom_inputs | Optional | object | The custom text to be added to a product. |
Request Examples
Curl
curl -X POST https://api.moltin.com/v2/carts/:reference/items \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "custom_item",
"name": "My Custom Item",
"sku": "my-custom-item",
"description": "My first custom item!",
"quantity": 1,
"price": {
"amount": 10000
}
}
}'
JavaScript SDK
const reference = "XXXX";
const item = {
name: "My Custom Item",
sku: "my-custom-item",
description: "My first custom item!",
quantity: 1,
price: {
amount: 10000,
},
};
// Where `EPCC` is an authenticated client
await EPCC.Cart(reference).AddCustomItem(item);
Adding a Product
Curl
curl -X POST https://api.moltin.com/v2/carts/:reference/items \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "custom_item",
"name": "My Custom Item",
"sku": "my-custom-item",
"custom_inputs": {
"personalization": "My personal message"
},
"description": "My first custom item!",
"quantity": 1,
"price": {
"amount": 10000
}
}
}'
JavaScript SDK
const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
client_id: 'X'
})
const reference = 'XXXX'
const item = {
name: 'My Custom Item',
sku: 'my-custom-item',
description: 'My first custom item!',
quantity: 1,
price: {
amount: 10000
}
}
Moltin.Cart(reference)
.AddCustomItem(item)
.then(cart => {
// Do something
})
Response example
201 Created
{
"data": [
{
"id": "581db51b-d4df-4aff-855d-e8ddbcf81b0c",
"type": "custom_item",
"name": "My Custom Item",
"description": "My first custom item!",
"sku": "my-custom-item",
"custom_inputs": {
"personalization": "My personal message"
},
"image": {
"mime_type": "",
"file_name": "",
"href": ""
},
"quantity": 1,
"manage_stock": false,
"unit_price": {
"amount": 10000,
"currency": "USD",
"includes_tax": true
},
"value": {
"amount": 10000,
"currency": "USD",
"includes_tax": true
},
"links": {},
"meta": {
"display_price": {
"with_tax": {
"unit": {
"amount": 10000,
"currency": "USD",
"formatted": "$100.00"
},
"value": {
"amount": 10000,
"currency": "USD",
"formatted": "$100.00"
}
},
"without_tax": {
"unit": {
"amount": 10000,
"currency": "USD",
"formatted": "$100.00"
},
"value": {
"amount": 10000,
"currency": "USD",
"formatted": "$100.00"
}
}
},
"timestamps": {
"created_at": "2018-05-08T10:11:17.871313413Z",
"updated_at": "2018-05-08T10:11:17.871313413Z"
}
}
}
],
"meta": {
"display_price": {
"with_tax": {
"amount": 57500,
"currency": "USD",
"formatted": "$575.00"
},
"without_tax": {
"amount": 57500,
"currency": "USD",
"formatted": "$575.00"
}
},
"timestamps": {
"created_at": "2018-05-08T10:00:20.171Z",
"updated_at": "2018-05-08T10:11:17.871313413Z",
"expires_at": "2018-05-20T10:11:17.871313413Z"
}
}
}
Adding a bundle
Curl
curl -X POST https://api.moltin.com/v2/carts/:reference/items \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"id": "5ab67bb3-b2c3-4348-af33-e370bd39b0c9",
"type": "cart_item",
"quantity": 1,
"bundle_configuration": {
"selected_options": {
"tshirt": {
"23759a57-13c1-4887-9ec2-fb47444751bd": 1
},
"comics": {
"c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce": 1,
"d9768b40-cf28-406e-bafc-a6d130627eca": 1
}
}
}
}
}'
Response example
{
"data": {
"id": "5ab67bb3-b2c3-4348-af33-e370bd39b0c9",
"type": "product",
"attributes": {
"name": "T-shirt and comics",
"description": "A t-shirt and two comics",
"components": {
"tshirt": {
"name": "T-shirt",
"options": [
{
"id": "23759a57-13c1-4887-9ec2-fb47444751bd",
"quantity": 1,
"type": "product"
},
{
"id": "ffb9024e-82ce-49f8-b2a1-95ce0a452056",
"quantity": 1,
"type": "product"
}
]
},
"comics": {
"name": "Comics",
"minimum": 2,
"maximum": 2,
"options": [
{
"id": "c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce",
"quantity": 1,
"type": "product"
},
{
"id": "d9768b40-cf28-406e-bafc-a6d130627eca",
"quantity": 1,
"type": "product"
},
{
"id": "623b47ee-f43b-45ab-8939-cc6269c323ec",
"quantity": 1,
"type": "product"
},
{
"id": "bfdf583d-aad8-4b5c-879a-06d8f4304988",
"quantity": 1,
"type": "product"
}
]
}
},
"price": {
"USD": {
"amount": 4000,
"includes_tax": false
}
},
"sku": "tshcom",
"published_at": "2022-02-28T16:40:39.731Z"
},
"meta": {
"bundle_configuration": {
"selected_options": {
"tshirt": {
"23759a57-13c1-4887-9ec2-fb47444751bd": 1
},
"comics": {
"c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce": 1,
"d9768b40-cf28-406e-bafc-a6d130627eca": 1
}
}
}
}
}
}
Best Practices
We recommend you to include a unique sku code in the request body when adding custom items to carts. If same sku is used for multiple products, it will collaspse into a single line item.
For example, if a cart consists of the following items:
product-1with quantity 1 andskucode assku-1product-2with quantity 1 andskucode assku-1product-3with quantity 1 andskucode assku-2.
The following response is returned where all products with the same sku codes are represented as a single line item, and products with a unique sku code are represented as a seperate item.
{
"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"
}
}
},
{
"id": "09165e3c-eb21-445f-8cd2-68eac8844030",
"type": "custom_item",
"name": "product-3",
"description": "My first custom item!",
"sku": "sku-2",
"slug": "",
"image": {
"mime_type": "",
"file_name": "",
"href": ""
},
"quantity": 1,
"manage_stock": false,
"unit_price": {
"amount": 20000,
"currency": "USD",
"includes_tax": true
},
"value": {
"amount": 20000,
"currency": "USD",
"includes_tax": true
},
"links": {},
"meta": {
"display_price": {
"with_tax": {
"unit": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.00"
},
"value": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.00"
}
},
"without_tax": {
"unit": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.00"
},
"value": {
"amount": 20000,
"currency": "USD",
"formatted": "$200.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": 20000,
"currency": "USD",
"formatted": "$200.00"
}
}
},
"timestamps": {
"created_at": "2023-05-02T16:28:29Z",
"updated_at": "2023-05-02T16:28:29Z"
}
}
}
],
"meta": {
"display_price": {
"with_tax": {
"amount": 60000,
"currency": "USD",
"formatted": "$600.00"
},
"without_tax": {
"amount": 60000,
"currency": "USD",
"formatted": "$600.00"
},
"tax": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
},
"discount": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
},
"without_discount": {
"amount": 60000,
"currency": "USD",
"formatted": "$600.00"
}
},
"timestamps": {
"created_at": "2023-05-02T16:27:53Z",
"updated_at": "2023-05-02T16:28:29Z",
"expires_at": "2023-05-07T16:28:29Z"
}
}
}