notion-upgrade-migration

name	notion-upgrade-migration
description	Upgrade @notionhq/client SDK versions and migrate between Notion API versions. Use when updating SDK packages, handling breaking changes between API versions, adopting new SDK features like comments API or status properties, or migrating Python notion-client. Trigger with phrases like "upgrade notion SDK", "notion migration", "notion breaking changes", "update notionhq client", "notion API version upgrade", "notion deprecation".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(git:*), Glob, Grep
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

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