Subscriptions - Dodo Payments Documentation

Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.

Upgrade & Downgrade

Control plan changes with proration and quantity updates.

On‑Demand Subscriptions

Authorize a mandate now and charge later with custom amounts.

Customer Portal

Let customers manage plans, billing, and cancellations.

Subscription Webhooks

React to lifecycle events like created, renewed, and canceled.

What Are Subscriptions?

Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:

SaaS licenses: Apps, APIs, or platform access
Memberships: Communities, programs, or clubs
Digital content: Courses, media, or premium content
Support plans: SLAs, success packages, or maintenance

Key Benefits

Predictable revenue: Recurring billing with automated renewals
Flexible cycles: Monthly, annual, custom intervals, and trials
Plan agility: Proration for upgrades and downgrades
Add‑ons and seats: Attach optional, quantifiable upgrades
Seamless checkout: Hosted checkout and customer portal
Developer-first: Clear APIs for creation, changes, and usage tracking

Creating Subscriptions

Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.

Subscription product creation

Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.

Product details

Product Name (required): The display name shown in checkout, customer portal, and invoices.
Product Description (required): A clear value statement that appears in checkout and invoices.
Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
Brand: Associate the product with a specific brand for theming and emails.
Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.

Pick the most accurate tax category to ensure correct tax collection per region.

Pricing

Type de tarification : Choisissez Subscription (ce guide). Les alternatives sont Single Payment et Usage Based Billing.
Prix (obligatoire) : Prix récurrent de base avec devise. Le prix doit être d’au moins $1 (ou l’équivalent dans la devise choisie). Les montants inférieurs à ce minimum ne sont pas pris en charge et l’abonnement ne fonctionnera pas.
Remise applicable (%) : Remise en pourcentage facultative appliquée au prix de base ; reflétée lors du checkout et sur les factures.
Répéter le paiement tous les (obligatoire) : Intervalle entre les renouvellements, par exemple tous les 1 Month. 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 Years). Une fois cette période terminée, les renouvellements s’arrêtent sauf prolongation.
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 est effectué automatiquement à la fin de l’essai.
Montant de l’essai : Frais initiaux facultatifs pour un essai payant. Laissez ce champ vide pour un essai gratuit. Consultez Paid Trials.
Sélectionner un add-on : Ajoutez jusqu’à 10 add-ons que les clients peuvent acheter avec le forfait de base.

Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.

Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.

Advanced settings

Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.

Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.

Subscription Trials

Les essais permettent aux clients d’évaluer un abonnement avant de payer le prix récurrent complet. Un essai peut être gratuit, auquel cas aucun montant n’est facturé avant sa fin, ou payant, auquel cas un montant réduit est facturé à l’avance. Dans les deux cas, le prix complet commence au premier renouvellement suivant la fin de l’essai.

Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14  // Overrides product's trial period
});

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

The trial_period_days value must be between 0 and 10,000 days.

Essais payants

Les essais ne doivent pas nécessairement être gratuits. Définissez un Montant de l’essai sur le prix récurrent d’un produit d’abonnement pour facturer des frais initiaux réduits pendant la période d’essai. Le prix récurrent complet prend ensuite le relais au premier renouvellement.

Formulaire de tarification d'un abonnement avec une durée d'essai et un montant d'essai facultatif pour un essai payant

Les essais payants sont configurés sur le prix du produit, et non par abonnement ou par session de checkout :

Champ	Type	Description
`trial_amount`	integer	Montant facturé aujourd’hui pour l’essai, dans les unités mineures de la devise du prix (par exemple, `500` pour $5.00). Nécessite `trial_period_days > 0`. Omettez-le ou définissez-le sur `null` pour un essai gratuit.
`trial_apply_discounts`	boolean	Indique si les codes de remise du checkout réduisent les frais de l’essai. La valeur par défaut est `false` : le montant de l’essai est donc facturé intégralement même lorsqu’une remise s’applique au prix récurrent.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Les essais payants passent également par le checkout. Le montant de l’essai est soumis aux taxes, apparaît dans les calculs de la session de checkout et dans la tarification des payment links, et la majoration Adaptive Currency est appliquée par devise. L’endpoint de prévisualisation renvoie trial_amount et trial_period_days afin que vous puissiez afficher le montant dû aujourd’hui avant la création de l’abonnement.

