Sign a customer in to a cart
Checks a customer's username and password and, when they match, puts that customer on the cart. Tax, shipping and promotions are worked out again for the customer's details. For a limited token this is how a shopper signs in during checkout; the token can then use the customer's saved payment methods. Wrong details are 401 with code invalid_login; after too many failures the customer is locked for 10 minutes (401, code account_locked). Any token type may call it; a limited token only for a bound cart.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
cart_id*stringThe id of the cart.
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.
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.
falsemax_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 <= 10application/json- body
A customer's sign-in details.
username*stringThe customer's username.
password*stringThe customer's password.
passwordThe cart, now with the customer.
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/string/login' \ -H 'Content-Type: application/json' \ -d '{ "username": "john@example.com", "password": "example-password"}'{ "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"}Retrieve cart item subscription terms GET
Returns the subscription the item would start if the cart were paid now: the price per period, how often, any trial and discount. Use it to show the shopper what they sign up for. An item whose product is not a subscription is `404`. Any token type may call it; a limited token only for a bound cart.
Sign the customer out of a cart POST
Takes the customer off the cart and works out tax, shipping and promotions again without them. The token is no longer bound to that customer but stays bound to the cart. Send no body. Any token type may call it; a limited token only for a bound cart. A cart with no customer is returned unchanged.