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?

Change a customer’s subscription plan to move them between tiers, adjust quantity for seat-based products, or migrate to a new product. The API automatically calculates prorations and charges based on your chosen billing mode.

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 the 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 that want to credit unused time on the old plan.

Credits the unused portion of the current cycle, prorated by time remaining
Then charges a full cycle at the new plan — the new plan price is never prorated
Net charge = full new cycle − (remaining fraction × full old cycle)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

requis

The ID of the active subscription to modify.

string

requis

Nouvel identifiant produit vers lequel modifier l’abonnement.

integer

requis

Nombre d’unités pour le nouveau plan (pour les produits basés sur les sièges).

string

requis

Comment gérer la facturation immédiate : prorated_immediately, full_immediately, difference_immediately ou do_not_bill.

array

Modules complémentaires facultatifs pour le nouveau plan. Omettre ce champ, envoyer null ou envoyer un tableau vide supprime tous les modules complémentaires existants. Incluez donc les modules complémentaires actuels pour les conserver.

string

Contrôle le comportement lorsque le paiement du changement de plan échoue :

prevent_change : conserver l’abonnement sur le plan actuel jusqu’à la réussite du paiement
apply_change (par défaut) : appliquer immédiatement le changement de plan quel que soit le résultat du paiement

If not specified, uses the business-level default setting.

boolean

Collecte le montant du changement de plan avec un lien de paiement au lieu de débiter le moyen de paiement enregistré de l’abonnement. Le client paie sur une page de checkout hébergée.Requires the business’s allow_plan_change_via_payment_link capability (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately, and on_payment_failure: prevent_change. See Collecting Payment via a Checkout Link. Ignored by the preview route.

string

URL vers laquelle le client est redirigé après avoir payé le lien de paiement. La redirection ajoute subscription_id, payment_id et status. Nécessite collect_via_payment_link: true ; sinon la requête échoue avec 422. Consultez Rediriger le client après le paiement.

boolean

défaut:"false"

Annule le lien de paiement impayé d’un changement de plan en attente afin que cette requête le remplace. Un paiement déjà effectué ou en cours renvoie 409. Consultez Remplacer un lien de paiement en attente. Ignoré par la route de prévisualisation.

array

Codes de réduction empilés facultatifs à appliquer au nouveau plan (20 maximum, appliqués dans l’ordre du tableau). Le comportement dépend de la valeur fournie :

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

string

obsolète

Obsolète — préférez discount_codes pour les nouvelles intégrations. Ce champ reste fonctionnel pour assurer la rétrocompatibilité, mais ne peut pas être combiné avec discount_codes dans la même requête.

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 cette option pour les déclassements 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 modifié (montée en gamme/descente en gamme/mise à jour d’un addon)
subscription.on_hold : débit du changement de plan échoué, renouvellements arrêtés
payment.succeeded : débit immédiat du changement de plan réussi
payment.failed : débit immédiat échoué

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

Update Your Application State

En fonction des événements webhook, mettez à jour votre application :

Accordez ou révoquez les fonctionnalités selon le nouveau plan
Mettez à jour le tableau de bord du client avec les détails du nouveau plan
Envoyez des e-mails de confirmation concernant les changements de plan
Consignez les changements de facturation à des fins d’audit

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 réussite des changements de plan
Configurez des alertes pour les changements de plan échoués

Votre implémentation du changement de plan d’abonnement est désormais prête pour la production.

Prévisualiser les changements de plan

Avant de valider un changement de plan, utilisez la Preview API pour montrer aux clients exactement le montant qui leur sera facturé :

Node.js SDK
Python SDK

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

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

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

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

Utilisez la Preview API pour créer des boîtes de dialogue de confirmation indiquant aux clients le montant exact qui leur sera facturé avant qu’ils ne confirment un changement de plan.

Dans immediate_charge.summary, customer_credits correspond à la variation nette du solde de crédits du client, dans la devise indiquée par customer_credits_currency. Il s’agit de la devise du portefeuille de crédits du client, qui est la devise de l’abonnement. Elle peut différer de currency dans le récapitulatif, qui s’applique à total_amount et tax. Par exemple, un client payant en INR pour un abonnement en USD voit ses crédits en USD.

Change Plan API

Utilisez la Change Plan API pour modifier le produit, la quantité et le comportement de la proratisation d’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() {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on) — all null for an ordinary off-session change.
  await client.subscriptions.changePlan('sub_123', {
    product_id: 'pdt_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log('Plan change accepted; awaiting webhooks');
}

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"
)

# change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
# client_secret, expires_on) — all None for an ordinary off-session change.
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print("Plan change accepted; awaiting webhooks")

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"))
  // ChangePlan returns a SubscriptionChangePlanResponse alongside the error.
  _, err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("pdt_new"),
      Quantity:             dodopayments.F(int64(3)),
      ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
      OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
    },
  })
  if err != nil { panic(err) }
  fmt.Println("Plan change applied")
}

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": "pdt_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

