Subscriptions - Dodo Payments Documentation

Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.

Upgrade & Downgrade

Control plan changes with proration and quantity updates.

On‑Demand Subscriptions

Authorize a mandate now and charge later with custom amounts.

Customer Portal

Let customers manage plans, billing, and cancellations.

Subscription Webhooks

React to lifecycle events like created, renewed, and canceled.

What Are Subscriptions?

Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:

SaaS licenses: Apps, APIs, or platform access
Memberships: Communities, programs, or clubs
Digital content: Courses, media, or premium content
Support plans: SLAs, success packages, or maintenance

Key Benefits

Predictable revenue: Recurring billing with automated renewals
Flexible cycles: Monthly, annual, custom intervals, and trials
Plan agility: Proration for upgrades and downgrades
Add‑ons and seats: Attach optional, quantifiable upgrades
Seamless checkout: Hosted checkout and customer portal
Developer-first: Clear APIs for creation, changes, and usage tracking

Creating Subscriptions

Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.

Subscription product creation

Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.

Product details

Product Name (required): The display name shown in checkout, customer portal, and invoices.
Product Description (required): A clear value statement that appears in checkout and invoices.
Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
Brand: Associate the product with a specific brand for theming and emails.
Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.

Pick the most accurate tax category to ensure correct tax collection per region.

Pricing

Preistyp: Wähle Subscription (dieser Leitfaden). Alternativen sind Einzelzahlung und nutzungsbasierte Abrechnung.
Preis (erforderlich): Wiederkehrender Grundpreis mit Währung. Der Preis muss mindestens $1 (oder dem Gegenwert in der gewählten Währung) entsprechen. Beträge unter diesem Mindestwert werden nicht unterstützt, und die Subscription funktioniert nicht.
Rabatt anwendbar (%): Optionaler prozentualer Rabatt auf den Grundpreis; wird im Checkout und auf Rechnungen berücksichtigt.
Zahlung wiederholen alle (erforderlich): Intervall für Verlängerungen, z. B. jeden Monat. Wähle den Turnus (Monate oder Jahre) und die Anzahl.
Subscription-Zeitraum (erforderlich): Gesamtlaufzeit, während der die Subscription aktiv bleibt (z. B. 10 Jahre). Nach Ablauf dieses Zeitraums werden keine Verlängerungen mehr durchgeführt, sofern der Zeitraum nicht erweitert wird.
Tage des Testzeitraums (erforderlich): Lege die Länge des Testzeitraums in Tagen fest. Verwende 0, um Testzeiträume zu deaktivieren. Die erste Abbuchung erfolgt automatisch nach Ende des Testzeitraums.
Testbetrag: Optionale Vorauszahlung für einen kostenpflichtigen Testzeitraum. Lass das Feld leer für einen kostenlosen Testzeitraum. Siehe Kostenpflichtige Testzeiträume.
Add-on auswählen: Füge bis zu 10 Add-ons hinzu, die Kunden zusammen mit dem Basistarif erwerben können.

Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.

Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.

Advanced settings

Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.

Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.

Subscription Trials

Testzeiträume ermöglichen es Kunden, eine Subscription zu prüfen, bevor sie den vollständigen wiederkehrenden Preis bezahlen. Ein Testzeitraum kann kostenlos sein, wobei bis zu seinem Ende nichts berechnet wird, oder kostenpflichtig, wobei vorab ein reduzierter Betrag berechnet wird. In beiden Fällen beginnt die Berechnung des vollständigen Preises mit der ersten Verlängerung nach Ende des Testzeitraums.

Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

The trial_period_days value must be between 0 and 10,000 days.

Kostenpflichtige Testzeiträume

Testzeiträume müssen nicht kostenlos sein. Lege beim wiederkehrenden Preis eines Subscription-Produkts einen Testbetrag fest, um für das Testfenster eine reduzierte Vorauszahlung zu berechnen. Der vollständige wiederkehrende Preis wird dann mit der ersten Verlängerung berechnet.

Subscription pricing form with a trial duration and an optional trial amount for a paid trial

Kostenpflichtige Testzeiträume werden über den Checkout konfiguriert, nicht pro Subscription oder Checkout-Session:

