Subscription Upgrade & Downgrade Guide - Dodo Payments Documentation

Change Plan API

Full API docs for updating subscriptions.

Plan Change Preview

See charge amounts before changing plans.

Integration Guide

Step-by-step subscription setup.

What is a subscription upgrade or downgrade?

Changing plans lets you move a customer between subscription tiers or quantities. Use it to:

Align pricing with usage or features
Move from monthly to annual (or vice versa)
Adjust quantity for seat-based products

Plan changes can trigger an immediate charge depending on the proration mode you choose.

When to use plan changes

Upgrade when a customer needs more features, usage, or seats
Downgrade when usage decreases
Migrate users to a new product or price without cancelling their subscription

Plan Change Flow

Prerequisites

Before implementing subscription plan changes, ensure you have:

A Dodo Payments merchant account with active subscription products
API credentials (API key and webhook secret key) from the dashboard
An existing active subscription to modify
Webhook endpoint configured to handle subscription events

For detailed setup instructions, see our Integration Guide.

Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

Understand Plan Change Requirements

Before implementing, determine:

Which subscription products can be changed to which others
What proration mode fits your business model
How to handle failed plan changes gracefully
Which webhook events to track for state management

Test plan changes thoroughly in test mode before implementing in production.

Choose Your Proration Strategy

Select the billing approach that aligns with your business needs:

prorated_immediately
difference_immediately
full_immediately
do_not_bill

Best for: SaaS applications wanting to charge fairly for unused time

Calculates exact prorated amount based on remaining cycle time
Charges a prorated amount based on unused time remaining in the cycle
Provides transparent billing to customers

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

subscription_id

string

requis

The ID of the active subscription to modify.

product_id

string

requis

The new product ID to change the subscription to.

quantity

integer

défaut:"1"

Number of units for the new plan (for seat-based products).

proration_billing_mode

string

requis

How to handle immediate billing: prorated_immediately, full_immediately, difference_immediately, or do_not_bill.

addons

array

Optional addons for the new plan. Leaving this empty removes any existing addons.

on_payment_failure

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.

discount_codes

array

Codes promo empilables optionnels à appliquer au nouveau plan (max 20, appliqués dans l’ordre du tableau). Le comportement dépend de ce que vous transmettez :

Non fourni / null — les remises existantes avec preserve_on_plan_change=true sont conservées si elles s’appliquent au nouveau produit.
[] (tableau vide) — supprime toutes les remises existantes de l’abonnement.
["CODE_A", "CODE_B", ...] — remplace toutes les remises existantes par cet ensemble empilable.

discount_code

string

obsolète

Obsolète — privilégier discount_codes pour les nouvelles intégrations. Ce champ fonctionne toujours pour assurer la compatibilité ascendante, mais ne peut pas être combiné avec discount_codes dans la même requête.

effective_at

string

défaut:"immediately"

Quand appliquer le changement de plan :

immediately (par défaut) : Appliquer immédiatement le changement de plan
next_billing_date : Programmer le changement pour la prochaine date de facturation. Le client conserve son plan actuel jusqu’à la fin de la période de facturation.

Utilisez next_billing_date pour les rétrogradations, afin que les clients gardent les avantages de leur plan actuel jusqu’à la fin de la période de facturation.

Handle Webhook Events

Configurez la gestion des webhooks pour suivre les résultats des changements de plan :

subscription.active : Changement de plan réussi, abonnement mis à jour
subscription.plan_changed : Plan d’abonnement changé (mise à niveau/rétrogradation/mise à jour des modules complémentaires)
subscription.on_hold : Échec du prélèvement pour le changement de plan, abonnement mis en pause
payment.succeeded : Prélèvement immédiat pour changement de plan réussi
payment.failed : Échec du prélèvement immédiat

Vérifiez toujours les signatures des webhooks et implémentez un traitement idempotent des événements.

Update Your Application State

Sur la base des événements des webhooks, mettez à jour votre application :

Accorder/révoquer des fonctionnalités en fonction du nouveau plan
Mettre à jour le tableau de bord client avec les nouveaux détails du plan
Envoyer des emails de confirmation concernant les changements de plan
Enregistrer les changements de facturation à des fins de vérification