Les essais gratuits restent inchangés. Si vous laissez le Montant de l’essai vide, le comportement existant est conservé : le premier prélèvement est 0 et le prix complet est facturé à la fin de l’essai.

Prévenir les abus des essais

Prévenir les abus des essais empêche les clients de réclamer plusieurs fois des essais pour la même entreprise. Lorsque cette option est activée, un client ayant déjà utilisé un essai est automatiquement redirigé vers un achat payant sans essai, au lieu de bénéficier d’un nouvel essai.

Activez cette option depuis l’onglet Subscriptions dans Settings. Une fois activée :

Les clients sont identifiés par leur adresse e-mail normalisée, avec suppression des alias utilisant le signe plus ; user+trial@example.com et user@example.com désignent donc la même personne.
Les utilisations sont enregistrées lors de l’activation de l’essai : un client qui annule le jour même a tout de même consommé son essai.
Les clients existants sont complétés à partir de leurs essais historiques par e-mail ; les anciens utilisateurs d’essai sont donc reconnus immédiatement.

Le paramètre est désactivé par défaut. Consultez Subscription Settings pour obtenir la liste complète des contrôles d’abonnement au niveau de l’entreprise.

Détecter l’état d’essai

Il n’existe actuellement aucun champ direct permettant de détecter l’état d’essai. La solution de contournement suivante nécessite d’interroger les paiements, ce qui est inefficace. Nous travaillons sur une solution plus efficace.

Pour déterminer si un abonnement en essai gratuit est en période d’essai, récupérez la liste des paiements de l’abonnement. S’il existe 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;

Cette vérification du montant nul ne fonctionne que pour les essais gratuits. Pour un essai payant, le premier paiement correspond au montant de l’essai, et non à 0. Comparez plutôt le premier paiement à trial_amount de l’abonnement, ou vérifiez si next_billing_date se trouve toujours dans la période d’essai.

Mettre à jour 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 sur une date passée. La date doit être ultérieure à la date actuelle.

Modifications des forfaits d’abonnement

Les modifications de forfait permettent de mettre à niveau ou de rétrograder les abonnements, d’ajuster les quantités ou de migrer vers d’autres produits. Selon le mode de proratisation sélectionné, une modification peut entraîner une facturation immédiate, créer un crédit ou n’appliquer aucun ajustement de facturation.

Vous pouvez modifier les forfaits d’abonnement et mettre à jour la prochaine date de facturation directement depuis le tableau de bord Dodo Payments. Cela permet d’ajuster rapidement les abonnements pour répondre aux demandes du support client, effectuer des mises à niveau promotionnelles ou migrer des forfaits sans effectuer d’appels API.

Activer les modifications de forfait en libre-service : Vous souhaitez que les clients puissent mettre eux-mêmes à niveau ou rétrograder leurs abonnements via le Customer Portal ? Ajoutez vos produits d’abonnement à une Product Collection et activez « Allow Subscription Updates » dans vos Subscription Settings.

Product Collections

Regroupez les produits associés dans des collections pour permettre des parcours fluides de mise à niveau ou de rétrogradation dans le Customer Portal.

Modes de proratisation

Choisissez la manière dont les clients sont facturés lors d’une modification de forfait :

Comparaison rapide des quatre modes de proratisation :

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Mise à niveau	Frais proratisés pour les jours restants	Différence de prix complète facturée	Prix complet du nouveau forfait facturé	Aucun frais — changement immédiat
Rétrogradation	Crédit proratisé pour les jours restants	Différence de prix complète sous forme de crédit	Aucun crédit, facturation complète	Aucun crédit — changement immédiat
Cycle de facturation	Réinitialisé à aujourd’hui	Réinitialisé à aujourd’hui	Réinitialisé à aujourd’hui	Reste inchangé
Idéal pour	Une facturation équitable basée sur le temps	Des changements de niveau simples	La réinitialisation du cycle de facturation	Les migrations gratuites ou changements commerciaux

