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_code

string

Code de réduction facultatif à appliquer au nouveau plan. Si fourni, il valide et applique la réduction au changement de plan. Si non fourni et que l’abonnement a déjà une réduction avec preserve_on_plan_change=true, la réduction existante sera conservée (si applicable au nouveau produit).

effective_at

string

défaut:"immediately"

Quand appliquer le changement de plan :

immediately (par défaut) : Appliquer le changement de plan immédiatement
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 conservent 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 add-ons)
subscription.on_hold : Échec du prélèvement pour changement de plan, abonnement 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

Basé sur les événements de webhook, mettez à jour votre application :

Accorder/révoquer des fonctionnalités en fonction du nouveau plan
Mettre à jour le tableau de bord client avec les détails du nouveau plan
Envoyer des e-mails de confirmation concernant les changements de plan
Enregistrer les changements de facturation pour des raisons d’audit

Test and Monitor

Testez rigoureusement votre implémentation :

Testez tous les modes de calcul des prorata 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 changements de plan échoués

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

Aperçu des changements de plan

Avant de s’engager dans un changement de plan, utilisez l’API Aperçu pour montrer aux clients exactement ce qui leur sera facturé :

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 Prévisualisation pour créer des boîtes de dialogue de confirmation qui montrent aux clients le montant exact qu’ils seront débités avant de confirmer un changement de plan.

API de changement de plan

Utilisez l’API Changer de plan pour modifier le produit, la quantité et le comportement des prorata 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’une facturation immédiate et/ou une facture est créée lors du changement de plan. Appuyez-vous toujours sur les événements de webhook (par exemple, payment.succeeded, subscription.plan_changed) pour confirmer les résultats.

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

Gestion des addons

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

// 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 addons sont inclus dans le calcul du prorata et seront facturés selon le mode de prorata sélectionné.

Application de codes de réduction

Vous pouvez appliquer un code de réduction lors du changement de plans d’abonnement. Cela est utile pour offrir des tarifs promotionnels sur les mises à niveau ou les migrations.

Node.js SDK
Python SDK
HTTP

// Apply a discount code during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_code: 'UPGRADE20'
});

# Apply a discount code during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_code="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_code": "UPGRADE20"
  }'

Comportement de la réduction lors du changement de plan

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

Utilisez l’API de Prévisualisation des changements de plan avec un discount_code pour montrer aux clients exactement combien ils économiseront avant de confirmer le changement de plan.

Modes de calcul des prorata

Choisissez comment facturer le client lors du changement de plan :

`prorated_immediately`

Facturation de la différence partielle dans le cycle actuel
Si en période d’essai, facturation immédiate et passage au nouveau plan maintenant
Rétrogradation : peut générer un crédit proratisé appliqué aux futurs renouvellements

`full_immediately`

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

Les crédits créés par les rétrogradations utilisant difference_immediately sont limités à l’abonnement et distincts des droits de facturation basée sur le crédit. Ils s’appliquent automatiquement aux futurs renouvellements du même abonnement et ne sont pas transférables entre abonnements.

`difference_immediately`

Mise à niveau : facturer immédiatement la différence entre les anciens et nouveaux plans
Rétrogradation : ajouter la valeur restante en tant que crédit interne à l’abonnement et l’appliquer automatiquement lors des renouvellements

`do_not_bill`

Aucune facturation ou crédit n’est calculé
Le client passe immédiatement au nouveau plan sans aucun 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 du nouveau plan en intégralité	Aucun frais
Crédit de rétrogradation	Crédit proratisé pour les jours restants	Différence de prix totale en tant que crédit	Aucun crédit	Aucun crédit
Cycle de facturation	Inchange	Inchange	Réinitialisé à aujourd’hui	Inchange
Comportement d’essai	Fin de l’essai, facturation immédiate	Fin de l’essai, facturation immédiate	Fin de l’essai, facturation totale	Fin de l’essai, pas de 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 des jours)	Basse (soustraction simple)	Basse (plein montant)	Aucune

Scénarios d’exemple

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

Plan actuel : Basic à 30 $/mois
Objectif de mise à niveau : Pro à 80 $/mois
Objectif de rétrogradation (de Pro) : Starter à 20 $/mois
Cycle de facturation : 30 jours, commencé le 1er janvier
Changement de plan se produit 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 basée sur le temps ; choisissez full_immediately pour redémarrer la facturation ; utilisez difference_immediately pour des mises à niveau simples et des crédits automatiques lors des 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 : Maintenir l’abonnement sur son plan actuel jusqu’à ce que le paiement réussisse.

Le changement de plan est marqué comme “en attente”
Le client conserve l’accès à son plan actuel
L’abonnement passe à l’état active uniquement après un paiement réussi
Utile lorsque vous souhaitez garantir le paiement avant de débloquer 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 passer à on_hold si le paiement échoue
Bon pour les améliorations 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 commercial configuré dans le tableau de bord.

Quand utiliser chaque mode

Scénario	Mode recommandé	Raison
Mise à niveau vers des fonctionnalités premium	`prevent_change`	Assurer le paiement avant de donner accès
Augmentation de quantité (plus de sièges)	`prevent_change`	Prévenir l’utilisation sans paiement
Rétrogradation des plans	`apply_change`	Le client réduit sa dépense
Clients d’entreprise de confiance	`apply_change`	Risque faible de non-paiement
Conversion de l’essai vers payant	`prevent_change`	Moment critique du paiement

Gestion des webhooks