Un changement de plan réussi renvoie immédiatement 200 OK — avant le règlement effectif d’un quelconque débit. Le contenu du corps (ChangePlanResponse) dépend de la manière dont le changement a été collecté :

Cas	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Changement programmé (`effective_at: next_billing_date`)	Tous les `null` — rien n’est encore facturé
`proration_billing_mode: do_not_bill`	Tous les `null` — aucun montant à facturer
Débit immédiat ordinaire (moyen de paiement enregistré)	Tous les `null`
`collect_via_payment_link: true` (lien émis)	Tous renseignés — références de checkout pour le client

Cette réponse confirme que la requête a été acceptée, et non qu’un débit a réussi. Pour un débit immédiat ordinaire, le résultat est résolu hors session juste après l’appel. Pour une requête collect_via_payment_link, l’abonnement reste sur son plan actuel jusqu’à ce que le client effectue le paiement.Confirmez le résultat via webhook (payment.succeeded, payment.failed, subscription.plan_changed) ou relisez l’abonnement avec GET /subscriptions/{subscription_id} — consultez Ce qui se passe tant que le lien est impayé pour le cas du lien de paiement.

Si le débit immédiat échoue, l’abonnement peut passer à subscription.on_hold jusqu’à la réussite du paiement.

Collecter un paiement via un lien de checkout

Par défaut, un changement de plan immédiat débite directement le moyen de paiement enregistré de l’abonnement. Définissez collect_via_payment_link: true pour rediriger le client vers une page de checkout hébergée — utile lorsqu’aucun moyen de paiement n’est enregistré ou lorsque vous souhaitez que le client confirme activement le nouveau prix.

Cela active l’option Collect Plan Change Payments by Payment Link dans Settings → Subscriptions, qui fait passer le parcours de changement de plan du Customer Portal par le checkout.

Conditions requises

collect_via_payment_link: true ne réussit que si toutes les conditions suivantes sont remplies — sinon la requête échoue avec 422 :

La capacité allow_plan_change_via_payment_link est activée pour l’entreprise (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at est immediately (valeur par défaut). Un changement programmé (next_billing_date) ne nécessite jamais de page de checkout.
La requête définit on_payment_failure: prevent_change. Une valeur apply_change explicite échoue avec 422.

collect_via_payment_link s’applique à tout changement immédiat entraînant un débit, y compris les déclassements, tant que les conditions ci-dessus sont remplies.

Si le changement aboutit à un montant nul ou à un crédit, aucun lien de paiement n’est émis : payment_link et les autres champs de checkout reviennent null, et le changement s’applique immédiatement. Il ne s’agit pas d’une 422. Appelez d’abord Preview Plan Change pour vérifier le montant avant de demander un lien.

Node.js SDK
Python SDK
HTTP

const response = await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'immediately',
  on_payment_failure: 'prevent_change',
  collect_via_payment_link: true,
});

// Hand response.payment_link to your frontend and send the customer there
console.log(response.payment_link);

response = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    effective_at="immediately",
    on_payment_failure="prevent_change",
    collect_via_payment_link=True,
)

