Stripe API-versionering: hoe het werkt en wat je kopieert

Stripe API-versionering werkt op datum. Elk account is vastgepind op een API-versie die naar een releasedatum is vernoemd, en elk afzonderlijk verzoek kan die pin overschrijven met een Stripe-Version-header. Op het moment van schrijven (oktober 2026) is de huidige versie in de docs van Stripe 2026-09-30.endive, en hetzelfde schema is iets wat een veel kleinere API in een weekend kan overnemen.

Elk Stripe-feit hieronder komt van de eigen pagina’s van Stripe, gelinkt waar het wordt gebruikt.

Hoe werkt Stripe API-versionering?

Stripe geeft elk account een standaard API-versie, en elk verzoek dat geen versie noemt gebruikt die. Aanroepers kiezen zelf wanneer ze overstappen, door de standaard te wijzigen of door een versie op afzonderlijke verzoeken in te stellen.

Volgens de engineering post van Stripe wordt het account vastgepind bij het eerste API-verzoek: het account wordt “automatically pinned to the most recent version available”, en vanaf dan krijgt elke aanroep die versie impliciet toegewezen.

De versiestring is een datum. Sinds de release 2024-09-30.acacia draagt hij ook een naam, zoals in 2026-09-30.endive. De datum ordent de versies, en de naam vertelt tot welke major-releasefamilie een versie behoort.

Hoe kies je een versie per verzoek?

Stuur de Stripe-Version-header mee met het verzoek, of stel de versie in de SDK in. De upgradegids van Stripe toont de headervorm, en dezelfde aanroep werkt in live- en testomgevingen.

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

De gids van Stripe merkt op dat wanneer je de versie globaal of per verzoek in een SDK instelt, de responseobjecten in die versie terugkomen.

Stripe raadt ook af om op de accountstandaard te leunen. In zijn eigen woorden: geef de versie voor elk verzoek op, met de header of een vastgepinde SDK, zodat jouw code de versie bepaalt en een dashboardinstelling niet.

SDK’s pinnen per taal anders. De docs zeggen dat recente versies van de dynamisch getypeerde libraries de API-versie gebruiken die de nieuwste was toen die SDK-release uitkwam, en dat sterk getypeerde (Java, Go en .NET) eraan vast zitten. Een libraryversie installeren is in feite een API-versie kiezen.

Wat gebeurt er met webhooks als de versie verandert?

Een webhook-event wordt gerenderd in de API-versie die aan het endpoint hangt, niet in de versie die je servercode gebruikt. De docs van Stripe zeggen dat events de versie gebruiken die bij het aanmaken van het endpoint is ingesteld, en anders de accountstandaard. Je SDK-versie wijzigen verandert niet wat je webhookhandler ontvangt.

Je verzoekpad en je eventpad kunnen dus op twee verschillende versies zitten. Bij event destinations stel je snapshot_api_version alleen in wanneer je de destination aanmaakt, dus een andere versie betekent een nieuwe destination.

Het upgradepad van Stripe hiervoor is een parallelle run. Maak een nieuw endpoint op de doelversie, stuur dezelfde events naar beide, leer de handler er een te verwerken en de andere te negeren, schakel dan over en zet het oude endpoint uit. Omdat elk event tijdens de overlap twee keer binnenkomt, moet de handler idempotent zijn. Dat is een goed patroon om te kopiëren voor elke API die events uitzendt, en een webhook-changelog is waar je de payloadwijzigingen aankondigt die dat nodig maken.

Wat zijn de maandelijkse en de major releases?

Sinds de release 2024-09-30.acacia brengt Stripe maandelijks een nieuwe API-versie uit zonder breaking changes, en geeft het twee keer per jaar een nieuwe major release uit die begint met een versie met breaking changes. Op de versioningpagina staat dat je naar elke maandelijkse release kunt upgraden zonder je code aan te passen, terwijl een major release wijzigingen kan vereisen.

Major releases dragen namen. De versioningpagina noemt Basil als voorbeeld, en de aankondiging van Stripe over het proces zegt dat de namen van planten komen, te beginnen met Acacia, en dat maandelijkse releases de naam van de voorafgaande major release houden, zodat de naam aangeeft dat ze veilig zijn om naar te upgraden. De changelog van Stripe toont de namen die in gebruik zijn, en op het moment van schrijven is de nieuwste entry 2026-09-30.endive.

De datum beantwoordt dus “hoe nieuw”, en de naam beantwoordt “is dit een breaking grens”. De aankondiging van Stripe laat ook ruimte voor uitzonderingen: het behoudt zich het recht voor een breaking change buiten de cyclus uit te brengen als een integratie er anders ernstig door zou worden geraakt. De aankondiging staat op Stripe’s new API release process.

Wat is de nieuwste versie van de Stripe API?

