Subscription Integration Guide

​

Voraussetzungen

• Ein Händlerkonto bei Dodo Payments
• Einen API-Schlüssel aus Developer → API Keys im Dashboard, gespeichert in DODO_PAYMENTS_API_KEY
• Ein Webhook-Secret aus Developer → Webhooks, gespeichert in DODO_PAYMENTS_WEBHOOK_KEY
• Mindestens ein unter Products erstelltes Abonnementprodukt

​

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: 'pdt_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": "pdt_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: 'pdt_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-Antwort

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

​

Webhooks

​

Abonnementereignistypen

1. subscription.active — Das Abonnement wurde aktiviert
2. subscription.updated — Ein Feld des Abonnements wurde geändert
3. subscription.on_hold — Eine Belastung für eine Verlängerung oder Planänderung ist fehlgeschlagen
4. subscription.failed — Die Erstellung des Abonnements ist fehlgeschlagen (endgültig; der Kunde muss sich erneut abonnieren)
5. subscription.renewed — Eine wiederkehrende Belastung war erfolgreich
6. subscription.past_due — Eine Verlängerung ist fehlgeschlagen und die Kulanzfrist wurde gestartet; der Kunde behält den Zugriff bis past_due_ends_at
7. subscription.plan_changed — Der Plan wurde hoch- oder heruntergestuft oder geändert
8. subscription.cancelled — Das Abonnement wurde gekündigt
9. subscription.expired — Das Abonnement hat das Ende seiner Laufzeit erreicht

​

Zahlungsszenarien

1. subscription.active: Das Mandat wird autorisiert und das Abonnement aktiviert.
2. payment.succeeded: Bestätigt die erste Belastung. Dieses Ereignis wird innerhalb von 2–10 Minuten nach dem Checkout erwartet.

1. Zu Beginn der Testphase (Checkout): subscription.active wird ausgelöst, sobald die Zahlungsmethode autorisiert wurde. Noch keine wiederkehrende Belastung. Die erste tatsächliche Belastung wird bis zum Ende der Testphase aufgeschoben.
2. Am Ende der Testphase: Der wiederkehrende Betrag wird belastet, und Sie erhalten payment.succeeded zusammen mit subscription.renewed.

• subscription.renewed: Wird bei jedem Abrechnungszyklus ausgelöst, wenn die Zahlung für die Verlängerung eingezogen wird, immer zusammen mit payment.succeeded. Das Ereignis enthält außerdem die aktualisierte next_billing_date.

1. Fehler beim Abonnement

• subscription.failed – Die Erstellung des Abonnements ist fehlgeschlagen, weil kein Mandat erstellt werden konnte.
• payment.failed – Zeigt eine fehlgeschlagene Zahlung an.

2. Abonnement pausiert

• subscription.on_hold – Das Abonnement wird aufgrund einer fehlgeschlagenen Verlängerungszahlung oder einer fehlgeschlagenen Belastung für eine Planänderung pausiert. Wenn Ihr Unternehmen eine Kulanzfrist hat, wechselt eine fehlgeschlagene Verlängerung zunächst zu past_due (subscription.past_due) und erst nach Ablauf der Kulanzfrist zu on_hold (oder cancelled, abhängig von Ihren Einstellungen für die Kulanzfrist). Siehe Abonnementstatus.
• Wenn ein Abonnement pausiert wird, verlängert es sich nicht automatisch, bis die Zahlungsmethode aktualisiert wurde.

​

subscription.failed vs. subscription.on_hold

​

Umgang mit pausierten Abonnements

​

Wann Abonnements pausiert werden

• Eine Verlängerungszahlung fehlschlägt: Die automatische Belastung für die Verlängerung schlägt aufgrund unzureichender Deckung, einer abgelaufenen Karte oder einer Ablehnung durch die Bank fehl
• Die Belastung für eine Planänderung fehlschlägt: Eine sofortige Belastung bei einer Hoch- oder Herabstufung des Plans schlägt fehl
• Die Autorisierung der Zahlungsmethode fehlschlägt: Die Zahlungsmethode kann für wiederkehrende Belastungen nicht autorisiert werden

​

Abonnements aus dem pausierten Status reaktivieren

1. Eine Belastung für ausstehende Beträge erstellt
2. Eine Rechnung für die Belastung erstellt
3. Die Zahlung mit der neuen Zahlungsmethode verarbeitet
4. Das Abonnement nach erfolgreicher Zahlung in den Status active reaktiviert