# Hand response.payment_link to your frontend and send the customer there
print(response.payment_link)

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": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "effective_at": "immediately",
    "on_payment_failure": "prevent_change",
    "collect_via_payment_link": true
  }'

Une requête réussie renvoie les références de checkout :

{
  "payment_id": "<payment_id>",
  "payment_link": "https://checkout.dodopayments.com/...",
  "client_secret": "<client_secret>",
  "expires_on": "<expires_on>"
}

Ce qui se passe tant que le lien est impayé

L’abonnement reste sur son plan actuel — product_id, recurring_pre_tax_amount et next_billing_date restent tous inchangés jusqu’au paiement du lien.
Toute nouvelle requête change-plan est rejetée avec 409 PendingPlanChangeExists tant que le lien est en attente. Pour remplacer le changement en attente, envoyez la nouvelle requête avec cancel_older_payment_link: true. Consultez Remplacer un lien de paiement en attente.
Pour réessayer après un paiement refusé, appelez à nouveau change-plan afin d’obtenir un nouveau lien.
Si le lien n’est jamais payé, il cesse de fonctionner après expires_on — l’abonnement redevient automatiquement disponible pour accepter une nouvelle requête de changement de plan peu après.
Si un changement programmé existait déjà et que vous le remplacez par cancel_scheduled_change_plan: true, la programmation d’origine reste en place tant que le lien est impayé et n’est annulée qu’une fois le lien payé — dans la même transaction que celle qui applique le nouveau plan.

Une fois qu’un changement immédiat via lien de paiement est émis, toute nouvelle requête de changement de plan concernant cet abonnement — y compris la prévisualisation sans effet de bord — est bloquée jusqu’à la résolution du lien. Une requête change-plan peut remplacer le lien en définissant cancel_older_payment_link: true. La prévisualisation ignore ce champ ; elle reste donc bloquée.

Rediriger le client après le paiement

Définissez return_url pour renvoyer le client vers votre site après le paiement du lien :

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "return_url": "https://example.com/billing/done"
}

Après le checkout, le client est redirigé vers return_url avec les paramètres de requête suivants :

Paramètre	Valeur
`subscription_id`	Abonnement concerné par le changement de plan.
`payment_id`	Paiement du changement de plan.
`status`	État du paiement du changement de plan, et non de l’abonnement : `active` une fois payé, `failed` en cas de refus, `pending` pendant le traitement.

Lorsque le paiement échoue, l’abonnement reste actif sur son plan actuel. Le nouveau plan peut être appliqué peu après la redirection, à l’arrivée du webhook de paiement ; relisez donc l’abonnement avant d’afficher le nouveau plan. return_url nécessite collect_via_payment_link: true. Sans celui-ci, la requête échoue avec 422.

Remplacer un lien de paiement en attente

Si le client quitte le checkout sans payer, définissez cancel_older_payment_link: true dans la requête change-plan suivante. Dodo Payments annule le lien impayé et le nouveau changement de plan remplace celui en attente. Le lien annulé n’accepte plus de paiement, même dans une page de checkout déjà ouverte.

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "cancel_older_payment_link": true
}

La requête est validée avant l’annulation du lien ; une requête non valide conserve donc le lien du client. Le lien n’est annulé que si le client n’a pas commencé à payer :

Paiement précédent	Réponse
Non ouvert, ouvert mais non payé, ou refusé	`200` avec le nouveau lien.
Le client paie actuellement, par exemple lors de 3D Secure	`409` `PLAN_CHANGE_PAYMENT_IN_PROGRESS`. Réessayez une fois le paiement terminé ou échoué.
Déjà payé	`409` `PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED`. Ne réessayez pas : le changement de plan précédent s’applique.
Le lien n’a pas pu être annulé	`503` `PLAN_CHANGE_LINK_CANCEL_FAILED`. Rien n’a changé ; vous pouvez réessayer.

Chaque requête change-plan émet sa propre facture. Le changement de plan remplacé et sa facture sont annulés. Si aucun changement de plan n’est en attente, cancel_older_payment_link n’a aucun effet.

