Versionado de la API de Stripe: cómo funciona y qué copiar

El versionado de la API de Stripe funciona por fechas. Cada cuenta está fijada a una versión de la API que lleva el nombre de una fecha de lanzamiento, y cualquier petición individual puede sustituir esa fijación con un encabezado Stripe-Version. En el momento de escribir esto (octubre de 2026), la versión actual en la documentación de Stripe es 2026-09-30.endive, y el mismo esquema es algo que una API mucho más pequeña puede copiar en un fin de semana.

Cada dato sobre Stripe de abajo procede de las propias páginas de Stripe, enlazadas donde se usa.

¿Cómo funciona el versionado de la API de Stripe?

Stripe da a cada cuenta una versión de API por defecto, y toda petición que no nombra una versión usa esa. Quien llama decide cuándo pasar a otra, cambiando la versión por defecto o fijando una versión en peticiones individuales.

La publicación de ingeniería de Stripe dice que la cuenta queda fijada la primera vez que hace una petición a la API: se “fija automáticamente a la versión más reciente disponible”, y desde entonces cada llamada recibe esa versión de forma implícita.

La cadena de versión es una fecha. Desde el lanzamiento 2024-09-30.acacia lleva además un nombre, como en 2026-09-30.endive. La fecha ordena las versiones, y el nombre indica a qué familia de lanzamiento mayor pertenece una versión.

¿Cómo eliges la versión en cada petición?

Envía el encabezado Stripe-Version en la petición, o fija la versión en el SDK. La guía de actualización de Stripe muestra la forma con encabezado, y la misma llamada funciona en entornos reales y de prueba.

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

La guía de Stripe señala que, cuando fijas la versión de forma global o por petición en un SDK, los objetos de respuesta llegan en esa versión.

Stripe también desaconseja apoyarse en la versión por defecto de la cuenta. En sus palabras, especifica la versión en cada petición, con el encabezado o con un SDK fijado, para que sea tu código quien decide la versión y no un ajuste del panel.

Los SDK fijan la versión de manera distinta según el lenguaje. La documentación dice que las versiones recientes de las bibliotecas de tipado dinámico usan la versión de API que era la última cuando salió esa versión del SDK, y las de tipado fuerte (Java, Go y .NET) quedan fijadas a ella. Instalar una versión de la biblioteca es, en la práctica, elegir una versión de la API.

¿Qué pasa con los webhooks cuando cambia la versión?

Un evento de webhook se genera en la versión de API asociada a su endpoint, no en la versión que usa el código de tu servidor. La documentación de Stripe dice que los eventos usan la versión fijada al crear el endpoint y, si no, la versión por defecto de la cuenta. Cambiar la versión de tu SDK no cambia lo que recibe tu manejador de webhooks.

Por eso tu camino de peticiones y tu camino de eventos pueden estar en dos versiones distintas. En los destinos de eventos, snapshot_api_version solo se fija al crear el destino, así que otra versión significa un destino nuevo.

El camino de actualización de Stripe para esto es una ejecución en paralelo. Crea un endpoint nuevo en la versión de destino, envía los mismos eventos a ambos, enseña al manejador a procesar uno e ignorar el otro, cambia y desactiva el endpoint antiguo. Como cada evento llega dos veces durante el solapamiento, el manejador tiene que ser idempotente. Es un buen patrón para copiar en cualquier API que emita eventos, y un changelog de webhooks es donde anuncias los cambios de payload que lo hacen necesario.

¿Qué son los lanzamientos mensuales y los mayores?

Desde el lanzamiento 2024-09-30.acacia, Stripe publica una versión nueva de la API cada mes sin cambios incompatibles, y emite un lanzamiento mayor dos veces al año que empieza con una versión que contiene cambios incompatibles. Su página de versionado dice que puedes pasar a cualquier lanzamiento mensual sin actualizar tu código, mientras que un lanzamiento mayor puede exigir cambios.

Los lanzamientos mayores llevan nombre. La página de versionado da Basil como ejemplo, y el anuncio del proceso por parte de Stripe dice que los nombres proceden de plantas, empezando por Acacia, y que los lanzamientos mensuales conservan el nombre del lanzamiento mayor anterior para señalar que es seguro actualizar a ellos. El changelog de Stripe lista los nombres en uso, y en el momento de escribir esto la entrada más reciente es 2026-09-30.endive.

Así, la fecha responde a “qué tan nueva” y el nombre responde a “si es un límite con cambios incompatibles”. El anuncio de Stripe también deja espacio para excepciones: se reserva el derecho de publicar un cambio incompatible fuera de ciclo cuando una integración se vería gravemente afectada sin él. El anuncio está en Stripe’s new API release process.

¿Cuál es la última versión de la API de Stripe?