Test and Monitor

Testez rigoureusement votre implémentation :

Testez tous les modes de proratisation avec différents scénarios
Vérifiez que la gestion des webhooks fonctionne correctement
Surveillez les taux de succès des changements de plan
Configurez des alertes pour les échecs de changement de plan

Votre implémentation de changement de plan d’abonnement est maintenant prête pour une utilisation en production.

Prévisualisation des changements de plan

Avant de valider un changement de plan, utilisez l’API de Prévisualisation pour montrer aux clients exactement ce qu’ils seront facturés :

Node.js SDK
Python SDK

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('Immediate charge:', preview.immediate_charge.summary);
console.log('New plan details:', preview.new_plan);

preview = client.subscriptions.preview_change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately"
)

# Show customer the charge before confirming
print("Immediate charge:", preview.immediate_charge.summary)
print("New plan details:", preview.new_plan)

Utilisez l’API de prévisualisation pour construire des boîtes de dialogue de confirmation montrant aux clients le montant exact qu’ils seront facturés avant de confirmer un changement de plan.

API de Changement de Plan

Utilisez l’API de Changement de Plan pour modifier le produit, la quantité et le comportement de proratisation pour un abonnement actif.

Exemples de démarrage rapide

Node.js SDK
Python SDK
Go SDK
HTTP

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function changePlan() {
  const result = await client.subscriptions.changePlan('sub_123', {
    product_id: 'prod_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log(result.status, result.invoice_id, result.payment_id);
}

changePlan();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

result = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print(result.status, result.get("invoice_id"), result.get("payment_id"))

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
  res, err := client.Subscriptions.ChangePlan(context.TODO(), dodopayments.SubscriptionChangePlanParams{
    SubscriptionID: dodopayments.F("sub_123"),
    ProductID:             dodopayments.F("prod_new"),
    Quantity:              dodopayments.F(int64(3)),
    ProrationBillingMode:  dodopayments.F(dodopayments.SubscriptionChangePlanParamsProrationBillingModeProratedImmediately),
    OnPaymentFailure:      dodopayments.F(dodopayments.OnPaymentFailurePreventChange), // Optional
  })
  if err != nil { panic(err) }
  fmt.Println(res.Status, res.InvoiceID, res.PaymentID)
}

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

Success

{
  "status": "processing",
  "subscription_id": "sub_123",
  "invoice_id": "inv_789",
  "payment_id": "pay_456",
  "proration_billing_mode": "prorated_immediately"
}

Les champs comme invoice_id et payment_id sont retournés uniquement lorsqu’un prélèvement immédiat et/ou une facture sont créés lors du changement de plan. Toujours se fier aux événements des webhooks (e.g., payment.succeeded, subscription.plan_changed) pour confirmer les résultats.

Si le prélèvement immédiat échoue, l’abonnement peut être déplacé vers subscription.on_hold jusqu’à ce que le paiement réussisse.

Gestion des Modules Complémentaires

Lors du changement de plans d’abonnement, vous pouvez également modifier les modules complémentaires :

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

Les modules complémentaires sont inclus dans le calcul de proratisation et seront facturés selon le mode de proratisation sélectionné.

Vous pouvez appliquer un ou plusieurs codes promo empilables lors du changement de plans d’abonnement (max 20, appliqués dans l’ordre du tableau). Ceci est utile pour offrir un tarif promotionnel sur des mises à niveau ou des migrations.

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

# Apply stacked discount codes during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_codes=["UPGRADE20"]
)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

Comportement des remises lors du changement de plan

`discount_codes` valeur	Comportement
Non fourni / `null`	Les remises existantes avec `preserve_on_plan_change=true` sont automatiquement conservées si elles s’appliquent au nouveau produit.
`[]` (tableau vide)	Toutes les remises existantes sont supprimées de l’abonnement.
`["CODE_A", "CODE_B", ...]`	Remplace toutes les remises existantes par cet ensemble empilable, validé et appliqué dans l’ordre du tableau.

Le champ singulier discount_code sur ce point de terminaison est obsolète mais fonctionne toujours pour assurer la compatibilité ascendante — les intégrations existantes n’ont pas besoin de changer immédiatement. Il ne peut pas être combiné avec discount_codes dans la même requête. Passez à la forme tableau quand cela est pratique.