Feld	Typ	Beschreibung
`trial_amount`	integer	Heute für den Testzeitraum berechneter Betrag in den kleineren Währungseinheiten der Preiswährung (zum Beispiel `500` für $5.00). Erfordert `trial_period_days > 0`. Für einen kostenlosen Testzeitraum weglassen oder auf `null` setzen.
`trial_apply_discounts`	boolean	Gibt an, ob Checkout-Rabattcodes die Testgebühr reduzieren. Standardmäßig `false`, sodass der Testbetrag auch dann vollständig berechnet wird, wenn ein Rabatt auf den wiederkehrenden Preis angewendet wird.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Kostenpflichtige Testzeiträume durchlaufen ebenfalls den Checkout. Der Testbetrag wird besteuert, in den Berechnungen der Checkout-Session und in der Preisgestaltung von Payment Links angezeigt, und das Adaptive Currency-Aufgeld wird je nach Währung angewendet. Der Preview-Endpunkt gibt trial_amount und trial_period_days zurück, damit du den heute fälligen Betrag anzeigen kannst, bevor die Subscription erstellt wird.

Kostenlose Testzeiträume bleiben unverändert. Wenn du Testbetrag nicht festlegst, bleibt das bestehende Verhalten erhalten: Die erste Abbuchung beträgt 0 und der vollständige Preis wird nach Ende des Testzeitraums berechnet.

Verhindern des Missbrauchs von Testzeiträumen

Missbrauch von Testzeiträumen verhindern verhindert, dass Kunden wiederholt Testzeiträume für dasselbe Unternehmen beanspruchen. Wenn diese Option aktiviert ist, wird ein Kunde, der bereits einen Testzeitraum eingelöst hat, automatisch zu einem kostenpflichtigen Kauf ohne Testzeitraum herabgestuft, anstatt einen neuen Testzeitraum zu erhalten.

Prevent Trial Misuse toggle in the Subscriptions settings tab

Aktiviere die Option im Tab Subscriptions unter Settings. Nach der Aktivierung gilt:

Kunden werden anhand der normalisierten E-Mail-Adresse abgeglichen. Dabei werden Plus-Aliase entfernt, sodass user+trial@example.com und user@example.com als dieselbe Person gelten.
Einlösungen werden bei der Aktivierung des Testzeitraums erfasst. Ein Kunde, der noch am selben Tag kündigt, hat seinen Testzeitraum daher trotzdem verbraucht.
Bestehende Kunden werden anhand ihrer früheren Testzeiträume per E-Mail nachgetragen, sodass frühere Nutzer von Testzeiträumen sofort erkannt werden.

Die Einstellung ist standardmäßig deaktiviert. Eine vollständige Liste der Subscription-Steuerungen auf Unternehmensebene findest du unter Subscription Settings.

Erkennen des Testzeitraumstatus

Derzeit gibt es kein direktes Feld zum Erkennen des Testzeitraumstatus. Die folgende Umgehungslösung erfordert das Abfragen von Zahlungen und ist daher ineffizient. Wir arbeiten an einer effizienteren Lösung.

Um festzustellen, ob sich eine Subscription mit einem kostenlosen Testzeitraum im Testzeitraum befindet, rufe die Liste der Zahlungen für die Subscription ab. Gibt es genau eine Zahlung mit dem Betrag 0, befindet sich die Subscription im Testzeitraum:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Diese Prüfung auf den Betrag null funktioniert nur bei kostenlosen Testzeiträumen. Bei einem kostenpflichtigen Testzeitraum entspricht die erste Zahlung dem Testbetrag und nicht 0. Vergleiche stattdessen die erste Zahlung mit trial_amount der Subscription oder prüfe, ob next_billing_date noch innerhalb des Testzeitraums liegt.

Testzeitraum aktualisieren

Verlängere den Testzeitraum, indem du next_billing_date aktualisierst:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

Du kannst next_billing_date nicht auf einen Zeitpunkt in der Vergangenheit setzen. Das Datum muss in der Zukunft liegen.

Änderungen an Subscription-Tarifen

