Preview an item change
Takes the same body as POST /subscriptions/{subscription_id}/items/{item_id} and returns what the change would cost and when it would apply, without charging or saving. A body with no change to quantity, price or discount answers 422. Secret, trusted and limited tokens may call it, with the same rules as updating the item.
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.
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.
What 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/string/preview' \ -H 'Content-Type: application/json' \ -d '{ "quantity": 2}'{ "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 }}Remove an item's scheduled change DELETE
Removes the change scheduled for this item at the end of the current period (`change_at_current_period_end`), such as a new quantity or a replacement product. Nothing is charged or refunded. Returns the item, not an empty body. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.
Get an item's billing terms GET
Returns the billing terms of one item: price, quantity, interval, trial, discount and a ready-to-show sentence. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.