Should I upgrade to Notion Old API Version vs SDK v5.12 Opt-In to 2026-03-11 now?
Decide whether to stay pinned on an older Notion API version or upgrade the SDK and adopt the March 2026 schema changes now.
Blockers
- requires_version: package/notionhq-client-v5-12-0 → protocol/notion-api-2026-03-11
- requires_version: package/notionhq-client-v5-12-0 → protocol/notion-api-2025-09-03
- breaking_change_in: format/after → protocol/notion-api-2026-03-11
- breaking_change_in: format/archived → protocol/notion-api-2026-03-11
- breaking_change_in: format/transcription → protocol/notion-api-2026-03-11
- requires_version: capability/webhooks → protocol/notion-api-2026-03-11
- breaking_change_in: package/notionhq-client-v5-0-0 → protocol/notion-api-2022-06-28
Who this is for
- small-team
- low-ops
Candidates
Stay on API version 2025-09-03 for now
As of 2026-03-20, Notion says it has no current plans to stop supporting older API versions. The official JS/TS SDK supports both API versions `2025-09-03` and `2026-03-11`, and the SDK default remains `2025-09-03` unless you explicitly set `notionVersion`. Deferring opt-in avoids immediate migration work for the three March 2026 breaking changes: `after` to `position`, `archived` to `in_trash`, and `transcription` to `meeting_notes`. This is the lowest-risk choice if your integration already works and you do not need the latest version alignment yet.
When to choose
Use this when you are `small-team` plus `low-ops` and want to avoid touching stable integration code right now. The decisive factor is that Notion has not published a deprecation deadline for older API versions, so there is no forced cutoff as of 2026-03-20.
Tradeoffs
You minimize immediate migration risk and can keep shipping without schema updates. The downside is staying off the newest API surface and carrying a later migration task.
Cautions
If you are pinned earlier than `2025-09-03`, do not assume the latest JS/TS SDK is compatible: Notion states SDK `v5.0.0` and above dropped support for `2022-06-28` and earlier. Also note that new webhook actions default to `2026-03-11`, so mixed-version behavior can appear over time.
Upgrade to @notionhq/client v5.12.0+ and opt in to 2026-03-11 now
As of 2026-03-20, Notion API version `2026-03-11` is available and the official JS/TS SDK added support in `@notionhq/client` `v5.12.0`. Notion describes the release as three breaking changes intended to simplify the API surface, and its upgrade guide says most integrations only need simple find-and-replace updates. The required migration points are `after` to `position` for Append Block Children, `archived` to `in_trash` in REST request and response handling, and `transcription` to `meeting_notes`. This path gets you onto the latest official version and aligns new code with current docs.
When to choose
Use this when version alignment and reducing future migration drag matter more than short-term stability. The decisive factor is whether you can budget a focused migration pass across REST calls, block filtering, and any typed code that still references deprecated names.
Tradeoffs
You clear the migration now and match the current API release with official SDK support. The cost is immediate regression risk anywhere your code or tests still depend on the old field names or block type.
Cautions
The SDK keeps old names in TypeScript types with `@deprecated` annotations, so code may still compile while remaining only partially migrated. Also, the `archived` to `in_trash` rename does not apply to webhook event payloads, so do not over-apply the rename to integration webhook consumers.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to Notion Old API Version vs SDK v5.12 Opt-In to 2026-03-11 now?"