Klaviyo Upgrade & Migration Skill

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.

npm list klaviyo-api          # e.g. klaviyo-api@15.0.0
npm view klaviyo-api version  # latest, e.g. 21.0.0

Step 2: Find affected usage

Read the releases changelog for the target major, then locate the call sites that will need edits.

grep -rn "from 'klaviyo-api'" src/
grep -rn "ApiKeySession\|ConfigWrapper\|ProfilesApi\|EventsApi" src/

Step 3: Apply the matching migration pattern

Pick the pattern that fits the errors you see and edit each call site. Full before/after code is in migration patterns:

Legacy v1/v2 → current API — replace raw /api/v2/... HTTP calls with typed EventsApi / ProfilesApi resource classes.
SDK major upgrade — swap the global ConfigWrapper('pk_***') for a per-instance new ApiKeySession('pk_***') passed to each *Api.
Property casing — rename snake_case attributes (first_name) to camelCase (firstName).

Step 4: Upgrade, verify, and ship

Install the target version pinned, let tsc and the test suite gate the change, and deploy to staging before production. Full commands: upgrade procedure.

git checkout -b upgrade/klaviyo-api-v21
npm install klaviyo-api@21.0.0 --save-exact
npx tsc --noEmit 2>&1 | grep -i "klaviyo\|error TS"   # find breaking changes
npm test

Step 5: Roll back if needed

If error rates rise after the upgrade, reinstall the previous exact version — see the rollback procedure. Because Step 4 pinned versions, rollback is a clean reinstall with no dependency guesswork.

Output

Running this workflow produces:

An upgrade/klaviyo-api-vNN branch with package.json + package-lock.json pinned to the target version via --save-exact.
Edited call sites in src/ using the current ApiKeySession pattern and camelCase attributes, with npx tsc --noEmit clean.
A green npm test (and staging test:integration) run confirming the migration.
A commit deployed to staging first, with a documented rollback commit ready if 24-hour error monitoring flags a regression.

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | TypeError: ConfigWrapper is not a function | Old SDK pattern | Switch to ApiKeySession pattern | | Property 'first_name' does not exist | Casing change | Use firstName (camelCase) | | response.data is undefined | Access pattern change | Use response.body.data | | revision not supported | Deprecated revision | Update revision header value |

Examples

Migrate a v2 identify call to the current SDK. After grep finds a legacy /api/identify call, replace it with createOrUpdateProfile:

import { ApiKeySession, ProfilesApi, ProfileEnum } from 'klaviyo-api';

const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);
const profilesApi = new ProfilesApi(session);
await profilesApi.createOrUpdateProfile({
  data: {
    type: ProfileEnum.Profile,
    attributes: { email: 'user@example.com', firstName: 'Jane', properties: { plan: 'pro' } },
  },
});

The full set of before/after examples — event tracking, the ConfigWrapper → ApiKeySession upgrade, and property casing — is in migration patterns.

Resources

Next Steps

For wiring these upgrade checks into continuous integration, see the klaviyo-ci-integration skill.

Agent Skills: Klaviyo Upgrade & Migration

Install this agent skill to your local

Skill Files