Toolkit CSV-Referenz

Dieser Leitfaden hilft Ihnen, Ihre CSV-Datei im Billing-Migrations-Toolkit anzugeben. In den folgenden Beispielen liegen alle Zeitstempel im Unix-EPOCH-Format vor. Wir stellen auch Testkundinnen und Testkunden sowie Preis-IDs zur Verfügung, die Sie in einer Sandbox verwenden können.

CSV-Voraussetzungen

Bevor Sie eine CSV-Datei erstellen oder herunterladen, sollten Sie Folgendes beachten:

Migrationsszenarien

Sie können die folgenden Migrationsszenarien auf Ihre eigene Migration anwenden, falls zutreffend:

• Abonnements mit Rabatten unterschiedlichen Preismodellen migrieren
• Abonnements mit verschiedenen Zahlungsmethoden migrieren
• Migrieren von Abonnements in verschiedenen Phasen des Abonnementzyklus
• Abonnements mit Steuern migrieren
• Abonnements mit Rabatten migrieren
• Abonnements innerhalb von Stripe migrieren
• Abonnements mit mehreren Phasen migrieren

Sie können jede von Stripe bereitgestellte CSV-Vorlage (Basis, Artikel mit mehreren Preisen, Ad-hoc-Preisgestaltung) bei Bedarf mit einem der folgenden Beispiele kombinieren.

Migrieren von Abonnements mit verschiedenen Preismodellen

Sie können Abonnements mit Pauschalpreisen migrieren, zum Beispiel einen Basic-Plan für 100 USD pro Monat oder einen Advanced-Plan für 200 USD pro Monat. Diese Abonnements können einen oder mehrere Posten haben.

Beispiel 1 (Basic): Migrieren eines Basic-Monatsabonnements über 100 USD mit der Menge 2, beginnend am 1. Januar 2024. Dieses Abonnement wird mit der Standard-Zahlungsmethode automatisch abgerechnet.

Beispiel 2 (Artikel mit mehreren Preisen): Migrieren Sie die folgenden Abonnements ab dem 1. Januar 2024, um sie automatisch mit der Standard-Zahlungsmethode zu belasten:

• Ein Basic-Monatsabonnement über 100 USD mit der Menge 2
• Ein Advanced-Monatsabonnement über 200 USD mit der Menge 1

Beispiel 3 (Basis): Migrieren Sie das folgende Abonnement ab dem 1. Januar 2024, um es automatisch mit der Standard-Zahlungsmethode zu belasten:

• Ein Basic-Monatsabonnement über 100 USD mit der Menge 2
• Eine zusätzliche Gebühr für Ad-hoc-Rechnungen in Höhe von 20 USD

Sie können Abonnements auch mit Ad-hoc-Preisen migrieren, wenn Sie keine festen Preisbeträge haben.

Beispiel 4 (Ad-hoc-Preisgestaltung): Migrieren Sie das folgende Abonnement ab dem 1. Januar 2024, um es automatisch mit der Standard-Zahlungsmethode zu belasten:

• Ein Ad-hoc-Monatsabonnement in Höhe von 153 USD mit der Menge 1

Abonnements mit verschiedenen Zahlungsmethoden migrieren

Sie können die Zahlung für die migrierten Abonnements entweder automatisch mit der standardmäßig gespeicherten Zahlungsmethode einziehen oder indem Sie eine Rechnung senden, die der Kunde/die Kundin bis zum Fälligkeitsdatum bezahlen kann.

Beispiel 1 (Basic): Migrieren eines Jahresabonnements über 500 USD mit der Menge 1, beginnend am 1. Januar 2024. Dieses Abonnement wird mit der Standard-Zahlungsmethode automatisch abgerechnet.

Beispiel 2 (Basic): Migrieren eines Jahresabonnements über 500 USD mit der Menge 1, beginnend am 1. Januar 2024. Dieses Abonnement wird über eine an den Kunden/die Kundin gesendete Rechnung mit einem Fälligkeitsdatum von 30 Tagen abgerechnet.

