Changer de plan

Modifiez le plan d’un abonnement existant, permettant à la fois des mises à niveau et des rétrogradations vers différents niveaux de tarification.

Remarque: Cela utilisera les informations de paiement existantes du client pour mettre à niveau/rétrograder le plan.

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,
});

​

Gestion des échecs de paiement

Utilisez le paramètre on_payment_failure pour contrôler ce qui se passe lorsque le paiement du changement de forfait échoue :

Valeur	Comportement
prevent_change	Maintient l’abonnement sur le forfait actuel jusqu’à ce que le paiement réussisse. Le changement de forfait reste en attente.
apply_change	Applique immédiatement le changement de forfait, indépendamment du résultat du paiement. C’est le comportement par défaut.

Si on_payment_failure n’est pas spécifié, le comportement revient au paramètre de niveau entreprise configuré sur le tableau de bord.

​

Codes de réduction

Vous pouvez appliquer un code de réduction lors de la modification des plans en passant le paramètre discount_code.

Scénario	Comportement
discount_code fourni	Valide et applique la réduction au nouveau plan.
discount_code non fourni, réduction existante avec preserve_on_plan_change=true	La réduction existante est conservée si applicable au nouveau produit.
discount_code non fourni, aucune réduction applicable	Aucune réduction appliquée.

Utilisez des codes de réduction lors des changements de plan pour offrir des prix promotionnels sur les mises à niveau, ou passez un code lors de la migration des clients vers un nouveau palier de plan.

Utilisez prevent_change pour des mises à niveau critiques où vous souhaitez garantir le paiement avant d’accorder l’accès aux fonctionnalités premium.

Autorisations

Authorization · string · header · requis

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

Paramètres de chemin

subscription_id · string · requis

Subscription Id

Corps

application/json

product_id · string · requis

Unique identifier of the product to subscribe to

proration_billing_mode · enum<string> · requis

Proration Billing Mode

Options disponibles: prorated_immediately, full_immediately, difference_immediately, do_not_bill

quantity · integer<int32> · requis

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

Plage requise: x >= 0

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

Optional discount code to apply to the new plan. If provided, validates and applies the discount to the plan change. If not provided and the subscription has an existing discount with preserve_on_plan_change=true, the existing discount will be preserved (if applicable to the new product).

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

Options disponibles: 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.

Options disponibles: prevent_change, apply_change

Réponse

200

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