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 Response

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

​

Webhooks

​

Subscription Event Types

1. subscription.active — Subscription ist aktiviert
2. subscription.updated — Ein Feld der Subscription wurde geändert
3. subscription.on_hold — Eine Zahlung für eine Verlängerung oder Planänderung ist fehlgeschlagen
4. subscription.failed — Subscription-Erstellung ist fehlgeschlagen (endgültig; der Kunde muss sich erneut anmelden)
5. subscription.renewed — Eine wiederkehrende Zahlung 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 herabgestuft oder geändert
8. subscription.cancelled — Die Subscription wurde gekündigt
9. subscription.expired — Die Subscription hat das Ende ihrer Laufzeit erreicht

​

Zahlungsszenarien

1. subscription.active: Das Mandat wird autorisiert und die Subscription aktiviert.
2. payment.succeeded: Bestätigt die erste Zahlung. Du solltest dieses Ereignis innerhalb von 2–10 Minuten nach dem Checkout erhalten.

1. Zu Beginn der Testphase (Checkout): subscription.active wird ausgelöst, sobald die Zahlungsmethode autorisiert wurde. Es wird noch keine wiederkehrende Zahlung eingezogen. Die erste tatsächliche Zahlung wird bis zum Ende der Testphase aufgeschoben.
2. Am Ende der Testphase: Der wiederkehrende Betrag wird eingezogen, und du erhältst 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 next_billing_date in aktualisierter Form.

1. Fehler bei der Subscription

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

2. Subscription pausiert

• subscription.on_hold - Die Subscription wird aufgrund einer fehlgeschlagenen Zahlung für eine Verlängerung oder einer fehlgeschlagenen Zahlung für eine Planänderung pausiert. Wenn dein Unternehmen eine Kulanzfrist hat, wird 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 deinen Einstellungen für die Kulanzfrist). Siehe Subscription States.
• Wenn eine Subscription pausiert wird, verlängert sie sich nicht automatisch, bis die Zahlungsmethode aktualisiert wurde.

​

subscription.failed vs. subscription.on_hold

​

Umgang mit pausierten Subscriptions

​

Wann Subscriptions pausiert werden

• Zahlung für eine Verlängerung fehlschlägt: Die automatische Zahlung für die Verlängerung schlägt aufgrund unzureichender Deckung, einer abgelaufenen Karte oder einer Ablehnung durch die Bank fehl
• Zahlung für eine Planänderung fehlschlägt: Eine sofortige Zahlung während eines Upgrades oder Downgrades schlägt fehl
• Autorisierung der Zahlungsmethode fehlschlägt: Die Zahlungsmethode kann für wiederkehrende Zahlungen nicht autorisiert werden

​

Reaktivieren pausierter Subscriptions

1. Eine Zahlung für ausstehende Beträge wird erstellt
2. Eine Rechnung für die Zahlung wird generiert
3. Die Zahlung wird mit der neuen Zahlungsmethode verarbeitet
4. Die Subscription wird 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 für einen Subscription Event Payload

​

Subscription-Pläne ändern

​

Proration-Optionen

​

1. prorated_immediately

• Der ungenutzte Anteil des aktuellen Abrechnungszyklus wird zeitanteilig gutgeschrieben. Die Gutschrift umfasst den Basisplan, die Menge und alle Add-ons
• Anschließend wird ein vollständiger Zyklus für den neuen Plan, die Menge und die Add-ons berechnet. Die Zahlung selbst wird niemals zeitanteilig berechnet
• Sofortige Nettobelastung = (vollständiger neuer Zyklus) minus (verbleibender Anteil x vollständiger alter Zyklus). Ist die Gutschrift höher, wird die Differenz als Subscription-spezifisches Guthaben für zukünftige Verlängerungen gespeichert
• Während einer Testphase wird der Nutzer sofort auf den neuen Plan umgestellt und der Kunde unmittelbar belastet

​

2. full_immediately

• Dem Kunden wird der vollständige Subscription-Betrag für den neuen Plan ohne Gutschrift für den vorherigen Zyklus berechnet
• Sowohl bei einem Upgrade als auch bei einem Downgrade zahlt der Kunde den gesamten Preis des neuen Plans von Anfang an
• Sinnvoll, wenn du unabhängig von der verbleibenden Zeit des alten Plans den vollständigen Betrag berechnen möchtest

​

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 an Tag 1 und an Tag 29 gleich viel
• Bei einem Upgrade wird dem Kunden die Differenz sofort berechnet. Beispiel: $30/Monat → $80/Monat = sofort berechnete $50
• Bei einem Downgrade wird die Preisdifferenz als Subscription-spezifisches Guthaben gespeichert und automatisch auf zukünftige Verlängerungen angerechnet. Beispiel: $50/Monat → $20/Monat = $30 Guthaben

​

4. do_not_bill

• Die Planänderung wird sofort angewendet, aber zum Zeitpunkt der Änderung nichts berechnet. Der neue Plan, die Menge und die Add-ons können sofort genutzt werden
• Da jetzt nichts berechnet wird, erhält der Kunde bei einem Upgrade den höherwertigen Plan für den Rest des aktuellen Zyklus kostenlos. Ein Downgrade tritt sofort in Kraft, ohne Gutschrift für den ungenutzten Teil des bereits bezahlten Zyklus
• Add-ons, die über do_not_bill gewährt wurden, 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

• Beim Aufruf dieser API leitet Dodo Payments sofort eine Zahlung basierend auf der ausgewählten Proration-Option ein
• Bei prorated_immediately wird der ungenutzte Anteil des aktuellen Zyklus bei jeder Änderung, unabhängig von Upgrade oder Downgrade, als Gutschrift berechnet. Übersteigt diese Gutschrift die Zahlung für den neuen Zyklus, wird der Rest zum Guthaben der Subscription hinzugefügt. Diese Gutschriften gelten nur für diese Subscription und werden ausschließlich zur Verrechnung zukünftiger wiederkehrender Zahlungen derselben Subscription verwendet
• Bei difference_immediately entspricht der Nettobetrag immer exakt der Preisdifferenz. Bei Downgrades wird der überschüssige Betrag als Subscription-spezifisches Guthaben gespeichert, ebenso wie bei prorated_immediately
• Die Option full_immediately umgeht Gutschriftenberechnungen 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 erhalten bleibt

​

Zahlungsabwicklung

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

​

On-Demand Subscriptions

​

Wichtige Informationen zur Subscription-Abrechnung

​

Zugehörige API-Referenz