Suivez l’état de l’abonnement 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/modifications des add-ons)
subscription.on_hold : échec de prélèvement, abonnement en pause
subscription.renewed : renouvellement réussi
payment.succeeded : paiement pour changement de plan ou renouvellement réussi
payment.failed : échec du paiement

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

Vérifier les signatures et gérer les 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, voir les Charger des webhooks d’abonnement et Charger des webhooks de paiement.

Meilleures pratiques

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

Stratégie de changement de plan

Testez rigoureusement : Testez toujours les changements de plan en mode test avant la production
Choisissez le prorata avec soin : Sélectionnez le mode de prorata qui correspond à votre modèle économique
Gérez les échecs avec soin : Implémentez une gestion des erreurs appropriée et une logique de nouvelle tentative
Surveillez les taux de succès : Suivez les taux de succès/échec des changements de plan et enquêtez sur les problèmes

Implémentation du webhook

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

Expérience utilisateur

Communiquez clairement : Informez les clients des changements de facturation et du calendrier
Fournissez des confirmations : Envoyez des e-mails de confirmation pour les changements de plan réussis
Gérez les cas particuliers : Considérez les périodes d’essai, les prorata et les paiements échoués
Mettez à jour l’interface utilisateur immédiatement : Reflé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 du webhook 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 nouvelle tentative
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 des créditsCauses courantes :

Attentes de mode de prorata : les rétrogradations créditent la différence de prix totale 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 à l’abonnement et ne se transfèrent pas entre abonnements
Le solde des crédits n’est pas visible dans le tableau de bord du client

Solutions :

Utilisez difference_immediately pour les rétrogradations lorsque vous voulez des crédits automatiques
Expliquez aux clients que les crédits s’appliquent aux futurs renouvellements du même abonnement
Mettez en œuvre un portail client pour afficher les soldes de crédits
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 du webhook incorrecte
Corps de la 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
Lisez le corps de la requête brute avant tout middleware d’analyse JSON
Utilisez la bibliothèque standard de vérification des webhooks pour votre plateforme
Testez la vérification de la signature du webhook dans l’environnement de développement

Plan change fails with 422 error

Symptômes : L’API renvoie une erreur 422 Entité non traitableCauses courantes :

ID d’abonnement ou ID de produit invalide
Abonnement non à l’é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 de 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 : Changement de plan 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
Banque a refusé la transaction
Détection de fraude a bloqué le prélèvement

Solutions :

Gérer correctement les événements de webhook payment.failed
Notifiez le client de mettre à jour le moyen de paiement
Implémentez une logique de nouvelle tentative pour les échecs temporaires
Envisagez d’autoriser les changements de plan avec des prélèvements immédiats échoués

Subscription on hold after plan change

Symptômes : Le prélèvement pour le changement de plan échoue et l’abonnement passe à l’état on_holdCe qui se passe : Lorsqu’un prélèvement de changement de plan échoue, l’abonnement est automatiquement placé à l’é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 à partir de 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 du moyen de paiement
Création automatique de prélèvement : L’API crée automatiquement un prélèvement pour les 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é en utilisant le 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 pour changement de plan échoue)
payment.succeeded : Paiement pour les dus restants réussi (après la mise à jour du moyen de paiement)
subscription.active : Abonnement réactivé après le paiement réussi

Meilleures pratiques :

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

Update Payment Method API Reference

Consultez la documentation complète de l’API pour mettre à jour les moyens de paiement et réactiver les abonnements.

Tester votre implémentation

Suivez ces étapes pour tester rigoureusement votre implémentation de 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 un point de terminaison de webhook de test
Configurez la surveillance et les journaux

Test different proration modes

Testez prorated_immediately avec différentes positions de cycle de facturation
Testez difference_immediately pour les mises à niveau et rétrogradations
Testez full_immediately pour réinitialiser les cycles de facturation
Testez do_not_bill pour des changements de plan sans frais/sans 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 des webhooks
Gérez gracieusement les événements de webhook en double
Testez les scénarios d’échec du traitement des webhooks

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 succès des changements de plan
Examinez les tickets de support client pour les problèmes de changement de plan

Gestion des erreurs

Gérez gracieusement les erreurs courantes de l’API dans votre implémentation :

Codes d’état HTTP

200 OK

Demande 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 demande invalides. Vérifiez que tous les champs requis sont fournis et correctement formatés.

401 Unauthorized

Clé API invalide ou manquante. Vérifiez que votre DODO_PAYMENTS_API_KEY est correcte et a les autorisations appropriées.

404 Not Found

ID d’abonnement introuvable ou n’appartenant 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

Erreur de serveur survenue. Réessayez la demande 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 des Webhooks

Integration Guides

Billing Deconstructions

Cookbooks

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

​Aperçu des changements de plan

​API de changement de plan

​Exemples de démarrage rapide

​Gestion des addons

​Application de codes de réduction

​Comportement de la réduction lors du changement de plan

​Modes de calcul des prorata

​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érifier les signatures et gérer les intentions

​Meilleures pratiques

​Stratégie de changement de plan

​Implémentation du webhook

​Expérience utilisateur

​Problèmes courants et solutions

Update Payment Method API Reference

​Tester 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

Aperçu des changements de plan

API de changement de plan

Exemples de démarrage rapide

Gestion des addons

Application de codes de réduction

Comportement de la réduction lors du changement de plan

Modes de calcul des prorata

`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érifier les signatures et gérer les intentions

Meilleures pratiques

Stratégie de changement de plan

Implémentation du webhook

Expérience utilisateur

Problèmes courants et solutions

Tester votre implémentation

Gestion des erreurs

Codes d’état HTTP

Format de réponse d’erreur

Prochaines étapes