Cambia piano

Modifica il piano di un abbonamento esistente, consentendo sia gli aggiornamenti che i downgrade a diversi livelli di prezzo.

Nota: Questo utilizzerà le informazioni di pagamento esistenti del cliente per aggiornare/downgradare il piano.

POST /subscriptions/{subscription_id}/change-plan

JavaScript

JavaScript

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

await client.subscriptions.changePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

​

Modifiche Pianificate al Piano

Usa il parametro effective_at per controllare quando la modifica del piano ha effetto:

Valore	Comportamento
immediately	Applica subito la modifica del piano. Questo è il comportamento predefinito.
next_billing_date	Pianifica la modifica per la prossima data di fatturazione. Il cliente mantiene l’accesso al piano attuale fino al termine del periodo di fatturazione.

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:

Valore	Comportamento
prevent_change	Mantieni l’abbonamento sul piano attuale fino a quando il pagamento ha successo. La modifica del piano rimane in sospeso.
apply_change	Applica immediatamente la modifica del piano indipendentemente dall’esito del pagamento. Questo è il comportamento predefinito.

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.

Valore discount_codes	Comportamento
Non fornito (null / omesso)	Gli sconti esistenti con preserve_on_plan_change=true sono preservati se applicabili al nuovo prodotto.
[] (array vuoto)	Tutti gli sconti esistenti sono rimossi dall’abbonamento.
["CODE_A", "CODE_B", ...]	Sostituisce eventuali sconti esistenti con questo set cumulabile, convalidato e applicato nell’ordine dell’array.

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

Show child attributes

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 · object

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

Show child attributes

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

200

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