Une vérification exécutée après la validation, comme le montant minimal du débit, peut néanmoins échouer après l’annulation du lien. L’abonnement reste alors sur son plan actuel, sans lien ouvert. Renvoyez la requête pour émettre un nouveau lien.

Gérer les addons

Lors de la modification des plans d’abonnement, vous pouvez également modifier les addons :

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

Les addons sont inclus dans le calcul de la proratisation et seront facturés selon le mode de proratisation sélectionné.

Appliquer des codes de réduction

Appliquez un ou plusieurs codes de réduction empilés lors de la modification des plans d’abonnement (20 maximum, appliqués dans l’ordre du tableau) :

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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="pdt_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": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

Comportement des réductions lors d’un changement de plan

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

Le champ singulier discount_code de cet endpoint est obsolète, mais reste fonctionnel pour assurer la rétrocompatibilité — les intégrations existantes n’ont pas besoin d’être modifiées immédiatement. Il ne peut pas être combiné avec discount_codes dans la même requête. Migrez vers le format tableau lorsque cela vous convient.

Utilisez la Preview Plan Change API avec discount_codes pour montrer aux clients exactement combien ils économiseront avant de confirmer le changement de plan.

Modes de proratisation

Choisissez comment facturer le client lors d’un changement de plan :

`prorated_immediately`

Crédite la portion inutilisée du cycle actuel — plan de base, quantité et addons — au prorata du temps restant
Puis facture un cycle complet avec le nouveau plan, la nouvelle quantité et les nouveaux addons. Le débit lui-même n’est jamais proratisé
Débit immédiat net = (nouveau cycle complet) − (fraction restante × ancien cycle complet)
Si le crédit dépasse le montant du nouveau cycle (cas fréquent lors des déclassements), la différence est conservée comme crédit associé à l’abonnement pour les renouvellements futurs
En période d’essai, facture immédiatement et bascule dès maintenant vers le nouveau plan

`full_immediately`

Facture immédiatement le montant total du nouveau plan
Ignore le temps restant de l’ancien plan — aucun crédit pour le cycle actuel

Les crédits créés par prorated_immediately et par les déclassements utilisant difference_immediately sont associés à l’abonnement et distincts des avantages de Credit-Based Billing. Ils s’appliquent automatiquement aux renouvellements futurs du même abonnement et ne sont pas transférables entre abonnements.

`difference_immediately`

Montée en gamme : facture immédiatement la différence de prix entre les anciens et les nouveaux plans
Descente en gamme : ajoute la valeur restante comme crédit interne à l’abonnement et l’applique automatiquement aux renouvellements

`do_not_bill`

Aucun débit ni 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 commerciales, les changements vers un plan gratuit ou l’absorption des différences de coût

Fonctionnalité	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Débit lors d’une montée en gamme	Nouveau cycle complet, moins le crédit du temps inutilisé	Différence de prix complète entre les plans	Prix total du nouveau plan	Aucun débit
Crédit lors d’une descente en gamme	Crédit du temps inutilisé, moins un nouveau cycle complet	Différence de prix complète sous forme de crédit	Aucun crédit	Aucun crédit
Cycle de facturation	Réinitialisé à aujourd’hui	Réinitialisé à aujourd’hui	Réinitialisé à aujourd’hui	Inchangé
Comportement pendant l’essai	Met fin à l’essai et facture immédiatement	Met fin à l’essai et facture immédiatement	Met fin à l’essai et facture le montant total	Conserve la date de fin de l’essai, aucun débit
Idéal pour	Créditer le temps inutilisé	Calculs simples de montée/descente en gamme	Réinitialiser les cycles de facturation	Migrations gratuites ou changements commerciaux
Complexité	Moyenne (calcul en jours)	Faible (soustraction simple)	Faible (débit total)	Aucune

Exemples de scénarios

Utilisez systématiquement ces valeurs de référence :

