| 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 <jeremy@intentsolutions.io> |
| 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:
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.