Utilisez l’API de Prévisualisation de Changement de Plan avec discount_codes pour montrer exactement aux clients combien ils économiseront avant de confirmer le changement de plan.

Modes de Proratisation

Choisissez comment facturer le client lors des changements de plan :

`prorated_immediately`

Facture pour la différence partielle dans le cycle actuel
Si en période d’essai, facture immédiatement et passe maintenant au nouveau plan
Rétrogradation : peut générer un crédit au prorata appliqué aux renouvellements futurs

`full_immediately`

Facture le montant total du nouveau plan immédiatement
Ignore le temps restant du plan ancien

Les crédits créés par les rétrogradations en utilisant difference_immediately sont liés à l’abonnement et distincts des droits de Facturation Basée sur le Crédit. Ils s’appliquent automatiquement aux renouvellements futurs du même abonnement et ne sont pas transférables d’un abonnement à un autre.

`difference_immediately`

Mise à niveau : facture immédiatement la différence de prix entre les anciens et les nouveaux plans
Rétrogradation : ajoute la valeur restante en crédit interne à l’abonnement et l’applique automatiquement aux renouvellements

`do_not_bill`

Aucun frais ou crédit n’est calculé
Le client passe immédiatement au nouveau plan sans ajustement de facturation
Le cycle de facturation reste inchangé
Idéal pour les migrations de courtoisie, les changements de plan gratuits ou l’absorption des différences de coût

Fonctionnalité	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Frais de mise à niveau	Différence proratisée pour les jours restants	Différence de prix totale entre les plans	Prix total du nouveau plan	Aucun frais
Crédit de rétrogradation	Crédit proratisé pour les jours restants	Différence de prix totale comme crédit	Aucun crédit	Aucun crédit
Cycle de facturation	Inchangé	Inchangé	Réinitialisé à aujourd’hui	Inchangé
Comportement pendant l’essai	Met fin à l’essai, facture immédiatement	Met fin à l’essai, facture immédiatement	Met fin à l’essai, facture le montant total	Met fin à l’essai, aucun frais
Idéal pour	Facturation équitable basée sur le temps	Calcul simple de mise à niveau/rétrogradation	Réinitialisation des cycles de facturation	Migrations gratuites ou changements de courtoisie
Complexité	Moyenne (calcul de jour)	Faible (soustraction simple)	Faible (montant total)	Aucune

Scénarios d’exemple

Utilisez ces chiffres canoniques de manière cohérente :

Plan actuel : Basique à 30 $/mois
Objectif de mise à niveau : Pro à 80 $/mois
Objectif de rétrogradation (à partir de Pro) : Starter à 20 $/mois
Cycle de facturation : 30 jours, commencé le 1er janvier
Changement de plan prévu pour le 16 janvier (15 jours restants, 15 jours utilisés)

Upgrade: Basic ($30) → Pro ($80) with prorated_immediately

Step 1: Calculate unused credit from current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Calculate prorated cost of new plan
  Remaining days = 15 out of 30 days
  New plan cost = $80 × (15/30) = $40.00

Step 3: Calculate immediate charge
  Charge = New plan cost − Credit
  Charge = $40.00 − $15.00 = $25.00

→ Customer pays $25.00 now
→ Next renewal (Feb 1): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with prorated_immediately

Step 1: Calculate unused credit from current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Calculate prorated cost of new plan
  Remaining days = 15 out of 30 days
  New plan cost = $20 × (15/30) = $10.00

Step 3: Calculate credit balance
  Credit = $40.00 − $10.00 = $30.00

→ No charge — $30.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal (Feb 1): $20.00 − $30.00 credit = $0.00
→ Following renewal (Mar 1): $20.00 − $10.00 remaining credit = $10.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with difference_immediately

Immediate charge = New plan price − Old plan price
                 = $80 − $30
                 = $50.00

→ Customer pays $50.00 now (regardless of cycle position)
→ Next renewal (Feb 1): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with difference_immediately

Credit = Old plan price − New plan price
       = $80 − $20
       = $60.00

