Skip to main content
POST
JavaScript

Scheduled Plan Changes

Use the effective_at parameter to control when the plan change takes effect:
Scheduled plan changes are ideal for downgrades — customers keep their current plan benefits until the end of the billing period, then automatically switch to the new plan.
To cancel a scheduled plan change before it takes effect, use the Cancel Scheduled Plan Change endpoint.

Payment Failure Handling

Use the on_payment_failure parameter to control what happens when the plan change payment fails:
If on_payment_failure is not specified, the behavior defaults to your business-level setting configured in the dashboard.

Discount Codes

You can apply one or more stacked discount codes when changing plans by passing the discount_codes array (max 20 entries, applied in array order). The singular discount_code field is deprecated but still works for existing integrations; it cannot be combined with discount_codes in the same request.
Use discount codes during plan changes to offer promotional pricing on upgrades, or pass codes when migrating customers to a new plan tier.
Use prevent_change for critical upgrades where you want to ensure payment before granting access to premium features.

Authorizations

Authorization
string
header
required

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

Path Parameters

subscription_id
string
required

Subscription Id

Body

application/json
product_id
string
required

Unique identifier of the product to subscribe to

proration_billing_mode
enum<string>
required

Proration Billing Mode

Available options:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
quantity
integer<int32>
required

Number of units to subscribe for. Must be at least 1.

Required range: x >= 0
adaptive_currency_fees_inclusive
boolean | null

Whether adaptive currency fees should be included in the price (true) or added on top (false). If not specified, uses the subscription's stored setting.

addons
Attach Addon Request · object[] | null

Addons for the new plan. Note : Leaving this empty would remove any existing addons

discount_code
string | null
deprecated

DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes.

discount_codes
string[] | null

Stacked discount codes to apply to the new plan. Max 20. Cannot be used together with discount_code. If provided, replaces any existing discount codes. Empty array removes all discounts. If not provided (None), existing discounts with preserve_on_plan_change=true are preserved.

effective_at
enum<string>

When to apply the plan change.

  • immediately (default): Apply the plan change right away
  • next_billing_date: Schedule the change for the next billing date
Available options:
immediately,
next_billing_date
metadata
null | Metadata · object

Metadata for the payment. If not passed, the metadata of the subscription will be taken

on_payment_failure
null | enum<string>

Controls behavior when the plan change payment fails.

  • prevent_change: Keep subscription on current plan until payment succeeds
  • apply_change (default): Apply plan change immediately regardless of payment outcome

If not specified, uses the business-level default setting.

Available options:
prevent_change,
apply_change

Response

Subscription plan changed. If on_payment_failure=prevent_change, the plan change is pending until payment succeeds.

Last modified on May 18, 2026