Cambia piano
Modifica il piano di un abbonamento esistente, consentendo sia upgrade sia downgrade verso diversi livelli di prezzo.
Nota: per impostazione predefinita, usa i dati di pagamento esistenti del cliente. Imposta collect_via_payment_link per addebitare il pagamento tramite una pagina di checkout ospitata.
Modifiche Pianificate al Piano
Usa il parametroeffective_at per controllare quando la modifica del piano ha effetto:
Gestione dei Fallimenti di Pagamento
Usa il parametroon_payment_failure per controllare cosa succede quando il pagamento per la modifica del piano fallisce:
on_payment_failure non è specificato, il comportamento predefinito dipende dal tuo settaggio aziendale configurato nella dashboard.Raccolta tramite Payment Link
Impostacollect_via_payment_link su true per inviare il cliente a una pagina di checkout ospitata invece di addebitare il metodo di pagamento salvato. La risposta include quindi payment_id, payment_link, client_secret e expires_on — reindirizza il cliente a payment_link per completare il pagamento.
Questo richiede:
422. Finché il link non è pagato, l’abbonamento rimane sul piano attuale e un’ulteriore richiesta change-plan restituisce 409, a meno che non venga impostato cancel_older_payment_link.
Reindirizzamento dopo il pagamento
Impostareturn_url per rimandare il cliente al tuo sito dopo il pagamento del link. Il reindirizzamento aggiunge subscription_id, payment_id e status come parametri della query.
statusindica lo stato del pagamento della modifica del piano, non lo stato dell’abbonamento.- Quando il pagamento non va a buon fine, l’abbonamento rimane attivo sul piano attuale. Per riprovare, chiama nuovamente
change-planper ottenere un nuovo link. - Il nuovo piano può essere applicato poco dopo il reindirizzamento, quando arriva il webhook del pagamento.
return_url richiede collect_via_payment_link: true. Senza di esso, la richiesta restituisce 422.
Sostituzione di un Payment Link in attesa
Se il cliente abbandona il checkout senza pagare, impostacancel_older_payment_link su true nella richiesta change-plan successiva. Dodo Payments annulla il link non pagato e la nuova modifica del piano sostituisce quella in attesa. Il link annullato non accetta più pagamenti.
La richiesta viene convalidata prima dell’annullamento del link, quindi una richiesta non valida mantiene il link del cliente. Il link viene annullato solo se il cliente non ha iniziato a pagare:
change-plan genera la propria fattura. La modifica del piano sostituita e la relativa fattura vengono annullate.
Codici sconto
Puoi applicare uno o più codici sconto cumulativi quando modifichi i piani, passando l’arraydiscount_codes (massimo 20 elementi, applicati nell’ordine dell’array). Il campo singolare discount_code è deprecato, ma continua a funzionare per le integrazioni esistenti; non può essere combinato con discount_codes nella stessa richiesta.
Autorizzazioni
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Parametri del percorso
Subscription Id
Corpo
Unique identifier of the product to subscribe to
Proration Billing Mode
prorated_immediately, full_immediately, difference_immediately, do_not_bill, prorated_immediately_keep_cycle Number of units to subscribe for. Must be at least 1.
x >= 0Whether 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 for the new plan. Note : Leaving this empty would remove any existing addons
Cancel the payment link of a pending plan change, so that this change can replace it.
The link is cancelled only if the customer has not started to pay. A
paid or in-progress payment gives a 409. A failed cancel gives a
503, and a retry is safe.
The request is validated before the cancel. A later failure, for example an amount below the minimum, leaves the subscription on its current plan with no open link. A retry is safe.
The preview route shares this request body and ignores this field.
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.
DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes.
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.
When to apply the plan change.
immediately(default): Apply the plan change right awaynext_billing_date: Schedule the change for the next billing date
immediately, next_billing_date Metadata for the payment. If not passed, the metadata of the subscription will be taken
Controls behavior when the plan change payment fails.
prevent_change: Keep subscription on current plan until payment succeedsapply_change(default): Apply plan change immediately regardless of payment outcome
With effective_at: next_billing_date, the plan change payment replaces the renewal payment.
If that payment fails with prevent_change, the plan change is cancelled.
The subscription then renews on the current plan, with the usual payment retries.
If not specified, uses the business-level default setting.
prevent_change, apply_change The URL that receives the customer after they pay the payment link.
Needs collect_via_payment_link: true. Without it, the request gets a
422. A change that collects no money issues no link and does not use
the URL. The preview route validates this field but does not use it.
The redirect adds subscription_id, payment_id and status. The
status value is the status of the plan-change payment. It is not the
status of the subscription. When that payment fails, the subscription
stays active on its current plan. To try again, call this endpoint
again to get a new link. The new plan can apply after the redirect,
when the payment webhook arrives.
Risposta
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.