Versionamento da API do Stripe: como funciona e o que copiar

O versionamento da API do Stripe funciona por data. Cada conta é fixada em uma versão da API com o nome de uma data de lançamento, e qualquer requisição pode sobrescrever essa fixação com um header Stripe-Version. No momento em que escrevo (outubro de 2026), a versão atual na documentação do Stripe é 2026-09-30.endive, e o mesmo esquema é algo que uma API bem menor pode copiar em um fim de semana.

Todo fato sobre o Stripe abaixo vem das próprias páginas do Stripe, com link no ponto em que é usado.

Como funciona o versionamento da API do Stripe?

O Stripe dá a cada conta uma versão padrão da API, e toda requisição que não nomeia uma versão usa essa. Quem chama escolhe quando migrar, alterando o padrão ou definindo uma versão em requisições individuais.

O post de engenharia do Stripe diz que a conta é fixada na primeira vez que faz uma requisição à API: ela é “automatically pinned to the most recent version available”, e a partir daí toda chamada recebe implicitamente essa versão.

A string da versão é uma data. Desde a release 2024-09-30.acacia, ela também carrega um nome, como em 2026-09-30.endive. A data ordena as versões, e o nome diz a que família de release major uma versão pertence.

Como escolher a versão em cada requisição?

Envie o header Stripe-Version na requisição, ou defina a versão no SDK. O guia de upgrade do Stripe mostra a forma com header, e a mesma chamada funciona em ambientes live e de teste.

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

O guia do Stripe observa que, quando você define a versão globalmente ou por requisição em um SDK, os objetos de resposta voltam nessa versão.

O Stripe também recomenda não depender do padrão da conta. Nas palavras dele, especifique a versão em cada requisição, com o header ou com um SDK fixado, para que o seu código decida a versão e não uma configuração de painel.

Os SDKs fixam de forma diferente conforme a linguagem. A documentação diz que as versões recentes das bibliotecas de tipagem dinâmica usam a versão da API que era a mais recente quando aquela release do SDK saiu, e as de tipagem forte (Java, Go e .NET) ficam presas a ela. Instalar uma versão da biblioteca é, na prática, escolher uma versão da API.

O que acontece com os webhooks quando a versão muda?

Um evento de webhook é renderizado na versão da API associada ao endpoint dele, não na versão que o código do seu servidor usa. A documentação do Stripe diz que os eventos usam a versão definida quando o endpoint foi criado e, caso contrário, o padrão da conta. Mudar a versão do seu SDK não muda o que o seu handler de webhook recebe.

O caminho das suas requisições e o caminho dos eventos podem, portanto, estar em duas versões diferentes. Para destinos de eventos, snapshot_api_version só é definido na criação do destino, então uma versão diferente significa um destino novo.

O caminho de upgrade do Stripe para isso é uma execução em paralelo. Crie um endpoint novo na versão de destino, envie os mesmos eventos aos dois, ensine o handler a processar um e ignorar o outro, depois troque e desative o endpoint antigo. Como todo evento chega duas vezes durante a sobreposição, o handler precisa ser idempotente. É um bom padrão para copiar em qualquer API que emite eventos, e um changelog de webhook é onde vocês anunciam as mudanças de payload que tornam isso necessário.

O que são as releases mensais e as major?

Desde a release 2024-09-30.acacia, o Stripe lança uma versão nova da API todo mês sem breaking changes, e emite uma release major nova duas vezes por ano, que começa com uma versão contendo breaking changes. A página de versionamento diz que dá para migrar para qualquer release mensal sem atualizar o código, enquanto uma release major pode exigir mudanças.

As releases major têm nomes. A página de versionamento cita Basil como exemplo, e o anúncio do processo pelo Stripe diz que os nomes vêm de plantas, começando por Acacia, e que as releases mensais mantêm o nome da release major anterior, para que o nome sinalize que migrar para elas é seguro. O changelog do Stripe lista os nomes em uso, e no momento em que escrevo a entrada mais nova é 2026-09-30.endive.

Assim, a data responde “quão nova”, e o nome responde “é um limite com breaking change?”. O anúncio do Stripe também deixa espaço para exceções: ele se reserva o direito de lançar uma breaking change fora do ciclo quando uma integração seria gravemente afetada sem ela. O anúncio está em Stripe’s new API release process.

Qual é a versão mais recente da API do Stripe?