→ No charge — $60.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal: $20.00 − $20.00 (from credit) = $0.00
→ Following renewal: $20.00 − $20.00 (from credit) = $0.00
→ Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with full_immediately

Immediate charge = Full new plan price = $80.00

→ Customer pays $80.00 now
→ No credit for unused time on old plan
→ Billing cycle resets to today (January 16)
→ Next renewal: February 16 at $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})

Mid-cycle upgrade with add-ons using prorated_immediately

Current: Basic plan ($30/month), no add-ons
New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
Change on day 16 of 30 (15 days remaining)

Step 1: Credit from current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Prorated cost of new plan + add-ons
  New plan = $80 × (15/30) = $40.00
  Add-ons = $30 × (15/30) = $15.00
  Total new = $55.00

Step 3: Immediate charge
  Charge = $55.00 − $15.00 = $40.00

→ Customer pays $40.00 now
→ Next renewal: $80.00 + $30.00 = $110.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

Comment chaque mode traite la facturation

Choisissez prorated_immediately pour une comptabilité équitable dans le temps ; choisissez full_immediately pour redémarrer la facturation ; utilisez difference_immediately pour des mises à niveau simples et des crédits automatiques lors de rétrogradations ; ou utilisez do_not_bill pour changer de plan sans ajustement de facturation.

Gestion des Échecs de Paiement

Contrôlez ce qui se passe lorsqu’un paiement de changement de plan échoue en utilisant le paramètre on_payment_failure.

Modes d’Échec de Paiement

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Comportement : Conservez l’abonnement sur son plan actuel jusqu’à ce que le paiement réussisse.

Le changement de plan est marqué “en attente”
Le client conserve l’accès à son plan actuel
L’abonnement se déplace vers l’état active seulement après un paiement réussi
Utile lorsque vous souhaitez garantir le paiement avant d’accorder des fonctionnalités améliorées

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

Comportement : Appliquer le changement de plan immédiatement, quel que soit le résultat du paiement.

Le changement de plan est appliqué même si le paiement échoue
Le client obtient un accès immédiat au nouveau plan
L’abonnement peut se déplacer vers on_hold si le paiement échoue
Bon pour des mises à niveau non critiques ou lorsque vous faites confiance au client

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'apply_change' // This is the default
});

Si non spécifié, le paramètre on_payment_failure utilise votre paramètre par défaut au niveau de l’entreprise configuré dans le tableau de bord.

Quand Utiliser Chaque Mode

Scénario	Mode Recommandé	Raison
Mise à niveau vers des fonctionnalités premium	`prevent_change`	Assurez le paiement avant d’accorder l’accès
Augmentation de la quantité (plus de sièges)	`prevent_change`	Prévenir l’usage sans paiement
Rétrogradation des plans	`apply_change`	Le client réduit ses dépenses
Clients d’entreprise de confiance	`apply_change`	Risque de non-paiement faible
Conversion de l’essai en abonnement payant	`prevent_change`	Moment de paiement critique

Gestion des Webhooks

Suivez l’état des abonnements via les webhooks pour confirmer les changements de plan et les paiements.

Types d’Événements à Gérer

subscription.active : abonnement activé
subscription.plan_changed : Plan d’abonnement modifié (mise à niveau/rétrogradation/changements de modules complémentaires)
subscription.on_hold : Échec du prélèvement, abonnement mis en pause
subscription.renewed : renouvellement réussi
payment.succeeded : Prélèvement pour changement de plan ou renouvellement réussi
payment.failed : Échec du paiement

Nous recommandons de piloter la logique commerciale à partir des événements d’abonnement et d’utiliser les événements de paiement pour confirmation et réconciliation.

Vérification des Signatures et Gestion des Intentions

Next.js Route Handler
Express.js

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req) {
  const webhookId = req.headers.get('webhook-id');
  const webhookSignature = req.headers.get('webhook-signature');
  const webhookTimestamp = req.headers.get('webhook-timestamp');
  const secret = process.env.DODO_WEBHOOK_SECRET;

  const payload = await req.text();
  // verifySignature is a placeholder – in production, use a Standard Webhooks library
  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

  switch (event.type) {
    case 'subscription.active':
      // mark subscription active in your DB
      break;
    case 'subscription.plan_changed':
      // refresh entitlements and reflect the new plan in your UI
      break;
    case 'subscription.on_hold':
      // notify user to update payment method
      break;
    case 'subscription.renewed':
      // extend access window
      break;
    case 'payment.succeeded':
      // reconcile payment for plan change
      break;
    case 'payment.failed':
      // log and alert
      break;
    default:
      // ignore unknown events
      break;
  }

  return NextResponse.json({ received: true });
}

