Nutzung für Abrechnungszwecke aufzeichnen
Notiz
Wir haben unseren nutzungsbasierten Abrechnungsprozess aktualisiert. Informationen zu unseren vorherigen Richtlinien finden Sie in unserer ältere Dokumentation für nutzungsbasierte Abrechnung.
Zähler konfigurieren
Stellen Sie sicher, dass Sie Ihren Zähler richtig konfiguriert haben, bevor Sie die Nutzung aufzeichnen. Zähler sind mit Ausnahme des Anzeigenamens unveränderlich.
Ereignisname
Dies ist der Name des Zählerereignisses, für das Sie die Nutzung mit diesem Zähler aufzeichnen möchten. Verwenden Sie diesen Namen im Feld event_name
des Zählerereignisses, wenn Sie die Nutzung an Stripe senden. So wird sichergestellt, dass die Nutzung vom korrekten Zähler verarbeitet und zusammengefasst wird. Sie können einen Ereignisnamen nur mit einem einzelnen Zähler verwenden.
Ereigniseingabe
Geben Sie an, wie Sie Ereignisse an Stripe senden möchten. Es gibt zwei Möglichkeiten:
- Rohdaten: Behandeln Sie alle Zählerereignisse als eigenständige Ereignisse. Mehrere Ereignisse, die für denselben Zeitstempel gesendet werden, überschreiben sich nicht gegenseitig und sind in der Zusammenfassung enthalten. Wird keine Angabe gemacht, so ist dies die Standardoption.
- Vorab zusammengefasst (stündlich oder täglich): Wenn Sie über ein bestimmtes Zeitintervall vorab zusammengefasste Ereignisse senden (stündlich oder täglich), verwendet Stripe nur das neueste Zählerereignis innerhalb des stündlichen oder täglichen Zeitfensters für die Zusammenfassung. Ein neueres Ereignis, das innerhalb desselben stündlichen oder täglichen Zeitfensters gesendet wird, überschreibt das vorherige.
Gruppierungsformel
Geben Sie an, wie die Nutzung über den Abrechnungszeitraum hinweg zusammengefasst werden soll. Zu den Optionen für diesen Parameter gehören:
- Summe: Berechnen Sie die Gebühr basierend auf der Summe aller Nutzungswerte für den Abrechnungszeitraum.
- Anzahl: Berechnen Sie die Gebühr basierend auf der Gesamtnutzung für den Abrechnungszeitraum.
- Letzte Nutzungsdaten (in Kürze verfügbar): Berechnen Sie die Gebühr basierend auf den letzten Nutzungsdaten für den Abrechnungszeitraum. Wenn keine Nutzung vorliegt, beträgt die Nutzungsmenge für die Abrechnung 0.
- Maximalwert (in Kürze verfügbar): Berechnen Sie die Gebühr basierend auf dem größten Wert im angegebenen Zeitbereich (Sekunde, Stunde, Tag) innerhalb des Abrechnungszeitraums. Zum Beispiel können Sie hier die maximale Anzahl an Nutzer/innen nehmen, die sich während eines beliebigen Tages während des Abrechnungszeitraums angemeldet haben. Dies wird oft als Abrechnung nach dem High-Watermark-Prinzip bezeichnet.
Überschreibungen der Schlüsselnutzlast
Geben Sie an, welche Schlüssel in der Ereignisnutzlast sich auf die Kunden- und die numerischen Nutzungswerte beziehen.
- value_settings: Definieren Sie den Schlüssel, der sich auf den numerischen Nutzungswert in der Nutzlast des Zählerereignisses mit diesem Parameter bezieht. Der Standardschlüssel ist
value
, Sie können jedoch auch einen anderen Schlüssel, wie z. B. Token, angeben. - customer_mapping: Definieren Sie den Schlüssel in der Ereignisnutzlast, der sich mit diesem Parameter auf die Stripe-Kunden-ID bezieht. Während der Standardschlüssel
stripe_customer_id
ist, können Sie auch einen anderen Schlüssel angeben, wie z. B.customer_id
.
Aufzeichnung der Nutzung
Sie können Informationen zur Nutzung an Stripe weitergeben, indem Sie Zählerereignisse mit einer customer_id
, einem numerischen Wert und optional einem Zeitstempel erstellen. Wie häufig Sie die Nutzung melden, bleibt Ihnen überlassen. Sie können die Nutzung beispielsweise bei Bedarf oder in Stapeln (z. B. jeden Tag) senden. Am Ende des Abrechnungszeitraums berechnet Stripe automatisch den Gesamtpreis und erstellt Rechnungen für die gesamte Nutzung während des Abrechnungszeitraums.
So erstellen Sie Zählerereignisse:
Idempotenz
Verwenden Sie Idempotenz-Schlüssel, um zu verhindern, dass die Nutzung aufgrund von Latenz oder anderen Problemen mehrmals gemeldet wird. Jedes Zählerereignis entspricht einer Kennung, die Sie in Ihrer Anfrage angeben können (wenn Sie keine Angabe machen, erstellen wir diese automatisch).
Ereignis-Zeitstempel
Der Zeitstempel muss innerhalb der letzten 35 Kalendertage und darf nicht mehr als 5 Minuten in der Zukunft liegen (das 5-Minuten-Fenster berücksichtigt mögliche Uhrenfehler zwischen Ihrem Server und den Systemen von Stripe).
Nutzungswerte
Der numerische Nutzungswert in der Nutzlast akzeptiert nur positive ganzzahlige Werte.
Möchten Sie Dezimalwerte oder negative Werte verwenden?
Kontaktieren Sie uns unter usage-based-billing@stripe.com, damit wir Ihr Anwendungsszenario besser verstehen können.
Ratenbegrenzungen
Beachten Sie die Ratenbegrenzung. Mit dem Endpoint des Zählerereignisses sind nur 1.000 Anrufe pro Sekunde pro Stripe-Konto und ein gleichzeitiger Anruf pro Kundin/Kunde und Zähler möglich. Wenn Ihr Dienst die Begrenzung überschreitet, können Sie Ihr Produkt in gewisse Mengen „bündeln“. Wenn Sie zum Beispiel stets nach 1.000 Anfragen abrechnen, ändern Sie Ihr Produkt auf „pro 1.000 Transaktionen“. Somit senden Sie ein Mal pro 1.000 Anfragen einen Nutzungsbericht.
Überwachen Sie 429
-Statuscodes und implementieren Sie einen Wiederholungsmechanismus mit einem exponentiellen Backoff-Zeitplan, um das Anfragevolumen zu verwalten.
Erwägen Sie auch, eine gewisse Zufälligkeit in den Backoff-Zeitplan aufzunehmen, um einen Thundering-Herd-Effekt zu vermeiden.
Sie sind an höheren Ratenbegrenzungen interessiert?
You can report usage either by dropping it into an S3 bucket or through a bulk endpoint. Learn about recording usage for billing with the S3 connector. For a better understanding of your specific needs and to get early access, reach out to us at usage-based-billing@stripe.com.
Best Practices
Die Nutzungsdaten sind entscheidend für eine genaue Abrechnung. Gestalten Sie Ihr System so, dass es auch Netzwerkausfälle gekonnt handhabt. Nutzen Sie beispielsweise eine zuverlässige Warteschlange wie Amazon SQS, um Daten an Stripe zu übertragen, damit Sie die Übertragung bei Bedarf erneut durchführen können.
Fehlerhafte Nutzung beheben
Sie können fälschlicherweise gemeldete Ereignisse über die Zählerereignisanpassungen stornieren. Sie benötigen eine Kennung des Zählerereignisses, um es abzubrechen.
Beim Abbrechen von Zählerereignissen gelten die folgenden Einschränkungen:
- Sie können nur Ereignisse abbrechen, die innerhalb der letzten 24 Stunden an Stripe gesendet wurden.
- Wir unterstützen keine Rechnungsanpassungen für stornierte Nutzung, die wir einer Kundin/einem Kunden bereits in Rechnung gestellt haben.
- Wenn Sie eine Nutzung stornieren, die bereits in einer finalisierten Rechnung enthalten ist, werden wir diese Rechnung nicht aktualisieren. Wir stellen ebenfalls keine neue, korrigierte Rechnung für die stornierte Nutzung aus.