Update a subscription item
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).
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.
falseapplication/json- body
Changes to one subscription item. A change to quantity, price or discount is applied at once (with a prorated charge or refund) or scheduled for the end of the period, by the same rules as adding an item.
quantity?integerThe new quantity. More is an upgrade, less is a downgrade. A limited token may only do this when your subscription settings allow customer upgrades or downgrades.
1 <= valuereference_price?numberThe new unit price, in reference_currency. Unless your account uses the agent model, you can lower the price but not raise it. A limited token may not send it (403).
reference_currency?stringThe new currency of reference_price. A limited token may not send it (403).
3 <= length <= 3reference_discount?numberThe new discount per unit. Unless your account uses the agent model, you can raise the discount but not lower it. 0 removes it. A limited token may not send it (403).
0 <= valuediscount_apply_count?|How many billings the discount applies to. Unless your account uses the agent model, it cannot be lowered. A limited token may not send it (403).
apply_immediately?booleantrue applies the change now, false schedules it for the period end. The default comes from the immediate upgrade and downgrade 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. At most one hour in the past and not before the current period start.
date-timechange_at_current_period_end?nullSend null to remove a scheduled change. Ignored for a limited token.
cancellation_reason?stringOnly saved when the item is cancelled or scheduled to be cancelled. Ignored for a limited token.
length <= 75meta?unknownAny data you want to store on the item. Replaces the old value. Ignored for a limited token.
The item after the change.
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/string' \ -H 'Content-Type: application/json' \ -d '{ "quantity": 2}'{ "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}Get a subscription item GET
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.
Cancel a subscription item POST
Cancels one item. By default (or with no body) the cancellation is scheduled for the end of the current period and the item is billed until then. With `cancel_at_current_period_end: false` the item is cancelled at once and any scheduled change to it is dropped. No refund is made. When the last active item is cancelled at once, the whole subscription is cancelled. Events `subscription_item:cancellation_scheduled` or `subscription_item:cancelled` fire. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as, and only when your subscription settings allow customers to cancel (otherwise `403`).