No momento em que escrevo (outubro de 2026), a página de versionamento do Stripe afirma que a versão atual é 2026-09-30.endive, e o changelog dele lista a mesma versão como a mais nova. O Stripe publica uma versão nova todo mês, então qualquer string impressa em um artigo envelhece rápido. Leiam o changelog ao vivo antes de fixar qualquer coisa, e fixem a versão contra a qual vocês testaram.

Como o Stripe mantém versões antigas funcionando?

O Stripe mantém versões antigas vivas escrevendo cada breaking change como um módulo autônomo de mudança de versão e aplicando os módulos de trás para a frente, a partir da forma mais nova dos dados. O post de engenharia sobre versionamento de API descreve o mecanismo.

Cada módulo declara o que muda, documenta a mudança e inclui uma função de transformação. O post dá o exemplo de um campo que muda de string para hash. Para montar uma resposta, o sistema descobre a versão de destino, depois volta no tempo e aplica cada módulo que encontra pelo caminho até chegar a essa versão.

Dois efeitos colaterais decorrem desse desenho, e o post nomeia os dois. Como os módulos declaram os campos e recursos que tocam, o Stripe consegue gerar o changelog da API a partir deles no deploy. E como a versão da conta é conhecida, a documentação pode se adaptar a ela e avisar sobre mudanças incompatíveis com versões anteriores desde aquela versão.

Quanto custa, e o que uma API menor deve copiar?

Versionar custa atenção de engenharia, e o Stripe admite isso. O post de engenharia reconhece um peso de manutenção e declara o objetivo de que, quanto menos for preciso pensar no comportamento antigo ao escrever código novo, melhor. Ele também descreve revisões leves de API antes do lançamento, para evitar precisar de uma mudança de versão.

Uma API pequena não pode pagar uma cadeia de módulos para cada versão antiga, e não precisa de uma. Copie as partes que carregam o valor:

1. Versões com data. Uma data não exige julgamento sobre o que conta como “major”, e quem chama consegue lê-la. O artigo de melhores práticas de versionamento de API compara isso com esquemas por URL e por header.
2. Um padrão fixado. Fixe a conta ou a chave na versão do primeiro uso, para que a API nunca mude sob uma integração que funciona.
3. Uma sobrescrita por requisição. Um header que deixa quem chama testar uma versão nova em uma chamada, em produção, antes de se comprometer.
4. Uma versão no endpoint de webhook. Os payloads de eventos são o lugar onde quem chama mais se surpreende.
5. Uma entrada de changelog por versão. Faça-a nomear a versão, a data, quem é afetado e o que fazer. O que conta como breaking é o teste para o que pertence a uma versão nova, e o artigo sobre changelog de API cobre a entrada em si.

Pulem a cadeia de módulos até que o número de versões suportadas a imponha. Duas ou três versões ativas se resolvem com alguns branches e uma data de sunset, o que encerrar uma versão de API detalha.

Se vocês publicam um changelog com datas, o histórico de versões é tão bom quanto as entradas dele. No Changeloop, uma entrada em rascunho é criada a partir de cada pull request integrado e retida para uma pessoa aprovar antes de ser publicada na página e no feed do changelog. É ali que uma entrada por versão é escrita, e o único portão humano é a revisão que diz o que quem chama precisa fazer.

FAQ

Qual é a versão mais recente da API do Stripe? No momento em que escrevo (outubro de 2026), a página de versionamento do Stripe afirma que a versão atual é 2026-09-30.endive. O Stripe emite uma versão nova todo mês, então confira o changelog antes de fixar, e escreva a versão no seu código em vez de depender do padrão da conta.

Como definir a versão da API do Stripe em uma requisição? Envie o header Stripe-Version, por exemplo Stripe-Version: 2026-09-30.endive, ou defina a versão no seu SDK de servidor, globalmente ou por requisição. Sem nenhum dos dois, a requisição usa a versão padrão da sua conta, que você define no Workbench.

Os webhooks usam a mesma versão da API do Stripe que as minhas requisições? Não necessariamente. Os eventos de webhook usam a versão definida quando o endpoint foi criado e, se nenhuma foi definida, o padrão da conta. Atualizar o SDK não muda o payload que o seu handler de webhook recebe, então atualize os endpoints separadamente e teste-os em paralelo.

O versionamento por data no estilo do Stripe serve para uma API pequena? Versões com data, um padrão fixado, um header por requisição e uma entrada de changelog por versão são baratos e valem a cópia. A cadeia interna de módulos de mudança de versão não vale, até que vocês suportem muitas versões antigas ao mesmo tempo. Comecem com duas versões ativas e uma data de sunset para a mais antiga.

As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.

Relacionado na changeloop: Documentação para desenvolvedores