Migrieren von Abonnements in verschiedenen Phasen des Abonnementzyklus

Beispiel 1 (Basic): Migrieren eines Abonnements, dessen Verlängerung fällig ist. Migrieren Sie beispielsweise ein monatliches Abonnement im Wert von 100 USD mit einem Verlängerungsdatum am 1. Januar 2024. Das Abonnement wird am 1. eines jeden Monats verlängert.

• Legen Sie das start_date auf das aktuelle Verlängerungsdatum fest, damit das Abonnement sofort belastet wird.
• Setzen Sie billing_cycle_anchor auf das Datum des nächsten Verlängerungszyklus.
• Setzen Sie proration_behavior auf none.

Beispiel 2 (Basic): Migrieren eines kostenpflichtigen Abonnements, das sich in der Mitte eines Abrechnungszyklus befindet. Migrieren Sie beispielsweise ein Monatsabonnement in Höhe von 100 USD mit einem ursprünglichen Startdatum am 25. Dezember. Das Migrationsdatum ist der 1. Januar und das Abonnement verlängert sich am 25. eines jeden Monats.

• Setzen Sie backdate_start_date auf das ursprüngliche Startdatum des Abonnements.
• Setzen Sie billing_cycle_anchor auf das bevorstehende Verlängerungsdatum.
• start_date auf das Migrationsdatum setzen.
• Setzen Sie proration_behavior auf none, um zu vermeiden, dass der Kunde/die Kundin erneut belastet wird, und halten Sie das Abonnement bis zum nächsten Abrechnungszeitraum in einem geplanten Zustand.

Beispiel 3 (Basic): Migrieren von Abonnements mit Testversionen. Migrieren Sie beispielsweise ein monatliches Basisabonnement in Höhe von 100 US-Dollar ab dem 1. Januar 2024. Das Abonnement wird bis zum 31. Januar 2024 getestet. Nach Ablauf der Testphase wird das Abonnement automatisch mit der Standard-Zahlungsmethode belastet.

Beispiel 4 (Basic): Migrieren von überfälligen Abonnements. Migrieren Sie beispielsweise ein monatliches Abonnement im Wert von 100 US-Dollar mit einem letzten Zyklusstartdatum am 25. Dezember, das nicht bezahlt wurde. Migrieren Sie diesen mittleren Zyklus ab dem 1. Januar mit einem Verlängerungsdatum am 25. eines jeden Monats. Dadurch wird eine anteilige Rechnung vom 1. Januar bis zum 25. Januar erstellt, für die Stripe versuchen kann, die Zahlung einzuziehen.

Um Abonnements zu migrieren, die sich in einem aktiven Zyklus befinden, aber im vorherigen System nicht bezahlt wurden, setzen Sie proration_behavior auf create_prorations, um sofort eine Rechnung zu erstellen und Zahlungen einzuziehen. Dies geht auch in den Dunning-Ablauf von Stripe ein, wenn die Zahlung noch unbezahlt ist.

Beispiel 5: Migrieren von Abonnements, die am Ende des Zyklus gekündigt werden müssen. Nach der Migration können Sie wählen, ob diese Abonnements belastet werden sollen oder nicht, basierend auf dem Migrationszeitpunkt (in der Mitte des Zyklus oder bei der Verlängerung).

Sie werden am Ende dieses Zeitraums gekündigt. Migrieren Sie beispielsweise ein monatliches Basisabonnement in Höhe von 100 US-Dollar ab dem 1. Januar 2024. Dieses Abonnement wird automatisch am 31. Januar 2024 gekündigt.

Abonnements mit Steuern migrieren

Beispiel 1 (Basic): Migrieren Sie Abonnements, um die Steuer automatisch zu berechnen, indem Sie Stripe Tax aktivieren. Migrieren Sie zum Beispiel ein 100 USD-Monatsabonnement ab dem 1. Januar 2024, wobei Stripe Tax aktiviert ist, um die Steuer automatisch zu berechnen.