Tarifänderungen ermöglichen Upgrades oder Downgrades von Subscriptions, die Anpassung von Mengen oder die Migration zu anderen Produkten. Je nach ausgewähltem Proration-Modus kann eine Änderung eine sofortige Belastung auslösen, ein Guthaben erstellen oder keine Anpassung der Abrechnung vornehmen.

Du kannst Subscription-Tarife ändern und das nächste Abrechnungsdatum direkt über das Dodo Payments-Dashboard aktualisieren. So lassen sich Subscriptions für Supportanfragen, werbliche Upgrades oder Tarifmigrationen schnell anpassen, ohne API-Aufrufe durchzuführen.

Self-Service-Tarifänderungen aktivieren: Sollen Kunden ihre eigenen Subscriptions über das Customer Portal upgraden oder downgraden können? Füge deine Subscription-Produkte einer Product Collection hinzu und aktiviere in deinen Subscription Settings die Option „Allow Subscription Updates“.

Product Collections

Gruppiere verwandte Produkte in Collections, um nahtlose Upgrade-/Downgrade-Pfade im Customer Portal zu ermöglichen.

Proration-Modi

Wähle aus, wie Kunden bei Tarifänderungen abgerechnet werden:

Kurzer Vergleich der vier Proration-Modi:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade	Anteilig berechneter Betrag für verbleibende Tage	Vollständige Preisdifferenz wird berechnet	Vollständiger Preis des neuen Tarifs wird berechnet	Keine Belastung – sofortiger Wechsel
Downgrade	Anteiliges Guthaben für verbleibende Tage	Vollständige Preisdifferenz als Guthaben	Kein Guthaben, vollständige Belastung	Kein Guthaben – sofortiger Wechsel
Abrechnungszyklus	Wird auf heute zurückgesetzt	Wird auf heute zurückgesetzt	Wird auf heute zurückgesetzt	Bleibt gleich
Am besten geeignet für	Faire zeitbasierte Abrechnung	Einfache Tarifstufenänderungen	Zurücksetzen von Abrechnungszyklen	Kostenlose Migrationen oder Kulanzwechsel

`prorated_immediately`

Berechnet einen anteiligen Betrag auf Grundlage der verbleibenden Zeit im aktuellen Abrechnungszyklus. Geeignet für eine faire Abrechnung, die ungenutzte Zeit berücksichtigt.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

`difference_immediately`

Berechnet die Preisdifferenz sofort (Upgrade) oder fügt Guthaben für zukünftige Verlängerungen hinzu (Downgrade). Geeignet für einfache Upgrade-/Downgrade-Szenarien.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Guthaben aus Downgrades mit difference_immediately ist auf die Subscription beschränkt und wird automatisch auf zukünftige Verlängerungen angewendet. Es unterscheidet sich von den Berechtigungen der Credit-Based Billing.

Wenn ein Kunde mit difference_immediately downgradet, wird der ungenutzte Wert zu einem auf die Subscription beschränkten Guthaben, das zukünftige Verlängerungen automatisch verrechnet:

`full_immediately`

Berechnet sofort den vollständigen Betrag des neuen Tarifs und ignoriert die verbleibende Zeit. Geeignet zum Zurücksetzen von Abrechnungszyklen.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

`do_not_bill`

Wechselt ohne Anpassung der Abrechnung zum neuen Tarif. Es gibt weder Proration-Belastungen noch Guthaben – der Kunde wechselt einfach zum neuen Tarif. Geeignet für Kulanzmigrationen, kostenlose Tarifwechsel oder Situationen, in denen du die Kostendifferenz übernehmen möchtest.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Szenario: Ein Kunde im Basic-Tarif (

30/Monat) führt am 16. Tag eines 30-tägigen Zyklus mit `prorated_immediately` ein Upgrade auf Pro (

80/Monat) durch.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Die nächste Verlängerung erfolgt am 15. Februar (16. Januar + 30 Tage): $80.00/Monat.

Ausführlichere Berechnungsbeispiele und Sonderfälle findest du in unserem vollständigen Upgrade-&-Downgrade-Leitfaden.

Example: Downgrade credit calculation

Szenario: Ein Kunde im Pro-Tarif (

80/Monat) downgradet mit `difference_immediately` auf Starter (

20/Monat).