Plan actuel : Basic à $30/mois
Cible de montée en gamme : Pro à $80/mois
Cible de descente en gamme (depuis Pro) : Starter à $20/mois
Cycle de facturation : 30 jours, commencé le 1er janvier
Le changement de plan intervient le 16 janvier (15 jours restants, 15 jours utilisés)

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

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $80.00 (never prorated)

Step 3: Calculate immediate charge
  Charge = Full new cycle − Credit
  Charge = $80.00 − $15.00 = $65.00

→ Customer pays $65.00 now
→ Customer starts a full month of Pro today
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

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

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

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $20.00 (never prorated)

Step 3: Net the two
  Net = $20.00 − $40.00 = −$20.00

→ No charge — $20.00 credit added to subscription
→ Billing cycle resets to today (January 16)
→ Credit auto-applies to future renewals
→ Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 (credit exhausted)
→ Following renewal (Mar 15): $20.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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)
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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: 'pdt_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: 'pdt_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 the unused time on the current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan + add-ons
  New plan = $80.00
  Add-ons  = $30.00
  Total new = $110.00 (never prorated)

Step 3: Immediate charge
  Charge = $110.00 − $15.00 = $95.00

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

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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 créditer le temps inutilisé de l’ancien plan tout en facturant un cycle complet du nouveau ; choisissez full_immediately pour redémarrer la facturation ; utilisez difference_immediately pour les montées en gamme simples et le crédit automatique lors des déclassements ; ou utilisez do_not_bill pour changer de plan sans aucun ajustement de facturation.

Gérer les échecs de paiement

Contrôlez ce qui se passe lorsqu’un paiement de changement de plan échoue à l’aide du paramètre on_payment_failure.

Modes d’échec de paiement

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Comportement : conserver l’abonnement sur son plan actuel jusqu’à la réussite du paiement.

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 la réussite du paiement
Utile lorsque vous souhaitez vous assurer du paiement avant d’accorder les fonctionnalités améliorées

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

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

Le changement de plan est appliqué même si le paiement échoue
Le client obtient immédiatement l’accès au nouveau plan
L’abonnement peut passer à l’état on_hold si le paiement échoue
Convient aux montées en gamme non critiques ou lorsque vous faites confiance au client

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

Si elle n’est pas spécifiée, le paramètre on_payment_failure utilise le paramètre par défaut défini au niveau de votre entreprise dans le tableau de bord.

Quand utiliser chaque mode

Scénario	Mode recommandé	Motif
Passage à des fonctionnalités premium	`prevent_change`	Garantir le paiement avant d’accorder l’accès
Augmentation de la quantité (plus de sièges)	`prevent_change`	Éviter toute utilisation sans paiement
Déclassement de plan	`apply_change`	Le client réduit ses dépenses
Clients d’entreprise de confiance	`apply_change`	Risque moindre de non-paiement
Conversion d’un essai en offre payante	`prevent_change`	Moment de paiement critique

Valeurs par défaut de l’entreprise et de la collecte

Définissez le comportement par défaut des montées et descentes en gamme au niveau de l’entreprise, sous Settings → Subscriptions. Ces valeurs par défaut s’appliquent à tous les changements de plan du Customer Portal et peuvent être remplacées pour chaque collection de produits. Des valeurs par défaut distinctes existent pour les montées et les descentes en gamme :

Paramètre	Champ (montée / descente en gamme)	Valeur par défaut (montée)	Valeur par défaut (descente)
Quand le nouveau plan commence	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
Comment le client est facturé	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Si le paiement du client échoue	`on_payment_failure`	`apply_change`	`apply_change`

Configurez les valeurs par défaut de l’entreprise sous Settings → Subscriptions, et les remplacements de collection sur chaque collection de produits. Chaque champ de collection est indépendant : laissez-le non défini pour hériter de la valeur par défaut de l’entreprise, ou définissez une valeur pour la remplacer.

Ordre de résolution

Pour un changement de plan donné, chaque paramètre est résolu dans l’ordre suivant :

per-request value (Change Plan API) → collection field (if set) → business field → system default