`prorated_immediately`

Facture un montant proratisé en fonction du temps restant dans le cycle de facturation actuel. Idéal pour une facturation équitable tenant compte du temps non utilisé.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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 les scénarios simples de mise à niveau ou de 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: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Les crédits issus des rétrogradations avec difference_immediately sont associés à l’abonnement et appliqués automatiquement aux renouvellements futurs. Ils sont distincts des avantages de Credit-Based Billing.

Lorsqu’un client rétrograde son forfait avec difference_immediately, la valeur non utilisée devient un crédit associé à l’abonnement qui compense automatiquement les renouvellements futurs :

`full_immediately`

Facture immédiatement le montant total du nouveau forfait, sans tenir compte du temps restant. Idéal pour réinitialiser les cycles de facturation.

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

`do_not_bill`

Passe au nouveau forfait sans aucun ajustement de facturation. Aucun frais de proratisation ni crédit : le client passe simplement au nouveau forfait. Idéal pour les migrations commerciales, les changements gratuits de forfait ou les situations où vous souhaitez absorber la différence de coût.

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

Example: Prorated upgrade calculation

Scénario : Un client disposant du forfait Basic (

30/month) passe au forfait Pro (

80/month) au 16e jour d’un cycle de 30 jours avec prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Prochain renouvellement le 15 février (16 janvier + 30 jours) : $80.00/month.

Pour consulter des exemples de calcul plus détaillés et des cas particuliers, reportez-vous à notre Guide complet des mises à niveau et rétrogradations.

Example: Downgrade credit calculation

Scénario : Un client disposant du forfait Pro (

80/month) rétrograde vers Starter (

20/month) avec difference_immediately.

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

Le crédit de $60 s’applique automatiquement aux renouvellements futurs :

Renouvellement 1 : $20 −$ 20 (crédit) = ** $0.00** (crédit restant de$ 40)
Renouvellement 2 : $20 −$ 20 (crédit) = ** $0.00** (crédit restant de$ 20)
Renouvellement 3 : $20 −$ 20 (crédit) = $0.00 (crédit épuisé)
Renouvellement 4 : $20.00 (prix complet)

Pour en savoir plus sur la gestion des crédits, consultez le Guide des mises à niveau et rétrogradations.

Modifier les forfaits avec des add-ons

Modifiez les add-ons lors d’un changement de forfait. Les add-ons sont inclus dans les calculs de proratisation :

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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
});

Par défaut (effective_at: 'immediately'), les changements de plan entraînent des frais immédiats. Transmettez effective_at: 'next_billing_date' pour planifier le changement à la prochaine date de facturation — le changement en attente est renvoyé sur l’abonnement sous la forme de scheduled_change, et vous pouvez l’annuler avec Annuler le changement de plan planifié. Les frais échoués peuvent faire passer l’abonnement au statut on_hold, sauf si vous transmettez on_payment_failure: 'prevent_change', ce qui conserve l’abonnement sur son plan actuel jusqu’à la réussite du paiement. Suivez les changements via les événements webhook subscription.plan_changed.

Prévisualiser les changements de forfait

Avant de confirmer un changement de forfait, prévisualisez les frais exacts et l’abonnement qui en résultera :

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

Preview Change Plan API

Prévisualisez les changements de forfait avant de les confirmer.

Mettre en pause et reprendre les abonnements

La mise en pause gèle un abonnement au lieu de le résilier. La facturation s’arrête, l’accès est révoqué et l’abonnement conserve son plan et son historique afin que le client puisse reprendre exactement là où il s’était arrêté. Utilisez cette option comme alternative à la résiliation pour fidéliser vos clients. Ouvrez n’importe quel abonnement actif sous Sales → Subscriptions, puis cliquez sur Pause subscription. Le statut devient paused et les renouvellements s’arrêtent jusqu’à la reprise de l’abonnement.

Que se passe-t-il lorsque vous mettez un abonnement en pause