Credit = Old plan − New plan = $80 − $20 = $60.00

Das Guthaben von $60 wird automatisch auf zukünftige Verlängerungen angewendet:

Verlängerung 1: $20 −$ 20 (Guthaben) = ** $0.00** (verbleibendes Guthaben:$ 40)
Verlängerung 2: $20 −$ 20 (Guthaben) = ** $0.00** (verbleibendes Guthaben:$ 20)
Verlängerung 3: $20 −$ 20 (Guthaben) = $0.00 (Guthaben aufgebraucht)
Verlängerung 4: $20.00 (vollständiger Preis)

Mehr darüber, wie Guthaben verwaltet wird, erfährst du im Upgrade-&-Downgrade-Leitfaden.

Tarifänderungen mit Add-ons

Ändere Add-ons bei Tarifänderungen. Add-ons werden in die Proration-Berechnungen einbezogen:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

Tarifänderungen lösen sofortige Belastungen aus. Fehlgeschlagene Belastungen können die Subscription in den Status on_hold versetzen. Verfolge Änderungen über subscription.plan_changed-Webhook-Events.

Tarifänderungen anzeigen

Zeige vor der Bestätigung einer Tarifänderung die genaue Belastung und die daraus resultierende Subscription an:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Zeige Tarifänderungen an, bevor du sie bestätigst.

Subscription-Status

Eine Subscription durchläuft während ihrer Laufzeit eine festgelegte Reihe von Status. Diese Tabelle dient als Referenz für jeden Status, seine Ursache und die Möglichkeit bzw. Vorgehensweise zur Wiederherstellung.

Status	Bedeutung	Wiederherstellbar?	Wiederherstellung / nächster Schritt
`pending`	Die Subscription wird erstellt oder verarbeitet	—	Warte auf `subscription.active` (oder `subscription.failed`)
`active`	Die Subscription ist aktiv und wird automatisch verlängert	—	Keine Aktion erforderlich
`on_hold`	Eine Zahlung für die Verlängerung (oder eine Tarifänderung) ist fehlgeschlagen; die Subscription ist pausiert	Ja	Aktualisiere die Zahlungsmethode, um sie zu reaktivieren – automatisch über Payment Retries und Dunning oder manuell über die Update Payment Method API
`cancelled`	Die Subscription wurde gekündigt und wird nicht verlängert	Nur erneuter Kauf	Der Kunde muss eine neue Subscription starten; Dunning kann zu einem erneuten Kauf auffordern
`failed`	Die Erstellung der Subscription ist fehlgeschlagen (das initiale Mandat oder die Zahlung war nicht erfolgreich)	Nein – endgültig	Der Kunde muss eine neue Subscription mit einer funktionierenden Zahlungsmethode erstellen
`expired`	Die Subscription hat das Ende ihrer Laufzeit erreicht	—	Der Kunde muss bei Bedarf eine neue Subscription starten

on_hold und failed werden häufig verwechselt. on_hold ist ein wiederherstellbarer Status für eine bereits aktive Subscription, deren Verlängerung fehlgeschlagen ist. failed ist ein endgültiger Status, der nur auftritt, wenn die initiale Erstellung der Subscription fehlschlägt – die Subscription kann nicht reaktiviert werden.

Zustandsautomat

Status „On Hold“

Eine Subscription wechselt in den Status on_hold, wenn:

Eine Zahlung für die Verlängerung fehlschlägt (unzureichendes Guthaben, abgelaufene Karte usw.)
Eine Belastung für eine Tarifänderung fehlschlägt
Die Autorisierung der Zahlungsmethode fehlschlägt

Wenn sich eine Subscription im Status on_hold befindet, wird sie nicht automatisch verlängert. Du musst die Zahlungsmethode aktualisieren, um die Subscription zu reaktivieren.

Aus „On Hold“ reaktivieren

Um eine Subscription aus dem Status on_hold zu reaktivieren, aktualisiere die Zahlungsmethode. Dadurch wird automatisch:

eine Belastung für die offenen Beträge erstellt
eine Rechnung erzeugt
die Zahlung über die neue Zahlungsmethode verarbeitet
die Subscription nach erfolgreicher Zahlung in den Status active reaktiviert

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  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:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Nach der erfolgreichen Aktualisierung der Zahlungsmethode für eine Subscription im Status on_hold erhältst du die Webhook-Events payment.succeeded gefolgt von subscription.active.