Op het moment van schrijven (oktober 2026) staat op de versioningpagina van Stripe dat de huidige versie 2026-09-30.endive is, en de changelog noemt dezelfde versie als de nieuwste. Stripe publiceert maandelijks een nieuwe versie, dus elke string die in een artikel staat veroudert snel. Lees de actuele changelog voordat je iets pint, en pin de versie waartegen je hebt getest.

Hoe houdt Stripe oude versies werkend?

Stripe houdt oude versies in leven door elke breaking change als een zelfstandige versiewijzigingsmodule te schrijven en de modules achterwaarts toe te passen vanaf de nieuwste vorm van de data. De engineering post over API-versionering beschrijft het mechanisme.

Elke module verklaart wat hij wijzigt, documenteert de wijziging en bevat een transformatiefunctie. De post geeft het voorbeeld van een veld dat van string naar hash verandert. Om een response te bouwen bepaalt het systeem de doelversie, loopt dan terug in de tijd en past elke module toe die het onderweg tegenkomt tot het die versie bereikt.

Uit dat ontwerp volgen twee neveneffecten, en de post noemt ze allebei. Omdat modules de velden en resources verklaren die ze raken, kan Stripe zijn API-changelog bij deployment daaruit genereren. En omdat de versie van het account bekend is, kan de documentatie zich eraan aanpassen en waarschuwen voor achterwaarts incompatibele wijzigingen sinds die versie.

Wat kost het, en wat moet een kleinere API kopiëren?

Versionering kost engineeringaandacht, en Stripe zegt dat zelf. De engineering post erkent een onderhoudslast en noemt het doel dat hoe minder je over oud gedrag hoeft na te denken bij het schrijven van nieuwe code, hoe beter. Hij beschrijft ook lichte API-reviews vóór de release, om een versiewijziging helemaal te vermijden.

Een kleine API kan zich geen modulereeks voor elke oude versie veroorloven, en heeft er ook geen nodig. Kopieer de onderdelen die de waarde dragen:

1. Gedateerde versies. Een datum vraagt geen oordeel over wat “major” is, en aanroepers kunnen hem lezen. Het artikel over beste practices voor API-versionering vergelijkt dit met URL- en headerschema’s.
2. Een vastgepinde standaard. Pin het account of de key bij eerste gebruik op de versie, zodat de API nooit onder een werkende integratie verschuift.
3. Een override per verzoek. Een header waarmee een aanroeper een nieuwe versie op één aanroep kan testen, in productie, voordat hij zich vastlegt.
4. Een versie op het webhook-endpoint. Eventpayloads zijn de plek waar aanroepers het vaakst worden verrast.
5. Eén changelog-entry per versie. Laat hem de versie, de datum, de getroffenen en wat te doen noemen. Wat telt als breaking is de toets voor wat überhaupt in een nieuwe versie hoort, en het artikel over de API-changelog behandelt de entry zelf.

Sla de modulereeks over tot het aantal ondersteunde versies het afdwingt. Twee of drie live versies lukken met een paar vertakkingen en een sunsetdatum, wat een API-versie uitfaseren doorloopt.

Als je een gedateerde changelog publiceert, is de versiegeschiedenis zo goed als haar entries. In Changeloop wordt uit elke gemergede pull request een conceptentry aangemaakt die door een mens wordt goedgekeurd voordat hij op de changelogpagina en in de feed verschijnt. Daar wordt een entry per versie geschreven, en de ene menselijke poort is de review die zegt wat een aanroeper moet doen.

FAQ

Wat is de nieuwste versie van de Stripe API? Op het moment van schrijven (oktober 2026) staat op de versioningpagina van Stripe dat de huidige versie 2026-09-30.endive is. Stripe geeft maandelijks een nieuwe versie uit, dus controleer de changelog voordat je pint, en schrijf de versie in je code in plaats van op de accountstandaard te vertrouwen.

Hoe stel ik de Stripe API-versie in op een verzoek? Stuur de Stripe-Version-header mee, bijvoorbeeld Stripe-Version: 2026-09-30.endive, of stel de versie in je server-side SDK globaal of per verzoek in. Zonder een van beide gebruikt een verzoek de standaardversie van je account, die je in Workbench instelt.

Gebruiken webhooks dezelfde Stripe API-versie als mijn verzoeken? Niet noodzakelijk. Webhook-events gebruiken de versie die bij het aanmaken van het endpoint is ingesteld, en de accountstandaard als er geen is ingesteld. Je SDK upgraden verandert de payload die je webhookhandler ontvangt niet, dus upgrade endpoints apart en test ze parallel.

Is datumversionering in Stripe-stijl geschikt voor een kleine API? Gedateerde versies, een vastgepinde standaard, een header per verzoek en één changelog-entry per versie zijn goedkoop en het kopiëren waard. De interne reeks versiewijzigingsmodules niet, tot je veel oude versies tegelijk ondersteunt. Begin met twee live versies en een sunsetdatum voor de oudste.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Documentatie voor ontwikkelaars