Une valeur transmise explicitement à la Change Plan API est toujours prioritaire. Les valeurs par défaut de l’entreprise et de la collection ne prennent effet qu’en l’absence de valeur explicite — ce qui est le cas pour tous les changements de plan initiés depuis le Customer Portal.

Configuration courante : conserver les montées en gamme sur immediately + difference_immediately afin que les clients paient la différence et obtiennent immédiatement l’accès, et conserver les déclassements sur next_billing_date afin que les clients gardent leur plan actuel jusqu’à la fin du cycle.

Gérer les 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é (montée/descente en gamme, modifications des addons)
subscription.on_hold : débit échoué, renouvellements arrêtés
subscription.renewed : renouvellement réussi
payment.succeeded : paiement du changement de plan ou du renouvellement réussi
payment.failed : paiement échoué

Fondez la logique métier sur les événements d’abonnement et utilisez les événements de paiement pour la confirmation et le rapprochement.

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_PAYMENTS_WEBHOOK_KEY;

  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_PAYMENTS_WEBHOOK_KEY;
  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 les schémas détaillés des payloads, consultez les payloads de webhook d’abonnement et les payloads de webhook de paiement.

Bonnes pratiques

Stratégie de changement de plan

Testez rigoureusement : testez toujours les changements de plan en mode test avant la production
Choisissez soigneusement la proratisation : sélectionnez le mode de proratisation adapté à votre modèle économique
Gérez les échecs avec élégance : implémentez une gestion des erreurs et une logique de nouvelle tentative appropriées
Surveillez les taux de réussite : suivez les taux de réussite et d’échec des changements de plan et étudiez 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 correctement les événements webhook en double
Traitez les événements de manière asynchrone : ne bloquez pas les réponses aux webhooks avec des opérations lourdes
Consignez tout : conservez des journaux détaillés à des fins de débogage et d’audit

Expérience utilisateur

Communiquez clairement : informez les clients des changements de facturation et de leur calendrier
Fournissez des confirmations : envoyez des e-mails de confirmation pour les changements de plan réussis
Gérez les cas particuliers : tenez compte des périodes d’essai, des proratisations et des paiements échoués
Mettez immédiatement l’interface à jour : reflétez les changements de plan dans l’interface de votre application

Problèmes courants et solutions

Résolvez les problèmes habituels 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 réception des webhooks
Problèmes de transaction de base de données lors de la mise à jour de l’état

Solutions :

Implémentez la gestion 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 les événements webhook manqués et déclencher des alertes
Vérifiez que l’endpoint webhook est accessible et répond correctement

Credits not applied after downgrade

Symptômes : le client déclasse son plan, mais ne voit pas son solde de créditsCauses courantes :

Attentes liées au mode de proratisation : les déclassements créditent la différence de prix totale entre les plans avec difference_immediately, tandis que prorated_immediately crédite le temps inutilisé de l’ancien cycle puis facture un cycle complet au nouveau plan — un solde de crédits ne subsiste donc que lorsque ce crédit dépasse le prix du nouveau plan
Les crédits sont propres à l’abonnement et ne sont pas transférés entre abonnements
Le solde de crédits n’est pas visible dans le tableau de bord du client

Solutions :

Utilisez difference_immediately pour les déclassements 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 le Customer Portal pour afficher les soldes de crédits
Consultez la prévisualisation de la prochaine facture pour voir les crédits appliqués

Webhook signature verification fails

Symptômes : les événements webhook sont rejetés en raison d’une signature non valideCauses courantes :

Clé secrète webhook incorrecte
Corps brut de la requête modifié avant la vérification de la signature
Algorithme de vérification de signature incorrect

Solutions :

Vérifiez que vous utilisez le bon DODO_PAYMENTS_WEBHOOK_KEY depuis le tableau de bord
Lisez le corps brut de la requête avant tout middleware d’analyse JSON
Utilisez la bibliothèque standard de vérification des webhooks pour votre plateforme
Testez la vérification des signatures 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 produit non valide
Abonnement qui n’est pas à l’état actif
Paramètres obligatoires manquants
Produit non disponible pour les changements de plan

Solutions :