import express from 'express';

const app = express();
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const webhookId = req.header('webhook-id');
  const webhookSignature = req.header('webhook-signature');
  const webhookTimestamp = req.header('webhook-timestamp');
  const secret = process.env.DODO_WEBHOOK_SECRET;
  const payload = req.body.toString('utf8');

  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return res.status(400).send('Invalid signature');

  // handle events like above
  res.json({ received: true });
});

app.listen(3000);

Pour des schémas de charge utile détaillés, consultez les charges utiles des webhooks d’abonnement et les charges utiles des webhooks de paiement.

Meilleures Pratiques

Suivez ces recommandations pour des changements de plan d’abonnement fiables :

Stratégie de Changement de Plan

Tester rigoureusement : Testez toujours les changements de plan en mode test avant la production
Choisir la proratisation avec soin : Sélectionnez le mode de proratisation qui s’aligne avec votre modèle commercial
Gérer les échecs avec soin : Mettez en œuvre une gestion appropriée des erreurs et une logique de reprise
Surveiller les taux de succès : Suivez les taux de succès/échec des changements de plan et examinez les problèmes

Implémentation des Webhooks

Vérifiez les signatures : Validez toujours les signatures des webhooks pour garantir leur authenticité
Implémentez l’idempotence : Gérez avec soin les événements de webhook en double
Traitez de manière asynchrone : Ne bloquez pas les réponses des webhooks avec des opérations lourdes
Tout enregistrer : Maintenez des journaux détaillés pour le débogage et la vérification

Expérience Utilisateur

Communiquez clairement : Informez les clients des changements de facturation et de leur calendrier
Fournissez des confirmations : Envoyez des confirmations par email pour les changements de plan réussis
Gérez les cas particuliers : Considérez les périodes d’essai, les proratisations et les paiements échoués
Mettez à jour l’interface utilisateur immédiatement : Réflétez les changements de plan dans l’interface de votre application

Problèmes Courants et Solutions

Résolvez les problèmes typiques rencontrés lors des changements de plan d’abonnement :

Charge created but subscription not updated

Symptômes : L’appel API réussit, mais l’abonnement reste sur l’ancien planCauses courantes :

Le traitement des webhooks a échoué ou a été retardé
L’état de l’application n’a pas été mis à jour après la réception des webhooks
Problèmes de transaction de base de données lors de la mise à jour de l’état

Solutions :

Implémentez une gestion robuste des webhooks avec une logique de reprise
Utilisez des opérations idempotentes pour les mises à jour d’état
Ajoutez une surveillance pour détecter et alerter sur les événements de webhook manqués
Vérifiez que le point de terminaison du webhook est accessible et répond correctement

Credits not applied after downgrade

Symptômes : Le client rétrograde, mais ne voit pas le solde de créditCauses courantes :

Attentes de mode de proratisation : les rétrogradations créditent la différence totale de prix du plan avec difference_immediately, tandis que prorated_immediately crée un crédit proratisé basé sur le temps restant dans le cycle
Les crédits sont spécifiques à un abonnement et ne se transfèrent pas entre abonnements
Solde de crédit non visible dans le tableau de bord client

Solutions :

Utilisez difference_immediately pour les rétrogradations lorsque vous souhaitez des crédits automatiques
Expliquez aux clients que les crédits s’appliquent aux renouvellements futurs du même abonnement
Implémentez un portail client pour montrer les soldes de crédit
Vérifiez l’aperçu de la prochaine facture pour voir les crédits appliqués

Webhook signature verification fails

Symptômes : Événements de webhook rejetés en raison d’une signature invalideCauses courantes :

Clé secrète de webhook incorrecte
Corps de requête brute modifié avant la vérification de la signature
Mauvais algorithme de vérification de la signature

Solutions :

