comecerodocs
Carts

Add an item to a cart

POST
/carts/{cart_id}/items

Adds a product to a cart. product_id is required (error BpmhEyl). The price comes from the product; only a secret or trusted token may set reference_price (a limited token gets 403, error m82tixT). A product already in the cart is replaced, not added to. Adding a bundle adds one item for the bundle and one for each of its products, and then the answer is an offset list of those items instead of one item. Tax, shipping and promotions are worked out again. Any token type may call it; a limited token only for a bound cart. A closed cart is 422.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

cart_id*string

The id of the cart.

Query Parameters

expand?string

Comma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse

Request Body

application/json
  1. body

An item to add to a cart, or the changes to an item. The price comes from the product unless a secret or trusted token sends reference_price.

product_id?string

The product to add. Required when you add an item (error BpmhEyl without it). The product must exist, must not be deleted, must be active and must have stock. A test product cannot go in a live cart. Adding a product that is already in the cart replaces that item. Ignored on an update: the item keeps its product.

item_id?string

Only on an update, and only when it matches the item_id in the URL. Never needed.

quantity?integer

How many units. A whole number, not negative. Defaults to 1 when you add an item.

Range0 <= value
reference_price?number

The unit price to charge instead of the product's price, in reference_currency. If that currency is not the cart's, the price is converted. A limited token may not send this field: core answers 403 (error m82tixT).

reference_currency?string

The ISO 4217 currency of reference_price. Must be a payment currency of your account. Defaults to the cart currency. A limited token may not send this field: core answers 403 (error m82tixT).

cross_sell_id?string

The cross_sell_id of an offer from GET /carts/{cart_id}/cross_sells when the shopper takes it. It applies the offer's discount. An id from another cart is refused.

up_sell_id?string

The up_sell_id of an offer from GET /carts/{cart_id}/up_sells when the shopper takes it. When you add the item alone, the item the offer upgrades is removed from the cart.

meta?||

Your own data for the item, a string or an object, up to 2048 characters. Copied to the order item when the cart is paid.

Response Body

The new item, or for a bundle a list of the new items.

application/json
  1. response

One line in a cart. A limited token does not see reference_price, reference_currency, tax_code or the settlement amounts.

object*"cart_item"

The object type. Always cart_item.

Value in"cart_item"
url*string

The full URL of the item.

Formaturi
item_id*string

The id of the item in the cart. For a product this is the product_id, so a product is in a cart at most once. Items made for a bundle's products get their own ids.

cross_sell_id?|

The cross-sell offer the item was added from, if any.

up_sell_id?|

The up-sell offer the item was added from, if any.

bundle_id?|

The product_id of the bundle this item belongs to, if any.

bundle_group_id?|

Shared by the bundle's own item and the items for its products. Items in a bundle cannot be changed one by one: delete one to remove the whole bundle.

date_created*string

When the item was added.

Formatdate-time
date_modified*string

When the item was last changed.

Formatdate-time
product_id*|

The product this item is for.

cart_id*string

The cart the item is in.

name*|

The product name.

type*|

The product type, for example digital, physical, service or bundle.

quantity*number

How many units. A whole number in a cart.

currency*string

The currency of the cart.

price*number

The price of one unit with discounts, in currency.

price_original*number

The price of one unit before discounts, in currency.

reference_price?|

The unit price you set for this item instead of the product's price, in reference_currency. Null when the product's own price is used. Not returned to a limited token.

reference_currency?|

The currency of reference_price. Not returned to a limited token.

subtotal*number

price times quantity, without tax, in currency.

subtotal_original*number

price_original times quantity, without tax, in currency.

discount*number

The discount on one unit, in currency.

discount_percent*number

The discount as a fraction of the original price, for example 0.2 for 20%.

tax*number

The tax on this line, in currency.

tax_original*number

The tax on this line before discounts, in currency.

total*number

subtotal plus tax, in currency.

total_original*number

subtotal_original plus tax_original, in currency.

tax_rate*number

The tax rate applied, as a fraction, for example 0.075 for 7.5%.

tax_code?|

The product's tax code. Not returned to a limited token.

settlement_currency?string

The settlement currency. Not returned to a limited token.

settlement_price?number

price in settlement_currency. Not returned to a limited token.

settlement_price_original?number

price_original in settlement_currency. Not returned to a limited token.

settlement_subtotal?number

subtotal in settlement_currency. Not returned to a limited token.

settlement_subtotal_original?number

subtotal_original in settlement_currency. Not returned to a limited token.

settlement_discount?number

discount in settlement_currency. Not returned to a limited token.

settlement_tax?number

tax in settlement_currency. Not returned to a limited token.

settlement_tax_original?number

tax_original in settlement_currency. Not returned to a limited token.

settlement_total?number

total in settlement_currency. Not returned to a limited token.

settlement_total_original?number

total_original in settlement_currency. Not returned to a limited token.

product?||

The URL of the product, or the product itself with expand=items.product.

subscription_plan?||

The URL of the product's subscription plan, or the plan itself with expand=items.subscription_plan. Null when the product is not a subscription.

subscription_terms*||

The URL of the subscription terms this item would start, or the terms with expand=items.subscription_terms. Null when the product is not a subscription.

meta*||

Your own data for the item, a string or an object, up to 2048 characters.

formatted?

Money amounts, the tax rate and dates as display strings. Only present with formatted=true.

curl -X POST 'https://api.comecero.com/api/v1/carts/string/items' \  -H 'Content-Type: application/json' \  -d '{  "product_id": "widget-pro.test",  "quantity": 1}'
Example Response
{  "object": "cart_item",  "url": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test",  "item_id": "pdf-pro.test",  "cross_sell_id": null,  "up_sell_id": null,  "bundle_id": null,  "bundle_group_id": null,  "date_created": "2026-11-07T19:19:12Z",  "date_modified": "2026-11-07T19:19:12Z",  "product_id": "pdf-pro.test",  "cart_id": "0091307952465CafhFSTa1",  "name": "PDF Viewer Pro",  "type": "digital",  "quantity": 2,  "currency": "USD",  "price": 99.95,  "price_original": 99.95,  "reference_price": null,  "reference_currency": null,  "subtotal": 199.9,  "subtotal_original": 199.9,  "discount": 0,  "discount_percent": 0,  "tax": 14.99,  "tax_original": 14.99,  "total": 214.89,  "total_original": 214.89,  "tax_rate": 0.075,  "tax_code": null,  "settlement_currency": "USD",  "settlement_price": 99.95,  "settlement_price_original": 99.95,  "settlement_subtotal": 199.9,  "settlement_subtotal_original": 199.9,  "settlement_discount": 0,  "settlement_tax": 14.99,  "settlement_tax_original": 14.99,  "settlement_total": 214.89,  "settlement_total_original": 214.89,  "product": "https://api.comecero.com/api/v1/products/pdf-pro.test",  "subscription_plan": null,  "subscription_terms": null,  "meta": null}

List cart items GET

Lists the items in a cart. An offset-based list; with no `limit` every item is on one page. `sort_by` takes `date_created` (the default), `date_modified`, `product_id` or `item_id`. Any token type may call it; a limited token only for a bound cart.

Remove all cart items DELETE

Empties a cart. Any token type may call it, a limited token too (only for a bound cart). A closed cart is `422`.