Webhook-Events nach Übergang

Jeder Übergang erzeugt einen Webhook, sodass du die Logik für Berechtigungen ohne Polling steuern kannst:

Übergang	Event
Subscription aktiviert	`subscription.active`
Verlängerung erfolgreich	`subscription.renewed`
Verlängerung fehlgeschlagen → pausiert	`subscription.on_hold`
Erstellung fehlgeschlagen	`subscription.failed`
Tarif hoch- oder herabgestuft	`subscription.plan_changed`
Gekündigt	`subscription.cancelled`
Laufzeit beendet	`subscription.expired`
Beliebige Feldänderungen	`subscription.updated`

Subscription Webhook Payloads

Sieh dir das vollständige Payload-Schema für Subscription-Lifecycle-Events an.

API-Verwaltung

Create subscriptions

Verwende POST /subscriptions, um Subscriptions programmgesteuert aus Produkten mit optionalen Testzeiträumen und Add-ons zu erstellen.

API Reference

Sieh dir die API zum Erstellen einer Subscription an.

Update subscriptions

Verwende PATCH /subscriptions/{id}, um Mengen zu aktualisieren, die Kündigung zum nächsten Abrechnungsdatum festzulegen oder Metadaten zu ändern.

API Reference

Erfahre, wie du Subscription-Details aktualisierst.

Change plans (proration)

Ändere das aktive Produkt und die Mengen mit Proration-Steuerungen.

API Reference

Sieh dir die Optionen für Tarifänderungen an.

On‑demand charges

Bei On-Demand-Subscriptions kannst du bestimmte Beträge nach Bedarf berechnen.

API Reference

Eine On-Demand-Subscription belasten.

List and retrieve

Verwende GET /subscriptions, um alle Subscriptions aufzulisten, und GET /subscriptions/{id}, um eine einzelne abzurufen.

API Reference

Sieh dir die APIs zum Auflisten und Abrufen an.

Usage history

Rufe erfasste Nutzung für nutzungsbasierte oder hybride Preismodelle ab.

API Reference

Siehe die API für die Nutzungshistorie.

Update payment method

Aktualisiere die Zahlungsmethode für eine Subscription. Bei aktiven Subscriptions wird die Zahlungsmethode für zukünftige Verlängerungen aktualisiert. Bei Subscriptions im Status on_hold wird die Subscription reaktiviert, indem eine Belastung für die offenen Beträge erstellt wird.Beim Erstellen eines neuen Links für Zahlungsmethoden (dem Anfragetyp New) kannst du allowed_payment_method_types übergeben, um einzuschränken, welche Zahlungsmethoden der Kunde auf dieser Seite sieht. Kunden sehen niemals eine Methode, die nicht in der Liste enthalten ist. Die Aufnahme einer Methode garantiert jedoch nicht, dass sie angezeigt wird, da ihre Verfügbarkeit weiterhin von Faktoren wie dem Standort des Kunden und deinen Unternehmenseinstellungen abhängt.

API Reference

Erfahre, wie du Zahlungsmethoden aktualisierst und Subscriptions reaktivierst.

Häufige Anwendungsfälle

SaaS und APIs: Gestufter Zugriff mit Add-ons für Sitze oder Nutzung
Inhalte und Medien: Monatlicher Zugriff mit einführenden Testzeiträumen
B2B-Supporttarife: Jahresverträge mit Premium-Support-Add-ons
Tools und Plugins: Lizenzschlüssel und versionierte Releases

Integrationsbeispiele

Checkout-Sessions (Subscriptions)

Füge beim Erstellen von Checkout-Sessions dein Subscription-Produkt und optionale Add-ons hinzu:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

Tarifänderungen mit Proration

Upgrade oder downgrade eine Subscription und steuere das Proration-Verhalten:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Kündigung zum nächsten Abrechnungsdatum

Plane eine Kündigung, die am Ende des aktuellen Abrechnungszeitraums wirksam wird:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

Subscription-Zeitraum verlängern

