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 - Indicates subscription activation
2. payment.succeeded - Confirms the initial payment:
   • For immediate billing (0 trial days): Expect within 2-10 minutes
   • For trial days: whenever that ends
3. subscription.renewed - Indicates payment deduction and renewal for next cycle. (Basically, whenever payment gets deducted for subscription products, you will get subscription.renewed webhook along with payment.succeeded)

1. Subscription Failure

• subscription.failed - Subscription creation failed due to failure to create a mandate.
• payment.failed - Indicates failed payment.

2. Subscription On Hold

• subscription.on_hold - Subscription is put on hold due to failed renewal payment or failed plan change charge.
• When a subscription goes on hold, it will not renew automatically until the payment method is updated.

​

subscription.failed vs. subscription.on_hold

​

Behandlung von Abonnements im Wartezustand

​

Wann Abonnements in den Wartezustand versetzt werden

• Erneuerungszahlung fehlschlägt: Die automatische Erneuerungsgebühr schlägt aufgrund unzureichender Mittel, abgelaufener Karte oder Bankenabweisung fehl
• Tarifänderungsgebühr fehlschlägt: Eine sofortige Gebühr während eines Upgrades/Downgrades des Tarifplans schlägt fehl
• Autorisierung der Zahlungsmethode fehlschlägt: Die Zahlungsmethode kann nicht für wiederkehrende Belastungen autorisiert werden

​

Reaktivierung von Abonnements im Wartezustand

1. Eine Gebühr für ausstehende Beträge
2. Eine Rechnung für die Gebühr
3. Verarbeitet die Zahlung mit der neuen Zahlungsmethode
4. Reaktiviert das Abonnement in den Zustand active nach erfolgreicher Zahlung

// 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
}

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.'
  });
}

​

Beispiel-Event-Payload für Abonnements

​

Ändern von Abonnementsplänen

​

Optionen zur Verrechnung

​

1. prorated_immediately

• Berechnet den anteiligen Betrag basierend auf der verbleibenden Zeit im aktuellen Abrechnungszyklus
• Belastet den Kunden nur für den Unterschied zwischen dem alten und dem neuen Plan
• Während eines Testzeitraums wird der Benutzer sofort auf den neuen Plan umgestellt und der Kunde sofort belastet

​

2. full_immediately

• Belastet den Kunden den vollen Abonnementbetrag für den neuen Plan
• Ignoriert verbleibende Zeit oder Guthaben aus dem vorherigen Plan
• Nützlich, wenn Sie den Abrechnungszyklus zurücksetzen oder den vollen Betrag unabhängig von der Verrechnung berechnen möchten

​

3. difference_immediately

• Beim Upgrade wird der Kunde sofort mit dem Unterschied zwischen den beiden Plänen belastet.
• Beispiel: Wenn der aktuelle Plan 30 Dollar kostet und der Kunde zu einem 80-Dollar-Plan wechselt, werden ihm sofort 50 Dollar berechnet.
• Beim Downgrade wird der nicht genutzte Betrag des aktuellen Plans als internes Guthaben hinzugefügt und automatisch auf zukünftige Abonnementverlängerungen angerechnet.
• Beispiel: Wenn der aktuelle Plan 50 Dollar kostet und der Kunde zu einem 20-Dollar-Plan wechselt, werden die verbleibenden 30 Dollar gutgeschrieben und für den nächsten Abrechnungszyklus verwendet.

​

Verhalten

• Wenn Sie diese API aufrufen, initiiert Dodo Payments sofort eine Gebühr basierend auf Ihrer gewählten Verrechnungsoption
• Wenn die Planänderung ein Downgrade ist und Sie prorated_immediately verwenden, werden Credits automatisch berechnet und dem Guthabensaldo des Abonnements hinzugefügt. Diese Guthaben sind spezifisch für dieses Abonnement und werden nur zur Verrechnung zukünftiger wiederkehrender Zahlungen desselben Abonnements verwendet
• Die Option full_immediately umgeht die Guthabenberechnung und berechnet den vollen neuen Planbetrag

​

Gebührenbearbeitung

• Die sofortige Gebühr, die bei der Planänderung initiiert wird, wird in der Regel in weniger als 2 Minuten bearbeitet
• Wenn diese sofortige Gebühr aus irgendeinem Grund fehlschlägt, wird das Abonnement automatisch in den Wartezustand versetzt, bis das Problem gelöst ist

​

On-Demand-Abonnements

​

Verwandte API-Referenz