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: Das Mandat wird autorisiert und das Abonnement aktiviert.
2. payment.succeeded: Bestätigt die erste Abbuchung. Dies 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. Es wird noch keine wiederkehrende Abbuchung vorgenommen. Die erste tatsächliche Abbuchung erfolgt erst nach Ende der Testphase.
2. Am Ende der Testphase: Der wiederkehrende Betrag wird abgebucht, 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 abgebucht wird, immer zusammen mit payment.succeeded. Enthält außerdem den aktualisierten Wert 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 Zahlung für die Verlängerung oder einer fehlgeschlagenen Abbuchung bei einer Planänderung pausiert.
• 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

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

​

Abonnements aus dem pausierten Status reaktivieren

1. Eine Abbuchung für ausstehende Beträge erstellen
2. Eine Rechnung für die Abbuchung generieren
3. Die Zahlung mit der neuen Zahlungsmethode verarbeiten
4. Das Abonnement nach erfolgreicher Zahlung in den Status active reaktivieren

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

​

Beispiel für eine Abonnementereignisnutzlast

​

Abonnementpläne ändern

​

Optionen für die anteilige Abrechnung

​

1. prorated_immediately

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

​

2. full_immediately

• Belastet den Kunden mit dem vollständigen Abonnementbetrag des neuen Plans
• Ignoriert die verbleibende Zeit und Gutschriften des vorherigen Plans
• Nützlich, wenn Sie den Abrechnungszyklus zurücksetzen oder unabhängig von der anteiligen Abrechnung den vollständigen Betrag berechnen möchten

​

3. difference_immediately

• Beim Upgrade wird dem Kunden sofort die Differenz zwischen den beiden Planbeträgen berechnet.
• Wenn der aktuelle Plan beispielsweise 30 Dollar kostet und der Kunde auf einen Plan für 80 Dollar upgradet, werden ihm sofort $50 berechnet.
• Beim Downgrade wird der nicht genutzte Betrag des aktuellen Plans als internes Guthaben hinzugefügt und automatisch auf zukünftige Verlängerungen des Abonnements angerechnet.
• Wenn der aktuelle Plan beispielsweise 50 Dollar kostet und der Kunde zu einem Plan für 20 Dollar wechselt, werden die verbleibenden $30 gutgeschrieben und auf den nächsten Abrechnungszyklus angerechnet.

​

4. do_not_bill

• Wendet die Planänderung sofort an, ohne zum Zeitpunkt der Änderung eine Abbuchung vorzunehmen.
• Der aktualisierte Plan (einschließlich Menge/Add-ons) wird bei der nächsten planmäßigen Verlängerung abgerechnet, und das ursprüngliche Abrechnungsdatum bleibt erhalten.

​

Verhalten

• Wenn Sie diese API aufrufen, leitet Dodo Payments sofort eine Abbuchung basierend auf der von Ihnen gewählten Option für die anteilige Abrechnung ein
• Wenn die Planänderung ein Downgrade ist und Sie prorated_immediately verwenden, werden Gutschriften automatisch berechnet und dem Guthaben des Abonnements hinzugefügt. Diese Gutschriften gelten nur für dieses Abonnement und werden ausschließlich zum Ausgleich zukünftiger wiederkehrender Zahlungen desselben Abonnements verwendet
• Die Option full_immediately umgeht die Gutschriftenberechnung und berechnet den vollständigen Betrag des neuen Plans

​

Verarbeitung der Abbuchung

• Die bei der Planänderung eingeleitete sofortige Abbuchung wird normalerweise in weniger als 2 Minuten verarbeitet
• Wenn diese sofortige Abbuchung 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