# Setzen Sie fortschrittliche nutzungsbasierte Abrechnung mit Preisplänen um Rechnen Sie Ihre Kundinnen und Kunden auf der Grundlage von Nutzung und wiederkehrenden Gebühren ab. Sie können verschiedene Preiskomponenten in einem einzigen Preisplan zusammenfassen, um komplexe Preismodelle zu implementieren, die mehrere Abrechnungsstrategien kombinieren. Erstellen Sie beispielsweise einen Preisplan, der [Preislisten](https://docs.stripe.com/billing/subscriptions/usage-based/rate-cards/about.md) für nutzungsbasierte Abrechnungen, [Lizenzgebühren](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans/license-fees/about.md) für wiederkehrende Zahlungen und [Serviceaktionen](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans/service-actions/about.md) für wiederkehrende Kreditgewährungszuweisungen enthält.Preislisten für nutzungsbasierte Abrechnungen, Lizenzgebühren für wiederkehrende Zahlungen und Serviceaktionen für wiederkehrende Kreditgewährungszuweisungen. Wenn ein Kunde ein Abonnement abschließt, registriert Stripe automatisch alle wiederkehrenden Komponenten und stellt sie in dem von Ihnen konfigurierten Rhythmus in Rechnung. Folgende Preismodelle werden beispielsweise unterstützt: - Pay-as-you-go - Echtzeit-Guthabenabrechnung mit Aufladungen - Pauschalgebühr und Überschreitungsgebühren > Preispläne befinden sich in der [privaten Vorschau](https://docs.stripe.com/release-phases.md) und könnten in Funktionalität und Integrationspfad Änderungen unterliegen, bevor sie allen Stripe-Nutzerinnen und -Nutzern allgemein zur Verfügung stehen. Kontaktieren Sie uns , um Zugang zu beantragen. ## Before you begin - Preispläne verwenden `/v2`-API-Endpoints. Erfahren Sie mehr über die [/v2 und /v1 Namespaces](https://docs.stripe.com/api-v2-overview.md). - Verwenden Sie [Sandboxes](https://docs.stripe.com/sandboxes.md), um die Integration Ihrer Preispläne zu testen. Sie können den Test-Modus nicht mit `/v2`-APIs verwenden. Sie können auch eine [geführte API-Version (Blueprint)](https://dashboard.stripe.com/test/workbench/blueprints/usage-based-billing?code-pane-shown=true) dieses Leitfadens im Dashboard verwenden. ## Preisplan erstellen Verwenden Sie das Stripe Dashboard oder die API, um einen Preisplan zu erstellen, der alle relevanten Abrechnungskomponenten Ihres Preismodells enthält. Konfigurieren Sie für jeden Preisplan Folgendes: - **Währung**: Geben Sie die Währungen für alle Komponenten in Ihrem Preisplan an. - **Steuer soll in Preisen enthalten sein**: Geben Sie an, ob die Steuer in Ihren Preis einbezogen werden soll (inklusive) oder ob sie zur Zwischensumme der Rechnung hinzuaddiert werden soll (exklusive). Erfahren Sie mehr über [inklusive und exklusive Steuern für die Abrechnung](https://docs.stripe.com/billing/taxes/tax-rates.md#inclusive-vs-exclusive-tax). - **Metadaten**: Fügen Sie optional Ihre eigenen Metadaten zum Preisplan hinzu. Nachdem Sie die Währungs- und Steuerparameter festgelegt haben, definieren Sie die relevanten Komponenten Ihres Plans. Welche Komponenten Sie einbeziehen, hängt von Ihrem Preismodell ab. Dieser Leitfaden veranschaulicht alle drei Komponenten ((Preislisten, Lizenzgebühren und Serviceaktionen). Beispielsweise sind für Pay-as-you-go-Preise und Echtzeit-Guthabenverrechnung mit Aufladungen lediglich eine Preisliste und eine Pauschalgebühr erforderlich, während für Überschreitungen eine Preisliste und eine Lizenzgebühr erforderlich sind und für wiederkehrende Gutschriften mit Überschreitungen eine Preisliste und eine Serviceaktion erforderlich sind. #### Dashboard ### Erstellen Sie den Preisplan 1. Klicken Sie auf der Seite [Preispläne](https://dashboard.stripe.com/test/pricing-plans) auf **Preisplan erstellen**. 1. Im Preisplan-Editor: - Geben Sie einen Anzeigenamen, die Währung und das Steuerverhalten an. - (Optional) Geben Sie unter **Erweiterte Einstellungen** eine Beschreibung, einen eindeutigen Suchschlüssel und Metadaten an. 1. Klicken Sie auf **Fortfahren**. ### Preisliste hinzufügen 1. Klicken Sie im Preisplan Editor auf + und **Preisliste**. 1. Im Preislisten-Editor: - Geben Sie einen Anzeigenamen an. - Legen Sie den Servicezeitraum fest . - (Optional) Geben Sie unter **Erweiterte Einstellungen** einen Suchschlüssel und Metadaten an. 1. Klicken Sie auf **Fortfahren**. ### Fügen Sie der Preisliste einen Preis hinzu. 1. Im Preis-Editor: - Geben Sie einen Anzeigenamen für den nutzungsbasierten Posten an (z. B. `Hypernian-Token`). - Wählen Sie einen vorhandenen **Zähler** aus oder erstellen Sie einen neuen, indem Sie auf + klicken. - Wählen Sie den **Preistyp** aus – **Fester Satz**, [Staffelpreis](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#volume-based-pricing) oder [Gestufter Preis](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#graduated-pricing). Im Hypernian-Beispiel wird der Festpreis verwendet. - Wählen Sie unter **Verkaufen als**, ob Sie einzelne Einheiten oder eine Gruppierung von Einheiten verkaufen möchten. Ein KI-Unternehmen könnte zum Beispiel seine Tokens in Paketen zu `100` Einheiten zu einem Preis von `0,04 USD` pro Paket verkaufen. - Geben Sie für Pakete die **Einheiten pro Paket** ein. - Wählen Sie aus, ob für **Teilpakete** auf- oder abgerundet werden soll. Wenn Sie aufrunden, werden einem/einer Nutzer/in, der/die 110 Einheiten nutzt, 0,08 USD in Rechnung gestellt. - Geben Sie den **Preis pro Paket** ein. - (Optional) Konfigurieren Sie **Erweiterte Einstellungen** für Ihren gemessenen Posten, z. B. Angabe eines **Produkt-Steuercodes** (erfahren Sie mehr über [Steuercodes](https://docs.stripe.com/tax/tax-codes.md)), **Einheitskennzeichnung**, **Suchschlüssel** und **Metadaten**. Sie können dem Preis auch Metadaten hinzufügen. 1. Klicken Sie auf **Fertig**. 1. (Optional) Klicken Sie auf + **Preis hinzufügen**, um der Preisliste zusätzliche Preise hinzuzufügen. ### Lizenzgebühr hinzufügen 1. Klicken Sie im Preisplan-Editor auf + und **Lizenzgebühr**. 1. Im Lizenzgebühren-Editor: - Geben Sie einen Anzeigenamen für den lizenzierten Posten an. - Legen Sie den Servicezeitraum fest . - Wählen Sie den **Preistyp**: **Festpreis**, [Volumen](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#volume-based-pricing) oder [Gestaffelt](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#graduated-pricing). Zum Beispiel `50.00 USD` pro Einheit. - (Optional) Konfigurieren Sie die **Erweiterten Einstellungen** für Ihren lizenzierten Posten, z. B. durch die Angabe eines **Produkt-Steuercodes** (Weitere Informationen zu [Steuercodes](https://docs.stripe.com/tax/tax-codes.md)), **Einheitskennzeichnung**, **Suchschlüssel** und **Metadaten**. Sie können der Gebühr auch Metadaten hinzufügen. 1. Klicken Sie auf **Fertig**. ### Serviceaktion hinzufügen 1. Klicken Sie im Preisplan-Editor auf + und **Gutschriftgewährung**. 1. Im Editor für wiederkehrende Gutschriftgewährungen: - Geben Sie einen Anzeigenamen für die Gutschriftgewährung an. - Legen Sie den Servicezeitraum fest . - Geben Sie einen Gutschriftsbetrag an. - (Optional) Konfigurieren Sie **Erweiterte Einstellungen** für Ihre wiederkehrende Gutschriftgewährung, z. B. die Spezifizierung eines **Antrags** oder eines **Suchschlüssels**. 1. Klicken Sie auf **Fertig**. Nachdem Sie den Preisplan konfiguriert haben, klicken Sie auf **Preisplan erstellen**. #### API ### Erstellen Sie den Preisplan Wenn Sie einen [Preisplan](https://docs.stripe.com/api/v2/pricing-plans.md?api-version=preview) erstellen, geben Sie einen Anzeigenamen, Währungen und das Steuerverhalten an (erfahren Sie mehr über [Steuerverhalten und Preislisten](https://docs.stripe.com/tax/subscriptions/rate-card-tax-codes-tax-behavior.md#set-a-default-tax-behavior-recommended)). ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Pro Pricing Plan", "currency": "usd", "tax_behavior": "exclusive" }' ``` Nachdem Sie die Anfrage für den Preisplan übermittelt haben, gibt Stripe das aktive Objekt `Pricing Plan` zurück. Sie können neue Kund/innen nicht auf einen inaktiven Preisplan abonnieren. ```json { "id": "bpp_test_61SjPwyNGx88hyuOg16SjPfE4ZSQFjWjdqlzQfWMCH1E", "object": "v2.billing.pricing_plan", "active": true, "created": "2025-06-14T21:52:04.000Z", "currency": "usd", "description": null, "display_name": "Pro Pricing Plan", "latest_version": "bppv_test_123", "live_version": "bppv_test_123", "lookup_key": null, "metadata": {}, "tax_behavior": "exclusive" } ``` ### Preisliste hinzufügen Um Ihrem Preisplan eine Preisliste hinzuzufügen, damit Sie Ihre Kundinnen und Kunden basierend auf der Nutzung abrechnen können, eine Preisliste erstellen und einen Anzeigenamen, die Währung, das Serviceintervall und das Steuerverhalten angeben. ```curl curl -X POST https://api.stripe.com/v2/billing/rate_cards \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Hypernian", "service_interval": "month", "service_interval_count": 1, "currency": "usd", "tax_behavior": "exclusive" }' ``` ### Zähler erstellen ```curl curl https://api.stripe.com/v1/billing/meters \ -u "<>:" \ -d "display_name=Hypernian tokens" \ -d event_name=hypernian_tokens \ -d "default_aggregation[formula]=sum" \ -d "customer_mapping[event_payload_key]=stripe_customer_id" \ -d "customer_mapping[type]=by_id" \ -d "value_settings[event_payload_key]=value" ``` ### Erstellen Sie einen nutzungsabhängigen Posten Nachdem Sie einen Zähler erstellt haben, erstellen Sie ein nutzungsbasiertes Element, das den konkreten Posten darstellt, für den die Kundin oder der Kunde bezahlt – zum Beispiel ein LLM-Modell oder eine Nutzungsebene für Token. ```curl curl -X POST https://api.stripe.com/v2/billing/metered_items \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Hypernian tokens", "meter": "{{METER_ID}}", "lookup_key": "hypernian_tokens" }' ``` ### Einen Tarif an den Zähler anhängen Nachdem Sie ein nutzungsbasiertes Element erstellt haben, hängen Sie einen Tarif an den Zähler an. ```curl curl -X POST https://api.stripe.com/v2/billing/rate_cards/{{RATE_CARD_ID}}/rates \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "metered_item": "{{METERED_ITEM_ID}}", "unit_amount": "5" }' ``` ### Preisliste einem Preisplan hinzufügen Nachdem Sie den Tarif erstellt haben, hängen Sie die Preisliste an den Preisplan an: ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "type": "rate_card", "rate_card": { "id": "{{RATE_CARD_ID}}", "version": "{{RATE_CARD_VERSION}}" }, "metadata": { "existing_key": "updated_value", "new_key": "new value" } }' ``` ### Lizenzgebühr hinzufügen Lizenzgebühren sind feste wiederkehrende Zahlungen, mit denen Sie Vorauszahlungen berechnen können. Erstellen Sie zunächst einen Lizenz-Posten: ```curl curl -X POST https://api.stripe.com/v2/billing/licensed_items \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Pricing Plan Licensed Item" }' ``` Erstellen Sie dann eine Lizenzgebühr: ```curl curl -X POST https://api.stripe.com/v2/billing/license_fees \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "E2E License", "licensed_item": "{{LICENSED_ITEM_ID}}", "unit_amount": "50000", "service_interval": "month", "service_interval_count": 1, "currency": "usd", "tax_behavior": "exclusive" }' ``` Verknüpfen Sie abschließend die Lizenzgebühr mit einem Preisplan: ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "type": "license_fee", "license_fee": { "id": "{{LICENSE_FEE_ID}}", "version": "{{LICENSE_FEE_VERSION}}" }, "lookup_key": "monthly-fee-component", "metadata": { "existing_key": "updated_value", "new_key": "new value" } }' ``` ### Serviceaktion hinzufügen Sie können Ihrem Preisplan neue Komponenten hinzufügen, einschließlich wiederkehrender Gutschriftgewährungen. Verwenden Sie wiederkehrende Gutschriftgewährungen, wenn Sie ein [Guthaben-basiertes Preismodell](https://docs.stripe.com/subscriptions/pricing-models/usage-based-pricing.md#credit-burndown) verwenden. Mit Serviceaktionen können Sie Kundinnen und Kunden wiederkehrende Gutschriften anbieten, die Gebühren für bestimmte abrechnungsfähige Posten, wie z. B. nutzungsbasierte Gebühren, ausgleichen können. Wenn Sie eine Service-Aktion erstellen, konfigurieren Sie Folgendes: - Betrag - Abrechnungshäufigkeit - Anwendbare abrechenbare Posten Um eine monatliche Gutschriftgewährung von 10 USD zu erstellen, die am Ende des Serviceintervalls verfällt: ```curl curl -X POST https://api.stripe.com/v2/billing/service_actions \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "service_interval": "month", "service_interval_count": 1, "type": "credit_grant", "lookup_key": "credit grant 28", "credit_grant": { "name": "Credit grant 28", "expiry_config": { "type": "end_of_service_period" }, "applicability_config": { "scope": { "price_type": "metered" } }, "amount": { "type": "monetary", "monetary": { "value": 1000, "currency": "usd" } } } }' ``` Fügen Sie die Serviceaktion Ihrem Preisplan hinzu: ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "type": "service_action", "service_action": { "id": "{{SERVICE_ACTION_ID}}" }, "lookup_key": "credit-grant-28", "metadata": { "existing_key": "updated_value", "new_key": "new value" } }' ``` ### Preisplan aktivieren Nachdem Sie die relevanten Komponenten für Ihr Preismodell hinzugefügt haben, aktivieren Sie diese Version des Preisplans. Nachdem der Plan aktiviert wurde, können Sie [Kunden auf ihn abonnieren](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#subscribe). ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}} \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "live_version": "latest" }' ``` ## Abonnieren Sie Ihre/n Kunde/Kundin auf einen Preisplan Nachdem Sie einen Preisplan eingerichtet haben, können Sie ihn für einen Kunden oder eine Kundin abonnieren. Sie können ein Abo erstellen, indem Sie die [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) mit[ entweder einer von Stripe gehosteten Seite oder eingebetteten Komponenten als Nutzeroberfläche für die Zahlung](https://docs.stripe.com/payments/checkout.md) verwenden. (Die Checkout-Sitzung erstellt auch einen Kunden bzw. eine Kundin). Sie können die API auch verwenden, um direkt ein Preisplan-Abo zu erstellen. Wenn Sie die direkte API-Methode verwenden, müssen Sie [einen Kunden bzw. eine Kundin](https://docs.stripe.com/api/customers/create.md), eine [Einzugsmethode](https://docs.stripe.com/api/v2/billing-settings/collection-settings/create.md?api-version=preview),[einen Abrechnungsrhythmus](https://docs.stripe.com/api/v2/billing/cadences/create.md?api-version=preview) und einen [Abrechnungs-Intent](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview) erstellen, wodurch das Preisplan-Abonnement erstellt wird. #### Von Stripe gehostete Seite Verwenden Sie die [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md), um eine Bezahlseite für Ihre Kundinnen und Kunden zu erstellen. Wenn ein Kunde auf **Abonnieren** klickt, erstellt die Checkout Session ein [Kundenobjekt](https://docs.stripe.com/api/customers.md) (wenn Sie keine Kunden-ID für die Session angegeben haben) und ein Preisplan-Abo. Wenn Sie mehrere Posten in `checkout_items` haben, wird für jeden Posten ein Preisplan-Abo erstellt. Im Folgenden finden Sie ein Beispiel dafür, wie ein vollständiger Preisplan mit Checkout aussieht. ![Beispiel für Preisplan](https://b.stripecdn.com/docs-statics-srv/assets/checkout_pricing_plan_example.2156a15535345b113c30e7efabe72867.png) Ein in Stripe Checkout angezeigter Preisplan ### Einschränkungen der Checkout-Sitzung während der privaten Vorschau Während der privaten Vorschau: - Sie können maximal fünf [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items) übergeben. - Sie können nur Karten, Link, Apple Pay und Google Pay akzeptieren. - Sie können keinen bestimmten [Abrechnungszyklusanker](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) übergeben. - Sie können keine [Steuersätze](https://docs.stripe.com/billing/taxes/tax-rates.md) verwenden, sondern nur die automatische Steuerberechnung. - Sie können keine Rabatte verwenden. - Sie können [Kunden nicht auf ein Abonnement beschränken](https://docs.stripe.com/payments/checkout/limit-subscriptions.md). - [Connect](https://docs.stripe.com/connect.md) kann nicht verwendet werden. - Sie können keine [optionalen Artikel](https://docs.stripe.com/payments/checkout/optional-items.md) oder [Cross-Selling](https://docs.stripe.com/payments/checkout/cross-sells.md) hinzufügen. Kontaktieren Sie [advanced-ubb-private-preview@stripe.com](mailto:advanced-ubb-private-preview@stripe.com), um frühzeitigen Zugriff zu erhalten und Produktfeedback oder -anfragen zu teilen. Um eine [Checkout-Session](https://docs.stripe.com/api/checkout/sessions/create.md) mit Preisplänen zu erstellen, fügen Sie ein Objekt im Array [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items) hinzu, dessen [type](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items-type) auf `pricing_plan_subscription_item` gesetzt ist und eine `pricing_plan_subscription_item`-Konfiguration enthält. Wenn Sie `checkout_items` anstelle von `line_items` verwenden, müssen Sie den [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) nicht angeben. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \ -d customer={{CUSTOMER_ID}} \ -d "checkout_items[0][type]=pricing_plan_subscription_item" \ -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \ -d success_url={{SUCCESS_URL}} ``` Wenn Ihr Preisplan eine Lizenzgebühr enthält, müssen Sie die Anzahl der Lizenzen angeben: So rufen Sie die Lizenzgebühren-Komponenten-ID ab: ```curl curl https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2025-09-30.preview" ``` Erstellen Sie die Checkout-Sitzung unter Verwendung der Lizenzgebühren-Komponenten-ID: ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \ -d customer={{CUSTOMER_ID}} \ -d "checkout_items[0][type]=pricing_plan_subscription_item" \ -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \ -d "checkout_items[0][pricing_plan_subscription_item][component_configurations][{{LICENSE_COMPONENT_ID}}][type]=license_fee_component" \ -d "checkout_items[0][pricing_plan_subscription_item][component_configurations][{{LICENSE_COMPONENT_ID}}][license_fee_component][quantity]=1" ``` Auf der Seite werden die Details Ihres Preisplans angezeigt und die Zahlungen der Kunden erfasst. Nach Abschluss der Sitzung wird das Preisplan-Abonnement erstellt und die Kundin/der Kunde an die URL weitergeleitet, die Sie für `success_url` angegeben haben. Erfahren Sie mehr über die [Anpassung des Weiterleitungsverhaltens mit Checkout](https://docs.stripe.com/payments/checkout/custom-success-page.md). #### Eingebettete Komponenten Für mehr Kontrolle über das Erscheinungsbild der Zahlungsseite Ihres Preisplans können Sie [eingebettete Komponenten](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) mit der Checkout Session API verwenden. Das [Session](https://docs.stripe.com/js/custom_checkout/session_object)-Objekt der eingebetteten Komponenten stellt die Details Ihres Preismodells in [session.orderSummaryItems](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-orderSummaryItems) bereit, sodass Sie eine Bestellübersicht für Ihr Preismodell, Lizenzgebühren und Preislisten rendern können. Sie müssen weiterhin denselben `checkout_items`-Parameter verwenden, wenn Sie die Checkout-Sitzung auf Ihrem Server erstellen. ### Einschränkungen der Checkout-Sitzung während der privaten Vorschau Während der privaten Vorschau: - Sie können maximal fünf [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items) übergeben. - Sie können nur Karten, Link, Apple Pay und Google Pay akzeptieren. - Sie können keinen bestimmten [Abrechnungszyklusanker](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) übergeben. - Sie können keine [Steuersätze](https://docs.stripe.com/billing/taxes/tax-rates.md) verwenden, sondern nur die automatische Steuerberechnung. - Sie können keine Rabatte verwenden. - Sie können [Kunden nicht auf ein Abonnement beschränken](https://docs.stripe.com/payments/checkout/limit-subscriptions.md). - [Connect](https://docs.stripe.com/connect.md) kann nicht verwendet werden. - Sie können keine [optionalen Artikel](https://docs.stripe.com/payments/checkout/optional-items.md) oder [Cross-Selling](https://docs.stripe.com/payments/checkout/cross-sells.md) hinzufügen. Kontaktieren Sie [advanced-ubb-private-preview@stripe.com](mailto:advanced-ubb-private-preview@stripe.com), um frühzeitigen Zugriff zu erhalten und Produktfeedback oder -anfragen zu teilen. ### Verwenden der Beta-Kopfzeile des Product Catalogs Wenn Sie eine Stripe-Instanz auf Ihrem Frontend mit Ihrem veröffentlichbaren Schlüssel initialisieren, geben Sie den Beta-Header `custom_checkout_product_catalog_1` ein. ```js const stripe = Stripe( '<>',{betas: ['custom_checkout_product_catalog_1']}, ); ``` ```javascript import {loadStripe} from '@stripe/stripe-js'; const stripe = loadStripe("<>", {betas: ['custom_checkout_product_catalog_1'], }); ``` #### API Verwenden Sie die APIs direkt, um [einen Kunden bzw. eine Kundin zu erstellen](https://docs.stripe.com/api/customers/create.md) und anschließend [ein Abrechnungsintervall zu erstellen](https://docs.stripe.com/api/v2/billing-cadences/cadences/create.md?api-version=preview). Sie können die Standard-Zahlungsmethode des Kunden oder der Kundin automatisch belasten oder ihm/ihr die Rechnung zur manuellen Bezahlung zusenden. Nachdem Sie einen Kunden oder eine Kundin und ein Abrechnungsintervall erstellt haben, können Sie [ein Preisplan-Abonnement erstellen](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview). Standardmäßig wickeln wir die gespeicherte Zahlung eines Kunden bzw. einer Kundin automatisch ab. Um eine Rechnung zu versenden, [erstellen Sie eine Erfassungseinstellung](https://docs.stripe.com/api/v2/billing-settings/collection-settings/create.md?api-version=preview), wobei `collection_method` auf `send_invoice` gesetzt wird. Geben Sie anschließend die Erfassungseinstellung an, wenn Sie die Kadenz erstellen. ## Kundennutzung aufzeichnen Nachdem Sie eine Kundin/einen Kunden für einen Preisplan mit einer Preisliste angemeldet haben, erfassen Sie die Nutzung Ihres Dienstes, indem Sie Zählerereignisse an einen Zähler senden. #### Dashboard 1. Gehen Sie zur Registerkarte [Preisplan-Abonnements](https://dashboard.stripe.com/test/pricing-plans/subscriptions). 1. Klicken Sie auf das Abonnement, für das Sie die Nutzung aufzeichnen möchten. 1. Wählen Sie **Anzeigen** aus, um die zugrunde liegenden Preisplan-Komponenten anzuzeigen, und navigieren Sie zu der Preisliste, für die Sie die Nutzung hinzufügen möchten. 1. Klicken Sie auf das Überlaufmenü (⋯) in der Zeile des Artikels, für den Sie die Nutzung aufzeichnen möchten, und dann auf **Verbrauch anzeigen**. 1. Klicken Sie auf der Detailseite des Zählers auf **+ Nutzung hinzufügen** und wählen Sie dann **Nutzung manuell eingeben** aus. 1. Gehen Sie im Dialogfeld **Nutzung hinzufügen** wie folgt vor: - Wählen Sie einen Kunden/eine Kundin aus. - Geben Sie einen **Wert** für die Nutzung an. - Wählen Sie ein Datum für den **Zeitstempel** aus. 1. Klicken Sie auf **Absenden**. #### API Verwenden Sie [Zählerereignisse](https://docs.stripe.com/api/billing/meter-event.md) zur [Erfassung der Kundennutzung](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage.md) für Ihren Zähler. Am Ende des Abrechnungsintervalls stellt Stripe die gemeldete Nutzung in Rechnung. Um die nutzungsbasierte Abrechnung zu testen, senden Sie Zählerereignisse über das Stripe Dashboard oder die API. Geben Sie bei Verwendung der API die Kunden/Kundin und den Nutzungswert beim `payload` an. Erfahren Sie mehr über das [Testen von Preisplan-Integrationen](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#test-the-integration). ```curl curl https://api.stripe.com/v1/billing/meter_events \ -u "<>:" \ -d event_name=hypernian_tokens \ -d "payload[stripe_customer_id]={{CUSTOMER_ID}}" \ -d "payload[value]=25" ``` ## Eine Rechnungsvorschau erstellen Erstellen Sie eine Vorschau-Rechnung, um eine Vorschau der Kundenrechnung anzuzeigen. Die Vorschau enthält die relevanten Posten aus den verschiedenen Preisplan-Komponenten. #### Dashboard 1. Gehen Sie zur Registerkarte [Preisplan-Abonnements](https://dashboard.stripe.com/test/pricing-plan/subscriptions). 1. Klicken Sie auf das Abonnement, für das Sie eine Rechnungsvorschau anzeigen möchten. 1. Scrollen Sie nach unten zum Abschnitt **Anstehende Rechnung**. Die Rechnung in der Vorschau zeigt den Betrag des Abonnements, der dem Kunden / der Kundin am angegebenen Datum in Rechnung gestellt werden soll, und enthält die entsprechenden gemessenen Posten, die Lizenzposten und das Guthaben. #### API ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -H "Stripe-Version: 2025-12-15.clover" \ -d billing_cadence=bc_test_61SrjnScUwT6mNskZ16SjPfE4ZSQFjWjdqlzQfWMCVnM ``` ```json {"hosted_invoice_url": "example.com/invoice", "invoice_pdf": null, "billing_reason": "manual", "collection_method": "charge_automatically", "created": 1680644467, "currency": "usd", "custom_fields": null, "customer": "cus_NeZwdNtLEOXuvB", "customer_address": null, "customer_email": "jennyrosen@example.com", "customer_name": "Jenny Rosen", "customer_phone": null, "customer_shipping": null, "customer_tax_exempt": "none", "customer_tax_ids": [], "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": [], "due_date": null, "ending_balance": null, "footer": null, "from_invoice": null, "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines" }, "id": "upcoming_in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_overpaid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "application_fee_amount": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "status": null }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "parent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680644467, "period_start": 1680644467, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "draft", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subtotal": 0, "subtotal_excluding_tax": 0, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_taxes": [], "webhooks_delivered_at": 1680644467 } ``` ## Wartungsereignisse überwachen Preisplan-Abonnements senden Ereignisbenachrichtigungen, wenn sich der Status von Service und Einzug ändert. Überwachen Sie diese Ereignisse und verwenden Sie sie, um Ihre Geschäftslogik zu erstellen: | Ereignis | Beschreibung | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `v2.billing.pricing_plan_subscription.servicing_activated` | Wird gesendet, wenn der Service des Abonnements aktiv wird, entweder wenn der erste Servicezeitraum beginnt oder wenn ein unterbrochenes Abonnement wiederaufgenommen wird. | | `v2.billing.pricing_plan_subscription.servicing_paused` | Wird gesendet, wenn Stripe die Wartung des Abonnements unterbricht. | | `v2.billing.pricing_plan_subscription.servicing_canceled` | Wird gesendet, wenn der Service des Abonnements gekündigt wird, entweder durch die Kundin/den Kunden oder durch Stripe. | | `v2.billing.pricing_plan_subscription.collection_current` | Wird gesendet, wenn der Zahlungseinzug des Abonnements aktuell ist und alle Zahlungen verarbeitet wurden. | | `v2.billing.pricing_plan_subscription.collection_awaiting_customer_action` | Wird gesendet, wenn der Zahlungseinzug eine Kundenmaßnahme erfordert (z. B. 3DS-Authentifizierung). | | `v2.billing.pricing_plan_subscription.collection_paused` | Wird gesendet, wenn Stripe den Zahlungseinzug für das Abonnement unterbricht. | Um diese [v2 Events](https://docs.stripe.com/api/v2/core/events.md?api-version=preview) zu verarbeiten, konfigurieren Sie eine [Event Destination](https://docs.stripe.com/api/v2/core/event_destinations.md?api-version=preview) und lassen Sie sie auf Ihren Webhook Endpoint verweisen. Sie haben folgende Möglichkeiten: - Erstellen Sie das Ereignisziel aus [Workbench](https://docs.stripe.com/workbench/event-destinations.md). - Erstellen Sie das Ereignisziel [über die Stripe-API](https://docs.stripe.com/api/v2/core/event_destinations.md?api-version=preview). Nachdem Sie ein Ziel erstellt haben, können Sie Ihren Webhook-Endpoint so einrichten, dass er diese Ereignisse verarbeitet: ```ruby require 'stripe' post '/v2_webhook_endpoint' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e status 400 return rescue Stripe::SignatureVerificationError => e status 400 return end client = Stripe::StripeClient.new("<>") case event.type when 'v2.billing.pricing_plan_subscription.servicing_activated' # Servicing becomes active, either when the first service period starts # or when a paused subscription resumes. subscription_id = event.related_object.id subscription = client.v2.billing.pricing_plan_subscriptions .retrieve(subscription_id) # Look up your user in the database using the metadata passed into # Checkout Session create user_id = subscription.metadata["my_user_id"] user = User.find_by_id(user_id) # Fill in your logic here: mark_subscription_active(user, subscription) when 'v2.billing.pricing_plan_subscription.servicing_paused' # Stripe pauses the subscription's servicing. subscription_id = event.related_object.id subscription = client.v2.billing.pricing_plan_subscriptions .retrieve(subscription_id) # Look up your user in the database using the metadata passed into # Checkout Session create user_id = subscription.metadata["my_user_id"] user = User.find_by_id(user_id) # Fill in your logic here: mark_subscription_paused(user, subscription) when 'v2.billing.pricing_plan_subscription.servicing_canceled' # Servicing is canceled, either by the customer or by Stripe. subscription_id = event.related_object.id subscription = client.v2.billing.pricing_plan_subscriptions .retrieve(subscription_id) # Look up your user in the database using the metadata passed into # Checkout Session create user_id = subscription.metadata["my_user_id"] user = User.find_by_id(user_id) # Fill in your logic here: mark_subscription_canceled(user, subscription) end status 200 end ``` ## Integration testen So testen Sie Ihre Integration: - [Erstellen Sie eine Sandbox](https://docs.stripe.com/sandboxes/dashboard/manage.md#create-a-sandbox). - Erstellen Sie einen Test-Preisplan und mindestens eine zugrunde liegende Preiskomponente in Ihrer Sandbox. - Verwenden Sie [Testkarten](https://docs.stripe.com/testing.md), um erfolgreiche und fehlgeschlagene Zahlungen zu simulieren. - Erstellen Sie [Testzählerereignisse](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#create-meter) zur Simulation der Nutzung. - Verwenden Sie [Simulationen](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md), um die Abrechnung zu simulieren. > #### Erstellen Sie keine Test-Uhren in der Vergangenheit > > Wenn Sie eine Test-Uhr für ein Preisplan-Abonnement erstellen, erstellen Sie nur Uhren in der Zukunft. Wenn Sie eine Uhr in der Vergangenheit erstellen, werden die Rechnungsbeträge nicht korrekt sein. Test-Uhr mit UNIX-Zeitstempel erstellen: ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks \ -u "<>:" \ -d frozen_time=1577836800 ``` Notieren Sie sich die ID der Test-Uhr. Erstellen Sie als Nächstes einen Testkunden/eine Testkundin mit der Uhr: ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=test@example.com" \ -d test_clock={{TEST_CLOCK_ID}} ``` Erstellen Sie ein Abrechnungsprofil: ```curl curl -X POST https://api.stripe.com/v2/billing/profiles \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "customer": "{{CUSTOMER_ID}}" }' ``` Erstellen Sie ein Abrechnungsintervall, um festzulegen, wann die Rechnung für den Kunden/die Kundin erstellt wird. Speichern Sie die ID. ```curl curl -X POST https://api.stripe.com/v2/billing/cadences \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "payer": { "billing_profile": "{{BILLING_PROFILE_ID}}" }, "billing_cycle": { "type": "month", "interval_count": 3 }, "settings": { "collection": { "id": "{{COLLECTION_SETTINGS_ID}}" } } }' ``` [Erstellen Sie ein Preisplan-Abonnement](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#subscribe) für die Testkundin/den Testkunden. Erstellen Sie einen [Abrechnungs-Intent](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview), um die Status des Preisplan Abonnements nachzuverfolgen. Zuerst erstellen Sie einen Entwurf für den Abrechnungs-Intent. Speichern Sie die ID des Intents. ```curl curl -X POST https://api.stripe.com/v2/billing/intents \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "currency": "usd", "cadence": "{{CADENCE_ID}}", "actions": [ { "type": "subscribe", "subscribe": { "type": "pricing_plan_subscription_details", "pricing_plan_subscription_details": { "pricing_plan": "{{PRICING_PLAN_ID}}", "pricing_plan_version": "{{PRICING_PLAN_VERSION}}" } } } ] }' ``` Als Nächstes nehmen Sie eine Rückstellung des Abrechnungs-Intents vor: ```curl curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/reserve \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" ``` Als nächstes bestätigen Sie die Abrechnungsabsicht, um das Abo für den Preisplan zu aktivieren und der Kundin bzw. dem Kunden die Rechnung gemäß Plan und Zeitraum zu stellen. (Wenn Sie die Einstellungen für den Einzug auf `automatic` gesetzt haben, müssen Sie einen erfolgreichen [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) haben, um den Intent zu bestätigen. Wenn Sie die Einstellungen für den Einzug auf `send_invoice` eingestellt haben, brauchen Sie die Zahlungsabsicht nicht zu übergeben). ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d customer={{CUSTOMER_ID}} \ -d payment_method=pm_card_visa \ -d "return_url=example.com" \ -d confirm=true ``` Zu Testzwecken können Sie `payment_method` auf „pm_card_visa“ setzen. ```curl curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/commit \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "payment_intent": "{{PAYMENT_INTENT_ID}}" }' ``` Bezahlen Sie die durch das Abonnement generierte Rechnung. Nachdem die Rechnung bezahlt wurde, können Sie die Nutzung simulieren und die Uhr vorstellen, wodurch die Abrechnung für den nächsten Monat ausgelöst wird. Wenn Sie Checkout verwenden, können Sie die `url` der zurückgegebenen Checkout-Sitzung in Ihrem Browser öffnen und die Zahlung mit einer [Testkarte](https://docs.stripe.com/testing.md#use-test-cards) abschließen. Zeichnen Sie einige Testnutzungen auf: ```curl curl -X POST https://api.stripe.com/v2/billing/meter_events \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "event_name": "hypernian_tokens", "payload": { "stripe_customer_id": "{{CUSTOMER_ID}}", "value": "100" } }' ``` Stellen Sie die eingefrorene Zeit der Test-Uhr um einen Monat vor. In diesem Beispiel hat die Test-Uhr derzeit einen Zeitstempel von `1577836800`. Um einen Monat hinzuzufügen, fügen Sie `30 * 24 * 60 * 60` oder `2592000` Sekunden hinzu. Der neue Zeitstempel in einem Monat ist `1580428800`. ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{TEST_CLOCK_ID}}/advance \ -u "<>:" \ -d frozen_time=1580428800 ``` ## Optional: Steuern einziehen Um Steuern automatisch einzuziehen, [erstellen Sie eine Checkout-Sitzung](https://docs.stripe.com/api/checkout/sessions/create.md), die [checkout_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-checkout_items) enthält, und legen Sie `automatic_tax.enabled` auf „true“ fest. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \ -d customer={{CUSTOMER_ID}} \ -d "checkout_items[0][type]=pricing_plan_subscription_item" \ -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \ -d success_url={{SUCCESS_URL}} \ -d "automatic_tax[enabled]=true" ``` Auf der Seite werden die Details Ihres Preisplans angezeigt und die Zahlungen der Kunden erfasst. Nachdem die Kunden die Sitzung abgeschlossen hat, werden sie an die URL weitergeleitet, die Sie für `success_url` angegeben haben. ## Optional: Richten Sie das Kundenportal ein Sie können Ihren Kund/innen Self-Service-Funktionen anbieten, indem Sie ein [Kundenportal](https://docs.stripe.com/customer-management/activate-no-code-customer-portal.md) einrichten. Die Verwendung des Kundenportals mit Tarifabonnements ist derzeit nur im Lesemodus möglich: Kund/innen können ihre Zahlungsmethoden für Tarifabonnements nicht kündigen oder Pläne ändern oder aktualisieren. Derzeit können Sie ein Kundenportal nur über das Dashboard konfigurieren. Wenn das Kundenportal mit Tarifabonnements verwendet wird, können Ihre Kund/innen Folgendes einsehen: - Der abonnierte Plan, einschließlich Details zu dem von Ihnen angebotenen Hybridplan. - Anstehende Rechnungen helfen zu verstehen, was den Kund/innen am Ende des Monats in Rechnung gestellt wird. - Die für das betreffende Abo hinterlegte Zahlungsmethode. - Frühere Rechnungen, die ihnen gestellt wurden. - Die Rechnungsinformationen der Kund/innen.