Verlängere die Laufzeit einer Subscription, indem du einen neuen subscription_period_count und subscription_period_interval an PATCH /subscriptions/{id} übergibst. Das Ablaufdatum der Subscription wird anhand der neuen Anzahl und des neuen Intervalls neu berechnet – zum Beispiel, um einem Kunden zusätzliche Zeit in seinem aktuellen Tarif zu gewähren:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

Der Zeitraum einer Subscription kann nur verlängert, niemals verkürzt werden.

On-Demand-Subscriptions

Erstelle eine On-Demand-Subscription und berechne Gebühren später nach Bedarf:

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Zahlungsmethode für aktive Subscription aktualisieren

Aktualisiere die Zahlungsmethode für eine aktive Subscription:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

Subscription aus „on_hold“ reaktivieren

Reaktiviere eine Subscription, die aufgrund einer fehlgeschlagenen Zahlung pausiert wurde:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Subscriptions mit RBI-konformen Mandaten

UPI- und indische Karten-Subscriptions unterliegen den Bestimmungen der RBI (Reserve Bank of India) und bestimmten Mandatsanforderungen:

Mandatslimits

Typ und Betrag des Mandats hängen von der wiederkehrenden Belastung deiner Subscription ab:

Belastungen unterhalb des Mandatsgrenzwerts (standardmäßig ₹15,000): Wir erstellen ein On-Demand-Mandat über den Grenzwert. Der Subscription-Betrag wird entsprechend der Subscription-Frequenz regelmäßig bis zur Höhe des Mandatslimits berechnet.
Belastungen in Höhe des Mandatsgrenzwerts oder darüber: Wir erstellen ein Subscription-Mandat (oder On-Demand-Mandat) über den genauen Subscription-Betrag.

Der Mandatsgrenzwert kann pro Merchant oder pro Anfrage über mandate_min_amount_inr_paise (INR-Paise) konfiguriert werden. Der bei der Bank registrierte Betrag ist max(mandate_floor, billing_amount) – dadurch wird der Grenzwert effektiv zur kundenseitigen Autorisierungsobergrenze, sobald die Abrechnung niedriger ist. Ausführliche Informationen zu RBI-konformen Mandaten und dem konfigurierbaren Mandatsgrenzwert für indische Zahlungsmethoden findest du auf der Seite India Payment Methods.

Hinweise zu Upgrades und Downgrades

Wichtig: Berücksichtige bei Upgrades oder Downgrades von Subscriptions sorgfältig die Mandatslimits:

Wenn ein Upgrade oder Downgrade zu einem Belastungsbetrag von mehr als Rs 15,000 führt und das bestehende On-Demand-Zahlungslimit überschreitet, kann die Transaktionsbelastung fehlschlagen.
In solchen Fällen muss der Kunde möglicherweise seine Zahlungsmethode aktualisieren oder die Subscription erneut ändern, um ein neues Mandat mit dem korrekten Limit einzurichten.

Autorisierung hoher Belastungen

Für Subscription-Belastungen von Rs 15,000 oder mehr gilt:

Die Bank fordert den Kunden zur Autorisierung der Transaktion auf.
Wenn der Kunde die Transaktion nicht autorisiert, schlägt sie fehl und die Subscription wird pausiert.

48-stündige Verarbeitungsverzögerung

Verarbeitungszeitplan: Wiederkehrende Belastungen bei indischen Karten und UPI-Subscriptions folgen einem besonderen Verarbeitungsmuster:

Belastungen werden am geplanten Datum entsprechend der Subscription-Frequenz initiiert.
Die tatsächliche Abbuchung vom Konto des Kunden erfolgt erst 48 Stunden nach Initiierung der Zahlung.
Dieses 48-Stunden-Fenster kann sich je nach Antworten der Bank-API um weitere 2–3 Stunden verlängern.

Zeitraum für die Mandatskündigung

Während des 48-stündigen Verarbeitungsfensters gilt:

Kunden können das Mandat über ihre Banking-Apps kündigen.
Wenn ein Kunde das Mandat in diesem Zeitraum kündigt, bleibt die Subscription aktiv (dies ist ein Sonderfall, der nur bei indischen Karten- und UPI-AutoPay-Subscriptions auftritt).
Die tatsächliche Abbuchung kann jedoch fehlschlagen. In diesem Fall versetzen wir die Subscription in den Status On Hold.

