comecerodocs
Carts

Retrieve a cart item

GET
/carts/{cart_id}/items/{item_id}

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

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.

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

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

Response Body

The 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 GET 'https://api.comecero.com/api/v1/carts/string/items/string'
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}

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`.

Update a cart item POST

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`.