klaviyo-upgrade-migration

name	klaviyo-upgrade-migration
description	Upgrade Klaviyo SDK versions and migrate between API revisions. Use when upgrading the klaviyo-api package, migrating from v1/v2 legacy APIs to the current REST API, or handling breaking changes between revisions. Trigger with phrases like "upgrade klaviyo", "klaviyo migration", "klaviyo breaking changes", "update klaviyo SDK", "klaviyo API revision".
allowed-tools	Read, Edit, Bash(npm:*), Bash(git:*)
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","klaviyo","email-marketing","cdp"]
compatibility	Designed for Claude Code

Klaviyo Upgrade & Migration

Overview

Guide for upgrading the klaviyo-api SDK, migrating from legacy v1/v2 APIs, and handling breaking changes between Klaviyo API revisions. The workflow assesses the current version, surfaces breaking changes with the TypeScript compiler, applies the matching migration pattern, and ships behind a staging deploy with a clean rollback.

Deep before/after code and the full command sequence live in references/ so this file stays a scannable map of the workflow:

• Migration patterns — legacy v1/v2 → current API, SDK major upgrade (ConfigWrapper → ApiKeySession), property casing.
• Upgrade & rollback procedure — pinned install, tsc/test gates, staging deploy, rollback, migration checklist.

Prerequisites

• The klaviyo-api package installed and a known current version (npm list klaviyo-api).
• Git available, with a clean working tree so the upgrade lands on its own branch.
• A working test suite (npm test), and ideally a staging integration test target.
• A Klaviyo private API key in the environment for integration verification.

Klaviyo API Revision Timeline

Each revision is supported for 2 years after release. Plan to move to the latest every 12-18 months so you never fall inside the deprecation window.

Revision	Released	Deprecated	Key Changes
2024-10-15	Oct 2024	Oct 2026	Reporting API, campaign message updates
2024-07-15	Jul 2024	Jul 2026	Custom objects, tracking settings
2024-02-15	Feb 2024	Feb 2026	Bulk operations, segments V2
2023-12-15	Dec 2023	Dec 2025	Profile subscription changes
2023-07-15	Jul 2023	Jul 2025	Relationship endpoint restructuring

Instructions

Step 1: Assess the current state

Compare what is installed against what is published to size the jump. A single major step is routine; skipping several majors means expect casing and import changes.