En el momento de escribir esto (octubre de 2026), la página de versionado de Stripe indica que la versión actual es 2026-09-30.endive, y su changelog lista la misma versión como la más reciente. Stripe publica una versión nueva cada mes, así que cualquier cadena impresa en un artículo envejece rápido. Lee el changelog en vivo antes de fijar nada, y fija la versión contra la que hiciste las pruebas.

¿Cómo mantiene Stripe funcionando las versiones antiguas?

Stripe mantiene vivas las versiones antiguas escribiendo cada cambio incompatible como un módulo de cambio de versión autocontenido y aplicando los módulos hacia atrás desde la forma más reciente de los datos. Su publicación de ingeniería sobre el versionado de la API describe el mecanismo.

Cada módulo declara qué cambia, documenta el cambio e incluye una función de transformación. La publicación da el ejemplo de un campo que pasa de cadena a hash. Para construir una respuesta, el sistema determina la versión de destino, retrocede en el tiempo y aplica cada módulo que encuentra por el camino hasta llegar a esa versión.

De ese diseño se siguen dos efectos secundarios, y la publicación nombra ambos. Como los módulos declaran los campos y recursos que tocan, Stripe puede generar su changelog de la API a partir de ellos al desplegar. Y como se conoce la versión de la cuenta, la documentación puede adaptarse a ella y avisar de los cambios incompatibles desde esa versión.

¿Cuánto cuesta, y qué debería copiar una API más pequeña?

El versionado cuesta atención de ingeniería, y Stripe lo dice. La publicación de ingeniería reconoce una carga de mantenimiento y plantea el objetivo de que cuanto menos haya que pensar en el comportamiento antiguo al escribir código nuevo, mejor. También describe revisiones ligeras de la API antes del lanzamiento, para evitar tener que cambiar de versión.

Una API pequeña no puede permitirse una cadena de módulos para cada versión antigua, y no la necesita. Copia las partes que aportan el valor:

1. Versiones con fecha. Una fecha no exige juzgar qué cuenta como “mayor”, y quien llama puede leerla. El artículo de buenas prácticas de versionado lo compara con los esquemas por URL y por encabezado.
2. Una versión por defecto fijada. Fija la cuenta o la clave a la versión del primer uso, para que la API nunca se mueva bajo una integración que funciona.
3. Una sustitución por petición. Un encabezado que permita a quien llama probar una versión nueva en una sola llamada, en producción, antes de comprometerse.
4. Una versión en el endpoint del webhook. Los payloads de eventos son donde más se sorprende a quien llama.
5. Una entrada de changelog por versión. Haz que nombre la versión, la fecha, a quién afecta y qué hacer. Qué cuenta como incompatible es la prueba de qué merece entrar en una versión nueva, y el artículo sobre el changelog de API cubre la propia entrada.

Sáltate la cadena de módulos hasta que el número de versiones soportadas te obligue. Dos o tres versiones vivas se pueden manejar con unas pocas ramas y una fecha de sunset, algo que retirar una versión de API recorre paso a paso.

Si publicas un changelog con fechas, el historial de versiones vale lo que valgan sus entradas. En Changeloop, se crea una entrada en borrador a partir de cada pull request fusionado y se retiene hasta que una persona la apruebe antes de publicarla en la página de changelog y en el feed. Ahí es donde se escribe la entrada de cada versión, y la única puerta humana es la revisión que dice qué debe hacer quien llama.

FAQ

¿Cuál es la última versión de la API de Stripe? En el momento de escribir esto (octubre de 2026), la página de versionado de Stripe indica que la versión actual es 2026-09-30.endive. Stripe emite una versión nueva cada mes, así que consulta su changelog antes de fijarla, y escribe la versión en tu código en lugar de depender de la versión por defecto de la cuenta.

¿Cómo fijo la versión de la API de Stripe en una petición? Envía el encabezado Stripe-Version, por ejemplo Stripe-Version: 2026-09-30.endive, o fija la versión en tu SDK del lado del servidor, de forma global o por petición. Sin ninguno de los dos, la petición usa la versión por defecto de tu cuenta, que tú fijas en Workbench.

¿Los webhooks usan la misma versión de la API de Stripe que mis peticiones? No necesariamente. Los eventos de webhook usan la versión fijada al crear el endpoint, y la versión por defecto de la cuenta si no se fijó ninguna. Actualizar tu SDK no cambia el payload que recibe tu manejador de webhooks, así que actualiza los endpoints por separado y pruébalos en paralelo.

¿El versionado por fechas al estilo Stripe es adecuado para una API pequeña? Las versiones con fecha, una versión por defecto fijada, un encabezado por petición y una entrada de changelog por versión son baratos y vale la pena copiarlos. La cadena interna de módulos de cambio de versión no lo es, hasta que soportes muchas versiones antiguas a la vez. Empieza con dos versiones vivas y una fecha de sunset para la más antigua.

Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.

Relacionado en changeloop: Documentación para desarrolladores