Abonnementpläne

Verwenden Sie Abonnementpläne, um Änderungen an Abonnements im Verlauf der Zeit zu automatisieren. Sie können Abonnements direkt über einen Zeitplan erstellen oder einen Zeitplan zu einem bestehenden Abonnement hinzufügen. Verwenden Sie das Attribut phases, um die am Abonnement vorzunehmenden Änderungen zu definieren. Sobald ein Zeitplan alle Phasen beendet hat, wird er gemäß seinem end_behavior abgeschlossen.

Folgende Änderungen könnten für Sie interessant sein:

• Starten eines Abonnements an einem Datum in der Zukunft
• Rückdatieren eines Abonnements auf ein Datum in der Vergangenheit
• Herauf- oder Herabstufen eines Abonnements

Abonnementpläne sind sowohl im Stripe Billing-Dashboard als auch in der API verfügbar. Im folgenden kurzen Video erklären wir Ihnen die Funktionsweise von Abonnementplänen im Dashboard:

In den folgenden Abschnitten der Dokumentation werden Abonnementpläne ausführlicher erläutert. Auf der Seite „Anwendungsszenarien“ finden Sie eine Reihe von Beispielen.

Phasen

Verwenden Sie beim Erstellen eines Abonnementplans das Attribut phases, um zu definieren, wann Änderungen auftreten und welche Eigenschaften des Abonnements geändert werden sollen. Zum Beispiel könnten Sie einen Gutschein über 50 % Rabatt für die ersten drei Monate eines Abonnements anbieten. In diesem Szenario würden Sie einen Abonnementplan mit einer dreimonatigen ersten Phase erstellen, in der der Gutschein über 50 % Rabatt angewendet wird. In der zweiten Phase würde das Abonnement wieder auf den regulären Preis angepasst und der Gutschein wieder entfernt werden. Phasen müssen fortlaufend ausgeführt werden, wodurch zu einem bestimmten Zeitpunkt immer nur eine Phase aktiv sein kann. Sie können bis zu 10 Phasen haben.

Die Länge einer Phase festlegen

Das Intervall eines Preises bestimmt, wie häufig ein Abonnement abgerechnet werden soll. Zum Beispiel wird ein monatliches Intervall pro Monat abgerechnet. Phasen haben ein iterations-Attribut, mit dem Sie die Dauer einer Phase festlegen können. Um die Länge der Phase zu bestimmen, multiplizieren Sie diesen Wert mit dem Intervall. Wenn bei einem Abonnementplan ein Preis mit einem monatlichen Intervall verwendet wird und Sie iterations=2 festgelegt haben, erstreckt sich die Phase über zwei Monate.

Das end_date einer Phase muss dem start_date der nächsten Phase entsprechen. Durch die Verwendung von iterations werden start_date und end_date automatisch ordnungsgemäß angegeben. Diese Werte können zwar auch manuell festgelegt werden, aber Stripe empfiehlt stattdessen die Verwendung von iterations. Da das manuelle Festlegen des Start- und Enddatums anfällig für Fehler ist, sollten Sie es nur für erweiterte Anwendungsszenarien verwenden.

In die nächste Phase wechseln

Phasenübergänge erfolgen automatisch, nachdem das end_date für eine Phase erreicht wurde. Wenn eine Phase startet, aktualisiert Stripe das Abonnement entsprechend den Attributen der nächsten Phase. Sie können optional die anteilmäßige Verrechnung aktivieren, um den Nutzerinnen und Nutzern die nicht genutzten Artikel oder die nicht genutzte Zeit auf dem Abonnementplan gutzuschreiben.

Verhalten bei anteilmäßiger Verrechnung

Es gibt zwei verschiedene Einstellungen für das Verhalten bei anteilmäßiger Verrechnung, die steuern, wie Stripe Abrechnungsanpassungen bei Änderungen des Abonnementplans handhabt:

1. Aktualisierung des Verhaltens bei anteilmäßiger Verrechnung planen: Der übergeordnete Parameter proration_behavior steuert, wie anteilmäßige Verrechnungen bei der Aktualisierung eines Abonnementplans so gehandhabt werden, dass sich dies auf die Abrechnungskonfiguration der aktuellen Phase auswirkt (z. B. durch Änderung von Preisen oder Mengen).

