Abonnements - Dodo Payments Documentation

Les abonnements vous permettent de vendre un accès continu avec des renouvellements automatisés. Utilisez des cycles de facturation flexibles, des essais gratuits, des changements de plan et des options supplémentaires pour adapter les prix à chaque client.

Mise à niveau & Rétrogradation

Contrôlez les changements de plan avec prorata et mises à jour de quantité.

Abonnements à la demande

Autorisez un mandat maintenant et facturez plus tard avec des montants personnalisés.

Portail Client

Permettez aux clients de gérer les plans, la facturation et les annulations.

Webhooks d'Abonnement

Réagissez aux événements de cycle de vie tels que créé, renouvelé et annulé.

Qu’est-ce que les Abonnements ?

Les abonnements sont des produits récurrents que les clients achètent selon un calendrier. Ils sont idéaux pour :

Licences SaaS : Applications, API ou accès à des plateformes
Adhésions : Communautés, programmes ou clubs
Contenu numérique : Cours, médias ou contenu premium
Plans de support : SLA, packages de réussite ou maintenance

Avantages Clés

Revenus prévisibles : Facturation récurrente avec renouvellements automatisés
Cycles flexibles : Mensuels, annuels, intervalles personnalisés et essais
Agilité des plans : Prorata pour les mises à niveau et rétrogradations
Options supplémentaires et sièges : Attachez des mises à niveau optionnelles et quantifiables
Paiement sans friction : Paiement hébergé et portail client
Orienté développeur : API claires pour la création, les changements et le suivi d’utilisation

Création d’Abonnements

Créez des produits d’abonnement dans votre tableau de bord Dodo Payments, puis vendez-les via le paiement ou votre API. Séparer les produits des abonnements actifs vous permet de versionner les prix, d’attacher des options supplémentaires et de suivre les performances de manière indépendante.

Création de produit d’abonnement

Configurez les champs dans le tableau de bord pour définir comment votre abonnement se vend, se renouvelle et se facture. Les sections ci-dessous correspondent directement à ce que vous voyez dans le formulaire de création.

Détails du produit

Nom du produit (obligatoire) : Le nom affiché dans le paiement, le portail client et les factures.
Description du produit (obligatoire) : Une déclaration de valeur claire qui apparaît dans le paiement et les factures.
Image du produit (obligatoire) : PNG/JPG/WebP jusqu’à 3 Mo. Utilisé dans le paiement et les factures.
Marque : Associez le produit à une marque spécifique pour le thème et les e-mails.
Catégorie fiscale (obligatoire) : Choisissez la catégorie (par exemple, SaaS) pour déterminer les règles fiscales.

Choisissez la catégorie fiscale la plus précise pour garantir une collecte correcte des taxes par région.

Tarification

Type de tarification : Choisissez Abonnement (ce guide). Les alternatives sont Paiement unique et Facturation basée sur l’utilisation.
Prix (obligatoire) : Prix récurrent de base avec devise.
Remise applicable (%) : Pourcentage de remise optionnel appliqué au prix de base ; reflété dans le paiement et les factures.
Répéter le paiement tous les (obligatoire) : Intervalle pour les renouvellements, par exemple, tous les 1 mois. Sélectionnez la cadence (mois ou années) et la quantité.
Période d’abonnement (obligatoire) : Durée totale pendant laquelle l’abonnement reste actif (par exemple, 10 ans). Après cette période, les renouvellements s’arrêtent à moins d’être prolongés.
Jours de période d’essai (obligatoire) : Définissez la durée de l’essai en jours. Utilisez 0 pour désactiver les essais. Le premier prélèvement se produit automatiquement à la fin de l’essai.
Sélectionner l’option supplémentaire : Attachez jusqu’à 3 options supplémentaires que les clients peuvent acheter avec le plan de base.

Modifier le prix d’un produit actif affecte les nouveaux achats. Les abonnements existants suivent vos paramètres de changement de plan et de prorata.

Les options supplémentaires sont idéales pour des extras quantifiables tels que des sièges ou du stockage. Vous pouvez contrôler les quantités autorisées et le comportement de prorata lorsque les clients les changent.

Paramètres avancés

Tarification incluant les taxes : Affichez les prix incluant les taxes applicables. Le calcul final des taxes varie toujours selon l’emplacement du client.
Générer des clés de licence : Émettez une clé unique à chaque client après achat. Consultez le guide des Clés de licence.
Livraison de produit numérique : Livrez des fichiers ou du contenu automatiquement après achat. En savoir plus dans Livraison de produit numérique.
Métadonnées : Attachez des paires clé-valeur personnalisées pour le marquage interne ou les intégrations client. Consultez Métadonnées.

