Get a subscription item
Returns one item of a subscription. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
subscription_id*stringThe subscription id.
item_id*stringThe item id. For a product item it is the product_id.
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.
falseThe item.
application/json- response
One item a subscription bills for. An item is either a product from your catalog or a custom item with its own name, type and price.
object*"subscription_item"The object type. Always subscription_item.
"subscription_item"url?stringThe full URL of this item.
uriitem_id*stringThe item id, unique within the subscription. For a product item it is the product_id. For a custom item it is the id you sent, or a number core assigns (1, 2 and so on).
date_created*stringWhen the item was added to the subscription.
date-timedate_modified*stringWhen the item was last changed.
date-timeproduct_id*|The product this item bills for. null for a custom item.
name*stringThe item name. For a product item it is copied from the product.
quantity*numberHow many units the subscription bills for.
reference_price*numberThe price of one unit for each billing period, in reference_currency. If reference_currency is not the subscription currency, the amount billed is converted at each renewal, so it can change with exchange rates.
reference_currency*stringThe three-letter ISO 4217 currency of reference_price.
reference_discount*numberThe discount taken off each unit, in reference_currency. 0 when there is no discount.
reference_discount_price*|The unit price after the discount (reference_price minus reference_discount), in reference_currency. null when there is no discount.
discount_apply_count*|How many billings the discount applies to. null means every billing, for as long as the subscription runs.
discount_applied_count?integerHow many billings the discount has been applied to so far.
cancelled?booleantrue once the item is cancelled. A cancelled item is no longer billed and cannot be uncancelled.
cancel_at_current_period_end?booleantrue when the item is set to be cancelled at the end of the current billing period. It is still billed until then.
date_cancelled?|When the cancellation was asked for. Set as soon as a cancellation at the period end is scheduled, so it can be before date_ended.
date-timedate_ended?|When the item stopped being billed. null while it is active.
date-timecancellation_reason?|Why the item was cancelled. Not returned to a limited token.
tax_code?|The tax code used for this item. For a product item it is copied from the product. Not returned to a limited token.
type*stringThe kind of item. For a product item it is copied from the product, so it can be bundle.
"digital""physical""service""bundle"change_at_current_period_end?|A change to this item that is scheduled for the end of the current billing period (a new quantity, price, or a replacement product). null when no change is scheduled. Remove it with DELETE /subscriptions/{subscription_id}/items/{item_id}/change_at_current_period_end.
product?||The product, as a URL, or the full object with expand=items.product. null for a custom item. Left out when the token may not read products.
subscription?|The subscription this item belongs to, as a URL, or the full subscription object with expand=subscription.
subscription_terms?|The billing terms of this item, as a URL, or the full object with expand=subscription_terms.
meta*unknownAny data you stored on the item.
formatted?Display text for reference_price, reference_discount and reference_discount_price. Only returned with formatted=true.
curl -X GET 'https://api.comecero.com/api/v1/subscriptions/string/items/string'{ "object": "subscription_item", "url": "https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test", "item_id": "acme-pro.test", "date_created": "2026-10-02T15:21:28Z", "date_modified": "2026-10-02T15:21:28Z", "product_id": "acme-pro.test", "name": "Acme Pro (monthly)", "quantity": 1, "reference_price": 19.95, "reference_currency": "USD", "reference_discount": 0, "reference_discount_price": null, "discount_apply_count": null, "discount_applied_count": 0, "cancelled": false, "cancel_at_current_period_end": false, "date_cancelled": null, "date_ended": null, "cancellation_reason": null, "tax_code": null, "type": "digital", "change_at_current_period_end": null, "product": "https://api.comecero.com/api/v1/products/acme-pro.test", "subscription": "https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8", "subscription_terms": "https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms", "meta": null}Preview adding an item POST
Takes the same body and `remove_item_id` as `POST /subscriptions/{subscription_id}/items` and returns what the change would cost and when it would apply, without charging. Send `date_effective` from the result with `apply_immediately: true` to make the real change with the same amounts. Always answers `200`. Secret, trusted and limited tokens may call it, with the same rules as adding an item.
Update a subscription item POST
Changes an item's quantity, price or discount, or its `meta`. A change to `meta` or `cancellation_reason` only is saved at once with no charge. A change to quantity, price or discount applies now or at the end of the current period; when scheduled it shows in the item's `change_at_current_period_end`. Money can move. When the change applies at once, the customer pays the prorated amount for the rest of the current period now (from their account balance first, then their saved payment method) and an invoice is made; a cheaper replacement or lower quantity is refunded prorated, to the original payment method where possible, otherwise to the account balance. Whether a change applies at once or at the period end depends on the immediate upgrade and downgrade product types in your subscription settings, or on `apply_immediately`. On a live subscription only one money-moving change is allowed every 10 minutes. Use the preview endpoint first to show the customer the amount. Always answers `200` with the item. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as; it may change the quantity only (when your subscription settings allow customer upgrades or downgrades).