Notion upgrade migration

Notion Upgrade & Migration

Overview

Step-by-step guide for upgrading @notionhq/client (Node.js) and notion-client (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version 2022-06-28 and the SDK feature timeline through v2.x.

The workflow is three phases — audit what you run today, upgrade on an isolated branch while fixing breaking changes, then verify every API surface before merging. Deep code (the full breaking-change catalog, the verification suite, and worked recipes) lives in references/ so this file stays a scannable playbook.

Prerequisites

• Existing project with @notionhq/client or notion-client installed
• Git repository with clean working tree (no uncommitted changes)
• Test suite covering Notion API calls (or willingness to add verification tests)
• NOTION_TOKEN environment variable configured

Instructions

Step 1: Audit Current Versions and API Surface

Determine what you are running today before changing anything.

# Node.js — installed vs latest SDK version
npm ls @notionhq/client
npm view @notionhq/client version

# Python — installed vs latest SDK version
pip show notion-client 2>/dev/null | grep Version
pip index versions notion-client 2>/dev/null | head -1

# Find which API version your code specifies
grep -rn "notionVersion\|Notion-Version\|notion_version" src/ lib/ app/ 2>/dev/null

Record the current SDK version and API version before proceeding. If no notionVersion is set explicitly, the SDK uses its built-in default (typically 2022-06-28 for current releases).

SDK version history — key milestones:

SDK Version	Notable Additions
2.2.0	Comments API support (notion.comments.create, notion.comments.list)
2.2.3	Status property type in database schemas
2.2.4	Unique ID property, verification property
2.2.13	Improved TypeScript discriminated unions for block types
2.2.15	Current stable — bug fixes, dependency updates

API version timeline:

API Version	Key Changes
2022-02-22	Rich text standardization, consistent pagination
2022-06-28	Current stable — most tutorials and production apps use this

Step 2: Perform the Upgrade

Create an isolated branch, upgrade the package, and address breaking changes before merging.

# Node.js
git checkout -b upgrade/notionhq-client-$(npm view @notionhq/client version)
npm install @notionhq/client@latest
git diff package.json package-lock.json

# Python
git checkout -b upgrade/notion-client-$(pip show notion-client 2>/dev/null | grep Version | awk '{print $2}')
pip install --upgrade notion-client
pip show notion-client | grep Version

After any major version bump, check four things: endpoint-type import paths (they moved in some releases), error-handling imports (stable across 2.x), new property types your extraction logic must handle gracefully (status added in 2.2.3, unique_id in 2.2.4), and an explicitly pinned notionVersion so behavior is reproducible instead of tracking the SDK default. The complete before/after code for Node.js and Python is in breaking-changes.md.

Step 3: Verify and Test the Upgrade

Run targeted verification tests to confirm nothing broke — test each API surface your application uses (auth, database query, page create/archive, block read/append, comments), then run the project suite and merge. Skeleton:

const notion = new Client({ auth: process.env.NOTION_TOKEN, notionVersion: '2022-06-28' });

async function verifyDatabaseQuery(databaseId: string) {
  const res = await notion.databases.query({ database_id: databaseId, page_size: 5 });
  console.log(`Query OK — ${res.results.length} pages, has_more=${res.has_more}`);
}

The full five-test verification suite plus the merge commands are in verification.md.

Output

• SDK upgraded to the latest stable release with exact version pinned in package.json
• API version explicitly set in client initialization (not relying on SDK default)
• New property types (status, unique_id) handled in extraction logic
• All existing API calls verified — database queries, page CRUD, block operations
• Upgrade branch merged with clean test run

Error Handling

Issue	Cause	Solution
TypeError: Cannot read properties of undefined	New property type returned by API that code does not handle	Add a default case to property type switch — see Step 2
APIResponseError: Could not find ...	Stale page/database ID after workspace migration	Re-share pages with the integration at notion.so/my-integrations
notionVersion is not a valid API version	Typo or unsupported version string	Use 2022-06-28 — confirm at developers.notion.com/reference/versioning
Type errors on api-endpoints imports	Import path changed between SDK major versions	Check node_modules/@notionhq/client/build/src/api-endpoints.d.ts for current exports
ENOTFOUND api.notion.com	Network or proxy blocking Notion API	Verify DNS, check corporate proxy, test with curl https://api.notion.com/v1/users/me
pip install fails for notion-client	Python version incompatible	Requires Python 3.7+; use pip install --upgrade pip first

Examples

Common follow-ons — each is a full recipe in examples.md:

• Rollback after a failed upgrade — pin the exact previous SDK version, restore source, re-test.
• Adopting the Comments API (SDK 2.2.0+) — create and list comments on a page.
• Detecting new property types — scan existing databases for types your extraction code does not yet handle.
• Deprecation monitoring — a bash audit for raw Notion-Version headers, untyped responses, and SDK version drift.

Resources

• Notion SDK Releases — changelog for every @notionhq/client version
• API Versioning — version lifecycle and header format
• Python notion-client — PyPI page with version history
• API Status — check for ongoing incidents before debugging upgrade issues

Next Steps

After upgrading, apply production patterns from notion-sdk-patterns and verify rate limit handling with notion-rate-limits.