Notion API Production Deployment Checklist

Overview

A structured 12-section checklist for deploying Notion API integrations to production, covering authentication security, capability scoping, page sharing, rate limits, pagination, error handling, versioning, retries, monitoring, graceful degradation, data validation, and OAuth token lifecycle. Each section maps to a specific failure mode seen in production Notion integrations, and every item is testable — the skill produces a verified pass/fail report, not aspirational guidance.

Prerequisites

• Node.js 18+ with @notionhq/client v2.x installed
• Working Notion integration tested in a development workspace
• Production Notion API token (internal) or OAuth credentials (public integration)
• Target databases and pages identified by ID
• Deployment platform configured (Vercel, Railway, AWS, etc.)

Verify SDK is installed:

node -e "const { Client } = require('@notionhq/client'); console.log('SDK loaded')" 2>/dev/null \
  || echo "MISSING: npm install @notionhq/client"

Instructions

Work through the checklist in order, marking each item pass or fail. A single fail in sections 1-6 is a deployment blocker.

1. Run the pre-deploy smoke test (see Examples) to confirm the token is set, auth works, and target databases are reachable. This catches the most common failure — a page that is not shared with the integration — before you go deeper.
2. Grade each of the 12 sections against its checkbox items. The summary table below is the map; the full item-by-item detail, fail criteria, and code snippets live in references/checklist-sections.md.
3. Pull implementation patterns (rate-limited queue, paginator, typed error handler, retry, cache fallback, property validator, OAuth exchange) from references/code-examples.md as each section requires them.
4. Record a pass/fail per section and total the blocking (1-6) vs non-blocking (7-12) failures.
5. Emit the readiness report (see Output) with the final verdict: ready to deploy, or blocked with the count of items to fix.

The 12 sections at a glance

Full detail for every section — all checkbox items, capability/alert tables, and inline snippets — is in references/checklist-sections.md.

Output

After completing all 12 sections, produce a deployment readiness report:

NOTION PRODUCTION READINESS REPORT
===================================
Date: YYYY-MM-DD
Integration: [integration name]
Environment: [production|staging]

Section 1:  Token Security          [PASS/FAIL]
Section 2:  Capability Scoping      [PASS/FAIL]
Section 3:  Page/DB Sharing         [PASS/FAIL]
Section 4:  Rate Limit Handling     [PASS/FAIL]
Section 5:  Pagination              [PASS/FAIL]
Section 6:  Error Handling          [PASS/FAIL]
Section 7:  API Version Pinned     [PASS/FAIL]
Section 8:  Retry Logic             [PASS/FAIL]
Section 9:  Monitoring              [PASS/FAIL]
Section 10: Graceful Degradation    [PASS/FAIL]
Section 11: Data Validation         [PASS/FAIL]
Section 12: OAuth (if applicable)   [PASS/FAIL/N/A]

BLOCKING FAILURES (Sections 1-6): [count]
NON-BLOCKING ISSUES (Sections 7-12): [count]

VERDICT: [READY TO DEPLOY / BLOCKED — fix N items]

Error Handling

Examples

Pre-Deploy Smoke Test Script

Run this first — it validates the token, auth, and target-database access in seconds.

#!/usr/bin/env bash
set -euo pipefail

echo "=== Notion Production Smoke Test ==="

# 1. Token is set
if [ -z "${NOTION_TOKEN:-}" ]; then
  echo "FAIL: NOTION_TOKEN not set"
  exit 1
fi
echo "PASS: NOTION_TOKEN is set (${#NOTION_TOKEN} chars)"

# 2. Token works (auth check)
AUTH_RESULT=$(curl -s -w "\n%{http_code}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28")

HTTP_CODE=$(echo "$AUTH_RESULT" | tail -1)
BODY=$(echo "$AUTH_RESULT" | head -n -1)

if [ "$HTTP_CODE" = "200" ]; then
  BOT_NAME=$(echo "$BODY" | jq -r '.name // "unknown"')
  echo "PASS: Auth OK — bot name: $BOT_NAME"
else
  echo "FAIL: Auth returned HTTP $HTTP_CODE"
  echo "$BODY" | jq . 2>/dev/null || echo "$BODY"
  exit 1
fi

# 3. Target database accessible (set NOTION_TARGET_DB to test)
DB_ID="${NOTION_TARGET_DB:-}"
if [ -n "$DB_ID" ]; then
  DB_RESULT=$(curl -s -o /dev/null -w "%{http_code}" \
    "https://api.notion.com/v1/databases/${DB_ID}" \
    -H "Authorization: Bearer ${NOTION_TOKEN}" \
    -H "Notion-Version: 2022-06-28")

  if [ "$DB_RESULT" = "200" ]; then
    echo "PASS: Target database accessible"
  else
    echo "FAIL: Target database returned HTTP $DB_RESULT — is it shared with the integration?"
    exit 1
  fi
fi

echo "=== Smoke Test Complete ==="

Production Client Initialization

See full production initialization for complete setup with rate limiting, version pinning, and log levels. For the per-section snippets (paginator, typed error handler, retry, cache fallback, property validator, OAuth exchange), see references/code-examples.md.

Resources

• Notion API Reference — Complete endpoint documentation
• Notion API Best Practices — Official key management guide
• Notion API Rate Limits — 3 req/sec per integration
• Notion API Changelog — Version differences and migration guides
• Notion Status Page — Real-time API availability
• @notionhq/client on npm — Official SDK documentation
• Notion OAuth Documentation — Public integration auth flow

Next Steps

After passing the production checklist, continue with related skills for ongoing operations. For initial setup and authentication, see notion-install-auth. For rate limit deep-dive, see notion-rate-limits. For error troubleshooting, see notion-common-errors. For incident response, see notion-incident-runbook. For API version migration, see notion-upgrade-migration. For monitoring setup, see notion-observability.