Skip to main content

Update Subscription

PUT 
/api/v2/subscriptions/:subscription_id

Update subscription items, coupons, billing interval, description, auto-cancel cycles, or payment methods.

Updatable fields:

  • Items (products and quantities) — deferred to the next cycle.
  • Subscription-level coupons — same deferral as items.
  • Recurring interval / interval count (e.g. monthly ↔ yearly) — deferred to the next cycle.
  • Description — applied immediately.
  • Until cycle number (auto-cancel) — applied immediately.
  • Payment method overrides — applied immediately.

Any change to items, coupons, or interval is recorded as a pending change that takes effect at current_period_end. The response carries a pending_change block describing the deferred change, including a next_invoice_preview and the per-line diff. If the next-cycle invoice has already been generated and is unpaid, it is automatically cancelled and re-issued with the new amount.

To change anything else (e.g. the consumer / payer), cancel the subscription and create a new one. Use DELETE /pending-change to revert a previously scheduled change before it takes effect.

Request​

Responses​

Successful Response