Les renouvellements s’arrêtent. Aucune facture n’est générée et aucune tentative de prélèvement de renouvellement n’est effectuée pendant la pause de l’abonnement.
L’accès est révoqué immédiatement. La mise en pause révoque chaque entitlement grant délivré ou en attente sur l’abonnement, ce qui désactive ses license keys et empêche l’émission de nouvelles URL de téléchargement de digital product. La reprise les accorde à nouveau, de la même manière que la récupération après on_hold.
L’horloge de facturation est gelée. next_billing_date et expires_at avancent tous deux exactement de la durée de la pause, afin que le client conserve le temps déjà payé.
Aucune limite de durée de pause n’est appliquée. Un abonnement en pause le reste jusqu’à ce qu’une personne le reprenne. Vous ne définissez pas de durée de pause à l’avance.

La mise en pause révoque l’accès immédiatement, et non à la fin de la période de facturation. Si un abonnement contrôle l’accès à votre produit, expliquez-le clairement au client avant sa confirmation.

La reprise ramène l’abonnement à active et restaure ses entitlements. Comme l’horloge était gelée, le prochain renouvellement a lieu après la durée de la pause par rapport à la date initialement prévue : un abonnement mis en pause pendant 12 jours est renouvelé avec 12 jours de retard.

Mettre en pause des abonnements basés sur l’utilisation

Un abonnement basé sur l’utilisation peut présenter une utilisation enregistrée mais pas encore facturée au moment de sa mise en pause. L’option Bill Usage at Pause sous Settings → Subscriptions détermine ce qui lui arrive :

Paramètre	Comportement
On (par défaut)	Dodo Payments émet une facture pour l’utilisation accumulée depuis la dernière date de facturation et la recouvre immédiatement.
Off	L’utilisation due est reportée et facturée sur la prochaine facture régulière de l’abonnement.

Seule l’utilisation mesurée est réglée de cette manière : les frais de base récurrents ne sont jamais facturés au moment de la pause. Les abonnements standard et on-demand n’ont rien à régler ; ce paramètre ne les affecte donc pas.

Bill Usage at Pause est enregistré pour chaque cycle de facturation. Le modifier en cours de cycle ne change pas le règlement du cycle déjà commencé ; la nouvelle valeur s’applique à partir du cycle suivant.

La facture de règlement est recouvrée comme toute autre facture et peut donc échouer. Si elle reste impayée au-delà de la période de grâce du dunning, l’abonnement passe à on_hold tout en restant marqué comme étant en pause.

Un abonnement dans cet état dispose de deux issues, qui diffèrent selon la partie qui prend en charge l’utilisation due :

Issue	Résultat
La facture de règlement est payée	L’abonnement revient à `paused`, et non à `active`. Reprenez-le explicitement lorsque le client est prêt.
Vous le reprenez directement	L’abonnement passe directement à `active` et la facture de règlement impayée est annulée, avec ses nouvelles tentatives en attente. L’utilisation due est passée en perte.

La reprise constitue une issue valide de cette suspension : vous n’avez pas besoin de recouvrer la facture de règlement au préalable. Sachez simplement que la reprise annule l’utilisation impayée au lieu de la reporter.

Permettre aux clients de mettre eux-mêmes leurs abonnements en pause

L’option Allow Subscription Pause sous Settings → Subscriptions contrôle la possibilité pour les clients de mettre en pause et de reprendre leur abonnement depuis le Customer Portal. Elle est désactivée par défaut ; la mise en pause en libre-service doit donc être activée explicitement.

Ce paramètre ne concerne que le Customer Portal. Vous pouvez toujours mettre en pause et reprendre un abonnement depuis le tableau de bord ou l’API, quelle que soit la position du bouton bascule. Le désactiver empêche les nouvelles mises en pause effectuées par les clients, mais ne bloque pas un client dont l’abonnement est déjà en pause : il peut toujours reprendre une pause qu’il a lui-même démarrée. Les pauses que vous avez démarrées restent sous votre contrôle.

Pausing from the Customer Portal

Découvrez ce que voit le client, y compris la boîte de dialogue de confirmation.

Mise en pause via l’API

La mise en pause et la reprise utilisent un seul champ pause sur l’endpoint de mise à jour d’un abonnement. Il n’existe pas d’endpoint de mise en pause distinct.

