Skip to navigation

Update Subscription Items

View as Markdown

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

subscription_idstringRequired
account_idstringRequired

Request

This endpoint expects an object.
itemslist of objectsRequired
proration_behaviorenumRequired

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).
Allowed values:
proration_datedatetime or nullOptional

Response

Successful Response
subscription_idstring
invoice_idstring or nullOptional
credit_note_idstring or nullOptional
payment_statusstring or nullOptional
payment_errorstring or nullOptional
floating_items_createdintegerOptionalDefaults to 0
proration_amount_atomintegerOptionalDefaults to 0
voided_invoice_idslist of stringsOptional
new_renewal_invoice_idstring or nullOptional
new_invoice_payment_statusstring or nullOptional

Errors

409
Conflict Error
422
Unprocessable Entity Error