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.

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

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

• API Versioning & Deprecation Policy
• v1/v2 Migration Guide
• Relationship Migration
• klaviyo-api-node Releases

Next Steps

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