Utilisez les métadonnées pour stocker des identifiants de votre système (par exemple, accountId) afin de pouvoir réconcilier les événements et les factures plus tard.

Essais d’Abonnement

Les essais permettent aux clients d’accéder aux abonnements sans paiement immédiat. Le premier prélèvement se produit automatiquement à la fin de l’essai.

Configuration des Essais

Définissez Jours de période d’essai dans la section de tarification du produit (utilisez 0 pour désactiver). Vous pouvez remplacer cela lors de la création d’abonnements :

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

La valeur trial_period_days doit être comprise entre 0 et 10 000 jours.

Détection de l’État d’Essai

Actuellement, il n’y a pas de champ direct pour détecter l’état d’essai. Ce qui suit est une solution de contournement qui nécessite de requêter les paiements, ce qui est inefficace. Nous travaillons sur une solution plus efficace.

Pour déterminer si un abonnement est en période d’essai, récupérez la liste des paiements pour l’abonnement. S’il y a exactement un paiement d’un montant de 0, l’abonnement est en période d’essai :

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Mise à Jour de la Période d’Essai

Prolongez l’essai en mettant à jour next_billing_date :

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

Vous ne pouvez pas définir next_billing_date à un moment passé. La date doit être dans le futur.

Changements de Plan d’Abonnement

Les changements de plan vous permettent de mettre à niveau ou de rétrograder des abonnements, d’ajuster les quantités ou de migrer vers différents produits. Chaque changement déclenche un prélèvement immédiat basé sur le mode de prorata que vous sélectionnez.

Modes de Prorata

Choisissez comment les clients sont facturés lors des changements de plan :

`prorated_immediately`

Facture le montant proratisé basé sur le temps restant dans le cycle de facturation actuel. Idéal pour une facturation équitable qui prend en compte le temps inutilisé.

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

`difference_immediately`

Facture immédiatement la différence de prix (mise à niveau) ou ajoute un crédit pour les renouvellements futurs (rétrogradation). Idéal pour des scénarios simples de mise à niveau/rétrogradation.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Les crédits provenant des rétrogradations utilisant difference_immediately sont limités à l’abonnement et s’appliquent automatiquement aux renouvellements futurs. Ils sont distincts des Crédits Client.

`full_immediately`

Facture immédiatement le montant total du nouveau plan, en ignorant le temps restant. Idéal pour réinitialiser les cycles de facturation.

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

Changer de Plans avec Options Supplémentaires

Modifiez les options supplémentaires lors des changements de plan. Les options supplémentaires sont incluses dans les calculs de prorata :

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

Les changements de plan déclenchent des prélèvements immédiats. Les prélèvements échoués peuvent déplacer l’abonnement vers le statut on_hold. Suivez les changements via les événements webhook subscription.plan_changed.

Prévisualiser les Changements de Plan

Avant de vous engager dans un changement de plan, prévisualisez le prélèvement exact et l’abonnement résultant :

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('You will be charged:', preview.immediate_charge.summary);

API de Prévisualisation du Changement de Plan

Prévisualisez les changements de plan avant de vous y engager.

États des Abonnements

Les abonnements peuvent être dans différents états tout au long de leur cycle de vie :

active : L’abonnement est actif et se renouvellera automatiquement
on_hold : L’abonnement est suspendu en raison d’un paiement échoué. Une mise à jour du mode de paiement est requise pour réactiver
cancelled : L’abonnement est annulé et ne se renouvellera pas
expired : L’abonnement a atteint sa date de fin
pending : L’abonnement est en cours de création ou de traitement

État En Attente

Un abonnement entre dans l’état on_hold lorsque :

Un paiement de renouvellement échoue (fonds insuffisants, carte expirée, etc.)
Un prélèvement de changement de plan échoue
L’autorisation du mode de paiement échoue

Lorsque l’abonnement est dans l’état on_hold, il ne se renouvellera pas automatiquement. Vous devez mettre à jour le mode de paiement pour réactiver l’abonnement.

Réactivation depuis l’État En Attente

Pour réactiver un abonnement depuis l’état on_hold, mettez à jour le mode de paiement. Cela crée automatiquement :

Un prélèvement pour les montants dus
Génère une facture
Traite le paiement en utilisant le nouveau mode de paiement
Réactive l’abonnement à l’état active après un paiement réussi

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Après avoir mis à jour avec succès le mode de paiement pour un abonnement on_hold, vous recevrez les événements webhook payment.succeeded suivis de subscription.active.

Gestion de l’API

Créer des abonnements

