Versionamento API di Stripe: come funziona e cosa copiare

Il versionamento API di Stripe funziona per data. Ogni account è fissato a una versione dell’API che prende il nome da una data di rilascio, e ogni singola richiesta può scavalcare quel valore con un header Stripe-Version. Al momento della scrittura (ottobre 2026), la versione corrente nella documentazione di Stripe è 2026-09-30.endive, e lo stesso schema è qualcosa che un’API molto più piccola può copiare in un fine settimana.

Ogni fatto su Stripe qui sotto viene dalle pagine di Stripe stessa, collegate dove vengono usate.

Come funziona il versionamento API di Stripe?

Stripe dà a ogni account una versione API predefinita, e ogni richiesta che non nomina una versione usa quella. Chi chiama sceglie quando passare, cambiando il valore predefinito o impostando una versione sulle singole richieste.

Il post di engineering di Stripe dice che l’account viene fissato la prima volta che fa una richiesta API: l’account è “automatically pinned to the most recent version available”, e da lì ogni chiamata riceve implicitamente quella versione.

La stringa di versione è una data. Dal rilascio 2024-09-30.acacia porta anche un nome, come in 2026-09-30.endive. La data ordina le versioni, e il nome dice a quale famiglia di rilasci major appartiene una versione.

Come si sceglie una versione per ogni richiesta?

Invia l’header Stripe-Version sulla richiesta, oppure imposta la versione nell’SDK. La guida all’upgrade di Stripe mostra la forma con l’header, e la stessa chiamata funziona negli ambienti live e di test.

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

La guida di Stripe osserva che quando imposti la versione a livello globale o per richiesta in un SDK, gli oggetti di risposta tornano in quella versione.

Stripe sconsiglia anche di appoggiarsi al valore predefinito dell’account. Nelle sue parole, specifica la versione per ogni richiesta, con l’header o con un SDK bloccato, così che sia il tuo codice a decidere la versione e non un’impostazione della dashboard.

Gli SDK fissano la versione in modo diverso a seconda del linguaggio. La documentazione dice che le versioni recenti delle librerie a tipizzazione dinamica usano la versione API che era l’ultima quando è uscita quella release dell’SDK, mentre quelle fortemente tipizzate (Java, Go e .NET) sono ancorate a essa. Installare una versione della libreria significa, di fatto, scegliere una versione API.

Cosa succede ai webhook quando cambia la versione?

Un evento webhook viene reso nella versione API associata al suo endpoint, non nella versione che usa il codice del tuo server. La documentazione di Stripe dice che gli eventi usano la versione impostata alla creazione dell’endpoint, e altrimenti quella predefinita dell’account. Cambiare la versione del tuo SDK non cambia ciò che riceve il tuo gestore webhook.

Il percorso delle richieste e quello degli eventi possono quindi trovarsi su due versioni diverse. Per le destinazioni degli eventi, imposti snapshot_api_version solo quando crei la destinazione, quindi una versione diversa richiede una nuova destinazione.

Il percorso di upgrade di Stripe per questo è un’esecuzione in parallelo. Crea un nuovo endpoint alla versione di destinazione, invia gli stessi eventi a entrambi, insegna al gestore a elaborarne uno e a ignorare l’altro, poi passa e disattiva il vecchio endpoint. Poiché durante la sovrapposizione ogni evento arriva due volte, il gestore deve essere idempotente. È un buon schema da copiare per qualsiasi API che emette eventi, e un changelog dei webhook è il posto dove annunciare le modifiche ai payload che lo rendono necessario.

Cosa sono i rilasci mensili e major?

Dal rilascio 2024-09-30.acacia, Stripe pubblica una nuova versione dell’API ogni mese senza breaking changes, ed emette una nuova major due volte l’anno che parte con una versione contenente breaking changes. La sua pagina sul versionamento dice che puoi passare a qualsiasi rilascio mensile senza aggiornare il codice, mentre una major può richiedere modifiche.

Le major hanno dei nomi. La pagina sul versionamento fa l’esempio di Basil, e l’annuncio del processo da parte di Stripe dice che i nomi vengono dalle piante, a partire da Acacia, e che i rilasci mensili mantengono il nome della major precedente, così il nome segnala che si può passare in sicurezza. Il changelog di Stripe elenca i nomi in uso, e al momento della scrittura la voce più recente è 2026-09-30.endive.

Quindi la data risponde a “quanto è nuova”, e il nome risponde a “è un confine di breaking change”. L’annuncio di Stripe lascia anche spazio a eccezioni: si riserva il diritto di rilasciare una breaking change fuori ciclo dove un’integrazione sarebbe gravemente colpita senza di essa. L’annuncio è in Stripe’s new API release process.

Qual è l’ultima versione dell’API di Stripe?

