comecerodocs
Carts

Retrieve cart item subscription terms

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

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.

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

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 subscription terms.

application/json
  1. response

The billing terms of a subscription item: what is billed, how often, any trial and any discount. Also returned for a product or cart item before a subscription exists, so you can show the shopper what they sign up for.

object*"subscription_terms"

The object type. Always subscription_terms.

Value in"subscription_terms"
price*number

The price of one unit for each billing period, in currency.

quantity*number

How many units are billed.

currency*string

The three-letter ISO 4217 currency of price and discount.

discount*number

The discount taken off each unit, in currency. 0 when none.

discount_price*|

The unit price after the discount, in currency. null when there is no discount.

discount_apply_count*|

How many billings the discount applies to. null means every billing.

discount_applied_count*integer

How many billings the discount has been applied to so far.

tax_inclusve*boolean

true when prices include tax for the customer's location. The field name is spelled this way in the API.

billing_interval*integer

How many billing_interval_unit make one billing period.

billing_interval_unit*string

The unit of the billing period.

Value in"minute""hour""day""month""year"
billing_interval_description*string

The billing period as text, for example 1 month or 3 months.

trial_interval*|

The trial length in trial_interval_unit. null when there is no trial.

trial_interval_unit*|

The unit of the trial. null when there is no trial.

Value in"minute""hour""day""month""year"null
trial_interval_description*|

The trial length as text, for example 14 days. null when there is no trial.

date_trial_start*|

When the trial starts or started. null when there is no trial.

Formatdate-time
date_trial_end*|

When the trial ends or ended. null when there is no trial.

Formatdate-time
end_at_billing_count*|

The number of billings after which billing stops. null means it bills until cancelled.

date_billing_start*string

When paid billing starts (the end of the trial, or the start date).

Formatdate-time
subscription_id*|

The subscription these terms belong to. null before a subscription exists.

description*string

The terms as one sentence in the customer's language, ready to show.

price_per_day*number

The price worked out per day, in currency. For display only.

price_per_month*number

The price worked out per month, in currency. For display only.

price_per_year*number

The price worked out per year, in currency. For display only.

formatted?

Display text for the prices and dates. Only returned with formatted=true.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/carts/string/items/string/subscription_terms'
Example Response
{  "object": "subscription_terms",  "price": 19.95,  "quantity": 1,  "currency": "USD",  "discount": 0,  "discount_price": null,  "discount_apply_count": null,  "discount_applied_count": 0,  "tax_inclusve": false,  "billing_interval": 1,  "billing_interval_unit": "month",  "billing_interval_description": "1 month",  "trial_interval": null,  "trial_interval_unit": null,  "trial_interval_description": null,  "date_trial_start": null,  "date_trial_end": null,  "end_at_billing_count": null,  "date_billing_start": "2026-10-02T15:21:28Z",  "subscription_id": "0093799318129SuLByRPW8",  "description": "Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95.",  "price_per_day": 0.66,  "price_per_month": 19.95,  "price_per_year": 239.4}

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

Sign a customer in to a cart POST

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.