Update Subscription Items
Update subscription items with proration handling.
Handles mid-cycle subscription changes (upgrades/downgrades) with three proration behaviors:
-
always_invoice: Creates invoice immediately and attempts payment now. Use when you want the customer to pay for the upgrade immediately.
-
create_prorations: Creates floating items (invoice_id=NULL) that will be collected at the next renewal. Use for deferred billing.
-
none: No proration, changes apply at next renewal only. Items are updated but no proration charges/credits are created.
Supports six item operations:
- Add new item:
{"price_id": "price_xxx", "quantity": 2} - Add new item at period end:
{"price_id": "price_xxx", "quantity": 2, "start_at_end": true}- Created inactive, activated at next renewal - Update existing item:
{"id": "si_xxx", "quantity": 5}or{"id": "si_xxx", "price_id": "price_yyy"} - Delete item now:
{"id": "si_xxx", "deleted": true} - Remove at period end:
{"id": "si_xxx", "drop_at_end": true}- Item removed at next renewal - Cancel scheduled removal:
{"id": "si_xxx", "drop_at_end": false}- Cancel pending removal
The endpoint calculates proration based on remaining time in the current billing period:
- Credits are created for unused time on old/deleted items (negative amounts)
- Charges are created for remaining time on new/updated items (positive amounts)
Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
Proration behavior for mid-cycle subscription changes.
- ALWAYS_INVOICE: Create invoice immediately and attempt payment now
- CREATE_PRORATIONS: Create floating items (invoice_id=NULL) for next renewal
- NONE: No proration, changes apply at next renewal only
- CHARGE_FULL: Charge the full new-plan price immediately with NO proration and NO unused-time credit, resetting the billing cycle to now (next renewal = now + new interval). change_plan only, immediate changes only. Always collects synchronously (charge-first); pay_before_change does not apply to it (a charge needing interactive 3DS/SCA declines inline rather than handing off a 402).