Vérifiez que vous utilisez le bon DODO_WEBHOOK_SECRET depuis le tableau de bord
Lire le corps de la requête brute avant tout middleware de parsing JSON
Utilisez la bibliothèque standard de vérification de signature de webhook pour votre plateforme
Testez la vérification des signatures de webhook dans l’environnement de développement

Plan change fails with 422 error

Symptômes : L’API renvoie une erreur 422 Unprocessable EntityCauses courantes :

ID d’abonnement ou ID de produit invalide
Abonnement non en état actif
Paramètres requis manquants
Produit non disponible pour les changements de plan

Solutions :

Vérifiez que l’abonnement existe et est actif
Assurez-vous que l’ID du produit est valide et disponible
Assurez-vous que tous les paramètres requis sont fournis
Consultez la documentation de l’API pour les exigences en matière de paramètres

Immediate charge fails during plan change

Symptômes : Le changement de plan est initié, mais le prélèvement immédiat échoueCauses courantes :

Fonds insuffisants sur le moyen de paiement du client
Moyen de paiement expiré ou invalide
La banque a refusé la transaction
La détection de fraude a bloqué le prélèvement

Solutions :

Gérez correctement les événements de webhook payment.failed
Notifiez le client pour mettre à jour son moyen de paiement
Implémentez une logique de reprise pour les échecs temporaires
Envisagez de permettre des changements de plan avec des prélèvements immédiats échoués

Subscription on hold after plan change

Symptômes : Échec du prélèvement de changement de plan et l’abonnement passe en état on_holdQue se passe-t-il : Lorsque le prélèvement de changement de plan échoue, l’abonnement est automatiquement placé en état on_hold. L’abonnement ne se renouvellera pas automatiquement tant que le moyen de paiement n’est pas mis à jour.Solution : Mettez à jour le moyen de paiement pour réactiver l’abonnementPour réactiver un abonnement depuis l’état on_hold après un échec de changement de plan :

Mettez à jour le moyen de paiement en utilisant l’API de Mise à Jour de Moyen de Paiement
Création automatique de prélèvement : L’API crée automatiquement un prélèvement pour les montants dus restants
Génération de facture : Une facture est générée pour le prélèvement
Traitement du paiement : Le paiement est traité à l’aide du nouveau moyen de paiement
Réactivation : Après un paiement réussi, l’abonnement est réactivé à l’état active

// Reactivate subscription from on_hold after failed plan change
async function reactivateAfterFailedPlanChange(subscriptionId) {
  // Update payment method - automatically creates charge for remaining dues
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    type: 'new',
    return_url: 'https://example.com/return'
  });
  
  if (response.payment_id) {
    console.log('Charge created for remaining dues:', response.payment_id);
    console.log('Payment link:', response.payment_link);
    
    // Redirect customer to payment_link to complete payment
    // Monitor webhooks for:
    // 1. payment.succeeded - charge succeeded
    // 2. subscription.active - subscription reactivated
  }
  
  return response;
}

// Or use existing payment method if available
async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    type: 'existing',
    payment_method_id: paymentMethodId
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

Événements de webhook à surveiller :

subscription.on_hold: Abonnement mis en attente (reçu lorsque le prélèvement de changement de plan échoue)
payment.succeeded: Paiement des montants dus réussi (après mise à jour du moyen de paiement)
subscription.active: Abonnement réactivé après paiement réussi

Meilleures pratiques :

Notifiez immédiatement les clients lorsqu’un prélèvement de changement de plan échoue
Fournissez des instructions claires sur la façon de mettre à jour leur moyen de paiement
Surveillez les événements des webhooks pour suivre le statut de réactivation
Envisagez d’implémenter une logique de reprise automatique pour les échecs de paiement temporaires

Update Payment Method API Reference

Consultez la documentation API complète pour la mise à jour des moyens de paiement et la réactivation des abonnements.

Test de votre implémentation

Suivez ces étapes pour tester rigoureusement l’implémentation de votre changement de plan d’abonnement :

Set up test environment

Utilisez des clés API de test et des produits de test
Créez des abonnements de test avec différents types de plan
Configurez le point de terminaison de webhook de test
Configurez la surveillance et l’enregistrement

Test different proration modes

