Which strategy should I use for Intercom API v2.12 Migration Before December 2026?
Choose whether to stay pinned to Intercom API v2.12 behavior for now or migrate to newer API versions before v2.12 is fully deprecated in December 2026.
Blockers
- eol_date: protocol/intercom-rest-api-v2.12 → n/a
- breaking_change_in: protocol/intercom-rest-api-v2.12 → capability/tickets
- breaking_change_in: protocol/intercom-rest-api-v2.14 → capability/tickets
- breaking_change_in: protocol/intercom-rest-api-v2.15 → capability/webhooks
- Lock-in via vendor/intercom
Who this is for
- low-ops
- enterprise
- small-team
Candidates
Stay on v2.12 temporarily while isolating migration blockers
Intercom's v2.12 changelog says the version includes breaking changes and that the API will be deprecated completely in December 2026. As of 2026-03-27, the public Intercom pricing page is still framed around workspace plans, seats, and usage charges rather than API-version pricing, so this is mainly a compatibility and delivery-timing decision. If you are already stable on v2.12, you can keep it briefly while you test newer versions via the `Intercom-Version` header and inventory webhook and ticket-state dependencies. This minimizes immediate churn, but it leaves a hard platform deadline in place.
When to choose
Use this when you need a short-term freeze because production integrations are stable on v2.12 and you have a near-term delivery constraint. The decisive factor is whether you can commit engineering time soon to remove migration blockers before December 2026.
Tradeoffs
Lowest immediate change risk and easiest rollback path, but it defers work into a fixed deprecation window and delays access to newer APIs and webhook behavior.
Cautions
v2.12 already changed ticket state responses to a `ticket_state` object, deprecated using `state` in request bodies in favor of `ticket_state_id`, and removed run assignment rules in v2.12 and all following versions. If your code still depends on older pre-v2.12 ticket or assignment behavior, pinning does not solve the underlying migration work.
Migrate now to the latest stable version shown in the docs
As of 2026-03-27, Intercom's current REST API reference shows v2.15, and both v2.14 and v2.15 introduce additional breaking changes on top of v2.12. v2.14 changes ticket update behavior and splits admin assignment limit activity logs, while v2.15 changes ticket webhook semantics, conversation webhook serialization, and some AI Agent enum values. Moving now reduces deadline risk and lets you adopt newer endpoints and fields instead of carrying a temporary compatibility layer until late 2026. This is the better long-horizon choice if you can test tickets, webhooks, and conversation payload consumers.
When to choose
Use this when you want to eliminate deprecation risk early and can run integration tests against webhook payloads and ticket workflows. The decisive factor is whether your integration depends on `ticket.closed`, HTML webhook fields, or older ticket update semantics.
Tradeoffs
Best long-term support posture and feature access, but it requires coordinated code changes across webhook consumers, ticket update calls, and any AI-state or conversation parsing logic.
Cautions
In v2.15, `ticket.closed` no longer means the same thing for resolved tickets, conversation webhook `body` and `subject` move to plain text, and date fields in webhook statistics move to Unix timestamps. In v2.14, `PUT /tickets/{id}` changes shape and requires attention to `admin_id` and assignment behavior.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Which strategy should I use for Intercom API v2.12 Migration Before December 2026?"