// Pause
await client.subscriptions.update('sub_123', { pause: true });

// Resume
await client.subscriptions.update('sub_123', { pause: false });

pause est exclusif de tous les autres champs : son envoi avec un autre champ est rejeté avec 422. Définir status sur paused ne met pas un abonnement en pause ; utilisez plutôt le champ pause.

La mise en pause émet subscription.paused et la reprise émet subscription.unpaused. Les deux contiennent l’objet d’abonnement complet, avec paused_at défini pendant la pause et null une fois l’abonnement repris.

Mise en pause et autres actions sur les abonnements

La résiliation reste possible. Vous pouvez résilier un abonnement en pause exactement comme un abonnement actif. Toute facture de règlement ouverte issue de la pause est annulée lors de cette action.
Les changements de plan planifiés sont retardés, et non supprimés. Un changement de plan planifié pour la prochaine date de facturation reste inchangé pendant la pause, puis s’applique à la date de facturation décalée après la reprise. Son scheduled_change.effective_at est un instantané pris lors de sa planification et n’est pas ajusté en fonction de la pause ; il peut donc afficher une date passée. Interprétez-le comme « était planifié pour », et non comme une date garantie. Pour supprimer le changement au lieu de le maintenir, utilisez Cancel Scheduled Plan Change.

États des abonnements

Un abonnement parcourt un ensemble défini de statuts au cours de sa durée de vie. Ce tableau constitue la référence pour chaque statut, sa cause et la manière dont vous pouvez — ou non — le récupérer.

Statut	Signification	Récupérable ?	Procédure de récupération / étape suivante
`pending`	L’abonnement est en cours de création ou de traitement	—	Attendre `subscription.active` (ou `subscription.failed`)
`active`	L’abonnement est actif et sera renouvelé automatiquement	—	Aucune action requise
`on_hold`	Un paiement de renouvellement (ou une facturation liée à un changement de plan) a échoué ; les renouvellements sont arrêtés	Oui	Mettre à jour le moyen de paiement pour réactiver l’abonnement — automatiquement via Payment Retries et Dunning, ou manuellement via l’API Update Payment Method
`paused`	L’abonnement a été volontairement mis en pause par vous ou le client ; la facturation est gelée et l’accès est révoqué	Oui	Le reprendre avec `pause: false`, ou depuis le Customer Portal lorsque la mise en pause en libre-service est activée — consultez Mettre en pause et reprendre les abonnements
`cancelled`	L’abonnement a été résilié et ne sera pas renouvelé	Rachat uniquement	Le client doit démarrer un nouvel abonnement ; le Dunning peut l’inviter à effectuer un rachat
`failed`	La création de l’abonnement a échoué (le mandat initial ou le paiement n’a pas abouti)	Non — terminal	Le client doit créer un nouvel abonnement avec un moyen de paiement fonctionnel
`expired`	L’abonnement est arrivé au terme de sa durée	—	Le client doit démarrer un nouvel abonnement s’il le souhaite

on_hold et failed sont souvent confondus. on_hold est un état récupérable pour un abonnement déjà actif dont le renouvellement a échoué. failed est un état terminal qui ne survient que lorsque la création initiale de l’abonnement échoue ; il ne peut pas être réactivé.

on_hold et paused sont également distincts. on_hold est involontaire : un paiement a échoué. paused est volontaire : vous ou le client avez choisi de geler l’abonnement et aucune tentative de renouvellement n’est effectuée tant qu’il reste en pause. Un abonnement basé sur l’utilisation peut toutefois avoir une facture de règlement ponctuelle due au moment de sa mise en pause ; consultez Mettre en pause des abonnements basés sur l’utilisation.

Machine à états

État suspendu

Un abonnement entre dans l’état on_hold lorsque :

Un paiement de renouvellement échoue (fonds insuffisants, carte expirée, etc.)
La facturation d’un changement de plan échoue
L’autorisation du moyen de paiement échoue
Une facture de règlement liée à une pause pour un abonnement basé sur l’utilisation reste impayée

Lorsqu’un abonnement est dans l’état on_hold, il ne se renouvelle pas automatiquement. Vous devez mettre à jour le moyen de paiement pour le réactiver.

