Stripe-API-Versionierung: Funktionsweise und Lehren

Die Stripe-API-Versionierung funktioniert über Datumsangaben. Jedes Konto ist an eine API-Version gebunden, die nach einem Release-Datum benannt ist, und jede einzelne Anfrage kann diese Bindung mit einem Stripe-Version-Header überschreiben. Zum Zeitpunkt des Schreibens (Oktober 2026) ist die aktuelle Version in der Stripe-Dokumentation 2026-09-30.endive, und dasselbe Schema kann eine viel kleinere API an einem Wochenende übernehmen.

Jede Stripe-Angabe unten stammt von Stripes eigenen Seiten, verlinkt an der Stelle, an der sie verwendet wird.

Wie funktioniert die Stripe-API-Versionierung?

Stripe gibt jedem Konto eine Standard-API-Version, und jede Anfrage, die keine Version nennt, nutzt sie. Die Aufrufer wählen selbst, wann sie wechseln, indem sie den Standard ändern oder bei einzelnen Anfragen eine Version setzen.

Stripes Engineering-Beitrag sagt, dass das Konto bei der ersten API-Anfrage festgelegt wird: Das Konto ist “automatically pinned to the most recent version available”, und ab dann wird jedem Aufruf implizit diese Version zugewiesen.

Der Versionsstring ist ein Datum. Seit dem Release 2024-09-30.acacia trägt er außerdem einen Namen, wie in 2026-09-30.endive. Das Datum ordnet die Versionen, und der Name verrät, zu welcher Major-Release-Familie eine Version gehört.

Wie wählt man eine Version pro Anfrage?

Sendet den Stripe-Version-Header mit der Anfrage oder setzt die Version im SDK. Stripes Upgrade-Leitfaden zeigt die Header-Form, und derselbe Aufruf funktioniert in Live- und Testumgebungen.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Stripes Leitfaden hält fest: Setzt ihr die Version global oder pro Anfrage in einem SDK, kommen die Antwortobjekte in dieser Version zurück.

Stripe rät außerdem davon ab, sich auf den Konto-Standard zu verlassen. In seinen Worten: Gebt die Version für jede Anfrage an, mit dem Header oder einem festgelegten SDK, damit euer Code die Version bestimmt und nicht eine Dashboard-Einstellung.

SDKs legen sich je nach Sprache unterschiedlich fest. Laut Doku nutzen neuere Versionen der dynamisch typisierten Bibliotheken die API-Version, die beim Erscheinen dieses SDK-Releases die neueste war, und stark typisierte (Java, Go und .NET) sind fest darauf gebunden. Eine Bibliotheksversion zu installieren heißt faktisch, eine API-Version zu wählen.

Was passiert mit Webhooks, wenn sich die Version ändert?

Ein Webhook-Event wird in der API-Version gerendert, die an seinem Endpunkt hängt, nicht in der Version, die euer Servercode nutzt. Stripes Doku sagt, Events nutzen die Version, die beim Anlegen des Endpunkts gesetzt war, sonst den Konto-Standard. Eine Änderung eurer SDK-Version ändert nicht, was euer Webhook-Handler empfängt.

Euer Anfragepfad und euer Event-Pfad können also auf zwei verschiedenen Versionen liegen. Bei Event-Zielen setzt ihr snapshot_api_version nur beim Anlegen des Ziels, eine andere Version bedeutet also ein neues Ziel.

Stripes Upgrade-Weg dafür ist ein paralleler Lauf. Legt einen neuen Endpunkt in der Zielversion an, sendet dieselben Events an beide, bringt dem Handler bei, einen zu verarbeiten und den anderen zu ignorieren, wechselt dann und deaktiviert den alten Endpunkt. Weil jedes Event während der Überlappung doppelt ankommt, muss der Handler idempotent sein. Das ist ein gutes Muster zum Kopieren für jede API, die Events sendet, und ein Webhook-Changelog ist der Ort, an dem ihr die Payload-Änderungen ankündigt, die es nötig machen.

Was sind die monatlichen und die Major Releases?

Seit dem Release 2024-09-30.acacia veröffentlicht Stripe monatlich eine neue API-Version ohne Breaking Changes und gibt zweimal im Jahr ein neues Major Release heraus, das mit einer Version mit Breaking Changes beginnt. Stripes Versionsseite sagt, dass ihr auf jedes monatliche Release aktualisieren könnt, ohne euren Code zu ändern, während ein Major Release Änderungen verlangen kann.

Major Releases tragen Namen. Die Versionsseite nennt Basil als Beispiel, und Stripes Ankündigung des Verfahrens sagt, die Namen stammen von Pflanzen, beginnend mit Acacia, und monatliche Releases behalten den Namen des vorangehenden Major Releases, damit der Name signalisiert, dass ein Update sicher ist. Stripes Changelog listet die verwendeten Namen, und zum Zeitpunkt des Schreibens ist der neueste Eintrag 2026-09-30.endive.

Das Datum beantwortet also “wie neu”, und der Name beantwortet “ist das eine Bruchgrenze”. Stripes Ankündigung lässt auch Raum für Ausnahmen: Sie behält sich vor, eine Breaking Change außerhalb des Zyklus auszuliefern, wenn eine Integration sonst schwer beeinträchtigt wäre. Die Ankündigung steht unter Stripe’s new API release process.

Was ist die neueste Version der Stripe-API?