// 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, {
  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 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,
    payment_method={"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, {
  payment_method: { 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 einer Nutzlast für ein Abonnementereignis

​

Abonnementpläne ändern

​

Proration-Optionen

​

1. prorated_immediately

• Schreibt den ungenutzten Anteil des aktuellen Abrechnungszyklus gut, anteilig nach der verbleibenden Zeit. Das Guthaben umfasst den Basisplan, die Menge und alle Add-ons
• Belastet anschließend einen vollständigen Zyklus zum neuen Plan, zur neuen Menge und zu den neuen Add-ons. Die Belastung selbst wird nie anteilig berechnet
• Netto-Sofortbelastung = (vollständiger neuer Zyklus) minus (verbleibender Anteil x vollständiger alter Zyklus). Ist das Guthaben höher, wird die Differenz als abonnementbezogenes Guthaben für künftige Verlängerungen zurückgehalten
• Während einer Testphase wird der Benutzer sofort auf den neuen Plan umgestellt und der Kunde direkt belastet

​

2. full_immediately

• Belastet dem Kunden den vollständigen Abonnementbetrag für den neuen Plan, ohne eine Gutschrift für den vorherigen Zyklus
• Sowohl bei einer Hoch- als auch bei einer Herabstufung zahlt der Kunde den vollständigen Preis des neuen Plans von Anfang an
• Nützlich, wenn Sie unabhängig von der verbleibenden Zeit des alten Plans den vollständigen Betrag berechnen möchten

​

3. difference_immediately

• Der Kunde zahlt nur die Differenz zwischen dem Preis des alten und des neuen Plans
• Der Betrag hängt nicht davon ab, wann im Zyklus die Änderung vorgenommen wird. Dasselbe Upgrade kostet am ersten und am 29. Tag gleich viel
• Bei einer Hochstufung wird dem Kunden die Differenz sofort berechnet. Beispiel: $30/Monat → $80/Monat = sofort berechnete $50
• Bei einer Herabstufung wird die Preisdifferenz als abonnementbezogenes Guthaben gespeichert und automatisch auf künftige Verlängerungen angerechnet. Beispiel: $50/Monat → $20/Monat = $30 als Guthaben gespeichert

​

4. do_not_bill

• Wendet die Planänderung sofort an, ohne zum Zeitpunkt der Änderung eine Belastung vorzunehmen. Der neue Plan, die neue Menge und die neuen Add-ons können sofort genutzt werden
• Da jetzt nichts belastet wird, erhält der Kunde bei einer Hochstufung den höherwertigen Plan für den Rest des aktuellen Zyklus kostenlos. Eine Herabstufung tritt sofort in Kraft, ohne Gutschrift für den ungenutzten Anteil des bereits bezahlten Zyklus
• Über do_not_bill gewährte Add-ons werden bei einer späteren Planänderung nicht gutgeschrieben, da sie nie berechnet wurden. Bei einer nachfolgenden Änderung wird die neue Add-on-Menge vollständig berechnet
• Der aktualisierte Plan (sowie Menge/Add-ons) wird bei der nächsten geplanten Verlängerung berechnet, und das ursprüngliche Abrechnungsdatum bleibt erhalten

​

Verhalten

• Wenn Sie diese API aufrufen, leitet Dodo Payments sofort eine Belastung auf Grundlage der ausgewählten Proration-Option ein
• Bei prorated_immediately wird bei jeder Änderung, sowohl bei einer Hoch- als auch bei einer Herabstufung, eine Gutschrift für den ungenutzten Anteil des aktuellen Zyklus berechnet. Übersteigt diese Gutschrift die Belastung für den neuen Zyklus, wird der Rest dem Guthaben des Abonnements hinzugefügt. Diese Gutschriften gelten nur für dieses Abonnement und werden ausschließlich zum Ausgleich künftiger wiederkehrender Zahlungen desselben Abonnements verwendet
• Bei difference_immediately entspricht der Nettobetrag immer exakt der Preisdifferenz. Bei Herabstufungen wird der Überschuss als abonnementbezogenes Guthaben gespeichert, ebenso wie bei prorated_immediately
• Die Option full_immediately überspringt die Guthabenberechnung und berechnet den vollständigen Betrag des neuen Plans
• Die Option do_not_bill wendet die Änderung sofort an, verschiebt die Abrechnung jedoch auf das nächste Verlängerungsdatum, das beibehalten wird

​

Verarbeitung der Belastung

• Die bei einer Planänderung eingeleitete sofortige Belastung wird normalerweise in weniger als 2 Minuten verarbeitet
• Wenn diese sofortige Belastung aus irgendeinem Grund fehlschlägt, wird das Abonnement automatisch pausiert, bis das Problem behoben ist

​

On-Demand-Abonnements

​

Wichtige Informationen zur Abonnementabrechnung

​

Zugehörige API-Referenz