Réactiver un abonnement suspendu

Pour réactiver un abonnement dans l’état on_hold, mettez à jour le moyen de paiement. Cette action :

Crée des frais correspondant aux sommes restantes dues
Génère une facture
Traite le paiement avec le nouveau moyen de paiement
Réactive l’abonnement dans l’état active lorsque le paiement est effectué

La seule exception est une suspension due à une facture de règlement impayée après une pause. Le règlement de cette facture ramène l’abonnement à paused, et non à active, car la pause correspond à l’état précédent l’échec du paiement. Reprenez-le explicitement une fois la facture réglée.

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    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 moyen de paiement d’un abonnement on_hold, vous recevrez les événements webhook payment.succeeded, suivis de subscription.active.

Événements webhook par transition

Chaque transition émet un webhook afin que vous puissiez gérer la logique des entitlements sans effectuer de polling :

Transition	Événement
Abonnement activé	`subscription.active`
Renouvellement réussi	`subscription.renewed`
Échec du renouvellement → suspendu	`subscription.on_hold`
Abonnement mis en pause	`subscription.paused`
Abonnement en pause repris	`subscription.unpaused`
Échec de la création	`subscription.failed`
Plan augmenté/réduit	`subscription.plan_changed`
Résilié	`subscription.cancelled`
Terme arrivé à échéance	`subscription.expired`
Modification d’un champ	`subscription.updated`

Subscription Webhook Payloads

Consultez le schéma complet de la charge utile des événements du cycle de vie des abonnements.

Gestion via l’API

Create subscriptions

Utilisez POST /checkouts pour créer des abonnements par programmation à partir de produits, avec des essais facultatifs (subscription_data.trial_period_days) et des add-ons (product_cart[].addons).

POST /subscriptions est obsolète. Les intégrations existantes continuent de fonctionner, mais les nouvelles intégrations doivent utiliser les Checkout Sessions.

API Reference

Consultez l’API de création d’une session Checkout.

Update subscriptions

Utilisez PATCH /subscriptions/{subscription_id} pour résilier à la prochaine date de facturation, prolonger la période de l’abonnement, mettre à jour les détails de facturation ou modifier les métadonnées. Pour modifier la quantité, utilisez plutôt la Change Plan API : PATCH n’accepte pas quantity.

API Reference

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

Pause and resume subscriptions

La mise en pause et la reprise utilisent le même endpoint PATCH /subscriptions/{subscription_id} avec le champ pause : pause: true met en pause un abonnement actif et pause: false le reprend. Le champ ne peut être combiné avec aucun autre champ dans la même requête. Pour connaître le comportement complet, les effets sur la facturation et les paramètres métier associés, consultez Mettre en pause et reprendre les abonnements.

API Reference

Consultez l’API de mise à jour d’un abonnement, y compris le champ pause.

Change plans (proration)

Modifiez le produit actif et les quantités avec les contrôles de proration.

API Reference

Examinez les options de changement de plan.

On‑demand charges

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

API Reference

Facturez un abonnement on-demand.

List and retrieve

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

API Reference

Parcourez les API de référencement et de récupération.

Usage history

Récupérez l’utilisation enregistrée pour les modèles tarifaires metered ou hybrides.

API Reference

Consultez l’API de l’historique d’utilisation.

Update payment method

Mettez à jour le moyen de paiement d’un abonnement. Pour les abonnements actifs, cette action met à jour le moyen de paiement utilisé pour les futurs renouvellements. Pour les abonnements dans l’état on_hold, elle réactive l’abonnement en créant des frais correspondant aux sommes restantes dues.Lors de la génération d’un nouveau lien de moyen de paiement (le type de requête New), vous pouvez transmettre allowed_payment_method_types pour limiter les moyens de paiement affichés au client sur cette page. Les clients ne verront jamais un moyen qui ne figure pas dans la liste, mais l’inclusion d’un moyen ne garantit pas qu’il apparaîtra (sa disponibilité dépend également de facteurs tels que la localisation du client et les paramètres de votre entreprise).

API Reference

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