Al momento della scrittura (ottobre 2026), la pagina di Stripe sul versionamento indica che la versione corrente è 2026-09-30.endive, e il suo changelog elenca la stessa versione come la più recente. Stripe pubblica una nuova versione ogni mese, quindi qualsiasi stringa stampata in un articolo invecchia in fretta. Leggi il changelog aggiornato prima di fissare qualcosa, e fissa la versione con cui hai testato.

Come fa Stripe a mantenere funzionanti le vecchie versioni?

Stripe mantiene vive le vecchie versioni scrivendo ogni breaking change come un modulo di cambio versione autonomo e applicando i moduli all’indietro a partire dalla forma più recente dei dati. Il suo post di engineering sul versionamento API descrive il meccanismo.

Ogni modulo dichiara cosa cambia, documenta la modifica e include una funzione di trasformazione. Il post fa l’esempio di un campo che passa da stringa a hash. Per costruire una risposta, il sistema determina la versione di destinazione, poi risale nel tempo e applica ogni modulo che trova lungo la strada fino a raggiungere quella versione.

Da questa progettazione seguono due effetti collaterali, e il post nomina entrambi. Poiché i moduli dichiarano i campi e le risorse che toccano, Stripe può generare il proprio changelog API da essi al momento del deploy. E poiché la versione dell’account è nota, la documentazione può adattarsi a essa e avvisare delle modifiche incompatibili dall’ultima versione usata.

Quanto costa, e cosa dovrebbe copiare un’API più piccola?

Il versionamento costa attenzione ingegneristica, e Stripe lo dice. Il post di engineering riconosce un onere di manutenzione e indica l’obiettivo: meno bisogna pensare al vecchio comportamento quando si scrive nuovo codice, meglio è. Descrive anche revisioni leggere dell’API prima del rilascio, per evitare di dover cambiare versione.

Un’API piccola non può permettersi una catena di moduli per ogni vecchia versione, e non ne ha bisogno. Copia le parti che portano valore:

1. Versioni datate. Una data non richiede di giudicare cosa conti come “major”, e chi chiama la può leggere. L’articolo sulle buone pratiche di versionamento la confronta con gli schemi a URL e a header.
2. Un valore predefinito fissato. Fissa l’account o la chiave alla versione del primo uso, così l’API non cambia sotto un’integrazione funzionante.
3. Un override per richiesta. Un header che permette a chi chiama di testare una nuova versione su una sola chiamata, in produzione, prima di impegnarsi.
4. Una versione sull’endpoint dei webhook. I payload degli eventi sono il punto in cui chi chiama si sorprende di più.
5. Una voce di changelog per versione. Fai in modo che nomini la versione, la data, chi è interessato e cosa fare. Cosa conta come breaking è il test per decidere cosa appartiene a una nuova versione, e l’articolo sul changelog API copre la voce in sé.

Salta la catena di moduli finché il numero di versioni supportate non la impone. Due o tre versioni attive si gestiscono con qualche ramo e una data di sunset, come spiega dismettere una versione API.

Se pubblichi un changelog datato, la cronologia delle versioni vale quanto le sue voci. In Changeloop, una bozza di voce viene creata da ogni pull request integrata e tenuta in attesa finché una persona la approva, prima di pubblicarla nella pagina del changelog e nel feed. È lì che si scrive la voce per versione, e l’unico controllo umano è la revisione che dice cosa deve fare chi chiama.

FAQ

Qual è l’ultima versione dell’API di Stripe? Al momento della scrittura (ottobre 2026), la pagina di Stripe sul versionamento indica che la versione corrente è 2026-09-30.endive. Stripe emette una nuova versione ogni mese, quindi controlla il suo changelog prima di fissarla, e scrivi la versione nel tuo codice invece di affidarti al valore predefinito dell’account.

Come imposto la versione dell’API di Stripe su una richiesta? Invia l’header Stripe-Version, per esempio Stripe-Version: 2026-09-30.endive, oppure imposta la versione nel tuo SDK lato server, a livello globale o per richiesta. Senza nessuno dei due, una richiesta usa la versione predefinita del tuo account, che imposti in Workbench.

I webhook usano la stessa versione dell’API di Stripe delle mie richieste? Non necessariamente. Gli eventi webhook usano la versione impostata alla creazione dell’endpoint, e quella predefinita dell’account se non ne è stata impostata una. Aggiornare l’SDK non cambia il payload che riceve il tuo gestore webhook, quindi aggiorna gli endpoint separatamente e testali in parallelo.

Il versionamento per data in stile Stripe va bene per una piccola API? Versioni datate, un valore predefinito fissato, un header per richiesta e una voce di changelog per versione costano poco e vale la pena copiarli. La catena interna di moduli di cambio versione no, finché non supporti molte vecchie versioni insieme. Parti con due versioni attive e una data di sunset per la più vecchia.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Documentazione per sviluppatori