Das Migrations-Toolkit überprüft, ob Sie Stripe Tax im Voraus aktiviert haben und ob Kunden/Kundinnen die erforderlichen Felder zur automatischen Berechnung der Steuer angegeben haben. Stellen Sie sicher, dass Ihre Kunden/Kundinnen vor der Migration die erforderlichen Informationen bereitstellen.

Beispiel 2 (Basis): Migrieren Sie Abonnements und berechnen Sie Steuern mithilfe von manuellen Steuersätzen. So migrieren Sie beispielsweise ein monatliches Basisabonnement in Höhe von 100 USD ab dem 1. Januar 2024 mit einer Steuer von 10 %, die mit manuellen Steuersätzen erstellt wurde:

• Erstellen Sie eine manuelle Steuersatz über 10 % im Dashboard (Produktkatalog > Gutscheine).
• Verwenden Sie die Steuersatz-ID in der CSV-Vorlage der Migration.

Beispiel 3 (Basis): Wenn Sie einen externen Steueranbieter wie Avalara oder Vertex verwenden:

Für migrierte Abonnements, bei denen die Steuer bereits berechnet wurde, lassen Sie sowohl automatic_tax als auch default_tax_rate in der CSV-Datei leer.

Nachdem die Abonnements migriert und live sind, folgen sie automatisch den Abläufen zur Steuerintegration, die Sie für neue Abonnements in Ihrer Billing-Integration eingerichtet haben.

Abonnements mit Rabatten migrieren

Das Migrations-Toolkit unterstützt derzeit nur einen Gutschein pro Abonnement.

Beispiel 1 (Basis): Sie können Abonnements mit Rabatten migrieren, die nach der Migration angewendet werden. So migrieren Sie beispielsweise ein 100 USD-Monatsabonnement ab dem 1. Januar 2024 mit einem dauerhaften Rabatt von 10 %:

• Erstellen Sie einen Gutschein über 10 % im Dashboard (Produktkatalog > Gutscheine).
• Verwenden Sie den Gutscheinnamen in der Migrations-CSV-Datei.

Abonnements innerhalb von Stripe migrieren

Die Schritte zur Migration von Abonnements von einem Stripe-Konto zu einem anderen sind die gleichen wie bei der Migration von einem Drittanbietersystem. Verwenden Sie das Billing-Migrations-Toolkit, um Abonnements zu migrieren. Sie müssen die Abonnementdaten für Ihre CSV-Datei aus Ihrem alten Stripe-Konto exportieren.

Beispiel 1 (Basis): So erstellen Sie eine Migrations-CSV für eine Stripe-zu-Stripe-Migration:

1. Exportieren Sie die Abonnements aus dem alten Stripe-Konto über das Dashboard.
2. Verwenden Sie das folgende CSV-Beispiel als Referenz, um Felder zwischen den alten und neuen Stripe-Konten zuzuordnen.

Abonnements mit mehreren Phasen migrieren

Das Migrations-Toolkit unterstützt nicht das direkte Hinzufügen mehrerer Phasen zu einem Abonnement. Wir empfehlen die folgende Vorgehensweise:

1. Verwenden Sie das Migrations-Toolkit, um die Anfangsphase des Abonnements zu migrieren.
2. Fügen Sie nach der Migration die zusätzlichen Phasen zu den migrierten Abonnementzeitplänen hinzu. Rufen Sie dazu den Update-Endpoint auf oder verwenden Sie das Stripe Subscriptions-Dashboard.
3. Passen Sie das start_date der Migration so an, dass zwischen den geplanten und den Live-Statusänderungen genügend Zeit bleibt. So können Sie die Phasenaktualisierungen vornehmen, bevor die Abonnements live gehen.

Vollständige CSV-Spezifikation