Skip to main content
POST
JavaScript

Schemalagda ändringar av plan

Använd parametern effective_at för att kontrollera när planändringen träder i kraft:
Schemalagda planändringar är idealiska för nedgradering — kunder behåller sina nuvarande planförmåner till slutet av faktureringsperioden, och byter sedan automatiskt till den nya planen.
För att avbryta en schemalagd planändring innan den träder i kraft, använd slutpunkten Cancel Scheduled Plan Change.

Hantering av betalningsfel

Använd parametern on_payment_failure för att kontrollera vad som händer när betalningen för planändringen misslyckas:
Om on_payment_failure inte anges, är beteendet förvalt till din affärsnivåinställning som konfigureras i instrumentpanelen.

Rabattkoder

Du kan använda en eller flera staplade rabattkoder när du byter planer genom att skicka discount_codes-arrayen (max 20 poster, tillämpas i arrayordning). Det enkla fältet discount_code är föråldrat men fungerar fortfarande för befintliga integrationer; det kan inte kombineras med discount_codes i samma förfrågan.
Använd rabattkoder vid planändringar för att erbjuda kampanjpriser på uppgraderingar, eller skicka koder när kunder migreras till en ny plannivå.
Använd prevent_change för kritiska uppgraderingar där du vill säkerställa betalning innan du ger åtkomst till premiumfunktioner.

Auktoriseringar

Authorization
string
header
obligatorisk

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

Sökvägsparametrar

subscription_id
string
obligatorisk

Subscription Id

Kropp

application/json
product_id
string
obligatorisk

Unique identifier of the product to subscribe to

proration_billing_mode
enum<string>
obligatorisk

Proration Billing Mode

Tillgängliga alternativ:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
quantity
integer<int32>
obligatorisk

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

Obligatoriskt intervall: 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

cancel_scheduled_change_plan
boolean

Replace a scheduled plan change with this one.

The scheduled change is cancelled by the transaction that applies this change. A change that never applies leaves the schedule in place.

effective_at: next_billing_date is allowed. The new schedule then replaces the old one in the request transaction.

A pending plan change still gets a 409. This field does not affect it.

The preview route shares this request body, so a preview that sets this field also passes the scheduled-change 409.

Collect the plan-change amount with a payment link. The customer then pays on a checkout page.

The business needs the allow_plan_change_via_payment_link capability. The request needs effective_at: immediately. The request also needs on_payment_failure: prevent_change.

The preview route shares this request body and ignores this field.

discount_code
string | null
föråldrad

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
Tillgängliga alternativ:
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.

Tillgängliga alternativ:
prevent_change,
apply_change

Svar

Subscription plan changed. A link request can return checkout details. A pending plan change applies after payment succeeds.

Handles for a hosted checkout page that settles a plan change.

The four fields repeat UpdatePaymentMethodResponse and a subset of CreateSubscriptionResponse. A shared type would rename the generated SDK types for all three routes, so each route keeps its own.

client_secret
string | null

Client secret for an embedded checkout.

expires_on
string<date-time> | null

When the link stops working.

payment_id
string | null

Id of the payment that settles the plan change.

Checkout page URL. Give this to the customer.

Senast ändrad 22 maj 2026