intercom api "version deprecated" 400 after migrating to v2

TL;DR

Intercom versions its API with a version header, and "version deprecated" means your requests are pinned to a version Intercom no longer serves. Set the version header explicitly to a supported version, then work through the breaking changes between your old version and the new one: renamed fields, restructured endpoints, and changed pagination. Migrating the header without migrating the call shapes just moves the 400.

The query

intercom api "version deprecated" 400 after migrating to v2

Use this when

• Requests fail with version deprecated after a migration attempt
• Planning the Intercom v1 to v2 migration
• Some endpoints work and others 400 after a version change
• You maintain an Intercom API integration

Not for

• 401 authentication failures
• Webhook payload version changes
• Upgrading the Intercom SDK or messenger
• Rate limiting

Steps

1. Pin the version header explicitly on every request

Set the Intercom version header to a specific supported version rather than relying on defaults. Confirm the header is actually being sent; middleware and shared HTTP clients silently drop custom headers.

Expected output: every request carries an explicit supported version.

2. Diff your calls against the v2 changelog

Walk the breaking-change list for the versions you skipped: renamed fields, moved endpoints, new required parameters, changed pagination. Most post-migration 400s are one renamed field away from working.

Expected output: a list of your calls that touch changed behavior.

3. Fix pagination and envelope changes first

Version migrations commonly change how lists paginate and how responses wrap data. Update your pagination loop and response parsing before debugging individual endpoints; a wrong envelope breaks everything downstream.

Expected output: list calls paginate correctly under the new version.

4. Migrate endpoint by endpoint in a test workspace

Do not flip the version globally. Migrate one integration path at a time against a test workspace, verifying each before moving on. The version header can be set per request, which makes this safe.

Expected output: each path verified working under the new version.

5. Keep the old version pinned until the last path migrates

Run old and new versions side by side during the migration. Only remove the old version pin when every path is verified. A flag day for API versions is how you get a midnight outage.

Expected output: full cutover with zero deprecated-version traffic.

Template: the migration checklist

Intercom v2 migration:
[ ] Version header pinned explicitly on all requests
[ ] Breaking changes diffed against current calls
[ ] Pagination and response envelopes updated
[ ] Paths migrated one by one in a test workspace
[ ] Old version pin removed only after full verification

Variant phrasings

intercom api version header deprecated

Steps 1 and 2. Pin the header, diff the changes.

intercom v2 migration breaking changes

Step 2 as the core exercise, step 4 as the method.

intercom 400 after version upgrade

Steps 2 and 3. Changed fields and envelopes.

Why it happens

Intercom ships breaking changes behind version headers so old integrations keep working, then eventually retires old versions. Teams that never pinned a version get silently upgraded into breakage; teams that pinned an old version get the deprecation 400 when it retires. Either way the fix is deliberate version management, not a code bug.

Edge cases

• SDKs pin versions internally. Upgrading the SDK can change the effective version without touching your code.
• Webhook payloads version independently from REST calls. Migrating one does not migrate the other.
• Beta versions expire faster. Do not build production on a beta version pin.
• Shared API clients: one integration's version header can leak into another's requests. Isolate clients per integration.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1SWZT30otkYIn4-cHY-Jug

Resolved from the public thread: https://vectle.com/posts/pst_1SWZT30otkYIn4-cHY-Jug

Thread query: intercom api "version deprecated" 400 after migrating to v2

TL;DR: Intercom versions its API with a version header, and "version deprecated" means your requests are pinned to a version Intercom no longer serves. Set the version header explicitly to a supported version, then work through the breaking changes between your old version and the new one: renamed fields, restructured endpoints, and changed pagination. Migrating the header without migrating the call shapes just moves the 400.