2. Verhalten bei der anteilsmäßigen Verrechnung bei Phasenübergängen: Jede Phase hat ihr eigenes proration_behavior-Attribut, das steuert, wie Stripe beim Übergang in diese Phase mit anteilsmäßigen Verrechnungen umgeht.

Aktualisierung des Verhaltens bei anteilmäßiger Verrechnung planen

Wenn Sie einen Abonnementplan aktualisieren und die Abrechnungskonfiguration der current_phase ändern, können Sie über den Top-Level-Parameter proration_behavior steuern, wie anteilige Verrechnungen gehandhabt werden.

Dieser Parameter funktioniert ähnlich wie der in der API zum Aktualisieren eines Abonnements und akzeptiert die folgenden Werte:

• (Standard) create_prorations: Generieren Sie anteilmäßige Anpassungen für Abrechnungsänderungen.
• none: Für die Aktualisierung werden keine anteilmäßigen Verrechnungen erstellt.
• always_invoice: Generieren Sie anteilmäßige Verrechnungen und finalisieren Sie eine Rechnung sofort.

Änderungen an nicht abrechnungsrelevanten Feldern (wie Metadaten) generieren unabhängig von dieser Einstellung keine anteilsmäßigen Verrechnungen.

Verhalten bei der anteilsmäßigen Verrechnung bei Phasenübergängen

Jede Phase kann ihre eigene proration_behavior-Einstellung definieren, um zu steuern, was passiert, wenn das Abonnement in diese Phase eintritt. Diese Einstellung gilt speziell für anteilige Verrechnungen, die während der Phasenübergänge generiert werden, und wird als Feld in der Phase gespeichert.

Wenn zum Beispiel phases[1] die Menge zu Beginn von 1 auf 3 erhöht, bestimmt das proration_behavior von phases[1], wie diese anteiligen Verrechnungen beim Übergang von phases[0] zu phases[1] gehandhabt werden:

• (Standard) create_prorations: Generieren Sie ausstehende Rechnungsposten für Abrechnungsänderungen.
• none: Beim Eintritt in diese Phase werden keine anteilsmäßigen Verrechnungen erstellt.
• always_invoice: Generieren Sie anteilsmäßige Verrechnungen und erstellen Sie sofort eine Rechnung, wenn Sie diese Phase beginnen.

Wenn Sie ändern müssen, wie bei einem zukünftigen Phasenübergang anteilsmäßige Verrechnungen gehandhabt werden, aktualisieren Sie die Einstellung proration_behavior für die zukünftige Phase, bevor diese aktiv wird.

Testzeiträume verwenden

Sie können Testzeiträume hinzufügen, indem Sie trial end für eine Phase festlegen. Wenn die gesamte Phase ein Test sein soll, legen Sie den Wert von trial_end auf den gleichen Zeitpunkt wie das end_date der Phase fest. Wenn nur ein Teil der Phase als Testzeitraum gelten soll, können Sie den Wert für trial_end auch auf einen Zeitpunkt vor dem end_date festlegen. Beim Terminieren von Aktualisierungen müssen Sie das neue trial_end für jede Phase angeben.

Einen Zeitplan abschließen

Abonnementpläne enden nach dem Beenden der letzten Phase. Zu diesem Zeitpunkt bleibt das Abonnement bestehen und ist nicht mehr mit dem Zeitplan verknüpft. Wenn Sie ein Abonnement nach Ende der letzten Phase eines Zeitplans kündigen möchten, können Sie end_behavior auf cancel festlegen. Das cancel_on_date des Abonnements wird erst festgelegt, wenn das Abonnement in die letzte Phase übergeht.

Phasen-Attribute übernehmen

Wenn eine Phase aktiv wird, werden alle in der Phase festgelegten Attribute auch für das Abonnement festgelegt. Die Attribute bleiben nach dem Ende der Phase unverändert, es sei denn, sie werden durch die folgende Phase geändert oder der Zeitplan hat keine Standardeinstellung. Sie können einige Attribute sowohl für Zeitpläne als auch für Phasen festlegen. Dazu gehören unter anderem:

Wenn eines der Attribute im Zeitplan definiert ist, wird es zur Standardeinstellung für alle Phasen. Wenn die gleiche Eigenschaft sowohl im Zeitplan als auch in der Phase definiert ist, überschreibt das Phasen-Attribut das Zeitplan-Attribut. Dieses Verfahren wird weiter unten erläutert:

Metadaten für Phasen verwenden

Sie können Phasen in Abonnementplänen verwenden, um Metadaten für das zugrunde liegende Abonnement festzulegen. Auf diese Weise können Sie die Metadaten eines Abonnements mit geplanten Aktualisierungen steuern.

{
  ...
  "object": "subscription_schedule",
  "phases": [
    { // Phase 1
      ...
      "metadata": {
        "channel": "self-serve",
        "region": "apac",
        "upsell-products": "alpha"
      },
    },
    { // Phase 2
      ...
      "metadata": {
        "channel": "sales",
        "churn-risk": "high",
        "upsell-products": ""
      },
    }
  ],
}

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "self-serve",
    "region": "apac",
    "upsell-products": "alpha"
  },
}

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "sales",
    "region": "apac",
    "churn-risk": "high"
  }
}

Erfahren Sie, wie Sie Abonnementmetadaten in Abonnementrechnungen kopieren.

Abonnementpläne erstellen

Die Seite „Anwendungsszenarien“ enthält ausführliche Beispiele. Im Folgenden finden Sie ein einfaches Beispiel für die Erstellung eines Abonnementplans mit einer Kundin/einem Kunden. Wenn Sie einen Zeitplan so erstellen, wird automatisch auch das Abonnement erstellt.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=cus_GBHHxuvBvO26Ea \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]"=price_1GqNdGAJVYItwOKqEHb \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][iterations]"=12

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d from_subscription=sub_GB98WOvaRAWPl6

Abonnementpläne aktualisieren

Sie können nur die aktuellen und zukünftigen Phasen von Abonnementplänen aktualisieren.

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=2 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=1580544000

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=now \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][start_date]"=now \
  -d "phases[1][end_date]"=1580544000

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=1580544000 \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][iterations]"=1

Eine Rechnung anzeigen

Verwenden Sie den Parameter schedule unter Vorschau erstellen, um eine Vorschau der nächsten Rechnung für ein Abonnement zu anzuzeigen.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d schedule=
{{SUBSCRIPTION_SCHEDULE_ID}}

Vorschau der Erstellung und Aktualisierung von Zeitplänen anzeigen

Verwenden Sie die Parameter in schedule_details, um eine Vorschau auf die Erstellung oder Aktualisierung eines Abonnementplans zu erhalten. Übergeben Sie einen vorhandenen schedule-Parameter, um Stripe mitzuteilen, ob es sich um eine Erstellung oder eine Aktualisierung handelt.

Übergeben Sie alle aktuellen und zukünftigen Phasen, die Sie in der Vorschau anzeigen.

Der folgende Code zeigt beispielsweise eine Vorschau der ersten Rechnung für einen Abonnementzeitplan mit der Phase 1 an, der über 12 Abrechnungszeiträume dauert.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "schedule_details[phases][0][start_date]"=now \
  -d "schedule_details[phases][0][items][0][price]"=
{{PRICE_ID}} \
  -d "schedule_details[phases][0][items][0][quantity]"=1 \
  -d "schedule_details[phases][0][iterations]"=12

Weitere Überlegungen

Abonnementpläne unterliegen in der Regel denselben Einschränkungen wie Abonnements, führen jedoch auch einige eigene Einschränkungen ein. Darüber hinaus kann die Interaktion zwischen Abonnementplänen und Abonnements zu unerwartetem Verhalten führen. Lesen Sie die folgenden Abschnitte, um Einschränkungen, das Produktverhalten und allgemeine Best Practices bei der Verwendung von Abonnementplänen zu verstehen.

Einschränkungen