Vérifiez que l’abonnement existe et est actif
Vérifiez que l’ID produit est valide et disponible
Assurez-vous que tous les paramètres obligatoires sont fournis
Consultez la documentation de l’API pour connaître les exigences relatives aux paramètres

Immediate charge fails during plan change

Symptômes : le changement de plan est initié, mais le débit immédiat échoueCauses courantes :

Fonds insuffisants sur le moyen de paiement du client
Moyen de paiement expiré ou non valide
Banque ayant refusé la transaction
Détection de fraude ayant bloqué le débit

Solutions :

Gérez correctement les événements webhook payment.failed
Informez le client qu’il doit mettre à jour son moyen de paiement
Implémentez une logique de nouvelle tentative pour les échecs temporaires
Envisagez d’autoriser les changements de plan lorsque les débits immédiats échouent

Subscription on hold after plan change

Symptômes : le débit du changement de plan échoue et l’abonnement passe à l’état on_holdCe qui se passe : Lorsque le débit d’un changement de plan échoue, l’abonnement passe automatiquement à l’état on_hold. L’abonnement ne sera pas renouvelé automatiquement tant que le moyen de paiement n’aura pas été mis à jour.Solution : mettez à jour le moyen de paiement pour réactiver l’abonnementPour réactiver un abonnement à l’état on_hold après l’échec d’un changement de plan :

