Версионирование API Stripe: как оно работает и что перенять

Версионирование API Stripe устроено по датам. Каждый аккаунт привязан к версии API, названной по дате релиза, а любой отдельный запрос может переопределить эту привязку заголовком Stripe-Version. На момент написания (октябрь 2026 года) текущая версия в документации Stripe это 2026-09-30.endive, и ту же схему гораздо меньший API может повторить за выходные.

Все факты о Stripe ниже взяты со страниц самого Stripe, со ссылками там, где они используются.

Как работает версионирование API Stripe?

Stripe даёт каждому аккаунту версию API по умолчанию, и каждый запрос, не называющий версию, использует её. Вызывающие сами выбирают, когда переходить: меняют версию по умолчанию или задают версию в отдельных запросах.

В инженерной статье Stripe сказано, что аккаунт закрепляется при первом запросе к API: он «автоматически закрепляется за самой свежей доступной версией», и с тех пор каждому вызову неявно присваивается эта версия.

Строка версии это дата. Начиная с релиза 2024-09-30.acacia в ней есть ещё и название, как в 2026-09-30.endive. Дата упорядочивает версии, а название показывает, к какому семейству мажорных релизов версия относится.

Как выбрать версию для отдельного запроса?

Отправьте в запросе заголовок Stripe-Version или задайте версию в SDK. Руководство Stripe по обновлению показывает форму с заголовком, и тот же вызов работает и в боевой, и в тестовой среде.

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

В руководстве Stripe отмечено, что если вы задаёте версию глобально или для запроса в SDK, объекты в ответах приходят в этой версии.

Stripe также советует не полагаться на версию аккаунта по умолчанию. По его словам, указывайте версию в каждом запросе, заголовком или закреплённым SDK, чтобы версию определял ваш код, а не настройка в панели.

SDK закрепляют версию по-разному в зависимости от языка. В документации сказано, что свежие версии библиотек для динамически типизированных языков используют ту версию API, которая была последней на момент выхода релиза SDK, а строго типизированные (Java, Go и .NET) жёстко к ней привязаны. Установить версию библиотеки значит, по сути, выбрать версию API.

Что происходит с вебхуками при смене версии?

Событие вебхука формируется в версии API, привязанной к его endpoint, а не в той, которую использует код вашего сервера. В документации Stripe сказано, что события используют версию, заданную при создании endpoint, а если её нет, то версию аккаунта по умолчанию. Смена версии SDK не меняет то, что получает ваш обработчик вебхуков.

Поэтому путь запросов и путь событий могут находиться на двух разных версиях. Для приёмников событий snapshot_api_version задаётся только при создании приёмника, так что другая версия означает новый приёмник.

Путь обновления у Stripe для этого такой: параллельный запуск. Создайте новый endpoint с целевой версией, отправляйте одни и те же события на оба, научите обработчик обрабатывать один и игнорировать другой, затем переключитесь и отключите старый endpoint. Поскольку в период перекрытия каждое событие приходит дважды, обработчик должен быть идемпотентным. Это хороший приём для любого API, которое рассылает события, а changelog вебхуков это место, где вы объявляете изменения payload, делающие его необходимым.

Что такое ежемесячные и мажорные релизы?

Начиная с релиза 2024-09-30.acacia Stripe выпускает новую версию API ежемесячно без breaking changes и дважды в год выпускает новый мажорный релиз, который начинается с версии с breaking changes. На странице версионирования сказано, что перейти на любой ежемесячный релиз можно без изменения кода, а мажорный релиз может потребовать правок.

У мажорных релизов есть названия. Страница версионирования приводит пример Basil, а в анонсе процесса Stripe сказано, что названия берутся из растений, начиная с Acacia, и что ежемесячные релизы сохраняют название предшествующего мажорного, чтобы название сигнализировало: на них безопасно переходить. В changelog Stripe перечислены используемые названия, и на момент написания самая новая запись это 2026-09-30.endive.

Так что дата отвечает на вопрос «насколько свежая», а название на вопрос «это граница breaking changes?». Анонс Stripe оставляет место и для исключений: компания оставляет за собой право выпустить внеплановое breaking change, если без него интеграция серьёзно пострадает. Анонс находится по адресу Stripe’s new API release process.

Какая последняя версия API Stripe?

На момент написания (октябрь 2026 года) на странице версионирования Stripe указано, что текущая версия это 2026-09-30.endive, и в его changelog та же версия значится самой новой. Stripe публикует новую версию ежемесячно, поэтому любая строка в статье быстро стареет. Прочитайте живой changelog, прежде чем что-то закреплять, и закрепляйте ту версию, на которой тестировали.

