Migrationsleitfaden für die Preise von Checkout

Die Prices API enthält eine neue Funktion und erweiterte Flexibilität für die Abbuchungen bei Ihren Kundinnen/Kunden. Die neue Integration bietet:

• Einheitlichere Modelle für Checkout-Artikel - statt Plänen, SKUs und Inline-Line-Artikeln, besteht nun jeder Artikel aus einem price.
• Außerdem besteht die Möglichkeit, Produktbilder für wiederkehrende Artikel darzustellen.
• Erstellung eines wiederverwendbaren Produkt- und Preiskatalogs statt eines einmaligen Line-Artikels.
• Erstellen Sie Inline-Preise für Abonnements.
• Wenden Sie dynamische Steuersätze auf Abonnements und Einmalzahlungen an.

Sie möchten nicht migrieren? Sie können Ihre aktuelle Integration weiterhin nutzen, neue Funktionen werden jedoch nicht unterstützt. Sie können alle neuen Pläne oder wiederkehrenden Preise verwenden, die Sie im Parameter plan Ihrer bestehenden API-Aufrufe erstellen.

Produkt- und Preisübersicht

Preise sind eine neue, grundlegende Größe in Stripe. Sie funktionieren mit Abonnements, Rechnungen und Checkout. Jeder Preis ist mit einem einzelnen Produkt verknüpft und jedes Produkt kann mehrere Preise haben. Verschiedene physische Waren oder Servicestufen sollten durch Produkte repräsentiert werden. Die Preisgebung für dieses Produkt sollte dann durch die Preise repräsentiert sein.

Diese Preise definieren den Grundpreis, die Währung und—für wiederkehrende Produkte—den Abrechnungszyklus. So können Sie Preise ändern und hinzufügen, ohne immer die Details Ihrer angebotenen Produkte verändern zu müssen. So können Sie also beispielsweise ein einzelnes „Gold“-Produkt zum Preis von 10 US$ pro Monat, 100 US$ im Jahr, 9 EUR pro Monat und 90 EUR pro Jahr anbieten. Oder Sie bieten ein T-Shirt in blau für 20 US$ und 15 EUR an.

Einmalzahlungen

Für Integrationen für Einmalzahlungen gelten folgende Änderungen:

• Statt Ad-hoc-Posten (d. h. Einstellung des Namens, Betrags und der Währung), müssen Sie für eine Checkout-Sitzung ein Produkt erstellen und in der Regel auch einen Preis.
• Modus ist jetzt ein Pflichtfeld.

Der Code der Client-Seite bleibt derselbe.

Zuweisungstabelle

Statt jedes Feld eines line_items zu definieren, nutzt Checkout die zugrunde liegenden Produkt- und Preisobjekte, um Namen, Beschreibung, Betrag, Währung und Bilder zu ermitteln. Sie können Produkte und Preise mit der API oder mit dem Dashboard erstellen.

Serverseitiger Code für Inline-Items

Bisher konnten Sie nur einmalige Posten inline erstellen. Mit Preisen können Sie weiterhin Ihre Posten inline konfigurieren, sie können aber darüber hinaus auch mit price_data Ihre Preise dynamisch definieren, wenn Sie die Checkout-Sitzung erstellen.

Wenn Sie die Checkout-Sitzung mit price_data erstellen, verweisen Sie auf eine bestehende Produkt-ID mit price_data.product oder definieren Sie Ihre Produktdaten dynamisch mit price_data.product_data. Das folgende Beispiel zeigt den Workflow für die Erstellung eines einmaligen Postens.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][price_data][currency]"=usd \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Serverseitiger Code für Einmal-Items

Mit der neuen Integration können Sie im Vorfeld einen Produkt- und Preiskatalog anlegen und müssen nicht stattdessen jedes Mal, wenn Sie eine Checkout-Sitzung erstellen, einen Betrag, eine Währung und einen Namen festlegen.

Sie können ein Produkt und einen Preis entweder mit der Prices API oder über das Dashboard anlegen. Um eine Checkout-Sitzung zu erstellen, benötigen Sie die Preis-ID. Das folgende Beispiel zeigt, wie Sie ein Produkt und einen Preis über die API anlegen:

curl https://api.stripe.com/v1/products \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d name=T-shirt \
  -d description="Comfortable cotton t-shirt" \
  -d "images[]"="https://example.com/t-shirt.png"

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Abonnements

Für Integrationen für wiederkehrende Zahlungen gelten folgende Änderungen:

• Alle Artikel werden an ein einziges line_items-Feld übergeben, statt an subscription_data.items.
• mode ist nun ein Pflichtfeld. Setzen Sie mode=subscription, wenn die Session nur wiederkehrende Artikel enthält.

Der Code der Client-Seite bleibt derselbe. Bestehende Pläne können überall dort verwendet werden, wo Preise akzeptiert werden.

Serverseitiger Code für Pläne

Hier ein „Vorher-Nachher“-Beispiel zur Erstellung einer Checkout Session mit einer Testversion und mit einem bestehenden Plan, für die jeweils alternativ auch einfach ein Preis festgelegt werden kann. Der Plan wird dann an line_items übergeben, anstatt an subscription_data.items.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Serverseitiger Code für wiederkehrenden Preis mit Einrichtungsgebühr

Wenn Sie wiederkehrende Pläne mit einer einmaligen Einrichtungsgebühr haben, erstellen Sie das Produkt und den Preis, der die Einmalgebühr darstellt, bevor Sie die Checkout-Sitzung anlegen. In der Zuweisungstabelle finden Sie Informationen darüber, wie die alten line_items-Felder in der neuen Integration zugewiesen werden. Sie können Produkt und Preis entweder über die Prices API oder das Stripe-Dashboard anlegen. Alternativ können Sie auch einmalige Posten inline erstellen. Das folgende Beispiel nutzt eine bestehende Preis-ID:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \
  -d "line_items[1][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Änderungen am Antwort-Objekt

Statt einer Auflistung mit display_items nutzt das Checkout Session-Objekt line_items. Das Feld line_items wird nicht automatisch dargestellt, wie es bei display_items der Fall war, sondern Sie können es mit Erweitern bei Erstellung einer Checkout-Sitzung einbinden:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="payment" \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Webhook-Änderungen

Da line_items einbindbar ist, listet der Webhook checkout.session.completed die Artikel nicht mehr standardmäßig auf. Das kleinere Antwortobjekt ermöglicht es Ihnen, Ihre Checkout-Webhooks schneller zu empfangen. Mit dem neuen line_items-Endpoint können Sie Ihre Artikel abrufen:

curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Weitere Details hierzu finden Sie unter Bestellungen mit Checkout abwickeln.