Mettez à jour le moyen de paiement à l’aide de la Update Payment Method API
Création automatique du débit : l’API crée automatiquement un débit pour les sommes restantes dues
Génération de la facture : une facture est générée pour le débit
Traitement du paiement : le paiement est traité avec le nouveau moyen de paiement
Réactivation : après la réussite du paiement, 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, {
    payment_method: { 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, {
    payment_method: { type: 'existing', payment_method_id: paymentMethodId }
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

# Reactivate subscription from on_hold after failed plan change
def reactivate_after_failed_plan_change(subscription_id):
    # Update payment method - automatically creates charge for remaining dues
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "new", "return_url": "https://example.com/return"},
    )
    
    if response.payment_id:
        print("Charge created for remaining dues:", response.payment_id)
        print("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
def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "existing", "payment_method_id": payment_method_id},
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

Événements webhook à surveiller :

subscription.on_hold : abonnement mis en attente (reçu lorsque le débit du changement de plan échoue)
payment.succeeded : paiement des sommes restantes dûes réussi (après la mise à jour du moyen de paiement)
subscription.active : abonnement réactivé après la réussite du paiement

Bonnes pratiques :

Informez immédiatement les clients lorsqu’un débit de changement de plan échoue
Fournissez des instructions claires pour mettre à jour leur moyen de paiement
Surveillez les événements webhook pour suivre l’état de la 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

Testez rigoureusement votre implémentation des changements 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 plans
Configurez un endpoint webhook de test
Configurez la surveillance et la journalisation

Test different proration modes

Testez prorated_immediately avec différentes positions dans le cycle de facturation
Testez difference_immediately pour les montées et descentes en gamme
Testez full_immediately pour réinitialiser les cycles de facturation
Testez do_not_bill pour les changements de plan sans débit ni crédit
Vérifiez que les calculs de crédits sont corrects

Test webhook handling

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

Test error scenarios

Testez avec des ID d’abonnement non valides
Testez avec des moyens de paiement expirés
Testez les échecs 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
Examinez les tickets du support client concernant les problèmes de changement de plan

Gestion des erreurs

Gérez correctement les erreurs API courantes dans votre implémentation :

Codes d’état HTTP

200 OK

Requête de changement de plan traitée avec succès. Le corps de la réponse est un ChangePlanResponse avec payment_id, payment_link, client_secret et expires_on. Les quatre valeurs peuvent être nulles ; le corps est donc sérialisé comme {} pour un changement ordinaire hors session. Elles sont renseignées pour une requête collect_via_payment_link réussie, qui renvoie les références de checkout — consultez Collecter un paiement via un lien de checkout. Si on_payment_failure=prevent_change, le changement de plan reste en attente jusqu’à la réussite du paiement.

400 Bad Request

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

401 Unauthorized

Clé API non valide ou manquante. Vérifiez que votre DODO_PAYMENTS_API_KEY est correcte et dispose des autorisations nécessaires.

409 Conflict

Un changement de plan en attente existe déjà pour cet abonnement (PendingPlanChangeExists). Pour un changement programmé, annulez-le avec DELETE /subscriptions/{subscription_id}/change-plan/scheduled avant d’en envoyer un nouveau. Pour un changement via lien de paiement en attente, envoyez la nouvelle requête avec cancel_older_payment_link: true pour le remplacer. Consultez Remplacer un lien de paiement en attente.Avec cancel_older_payment_link: true, une 409 signifie que le client paie actuellement le lien précédent (PLAN_CHANGE_PAYMENT_IN_PROGRESS) ou qu’il l’a déjà payé (PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED).

503 Service Unavailable

Avec cancel_older_payment_link: true, le lien de paiement précédent n’a pas pu être annulé (PLAN_CHANGE_LINK_CANCEL_FAILED). Rien n’a changé ; vous pouvez réessayer la requête.

422 Unprocessable Entity

L’abonnement est inactif ou à la demande, ou la requête ne peut pas utiliser collect_via_payment_link — l’entreprise n’a pas activé la capacité, effective_at n’est pas immediately, ou on_payment_failure n’est pas prevent_change. Consultez Conditions requises. Un ID d’abonnement inexistant ou n’appartenant pas à votre compte renvoie 404 avec le code NOT_FOUND.

500 Internal Server Error

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

Format de réponse des erreurs

Les erreurs renvoient un corps JSON avec un code et un message compréhensible par l’utilisateur :

{
  "code": "INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED",
  "message": "Changing plans is not supported for inactive subscriptions"
}

Consultez les codes d’erreur pour obtenir la liste complète.

Étapes suivantes

Consultez la Change Plan API
Découvrez Credit-Based Billing
Implémentez des alertes pour subscription.on_hold
Consultez le guide d’intégration des 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évisualiser les changements de plan

​Change Plan API

​Exemples de démarrage rapide

​Collecter un paiement via un lien de checkout

​Conditions requises

​Ce qui se passe tant que le lien est impayé

​Rediriger le client après le paiement

​Remplacer un lien de paiement en attente

​Gérer les addons

​Appliquer des codes de réduction

​Comportement des réductions lors d’un changement de plan

​Modes de proratisation

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Exemples de scénarios

​Comment chaque mode traite la facturation

​Gérer les échecs de paiement

​Modes d’échec de paiement

​Quand utiliser chaque mode

​Valeurs par défaut de l’entreprise et de la collecte

​Ordre de résolution

​Gérer les webhooks

​Types d’événements à gérer

​Vérifier les signatures et gérer les intentions

​Bonnes pratiques

​Stratégie de changement de plan

​Implémentation des webhooks

​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 des erreurs

​Étapes suivantes

What Is a Subscription Upgrade or Downgrade?

When to Use Plan Changes

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Prévisualiser les changements de plan

Change Plan API

Exemples de démarrage rapide

Collecter un paiement via un lien de checkout

Conditions requises

Ce qui se passe tant que le lien est impayé

Rediriger le client après le paiement

Remplacer un lien de paiement en attente

Gérer les addons

Appliquer des codes de réduction

Comportement des réductions lors d’un changement de plan

Modes de proratisation

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Exemples de scénarios

Comment chaque mode traite la facturation

Gérer les échecs de paiement

Modes d’échec de paiement

Quand utiliser chaque mode

Valeurs par défaut de l’entreprise et de la collecte

Ordre de résolution

Gérer les webhooks

Types d’événements à gérer

Vérifier les signatures et gérer les intentions

Bonnes pratiques

Stratégie de changement de plan

Implémentation des webhooks

Expérience utilisateur

Problèmes courants et solutions

Tester votre implémentation

Gestion des erreurs

Codes d’état HTTP

Format de réponse des erreurs

Étapes suivantes