comecerodocs
Carts

Update a cart item

POST
/carts/{cart_id}/items/{item_id}

Changes the quantity, meta or (secret and trusted tokens only) reference_price of an item. A limited token sending reference_price or reference_currency gets 403 (error m82tixT). An item that is part of a bundle cannot be changed (400, error kx3Bq7T): delete it and add the bundle 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.

item_id*string

The id of the item. For a product, the product_id.

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 changed item.

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.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/carts/string/items/string' \  -H 'Content-Type: application/json' \  -d '{  "quantity": 3}'
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}

Retrieve a cart item GET

Returns one item of a cart. Any token type may call it; a limited token only for a bound cart.

Remove a cart item DELETE

Removes one item. Removing an item of a bundle removes the whole bundle. Secret and trusted tokens only: a limited token gets `403`. To let a shopper remove an item, update the cart with the new `items` list. A closed cart is `422`.