Vai al contenuto principale
POST
JavaScript

Modifiche Pianificate al Piano

Usa il parametro effective_at per controllare quando la modifica del piano ha effetto:
Le modifiche pianificate al piano sono ideali per i downgrade: i clienti mantengono i benefici del loro piano attuale fino alla fine del periodo di fatturazione, per poi passare automaticamente al nuovo piano.
Per annullare una modifica pianificata del piano prima che entri in vigore, utilizza l’endpoint Annulla Modifica Pianificata del Piano.

Gestione dei Fallimenti di Pagamento

Usa il parametro on_payment_failure per controllare cosa succede quando il pagamento per la modifica del piano fallisce:
Se on_payment_failure non è specificato, il comportamento predefinito dipende dal tuo settaggio aziendale configurato nella dashboard.

Codici Sconto

Puoi applicare uno o più codici sconto cumulabili quando cambi piano passando l’array discount_codes (massimo 20 voci, applicate nell’ordine dell’array). Il campo singolare discount_code è deprecato ma funziona ancora per le integrazioni esistenti; non può essere combinato con discount_codes nella stessa richiesta.
Usa i codici sconto durante i cambiamenti di piano per offrire prezzi promozionali sugli upgrade, o passa i codici quando migrano i clienti a un nuovo livello di piano.
Usa prevent_change per upgrade critici in cui vuoi assicurarti il pagamento prima di concedere l’accesso alle funzionalità premium.

Autorizzazioni

Authorization
string
header
obbligatorio

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

Parametri del percorso

subscription_id
string
obbligatorio

Subscription Id

Corpo

application/json
product_id
string
obbligatorio

Unique identifier of the product to subscribe to

proration_billing_mode
enum<string>
obbligatorio

Proration Billing Mode

Opzioni disponibili:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
quantity
integer<int32>
obbligatorio

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

Intervallo richiesto: 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
deprecato

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
Opzioni disponibili:
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.

Opzioni disponibili:
prevent_change,
apply_change

Risposta

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

Ultima modifica il 22 maggio 2026