Cas d’utilisation courants

SaaS et API : accès par niveaux avec des add-ons pour les sièges ou l’utilisation
Contenu et médias : accès mensuel avec essais d’introduction
Plans de support B2B : contrats annuels avec add-ons de support premium
Outils et plugins : license keys et versions publiées

Exemples d’intégration

Checkout Sessions (abonnements)

Lors de la création de Checkout Sessions, incluez votre produit d’abonnement et les add-ons facultatifs :

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

Changements de plan avec proration

Augmentez ou réduisez un abonnement et contrôlez le comportement de la proration :

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

Résilier à la prochaine date de facturation

Planifiez une résiliation qui prendra effet à la fin de la période de facturation actuelle :

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

Prolonger la période de l’abonnement

Prolongez la durée d’un abonnement en transmettant un nouvel subscription_period_count et subscription_period_interval à PATCH /subscriptions/{subscription_id}. La date d’expiration de l’abonnement est recalculée à partir du nouveau nombre et du nouvel intervalle — par exemple, pour accorder du temps supplémentaire à un client sur son plan actuel :

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

La période d’un abonnement peut uniquement être prolongée, jamais raccourcie.

Abonnements on-demand

Créez un abonnement on-demand et facturez-le ultérieurement selon les besoins :

const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Mettre à jour le moyen de paiement d’un abonnement actif

Mettez à jour le moyen de paiement d’un abonnement actif :

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

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

Réactiver un abonnement depuis on_hold

Réactivez un abonnement suspendu en raison d’un échec de paiement :

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    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 des mandats conformes à la RBI

Les abonnements UPI et par carte indienne sont soumis aux réglementations de la RBI (Reserve Bank of India) et à des exigences spécifiques en matière de mandat :

Limites des mandats

Le type et le montant du mandat dépendent des frais récurrents de votre abonnement :

Frais inférieurs au seuil du mandat (15 000 ₹ par défaut) : Nous créons un mandat on-demand pour le montant du seuil. Le montant de l’abonnement est facturé périodiquement selon la fréquence de votre abonnement, jusqu’à la limite du mandat.
Frais égaux ou supérieurs au seuil du mandat : Nous créons un mandat d’abonnement (ou un mandat on-demand) correspondant exactement au montant de l’abonnement.

Le seuil du mandat peut être configuré par merchant ou par requête via mandate_min_amount_inr_paise (paise INR). Le montant enregistré auprès de la banque est max(mandate_floor, billing_amount) ; le seuil devient donc effectivement le plafond d’autorisation affiché au client lorsque la facturation est inférieure. Pour plus d’informations sur les mandats conformes à la RBI et le seuil de mandat configurable pour les moyens de paiement indiens, consultez la page India Payment Methods.

Considérations relatives aux augmentations et réductions de plan

Important : lors de l’augmentation ou de la réduction d’un abonnement, tenez soigneusement compte des limites du mandat :

Si une augmentation ou une réduction entraîne un montant supérieur à 15 000 Rs et dépasse la limite de paiement on-demand existante, les frais de transaction peuvent échouer.
Dans ce cas, le client devra peut-être mettre à jour son moyen de paiement ou modifier à nouveau l’abonnement afin d’établir un nouveau mandat avec la limite appropriée.

Autorisation des frais de montant élevé

Pour les frais d’abonnement de 15 000 Rs ou plus :

La banque demandera au client d’autoriser la transaction.
Si le client n’autorise pas la transaction, celle-ci échouera et l’abonnement sera suspendu.

Délai de traitement de 48 heures

Calendrier de traitement : les frais récurrents des cartes indiennes et des abonnements UPI suivent un schéma de traitement particulier :

Les frais sont initiés à la date prévue, conformément à la fréquence de votre abonnement.
Le débit effectif du compte du client n’a lieu qu’après 48 heures suivant l’initiation du paiement.
Cette fenêtre de 48 heures peut être prolongée de 2 à 3 heures supplémentaires selon les réponses de l’API bancaire.

Fenêtre d’annulation du 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 reste actif (il s’agit d’un cas particulier des abonnements Indian card et UPI AutoPay).
Toutefois, le débit effectif peut échouer ; dans ce cas, nous plaçons l’abonnement on hold.

