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.
npm list klaviyo-api
npm view klaviyo-api version
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"
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.
