Subscription Integration Guide

​

Prerequisites

• A Dodo Payments merchant account
• API credentials (API key and webhook secret key) from the dashboard

​

API Integration

​

Checkout Sessions

import DodoPayments from 'dodopayments';

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

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

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

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "prod_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

API Response

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhooks

​

Subscription Event Types

1. subscription.active - Subscription is successfully activated.
2. subscription.updated - Subscription object was updated (fires on any field change).
3. subscription.on_hold - Subscription is put on hold due to failed renewal.
4. subscription.failed - Subscription creation failed during mandate creation.
5. subscription.renewed - Subscription is renewed for the next billing period.

​

Payment Scenarios

1. subscription.active : le mandat est autorisé et l’abonnement est activé.
2. payment.succeeded : confirme le premier débit. Attendez-vous à le recevoir dans les 2 à 10 minutes suivant le checkout.

1. Au début de l’essai (checkout) : subscription.active est déclenché une fois le moyen de paiement autorisé. Aucun débit récurrent n’est encore effectué. Le premier débit réel est reporté à la fin de l’essai.
2. À la fin de l’essai : le montant récurrent est débité et vous recevez payment.succeeded avec subscription.renewed.

• subscription.renewed : est déclenché à chaque cycle de facturation lorsque le paiement du renouvellement est débité, toujours avec payment.succeeded. Il contient également le next_billing_date mis à jour.

1. Échec de l’abonnement

• subscription.failed - La création de l’abonnement a échoué, car le mandat n’a pas pu être créé.
• payment.failed - Indique un paiement échoué.

2. Abonnement suspendu

• subscription.on_hold - L’abonnement est suspendu en raison de l’échec du paiement du renouvellement ou du débit lié à la modification du plan.
• Lorsqu’un abonnement est suspendu, il ne se renouvelle pas automatiquement tant que le moyen de paiement n’a pas été mis à jour.

​

subscription.failed contre subscription.on_hold

​

Gérer un abonnement suspendu

​

Quand les abonnements sont suspendus

• Le paiement du renouvellement échoue : le débit automatique du renouvellement échoue en raison de fonds insuffisants, d’une carte expirée ou d’un refus bancaire
• Le débit lié à la modification du plan échoue : un débit immédiat lors de la mise à niveau ou de la rétrogradation du plan échoue
• L’autorisation du moyen de paiement échoue : le moyen de paiement ne peut pas être autorisé pour des débits récurrents

​

Réactiver un abonnement suspendu

1. Crée un débit correspondant aux sommes restantes dues
2. Génère une facture pour ce débit
3. Traite le paiement avec le nouveau moyen de paiement
4. Réactive l’abonnement à l’état active lorsque le paiement est effectué avec succès

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  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 for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    type="new",
    return_url="https://example.com/return"
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

Exemple de payload d’événement Subscription

​

Modifier les plans d’abonnement

​

Options de prorata

​

1. prorated_immediately

• Calcule le montant au prorata en fonction du temps restant dans le cycle de facturation actuel
• Ne facture au client que la différence entre l’ancien et le nouveau plan
• Pendant une période d’essai, bascule immédiatement l’utilisateur vers le nouveau plan et facture le client immédiatement

​

2. full_immediately

• Facture au client le montant total de l’abonnement du nouveau plan
• Ignore le temps restant ou les crédits du plan précédent
• Utile lorsque vous souhaitez réinitialiser le cycle de facturation ou facturer le montant total indépendamment du prorata

​

3. difference_immediately

• Lors d’une mise à niveau, la différence entre les deux montants des plans est immédiatement facturée au client.
• Par exemple, si le plan actuel coûte 30 Dollars et que le client passe à un plan de 80 Dollars, il est immédiatement facturé de $50.
• Lors d’une rétrogradation, le montant inutilisé du plan actuel est ajouté sous forme de crédit interne et automatiquement appliqué aux futurs renouvellements de l’abonnement.
• Par exemple, si le plan actuel coûte 50 Dollars et que le client passe à un plan de 20 Dollars, les $30 restants sont crédités et utilisés lors du prochain cycle de facturation.

​

4. do_not_bill

• Applique immédiatement la modification du plan, mais ne facture rien au moment de la modification.
• Le plan mis à jour (ainsi que la quantité et les modules complémentaires) est facturé lors du prochain renouvellement planifié, et la date de facturation initiale est conservée.

​

Comportement

• Lorsque vous appelez cette API, Dodo Payments initie immédiatement un débit selon l’option de prorata sélectionnée
• Si la modification du plan est une rétrogradation et que vous utilisez prorated_immediately, les crédits sont automatiquement calculés et ajoutés au solde de crédits de l’abonnement. Ces crédits sont propres à cet abonnement et ne seront utilisés que pour compenser les futurs paiements récurrents du même abonnement
• L’option full_immediately ignore le calcul des crédits et facture le montant total du nouveau plan

​

Traitement du débit

• Le débit immédiat initié lors de la modification du plan termine généralement son traitement en moins de 2 minutes
• Si ce débit immédiat échoue pour quelque raison que ce soit, l’abonnement est automatiquement suspendu jusqu’à la résolution du problème

​

Abonnements à la demande

​

Points essentiels à connaître sur la facturation des abonnements

​

Référence API associée