Add a subscription item
Adds an item to a running subscription, or replaces one item with another when you send remove_item_id (an upgrade or downgrade). The item is a product (product_id) or a custom item (name, type, reference_price and reference_currency, no product_id). Answers 201 with the new item when the change applies now, or 200 with the pending item when it is scheduled for the end of the current period (then nothing is charged and the item shows in add_at_current_period_end or the replaced 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. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as; it may not send prices, discounts or apply_immediately, may only replace product items, and only when your subscription settings allow customer upgrades or downgrades.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
subscription_id*stringThe subscription id.
remove_item_id?stringThe id of an active item to replace with the new one. A new item at the same or a higher price is an upgrade; a lower price is a downgrade. A product on another subscription plan makes a new subscription when paid, if the product allows that term change.
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.
falseapplication/json- body
An item to bill for. Send a product_id to bill for a product from your catalog. Or leave product_id out to add a custom item: then name, type, reference_price (more than 0) and reference_currency are required. A reseller account must send product_id, and in practice so must a limited token, because it may not send prices.
product_id?stringThe product to bill for. The item takes its name, type and tax code from the product, and its item_id is the product_id. To add a product to a running subscription at once, the product must use the same subscription plan as the subscription.
item_id?stringYour own id for a custom item. If you send it with product_id, it must equal the product_id. If you leave it out, a number is assigned.
name?stringThe item name. Required for a custom item. Ignored when product_id is sent.
type?stringThe kind of item. Required for a custom item. Ignored when product_id is sent.
"digital""physical""service"tax_code?stringThe tax code for a custom item. Ignored when product_id is sent.
quantity?integerHow many units to bill for.
1 <= value1reference_price?numberThe price of one unit for each billing period, in reference_currency. Required for a custom item. For a product item it overrides the product price. A limited token may not send it (403).
0 < valuereference_currency?stringThe three-letter ISO 4217 currency of reference_price. Required for a custom item. Your account must have a gateway for it. A limited token may not send it (403).
3 <= length <= 3reference_discount?numberA discount taken off each unit, in reference_currency. Cannot be more than the price. A limited token may not send it (403).
0 <= valuediscount_apply_count?|How many billings the discount applies to. Leave it out or send null to apply it to every billing. A limited token may not send it (403).
1 <= valueapply_immediately?booleanOnly for POST /subscriptions/{subscription_id}/items and its preview. true adds the item now and charges the prorated amount for the rest of the current period. false schedules it for the end of the period. The default comes from the immediate upgrade product types in your subscription settings. Sending a value other than the default needs permission to update subscription settings. A limited token may not send it (403).
date_effective?stringOnly with apply_immediately. The UTC time the change counts from, used for proration. Use date_effective from a preview to get the same amounts. It may be at most one hour in the past and not before the current period start.
date-timeThe change is scheduled for the end of the current period. Returns the pending 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 POST 'https://api.comecero.com/api/v1/subscriptions/string/items' \ -H 'Content-Type: application/json' \ -d '{ "product_id": "widget-pro.test", "quantity": 1}'{ "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}List subscription items GET
Returns the items of a subscription, including cancelled ones, as a plain JSON array (no paging wrapper). `limit` and `offset` slice the array. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.
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.