Gestion des cas particuliers : si vous fournissez immédiatement aux clients des avantages, crédits ou usages liés à l’abonnement lors de l’initiation des frais, vous devez gérer correctement cette fenêtre de 48 heures dans votre application. Envisagez :

De retarder l’activation des avantages jusqu’à la confirmation du paiement
De mettre en place des périodes de grâce ou un accès temporaire
De surveiller le statut de l’abonnement pour détecter les annulations de mandat
De gérer les états de suspension de l’abonnement dans la logique de votre application

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

Bonnes pratiques

Commencez par des niveaux clairs : 2 à 3 plans présentant des différences évidentes
Communiquez les tarifs : affichez les totaux, la proration et le prochain renouvellement
Utilisez les essais avec discernement : convertissez grâce à l’onboarding, et pas uniquement grâce à la durée
Tirez parti des add-ons : gardez des plans de base simples et proposez des options supplémentaires
Testez les changements : validez les changements de plan et la proration en mode test

Les abonnements constituent une base flexible pour les revenus récurrents. Commencez simplement, testez rigoureusement et améliorez votre approche en fonction des indicateurs d’adoption, de churn et d’expansion.

Dernière modification le 21 août 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Essais payants

​Prévenir les abus des essais

​Détecter l’état d’essai

​Mettre à jour la période d’essai

​Modifications des forfaits d’abonnement

Product Collections

​Modes de proratisation

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Modifier les forfaits avec des add-ons

​Prévisualiser les changements de forfait

Preview Change Plan API

​Mettre en pause et reprendre les abonnements

​Que se passe-t-il lorsque vous mettez un abonnement en pause

​Mettre en pause des abonnements basés sur l’utilisation

​Permettre aux clients de mettre eux-mêmes leurs abonnements en pause

Pausing from the Customer Portal

​Mise en pause via l’API

​Mise en pause et autres actions sur les abonnements

​États des abonnements

​Machine à états

​État suspendu

​Réactiver un abonnement suspendu

​Événements webhook par transition

Subscription Webhook Payloads

​Gestion via l’API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Cas d’utilisation courants

​Exemples d’intégration

​Checkout Sessions (abonnements)

​Changements de plan avec proration

​Résilier à la prochaine date de facturation

​Prolonger la période de l’abonnement

​Abonnements on-demand

​Mettre à jour le moyen de paiement d’un abonnement actif

​Réactiver un abonnement depuis on_hold

​Abonnements avec des mandats conformes à la RBI

​Limites des mandats

​Considérations relatives aux augmentations et réductions de plan

​Autorisation des frais de montant élevé

​Délai de traitement de 48 heures

​Fenêtre d’annulation du mandat

​Bonnes pratiques

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Essais payants

Prévenir les abus des essais

Détecter l’état d’essai

Mettre à jour la période d’essai

Modifications des forfaits d’abonnement

Modes de proratisation

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Modifier les forfaits avec des add-ons

Prévisualiser les changements de forfait

Mettre en pause et reprendre les abonnements

Que se passe-t-il lorsque vous mettez un abonnement en pause

Mettre en pause des abonnements basés sur l’utilisation

Permettre aux clients de mettre eux-mêmes leurs abonnements en pause

Mise en pause via l’API

Mise en pause et autres actions sur les abonnements

États des abonnements

Machine à états

État suspendu

Réactiver un abonnement suspendu

Événements webhook par transition

Gestion via l’API

Cas d’utilisation courants

Exemples d’intégration

Checkout Sessions (abonnements)

Changements de plan avec proration

Résilier à la prochaine date de facturation

Prolonger la période de l’abonnement

Abonnements on-demand

Mettre à jour le moyen de paiement d’un abonnement actif

Réactiver un abonnement depuis on_hold

Abonnements avec des mandats conformes à la RBI

Limites des mandats

Considérations relatives aux augmentations et réductions de plan

Autorisation des frais de montant élevé

Délai de traitement de 48 heures

Fenêtre d’annulation du mandat

Bonnes pratiques