Как Stripe сохраняет работу старых версий?

Stripe держит старые версии живыми, записывая каждое breaking change как самостоятельный модуль изменения версии и применяя модули в обратном порядке, от самой новой формы данных. Механизм описан в инженерной статье о версионировании API.

Каждый модуль объявляет, что он меняет, документирует изменение и содержит функцию преобразования. В статье приведён пример поля, которое из строки превращается в хеш. Чтобы собрать ответ, система определяет целевую версию, затем идёт назад во времени и применяет каждый встретившийся по пути модуль, пока не дойдёт до этой версии.

Из такой конструкции вытекают два побочных эффекта, и оба названы в статье. Поскольку модули объявляют поля и ресурсы, которых касаются, Stripe может генерировать свой changelog API из них при деплое. А поскольку версия аккаунта известна, документация может подстраиваться под неё и предупреждать об обратно несовместимых изменениях, появившихся с этой версии.

Чего это стоит и что взять небольшому API?

Версионирование стоит инженерного внимания, и Stripe это признаёт. В инженерной статье упомянута нагрузка на сопровождение и поставлена цель: чем меньше нужно думать о старом поведении при написании нового кода, тем лучше. Там же описаны лёгкие проверки API перед релизом, чтобы вообще не нуждаться в смене версии.

Небольшой API не может позволить себе цепочку модулей на каждую старую версию и не нуждается в ней. Берите части, в которых вся ценность:

1. Версии с датой. Дате не нужно суждение о том, что считать «мажорным», и вызывающие её читают. Статья лучшие практики версионирования API сравнивает это со схемами через URL и заголовок.
2. Закреплённая версия по умолчанию. Закрепите аккаунт или ключ за версией при первом использовании, чтобы API никогда не менялось под работающей интеграцией.
3. Переопределение в запросе. Заголовок, позволяющий вызывающему проверить новую версию на одном вызове, в боевой среде, до того как переходить.
4. Версия на endpoint вебхука. Payload событий это то место, где вызывающих чаще всего ждёт сюрприз.
5. Одна запись changelog на версию. Пусть в ней будут версия, дата, кого это касается и что делать. Что считается breaking это проверка того, что вообще принадлежит новой версии, а саму запись разбирает статья changelog API.

Цепочку модулей пропустите, пока число поддерживаемых версий этого не потребует. Две-три живые версии можно держать несколькими ветвлениями и датой sunset, о чём рассказывает статья вывод версии API из эксплуатации.

Если вы публикуете changelog с датами, история версий хороша ровно настолько, насколько хороши записи. В Changeloop из каждого влитого pull request создаётся черновик записи, и он удерживается до одобрения человеком, а затем публикуется на странице changelog и в ленте. Именно здесь пишется запись на версию, а единственный человеческий барьер это проверка, говорящая, что должен сделать вызывающий.

FAQ

Какая последняя версия API Stripe? На момент написания (октябрь 2026 года) на странице версионирования Stripe указано, что текущая версия это 2026-09-30.endive. Stripe выпускает новую версию ежемесячно, так что проверьте его changelog перед закреплением и впишите версию в код, а не полагайтесь на версию аккаунта по умолчанию.

Как задать версию API Stripe в запросе? Отправьте заголовок Stripe-Version, например Stripe-Version: 2026-09-30.endive, или задайте версию в серверном SDK глобально либо для запроса. Без того и другого запрос использует версию вашего аккаунта по умолчанию, которую вы задаёте в Workbench.

Используют ли вебхуки ту же версию API Stripe, что и мои запросы? Не обязательно. События вебхуков используют версию, заданную при создании endpoint, а если её нет, версию аккаунта по умолчанию. Обновление SDK не меняет payload, который получает ваш обработчик, поэтому обновляйте endpoint отдельно и тестируйте их параллельно.

Подходит ли небольшому API версионирование по датам в стиле Stripe? Версии с датой, закреплённая версия по умолчанию, заголовок в запросе и одна запись changelog на версию дёшевы и их стоит перенять. Внутренняя цепочка модулей изменения версии не стоит усилий, пока вы не поддерживаете много старых версий одновременно. Начните с двух живых версий и даты sunset для старшей.

Технические утверждения в этой статье не проходили независимую проверку. Если здесь что-то не так, сообщите нам, и мы исправим.

По теме на changeloop: Документация для разработчиков