Utilisez POST /subscriptions pour créer des abonnements de manière programmatique à partir de produits, avec des essais et des options supplémentaires facultatifs.

Référence API

Consultez l’API de création d’abonnement.

Mettre à jour des abonnements

Utilisez PATCH /subscriptions/{id} pour mettre à jour les quantités, annuler à la fin de la période ou modifier les métadonnées.

Référence API

Découvrez comment mettre à jour les détails de l’abonnement.

Changer de plans (prorata)

Changez le produit actif et les quantités avec des contrôles de prorata.

Référence API

Examinez les options de changement de plan.

Frais à la demande

Pour les abonnements à la demande, facturez des montants spécifiques à la demande.

Référence API

Facturez un abonnement à la demande.

Lister et récupérer

Utilisez GET /subscriptions pour lister tous les abonnements et GET /subscriptions/{id} pour en récupérer un.

Référence API

Parcourez les API de listing et de récupération.

Historique d'utilisation

Récupérez l’utilisation enregistrée pour les modèles de tarification mesurés ou hybrides.

Référence API

Consultez l’API d’historique d’utilisation.

Mettre à jour le mode de paiement

Mettez à jour le mode de paiement pour un abonnement. Pour les abonnements actifs, cela met à jour le mode de paiement pour les renouvellements futurs. Pour les abonnements dans l’état on_hold, cela réactive l’abonnement en créant un prélèvement pour les montants dus.

Référence API

Découvrez comment mettre à jour les modes de paiement et réactiver les abonnements.

Cas d’Utilisation Courants

SaaS et API : Accès par niveaux avec options supplémentaires pour sièges ou utilisation
Contenu et médias : Accès mensuel avec essais d’introduction
Plans de support B2B : Contrats annuels avec options de support premium
Outils et plugins : Clés de licence et versions publiées

Exemples d’Intégration

Sessions de Paiement (abonnements)

Lors de la création de sessions de paiement, incluez votre produit d’abonnement et des options supplémentaires facultatives :

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

Changements de plan avec prorata

Mettez à niveau ou rétrogradez un abonnement et contrôlez le comportement de prorata :

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

Annuler à la fin de la période

Planifiez une annulation sans résiliation immédiate de l’accès :

await client.subscriptions.update('sub_123', {
  cancel_at_period_end: true
});

Abonnements à la demande

Créez un abonnement à la demande et facturez plus tard si nécessaire :

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: true
});

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

Mettre à jour le mode de paiement pour un abonnement actif

Mettez à jour le mode de paiement pour un abonnement actif :

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

Réactiver un abonnement depuis l’état en attente

Réactivez un abonnement qui a été mis en attente en raison d’un paiement échoué :

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Abonnements avec Mandats Conformes à la RBI

Les abonnements UPI et par carte indienne fonctionnent sous les réglementations de la RBI (Réserve Bank of India) avec des exigences de mandat spécifiques :

Limites de Mandat

Le type et le montant du mandat dépendent du prélèvement récurrent de votre abonnement :

Prélèvements inférieurs à ₹15,000 : Nous créons un mandat à la demande pour ₹15,000 INR. Le montant de l’abonnement est prélevé périodiquement selon la fréquence de votre abonnement, jusqu’à la limite du mandat.
Prélèvements de ₹15,000 ou plus : Nous créons un mandat d’abonnement (ou mandat à la demande) pour le montant exact de l’abonnement.

Considérations de Mise à Niveau et de Rétrogradation

Important : Lors de la mise à niveau ou de la rétrogradation des abonnements, considérez attentivement les limites de mandat :

Si une mise à niveau/rétrogradation entraîne un montant de prélèvement qui dépasse ₹15,000 et dépasse la limite de paiement à la demande existante, le prélèvement peut échouer.
Dans de tels cas, le client peut avoir besoin de mettre à jour son mode de paiement ou de changer à nouveau l’abonnement pour établir un nouveau mandat avec la limite correcte.

Autorisation pour des Prélèvements de Haute Valeur

Pour les prélèvements d’abonnement de ₹15,000 ou plus :

Le client sera invité par sa banque à autoriser la transaction.
Si le client ne parvient pas à autoriser la transaction, celle-ci échouera et l’abonnement sera mis en attente.

Délai de Traitement de 48 Heures

Chronologie de Traitement : Les prélèvements récurrents sur les cartes indiennes et les abonnements UPI suivent un modèle de traitement unique :

Les prélèvements sont initiés à la date prévue selon la fréquence de votre abonnement.
La décision réelle du compte du client n’a lieu qu’après 48 heures à partir de l’initiation du paiement.
Cette fenêtre de 48 heures peut être prolongée jusqu’à 2-3 heures supplémentaires en fonction des réponses de l’API bancaire.