Testez prorated_immediately avec diverses positions de cycle de facturation
Testez difference_immediately pour les mises à niveau et les rétrogradations
Testez full_immediately pour réinitialiser les cycles de facturation
Testez do_not_bill pour des changements de plan sans frais/ni crédit
Vérifiez que les calculs de crédit sont corrects

Test webhook handling

Vérifiez que tous les événements de webhook pertinents sont reçus
Testez la vérification des signatures de webhook
Gérez avec soin les événements de webhook en double
Testez les scénarios d’échec de traitement de webhook

Test error scenarios

Testez avec des ID d’abonnement invalides
Testez avec des moyens de paiement expirés
Testez les échecs de réseau et les délais d’attente
Testez avec des fonds insuffisants

Monitor in production

Configurez des alertes pour les changements de plan échoués
Surveillez les temps de traitement des webhooks
Suivez les taux de réussite des changements de plan
Passez en revue les tickets de support client pour les problèmes de changement de plan

Gestion des Erreurs

Gérez avec soin les erreurs communes de l’API dans votre implémentation :

Codes d’État HTTP

200 OK

Requête de changement de plan traitée avec succès. L’abonnement est en cours de mise à jour et le traitement du paiement a commencé.

400 Bad Request

Paramètres de requête invalides. Vérifiez que tous les champs requis sont fournis et formatés correctement.

401 Unauthorized

Clé API invalide ou manquante. Vérifiez que votre DODO_PAYMENTS_API_KEY est correct et dispose des autorisations appropriées.

404 Not Found

ID d’abonnement introuvable ou n’appartient pas à votre compte.

422 Unprocessable Entity

L’abonnement ne peut pas être modifié (par exemple, déjà annulé, produit non disponible, etc.).

500 Internal Server Error

Une erreur de serveur s’est produite. Réessayez la requête après un bref délai.

Format de Réponse d’Erreur

{
  "error": {
    "code": "subscription_not_found",
    "message": "The subscription with ID 'sub_123' was not found",
    "details": {
      "subscription_id": "sub_123"
    }
  }
}

Prochaines étapes

Consultez l’API de Changement de Plan
Explorez la Facturation Basée sur le Crédit
Implémentez des alertes pour subscription.on_hold
Consultez notre Guide d’Intégration de Webhooks

Change Plan API

Plan Change Preview

Integration Guide

​What is a subscription upgrade or downgrade?

​When to use plan changes

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Prévisualisation des changements de plan

​API de Changement de Plan

​Exemples de démarrage rapide

​Gestion des Modules Complémentaires

​Application de Codes Promo

​Comportement des remises lors du changement de plan

​Modes de Proratisation

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Scénarios d’exemple

​Comment chaque mode traite la facturation

​Gestion des Échecs de Paiement

​Modes d’Échec de Paiement

​Quand Utiliser Chaque Mode

​Gestion des Webhooks

​Types d’Événements à Gérer

​Vérification des Signatures et Gestion des Intentions

​Meilleures Pratiques

​Stratégie de Changement de Plan

​Implémentation des Webhooks

​Expérience Utilisateur

​Problèmes Courants et Solutions

Update Payment Method API Reference

​Test de votre implémentation

​Gestion des Erreurs

​Codes d’État HTTP

​Format de Réponse d’Erreur

​Prochaines étapes

What is a subscription upgrade or downgrade?

When to use plan changes

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Prévisualisation des changements de plan

API de Changement de Plan

Exemples de démarrage rapide

Gestion des Modules Complémentaires

Application de Codes Promo

Comportement des remises lors du changement de plan

Modes de Proratisation

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Scénarios d’exemple

Comment chaque mode traite la facturation

Gestion des Échecs de Paiement

Modes d’Échec de Paiement

Quand Utiliser Chaque Mode

Gestion des Webhooks

Types d’Événements à Gérer

Vérification des Signatures et Gestion des Intentions

Meilleures Pratiques

Stratégie de Changement de Plan

Implémentation des Webhooks

Expérience Utilisateur

Problèmes Courants et Solutions

Test de votre implémentation

Gestion des Erreurs

Codes d’État HTTP

Format de Réponse d’Erreur

Prochaines étapes