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

​

Abonnement-Ereignistypen

1. subscription.active - Abonnement wurde erfolgreich aktiviert.
2. subscription.updated - Abonnementobjekt wurde aktualisiert (wird bei jeder Feldänderung ausgelöst).
3. subscription.on_hold - Abonnement wird wegen fehlgeschlagener Verlängerung pausiert.
4. subscription.failed - Abonnementerstellung schlug bei der Erstellung des Mandats fehl.
5. subscription.renewed - Abonnement wird für den nächsten Abrechnungszeitraum erneuert.

​

Zahlungsszenarien

1. subscription.active - Zeigt die Aktivierung des Abonnements an
2. payment.succeeded - Bestätigt die Erstzahlung:
   • Bei sofortiger Abrechnung (0 Testtage): Erwartet innerhalb von 2-10 Minuten
   • Bei Testtagen: immer wenn diese enden
3. subscription.renewed - Zeigt den Zahlungsabzug und die Erneuerung für den nächsten Zyklus an. (Grundsätzlich erhalten Sie immer, wenn eine Zahlung für Abonnementprodukte abgezogen wird, den subscription.renewed Webhook zusammen mit payment.succeeded)

1. Abonnementausfall

• subscription.failed - Abonnementerstellung fehlgeschlagen aufgrund eines fehlgeschlagenen Mandats.
• payment.failed - Zeigt fehlgeschlagene Zahlung an.

2. Abonnement pausiert

• subscription.on_hold - Abonnement wird aufgrund einer fehlgeschlagenen Verlängerungszahlung oder einer fehlgeschlagenen Planänderungsgebühr pausiert.
• Wenn ein Abonnement pausiert, wird es nicht automatisch erneuert, bis die Zahlungsmethode aktualisiert wird.

​

subscription.failed vs. subscription.on_hold

​

Abonnement auf Pausiert behandeln

​

Wann Abonnements auf Pausiert gestellt werden

• Verlängerungszahlung fehlschlägt: Die automatische Verlängerungsgebühr schlägt aufgrund unzureichender Mittel, abgelaufener Karte oder Bankablehnung fehl
• Planänderungsgebühr fehlschlägt: Eine sofortige Gebühr während eines Plan-Upgrades/Downgrades schlägt fehl
• Zahlungsmethode-Autorisierung fehlschlägt: Die Zahlungsmethode kann nicht für wiederkehrende Gebühren autorisiert werden

​

Reaktivierung von Abonnements von Pausiert

1. Erstellung einer Gebühr für ausstehende Beträge
2. Erstellung einer Rechnung für die Gebühr
3. Verarbeitung der Zahlung mit der neuen Zahlungsmethode
4. Reaktivierung des Abonnements in den active Zustand 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
}

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

​

Beispieldaten für Abonnementereignisse

​

Abonnementpläne ändern

​

Optionen für anteilige Abrechnung

​

1. prorated_immediately

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

​

2. full_immediately

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

​

3. difference_immediately

• Beim Upgrade wird der Kunde sofort mit dem Unterschied zwischen den beiden Planbeträgen belastet.
• Beispielsweise, wenn der aktuelle Plan 30 Dollar kostet und der Kunde auf 80 Dollar wechselt, werden ihm sofort 50 Dollar berechnet.
• Bei einem Downgrade wird der ungenutzte Betrag des aktuellen Plans als internes Guthaben hinzugefügt und automatisch auf zukünftige Abonnementverlängerungen angerechnet.
• Beispielsweise, wenn der aktuelle Plan 50 Dollar beträgt und der Kunde auf einen 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 der von Ihnen gewählten Option für anteilige Abrechnung
• Wenn die Planänderung ein Downgrade ist und Sie prorated_immediately verwenden, werden Guthaben automatisch berechnet und dem Guthaben 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 full_immediately Option umgeht die Guthabenberechnung und belastet den vollen Betrag des neuen Plans

​

Gebührenverarbeitung

• Die sofortige Gebühr, die bei der Planänderung initiiert wird, wird normalerweise in weniger als 2 Minuten abgeschlossen
• Wenn diese sofortige Gebühr aus irgendeinem Grund fehlschlägt, wird das Abonnement automatisch pausiert, bis das Problem behoben ist

​

On-Demand-Abonnements

​

Verwandte API-Referenz