Fenêtre d’Annulation de Mandat

Pendant la fenêtre de traitement de 48 heures :

Les clients peuvent annuler le mandat via leurs applications bancaires.
Si un client annule le mandat pendant cette période, l’abonnement restera actif (c’est un cas particulier spécifique aux abonnements par carte indienne et UPI AutoPay).
Cependant, la décision réelle peut échouer, et dans ce cas, nous mettrons l’abonnement en attente.

Gestion des Cas Particuliers : Si vous fournissez des avantages, des crédits ou une utilisation d’abonnement aux clients immédiatement après l’initiation du prélèvement, vous devez gérer cette fenêtre de 48 heures de manière appropriée dans votre application. Considérez :

Retarder l’activation des avantages jusqu’à la confirmation du paiement
Mettre en œuvre des périodes de grâce ou un accès temporaire
Surveiller l’état de l’abonnement pour les annulations de mandat
Gérer les états d’attente d’abonnement dans la logique de votre application

Surveillez les webhooks d’abonnement pour suivre les changements d’état de paiement et gérer les cas particuliers où les mandats sont annulés pendant la fenêtre de 48 heures.

Meilleures Pratiques

Commencez avec des niveaux clairs : 2–3 plans avec des différences évidentes
Communiquez les prix : Affichez les totaux, le prorata et le prochain renouvellement
Utilisez les essais de manière réfléchie : Convertissez avec l’intégration, pas seulement le temps
Exploitez les options supplémentaires : Gardez les plans de base simples et vendez des extras
Testez les changements : Validez les changements de plan et le prorata en mode test

Les abonnements sont une base flexible pour des revenus récurrents. Commencez simplement, testez minutieusement et itérez en fonction des métriques d’adoption, de désabonnement et d’expansion.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Mise à niveau & Rétrogradation

Abonnements à la demande

Portail Client

Webhooks d'Abonnement

​Qu’est-ce que les Abonnements ?

​Avantages Clés

​Création d’Abonnements

​Création de produit d’abonnement

​Détails du produit

​Tarification

​Paramètres avancés

​Essais d’Abonnement

​Configuration des Essais

​Détection de l’État d’Essai

​Mise à Jour de la Période d’Essai

​Changements de Plan d’Abonnement

​Modes de Prorata

​prorated_immediately

​difference_immediately

​full_immediately

​Changer de Plans avec Options Supplémentaires

​Prévisualiser les Changements de Plan

API de Prévisualisation du Changement de Plan

​États des Abonnements

​État En Attente

​Réactivation depuis l’État En Attente

​Gestion de l’API

Référence API

Référence API

Référence API

Référence API

Référence API

Référence API

Référence API

​Cas d’Utilisation Courants

​Exemples d’Intégration

​Sessions de Paiement (abonnements)

​Changements de plan avec prorata

​Annuler à la fin de la période

​Abonnements à la demande

​Mettre à jour le mode de paiement pour un abonnement actif

​Réactiver un abonnement depuis l’état en attente

​Abonnements avec Mandats Conformes à la RBI

​Limites de Mandat

​Considérations de Mise à Niveau et de Rétrogradation

​Autorisation pour des Prélèvements de Haute Valeur

​Délai de Traitement de 48 Heures

​Fenêtre d’Annulation de Mandat

​Meilleures Pratiques

Qu’est-ce que les Abonnements ?

Avantages Clés

Création d’Abonnements

Création de produit d’abonnement

Détails du produit

Tarification

Paramètres avancés

Essais d’Abonnement

Configuration des Essais

Détection de l’État d’Essai

Mise à Jour de la Période d’Essai

Changements de Plan d’Abonnement

Modes de Prorata

`prorated_immediately`

`difference_immediately`

`full_immediately`

Changer de Plans avec Options Supplémentaires

Prévisualiser les Changements de Plan

États des Abonnements

État En Attente

Réactivation depuis l’État En Attente

Gestion de l’API

Cas d’Utilisation Courants

Exemples d’Intégration

Sessions de Paiement (abonnements)

Changements de plan avec prorata

Annuler à la fin de la période

Abonnements à la demande

Mettre à jour le mode de paiement pour un abonnement actif

Réactiver un abonnement depuis l’état en attente

Abonnements avec Mandats Conformes à la RBI

Limites de Mandat

Considérations de Mise à Niveau et de Rétrogradation

Autorisation pour des Prélèvements de Haute Valeur

Délai de Traitement de 48 Heures

Fenêtre d’Annulation de Mandat

Meilleures Pratiques