---
title: "Growing A Platform: Introducing API Versioning In Intercom"
description: "Intercom introduced API versioning for their REST and Messenger Framework APIs, using their open-source Requisite library, enabling safe, frequent updates without breaking existing integrations. Previously, API changes required advance notice and coordinated migrations, which was unreliable and hindered iteration, so they conducted user research to identify friction points. The versioning system uses ‘version changes’ — single transformations that roll back a model change to a previous version, such as renaming user_id to customer_id, allowing controllers to always operate on the latest version and chain multiple changes. Developers can test isolated requests using a specific header and upgrade through the Developer Hub, with the ability to roll back immediately if something goes wrong. This design, inspired by Stripe’s approach, allows Intercom to ship changes more frequently and safely across REST API, Messenger Framework, and webhooks."
---

# Growing A Platform: Introducing API Versioning In Intercom

[Intercom](https://yomu.fyi/company/intercom) · Oct 9, 2026

**Type:** Problem & solution

## Summary

Intercom introduced API versioning for their REST and Messenger Framework APIs, using their open-source Requisite library, enabling safe, frequent updates without breaking existing integrations. Previously, API changes required advance notice and coordinated migrations, which was unreliable and hindered iteration, so they conducted user research to identify friction points. The versioning system uses ‘version changes’ — single transformations that roll back a model change to a previous version, such as renaming user\_id to customer\_id, allowing controllers to always operate on the latest version and chain multiple changes. Developers can test isolated requests using a specific header and upgrade through the Developer Hub, with the ability to roll back immediately if something goes wrong. This design, inspired by Stripe’s approach, allows Intercom to ship changes more frequently and safely across REST API, Messenger Framework, and webhooks.

## Context

Intercom’s engineering team faced the challenge of making backwards-incompatible changes to their APIs without breaking existing integrations, which conflicted with their principle of shipping frequently. They conducted user research to understand developer needs and identified the need for clear changelogs, advance notice, and easy testing and rollback.

## Approach / What changed

Intercom implemented API versioning by introducing VersionChange objects that represent single transformations to roll back a model change to a previous version. Controllers always operate on the latest version, and transformations are applied in reverse order for older versions. Multiple VersionChanges are compiled into a Version. Developers can test with a header and upgrade via the Developer Hub.

## Takeaways

- API versioning allows Intercom to ship changes more frequently and safely without forcing all developers to upgrade immediately.
- The versioning system uses VersionChange objects that transform the latest model back to previous versions, keeping controllers on the latest version.
- Developers can test isolated requests using a specific header and upgrade or roll back through the Developer Hub.

## FAQ

### How does Intercom handle backwards-incompatible changes?

They introduce version changes that transform the latest model to previous versions, allowing developers to opt-in to new versions when ready.

### Can developers test new API versions before upgrading?

Yes, they can test isolated requests using a specific header to ensure compatibility before updating their app's version.

### What inspired Intercom's API versioning approach?

The approach was inspired by Stripe's API versioning blog post.

**Tags:** [API](https://yomu.fyi/topic/api), [API Versioning](https://yomu.fyi/topic/api-versioning), [Developer Experience](https://yomu.fyi/topic/developer-experience), [REST APIs](https://yomu.fyi/topic/rest-api)

- Source: [Intercom](https://www.intercom.com/blog/api-versioning)
- Source URL: https://www.intercom.com/blog/api-versioning
- Ingested by Yomu: 2026-10-09T12:01:53.233Z

[Read original post](https://www.intercom.com/blog/api-versioning)