Create a cart
Creates a cart, with items and a customer if you send them. Prices, tax, shipping and promotions are worked out for you. Any token type may call it. A limited token is bound to the new cart, so it can read and change it later. With no customer in the request, an empty customer is made for the cart. A limited token may not set reference_price on an item (403, error m82tixT). max_cross_sells and max_up_sells limit the offers when you expand them.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
expand?stringComma-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?stringComma-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?stringComma-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?booleanWhen 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.
falsetimezone?stringAn IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.
max_cross_sells?integerHow many cross-sell offers to return when cross_sells is expanded, 0 to 10. Default 3.
0 <= value <= 10max_up_sells?integerHow many up-sell offers to return when up_sells is expanded, 0 to 10. Default 3.
0 <= value <= 10user_ip_address?stringThe shopper's IP address, when your server calls with a secret token on the shopper's behalf. Comecero uses it for fraud checks and to find the shopper's country. Only read for a secret token: for every other token the address the request comes from is used. A value that is not a valid IPv4 or IPv6 address is ignored.
application/json- body
The fields you can set on a cart. On an update, only the fields you send change, except items: sending items replaces every item in the cart.
order_id?stringOnly when you create the cart. The id the order gets when the cart is paid. Letters, numbers, underscores, dashes and periods only, and not in use by another order or invoice. Stored in upper case. Assigned for you when left out.
length <= 30currency?stringThe ISO 4217 currency the shopper pays in. Must be a currency your account takes. Guessed from the shopper's location when left out on create. Changing it reprices every item.
customer_id?|An existing customer to put on the cart. Send this or customer, not both. A token made by a customer login always uses its own customer.
customer?The shopper's details. To change an existing customer, include its customer_id inside this object. When you send no customer on create, an empty customer is made for the cart.
items?array<>The items in the cart. Each needs a product_id. On an update this list replaces all items; a reference price set before is kept for an item that is sent again without one.
promotion_code?|A coupon code. It must be valid for this shopper (error code invalid_promotion_code). Send null to remove it.
shipping_method_id?|The shipping method the shopper picked. It must exist and ship to the customer's location. Pick one from shipping_quotes in the cart options.
referrer?|Your own label for where the sale came from, such as a campaign.
length <= 256affiliate_id?|The affiliate or partner credited with the sale.
length <= 75meta?||Your own data for the cart, a string or an object, up to 2048 characters. Copied to the order when the cart is paid.
The new cart.
application/json- response
A shopper's basket: the items, the customer, the totals and links to what the shopper can do next. A limited token does not see the settlement amounts.
object*"cart"The object type. Always cart.
"cart"url*stringThe full URL of the cart.
uricart_id*stringThe id of the cart. Comecero assigns it when the cart is created.
date_created*stringWhen the cart was created.
date-timedate_modified*stringWhen the cart was last changed.
date-timetest*booleanTrue for a test cart, false for a live one. Set by the token that created it.
account_id*stringThe account the cart belongs to.
order_id*stringThe id the order gets when the cart is paid. Taken from the request when you create the cart, otherwise assigned by Comecero. Always upper case.
open*booleanTrue while the cart can be changed. A cart closes when a payment for it succeeds, and a closed cart cannot be changed or paid again.
payment_status*|Null until a payment for the cart succeeds. pending when the payment is authorized but not captured, completed when it is captured, refunded or cancelled after the order is refunded or cancelled.
"pending""completed""refunded""cancelled"nullcurrency*stringThe ISO 4217 currency the shopper sees and pays in. Taken from the request, otherwise guessed from the shopper's location.
subtotal*numberThe sum of all items with item discounts, without tax, in currency.
subtotal_original*numberThe sum of all items without discounts and without tax, in currency.
shipping*numberThe shipping amount with discounts, without tax, in currency.
shipping_original*numberThe shipping amount without discounts and without tax, in currency.
discount*numberThe discount applied to the cart as a whole, in currency. Item discounts are not included.
item_discounts*numberThe sum of all item discounts, in currency.
total_discounts*numberThe cart discount plus all item discounts, in currency.
total_discounts_percent*numberThe total discount as a fraction of the original total, for example 0.1 for 10%.
tax*numberThe tax on the cart, in currency.
tax_original*numberThe tax before discounts, in currency.
total*numberWhat the shopper pays, with discounts and tax, in currency.
total_original*numberThe total before discounts (subtotal_original plus shipping_original plus tax_original), in currency.
tax_inclusive*booleanTrue when item prices already include tax.
total_payments*numberThe sum of successful payments made for the cart, in currency.
total_remaining*numbertotal minus total_payments, in currency.
discount_on_gross*booleanTrue when discounts are worked out on prices that include tax.
settlement_currency?stringThe currency the payment will be settled to your account in. Not returned to a limited token.
settlement_subtotal?numbersubtotal in settlement_currency. Not returned to a limited token.
settlement_subtotal_original?numbersubtotal_original in settlement_currency. Not returned to a limited token.
settlement_shipping?numbershipping in settlement_currency. Not returned to a limited token.
settlement_shipping_original?numbershipping_original in settlement_currency. Not returned to a limited token.
settlement_discount?numberdiscount in settlement_currency. Not returned to a limited token.
settlement_total_discounts?numbertotal_discounts in settlement_currency. Not returned to a limited token.
settlement_tax?numbertax in settlement_currency. Not returned to a limited token.
settlement_tax_original?numbertax_original in settlement_currency. Not returned to a limited token.
settlement_total?numbertotal in settlement_currency. Not returned to a limited token.
settlement_total_original?numbertotal_original in settlement_currency. Not returned to a limited token.
customer_ip_address*|The IP address of the shopper's last request to the cart.
customer_ip_country*|The ISO 3166-1 alpha-2 country of customer_ip_address.
referrer*|Your own label for where the sale came from, such as a campaign. Up to 256 characters.
affiliate_id*|The affiliate or partner credited with the sale. Up to 75 characters.
promotion_code*|The coupon code applied to the cart, if any.
items_count*integerThe number of lines in items.
items_quantity*numberThe sum of the quantities of all items.
items*array<>The items in the cart.
shipping_item*|The shipping line for the selected shipping method, or null when no shipping applies.
customer*|The customer on the cart, always in full, or null when there is none yet.
order?||Null while the cart is open. Once paid, the URL of the order, or the order itself with expand=order.
payments?|The URL of the payments made for the cart, or an offset list of them with expand=payments (not inside a list of carts).
promotions*|The URL of the promotions applied to the cart, or an offset list of them with expand=promotions (not inside a list of carts).
options*|The URL of the cart options, or the options object with expand=options (not inside a list of carts).
meta*||Your own data for the cart: a string or an object, up to 2048 characters. Copied to the order when the cart is paid.
related_products*|The URL of products related to the items in the cart, or an offset list of them with expand=related_products (not inside a list of carts).
cross_sells*|The URL of cross-sell offers for the cart, or an offset list of them with expand=cross_sells (not inside a list of carts).
up_sells*|The URL of up-sell offers for the cart, or an offset list of them with expand=up_sells (not inside a list of carts).
formatted?The money amounts, dates and IP country as display strings in the shopper's locale. Only present with formatted=true.
warnings?array<>Only on a cart read. Present when a bundle in the cart holds a product that was since deleted or made inactive. The cart can still be read, but a change or a payment fails until the bundle is removed.
curl -X POST 'https://api.comecero.com/api/v1/carts' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "items": [ { "product_id": "widget-pro.test", "quantity": 1 } ]}'{ "object": "cart", "url": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1", "cart_id": "0091307952465CafhFSTa1", "date_created": "2026-11-07T19:19:12Z", "date_modified": "2026-11-07T19:21:40Z", "test": true, "account_id": "AB1234", "order_id": "8352-CSGYX-348", "open": true, "payment_status": null, "currency": "USD", "subtotal": 199.9, "subtotal_original": 199.9, "shipping": 0, "shipping_original": 0, "discount": 0, "item_discounts": 0, "total_discounts": 0, "total_discounts_percent": 0, "tax": 14.99, "tax_original": 14.99, "total": 214.89, "total_original": 214.89, "tax_inclusive": false, "total_payments": 0, "total_remaining": 214.89, "discount_on_gross": false, "settlement_currency": "USD", "settlement_subtotal": 199.9, "settlement_subtotal_original": 199.9, "settlement_shipping": 0, "settlement_shipping_original": 0, "settlement_discount": 0, "settlement_total_discounts": 0, "settlement_tax": 14.99, "settlement_tax_original": 14.99, "settlement_total": 214.89, "settlement_total_original": 214.89, "customer_ip_address": "203.0.113.44", "customer_ip_country": "US", "referrer": "campaign-0044", "affiliate_id": null, "promotion_code": null, "items_count": 1, "items_quantity": 2, "items": [ { "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 } ], "shipping_item": null, "customer": { "object": "customer", "url": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1", "customer_id": "0091307952481CuXUhvCA1", "date_created": "2026-11-07T19:19:12Z", "date_modified": "2026-11-07T19:21:40Z", "account_id": "AB1234", "test": true, "company_name": null, "name": "John Smith", "email": "john@example.com", "phone": null, "billing_address": { "object": "address", "name": null, "address_1": null, "address_2": null, "city": null, "state_prov": null, "postal_code": "27265", "country": "US", "email": null, "meta": null }, "shipping_address": { "object": "address", "name": null, "address_1": null, "address_2": null, "city": null, "state_prov": null, "postal_code": null, "country": null, "email": null, "meta": null }, "username": null, "tax_number": null, "tax_exempt": false, "has_payments": false, "locale": "en-US", "meta": null, "payment_methods": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods", "payments": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments", "refunds": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds", "orders": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders", "subscriptions": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions", "invoices": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices" }, "order": null, "payments": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments", "promotions": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions", "options": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options", "meta": null, "related_products": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products", "cross_sells": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells", "up_sells": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}List all carts GET
Lists the carts of your account, newest last unless you send `desc=true`. A cursor-based list: page with `after_item` and `before_item`. It has no `sort_by`. Secret and trusted tokens only; a limited token gets `403`. Inside the list, `payments`, `promotions`, `options`, `related_products`, `cross_sells` and `up_sells` are always URLs.
Retrieve a cart GET
Returns a cart with fresh prices. Any token type may call it; a limited token only for a cart it is bound to (`403` otherwise). A cart not used for a while expires and is then `404`. Add `expand=options` to get the cart options in the same call. When a bundle in the cart holds a product that was since removed, the cart has `warnings`.