Preview adding an item
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.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
subscription_id*stringThe subscription id.
remove_item_id?stringThe id of an active item the new one would replace.
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-timeWhat the change would do.
application/json- response
What a change to a subscription's items would do: what the customer pays or gets back now, when the change takes effect and the new billing terms. Returned by the preview endpoints. Nothing is changed and no money moves.
object*"subscription_change_summary"The object type. Always subscription_change_summary.
"subscription_change_summary"payment_total*numberThe prorated amount the customer would pay now, in currency. 0 when the change is scheduled for the period end.
refund_total*numberThe prorated amount the customer would get back now, in currency. A refund goes to the original payment method where possible, otherwise to the customer's account balance.
net_total*numberpayment_total minus refund_total, in currency.
currency*stringThe subscription currency.
date_next_payment*stringWhen the next regular renewal is billed.
date-timedate_effective*stringWhen the change takes effect, always in UTC. To apply exactly the previewed amounts, send this value back as date_effective with apply_immediately: true.
date-timegenerates_new_subscription*booleantrue when the change moves the item to a product on a different subscription plan, which makes a new subscription.
apply_at_period_end*booleantrue when the change is scheduled for the end of the current billing period.
subscription_terms*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.
formatted?Display text for the totals and dates. Only with formatted=true.
curl -X POST 'https://api.comecero.com/api/v1/subscriptions/string/items/preview' \ -H 'Content-Type: application/json' \ -d '{ "product_id": "widget-pro.test", "quantity": 1}'{ "object": "subscription_change_summary", "payment_total": 13.3, "refund_total": 0, "net_total": 13.3, "currency": "USD", "date_next_payment": "2026-12-02T15:21:28Z", "date_effective": "2026-11-12T10:00:00Z", "generates_new_subscription": false, "apply_at_period_end": false, "subscription_terms": { "object": "subscription_terms", "price": 19.95, "quantity": 2, "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, per quantity.", "price_per_day": 0.66, "price_per_month": 19.95, "price_per_year": 239.4 }}Add a subscription item POST
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.
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.