• Sie können nur bis zu 10 aktuelle oder zukünftige Phasen gleichzeitig in einem Abonnementplan definieren. Vergangene Phasen werden nicht auf dieses Limit angerechnet.
• Abonnementplanphasen unterliegen denselben Einschränkungen wie Abonnements, wenn Abonnementplanphasen mit mehreren Elementen erstellt werden.

Dashboard-Beschränkungen

Sie können Abonnementpläne ohne Code im Dashboard erstellen und aktualisieren.

Im Dashboard können Sie die folgenden Einstellungen global für alle Phasen festlegen, jedoch nicht pro Phase:

• Abrechnungsschwellen
• Zahlungsmethoden
• Rechnungseinstellungen
• Abonnementbeschreibung
• Testtage (nur in der ersten Phase möglich)

Die folgenden Parameter werden im Dashboard nicht unterstützt:

• Metadaten des Abonnementplan
• Metadaten des Phasenelements
• Währung
• Alle Connect-Parameter

Abonnement wird aktualisiert, wenn ein Zeitplan angehängt ist

Verwenden Sie Abonnementpläne, um Abonnements automatisch zu ändern, wenn die Zeit verstrichen ist und die nächste Phase des Zeitplans beginnt. Einige Änderungen, die Sie direkt am Abonnement vornehmen, werden auf die Phasen des Abonnementplans übertragen, andere jedoch nicht. Das bedeutet, dass alle Änderungen, die Sie direkt am Abonnement vornehmen, beim Eintritt in die nächste Phase durch den Abonnementplan überschrieben werden können.

Wenn Sie Änderungen an einem Abonnement planen, befolgen Sie diese Best Practices:

• Wenn ein Abonnementplan an ein Abonnement angefügt ist, verwenden Sie zum Ändern des Abonnements die Subscription Schedule AP anstelle der Subscriptions API.
• Speichern Sie die Abonnement-Zeitplan-IDs neben der Abonnement-ID für zukünftige API-Updates. Die Abonnementzeitplan-ID wird zurückgegeben, wenn Sie die API verwenden, um sie zu erstellen oder über den Webhook subscription_schedule.created, wenn Stripe sie automatisch erstellt, zum Beispiel wenn ein Kunde/eine Kundin ein Downgrade im Kundenportal geplant hat.
• Verwerfen Sie die Abonnementplan-IDs, wenn ein Abonnementplan veröffentlicht wird. Sie können Änderungen an den Abonnements direkt vornehmen oder einen neuen Abonnementplan erstellen. Die Abonnementplan-ID wird zurückgegeben, wenn sie mit der API oder über das Webhook-Ereignis subscription_schedule .released freigegeben wird, wenn der Abonnementplan freigegeben wird.
• Verwenden Sie möglichst das Dashboard, um Abonnements zu ändern, wodurch alle angehängten Abonnementpläne automatisch aktualisiert werden.

Insbesondere wenn Sie eines der folgenden Abonnementattribute direkt in einem Abonnement ändern, wird mit dieser Aktion möglicherweise automatisch eine neue Abonnementplanphase erstellt:

• discounts
• tax_rates
• items
• trial_end, trial_settings, trial_start
• application_fee_percent
• add_invoice_items
• automatic_tax

Angenommen, Sie haben ein Abonnement mit zwei Posten. Dem Abonnement ist ein Abonnementplan mit einer einzigen Phase beigefügt, der den aktuellen Status des Abonnements widerspiegelt. Wenn Sie die API verwenden, um einen der Posten zu löschen, wird die Phase des angehängten Abonnementplans automatisch in zwei Phasen unterteilt:

1. Die Phase, die gerade zu Ende ging und zwei Abonnementposten hatte
2. Die neue Phase, die nur einen Posten im Abonnement enthält

Wenn die Phasen des Abonnementplans automatisch aufgeteilt werden, werden die folgenden Eigenschaften von der aktuellen Phase in die neue Phase kopiert:

• proration_behavior
• billing_cycle_anchor
• cancel_at_period_end
• description
• metadata
• pause_collection

Darüber hinaus kann Stripe die folgenden Top-Level-Abonnementattribute in den Abonnementplan oder seine default_settings kopieren:

Aktualisierungen der metadata von Abonnements werden nicht an einen angehängten Abo-Zeitplan weitergegeben.