Zum Zeitpunkt des Schreibens (Oktober 2026) gibt Stripes Versionsseite an, dass die aktuelle Version 2026-09-30.endive ist, und der Changelog führt dieselbe Version als neueste. Stripe veröffentlicht monatlich eine neue Version, daher veraltet jeder in einem Artikel abgedruckte String schnell. Lest den Live-Changelog, bevor ihr etwas festlegt, und legt die Version fest, gegen die ihr getestet habt.

Wie hält Stripe alte Versionen am Laufen?

Stripe hält alte Versionen am Leben, indem es jede Breaking Change als eigenständiges Versionsänderungs-Modul schreibt und die Module rückwärts ab der neuesten Datenform anwendet. Der Engineering-Beitrag zur API-Versionierung beschreibt den Mechanismus.

Jedes Modul erklärt, was es ändert, dokumentiert die Änderung und enthält eine Transformationsfunktion. Der Beitrag nennt als Beispiel ein Feld, das von einem String zu einem Hash wird. Um eine Antwort zu bauen, ermittelt das System die Zielversion, geht dann in der Zeit zurück und wendet jedes Modul an, das es unterwegs findet, bis es diese Version erreicht.

Aus diesem Design ergeben sich zwei Nebeneffekte, die der Beitrag beide nennt. Weil Module die Felder und Ressourcen deklarieren, die sie berühren, kann Stripe daraus beim Deployment seinen API-Changelog erzeugen. Und weil die Version des Kontos bekannt ist, kann sich die Dokumentation daran anpassen und vor rückwärts inkompatiblen Änderungen seit dieser Version warnen.

Was kostet es, und was sollte eine kleinere API übernehmen?

Versionierung kostet Entwicklungsaufmerksamkeit, und Stripe sagt das selbst. Der Engineering-Beitrag räumt einen Wartungsaufwand ein und nennt das Ziel, dass der Aufwand für altes Verhalten beim Schreiben neuen Codes umso besser ist, je geringer er ausfällt. Er beschreibt außerdem leichte API-Reviews vor dem Release, um eine Versionsänderung gar nicht erst zu brauchen.

Eine kleine API kann sich keine Modulkette für jede alte Version leisten und braucht auch keine. Übernehmt die Teile, die den Wert tragen:

1. Datierte Versionen. Ein Datum braucht kein Urteil darüber, was “major” ist, und Aufrufer können es lesen. Der Artikel API-Versionierung Best Practices vergleicht das mit URL- und Header-Schemata.
2. Ein festgelegter Standard. Bindet das Konto oder den Schlüssel bei der ersten Nutzung an die Version, damit sich die API nie unter einer funktionierenden Integration verschiebt.
3. Ein Überschreiben pro Anfrage. Ein Header, mit dem ein Aufrufer eine neue Version an einem Aufruf in Produktion testen kann, bevor er sich festlegt.
4. Eine Version am Webhook-Endpunkt. Bei Event-Payloads werden Aufrufer am häufigsten überrascht.
5. Ein Changelog-Eintrag pro Version. Er nennt die Version, das Datum, wer betroffen ist und was zu tun ist. Was als Breaking Change zählt ist der Test dafür, was überhaupt in eine neue Version gehört, und der Artikel zum API-Changelog behandelt den Eintrag selbst.

Lasst die Modulkette weg, bis die Zahl unterstützter Versionen sie erzwingt. Zwei oder drei laufende Versionen lassen sich mit ein paar Verzweigungen und einem Sunset-Datum handhaben, was eine API-Version abschalten durchgeht.

Veröffentlicht ihr einen datierten Changelog, ist die Versionshistorie nur so gut wie ihre Einträge. In Changeloop wird aus jedem gemergten Pull Request ein Eintragsentwurf erstellt und zur Freigabe durch einen Menschen zurückgehalten, bevor er auf der Changelog-Seite und im Feed erscheint. Dort entsteht der Eintrag pro Version, und das eine menschliche Tor ist der Review, der sagt, was ein Aufrufer tun muss.

FAQ

Was ist die neueste Version der Stripe-API? Zum Zeitpunkt des Schreibens (Oktober 2026) gibt Stripes Versionsseite an, dass die aktuelle Version 2026-09-30.endive ist. Stripe gibt monatlich eine neue Version heraus, prüft also den Changelog, bevor ihr festlegt, und schreibt die Version in euren Code, statt euch auf den Konto-Standard zu verlassen.

Wie setze ich die Stripe-API-Version bei einer Anfrage? Sendet den Stripe-Version-Header, zum Beispiel Stripe-Version: 2026-09-30.endive, oder setzt die Version in eurem serverseitigen SDK global oder pro Anfrage. Ohne beides nutzt eine Anfrage die Standardversion eures Kontos, die ihr in Workbench festlegt.

Nutzen Webhooks dieselbe Stripe-API-Version wie meine Anfragen? Nicht unbedingt. Webhook-Events nutzen die Version, die beim Anlegen des Endpunkts gesetzt war, und den Konto-Standard, falls keine gesetzt wurde. Ein SDK-Upgrade ändert nicht die Payload, die euer Webhook-Handler empfängt, also aktualisiert Endpunkte getrennt und testet sie parallel.

Ist Versionierung nach Datum im Stripe-Stil das Richtige für eine kleine API? Datierte Versionen, ein festgelegter Standard, ein Header pro Anfrage und ein Changelog-Eintrag pro Version sind günstig und lohnen sich zu kopieren. Die interne Kette von Versionsänderungs-Modulen nicht, solange ihr nicht viele alte Versionen gleichzeitig unterstützt. Beginnt mit zwei laufenden Versionen und einem Sunset-Datum für die ältere.

Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.

Mehr bei changeloop: Entwicklerdokumentation