Behandlung von Sonderfällen: Wenn du Kunden unmittelbar bei Initiierung der Belastung Vorteile, Guthaben oder Subscription-Nutzung gewährst, musst du dieses 48-Stunden-Fenster in deiner Anwendung angemessen berücksichtigen. Erwäge:

Die Aktivierung von Vorteilen bis zur Zahlungsbestätigung zu verzögern
Kulanzzeiträume oder vorübergehenden Zugriff zu implementieren
den Subscription-Status auf Mandatskündigungen zu überwachen
pausierte Subscription-Status in der Anwendungslogik zu behandeln

Überwache Subscription-Webhooks, um Änderungen des Zahlungsstatus zu verfolgen und Sonderfälle zu behandeln, in denen Mandate während des 48-Stunden-Fensters gekündigt werden.

Best Practices

Beginne mit klaren Tarifstufen: 2–3 Tarife mit deutlichen Unterschieden
Kommuniziere die Preisgestaltung: Zeige Summen, Proration und die nächste Verlängerung
Setze Testzeiträume gezielt ein: Konvertiere mit Onboarding, nicht nur mit Zeit
Nutze Add-ons: Halte Basistarife einfach und biete zusätzliche Funktionen als Upsell an
Teste Änderungen: Validiere Tarifänderungen und Proration im Testmodus

Subscriptions sind eine flexible Grundlage für wiederkehrende Umsätze. Beginne einfach, teste gründlich und passe dein Angebot anhand von Kennzahlen zu Akzeptanz, Abwanderung und Expansion iterativ an.

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Kostenpflichtige Testzeiträume

​Verhindern des Missbrauchs von Testzeiträumen

​Erkennen des Testzeitraumstatus

​Testzeitraum aktualisieren

​Änderungen an Subscription-Tarifen

Product Collections

​Proration-Modi

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Tarifänderungen mit Add-ons

​Tarifänderungen anzeigen

Preview Change Plan API

​Subscription-Status

​Zustandsautomat

​Status „On Hold“

​Aus „On Hold“ reaktivieren

​Webhook-Events nach Übergang

Subscription Webhook Payloads

​API-Verwaltung

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Häufige Anwendungsfälle

​Integrationsbeispiele

​Checkout-Sessions (Subscriptions)

​Tarifänderungen mit Proration

​Kündigung zum nächsten Abrechnungsdatum

​Subscription-Zeitraum verlängern

​On-Demand-Subscriptions

​Zahlungsmethode für aktive Subscription aktualisieren

​Subscription aus „on_hold“ reaktivieren

​Subscriptions mit RBI-konformen Mandaten

​Mandatslimits

​Hinweise zu Upgrades und Downgrades

​Autorisierung hoher Belastungen

​48-stündige Verarbeitungsverzögerung

​Zeitraum für die Mandatskündigung

​Best Practices

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Kostenpflichtige Testzeiträume

Verhindern des Missbrauchs von Testzeiträumen

Erkennen des Testzeitraumstatus

Testzeitraum aktualisieren

Änderungen an Subscription-Tarifen

Proration-Modi

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Tarifänderungen mit Add-ons

Tarifänderungen anzeigen

Subscription-Status

Zustandsautomat

Status „On Hold“

Aus „On Hold“ reaktivieren

Webhook-Events nach Übergang

API-Verwaltung

Häufige Anwendungsfälle

Integrationsbeispiele

Checkout-Sessions (Subscriptions)

Tarifänderungen mit Proration

Kündigung zum nächsten Abrechnungsdatum

Subscription-Zeitraum verlängern

On-Demand-Subscriptions

Zahlungsmethode für aktive Subscription aktualisieren

Subscription aus „on_hold“ reaktivieren

Subscriptions mit RBI-konformen Mandaten

Mandatslimits

Hinweise zu Upgrades und Downgrades

Autorisierung hoher Belastungen

48-stündige Verarbeitungsverzögerung

Zeitraum für die Mandatskündigung

Best Practices