klaviyo-upgrade-migration | klaviyo-pack

Stats

Actions

Tags

klaviyo-upgrade-migration | klaviyo-pack

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.

Prerequisites

Current Klaviyo SDK installed
Git for version control
Test suite available

Klaviyo API Revision Timeline

Each revision is supported for 2 years after release. Connect to the latest every 12-18 months.

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 Current State

# Check current SDK version
npm list klaviyo-api
# e.g., [email protected]

# Check latest available
npm view klaviyo-api version
# e.g., 21.0.0

# See all available versions
npm view klaviyo-api versions --json | tail -10

Step 2: Review Breaking Changes

# View changelog
# https://github.com/klaviyo/klaviyo-api-node/releases

# Find your usage patterns that may be affected
grep -rn "from 'klaviyo-api'" src/
grep -rn "ApiKeySession\|ProfilesApi\|EventsApi" src/

Step 3: Common Migration Patterns

Legacy v1/v2 to Current API

// BEFORE: Legacy v1/v2 endpoints (DEPRECATED)
// POST https://a.klaviyo.com/api/v2/list/LIST_ID/subscribe
// POST https://a.klaviyo.com/api/track

// AFTER: Current REST API (2024-10-15)
import { ApiKeySession, ProfilesApi, EventsApi, ProfileEnum } from 'klaviyo-api';

const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);

// v2 Track → Create Event
const eventsApi = new EventsApi(session);
await eventsApi.createEvent({
  data: {
    type: 'event',
    attributes: {
      metric: { data: { type: 'metric', attributes: { name: 'Placed Order' } } },
      profile: { data: { type: 'profile', attributes: { email: '[email protected]' } } },
      properties: { orderId: '123' },
      time: new Date().toISOString(),
      value: 99.99,
    },
  },
});

// v2 Identify → Create or Update Profile
const profilesApi = new ProfilesApi(session);
await profilesApi.createOrUpdateProfile({
  data: {
    type: ProfileEnum.Profile,
    attributes: {
      email: '[email protected]',
      firstName: 'Jane',
      properties: { plan: 'pro' },
    },
  },
});

SDK Version Upgrade (e.g., v15 to v21)

// BEFORE (older SDK versions): ConfigWrapper pattern
// import { ConfigWrapper, Profiles } from 'klaviyo-api';
// ConfigWrapper('pk_***');
// const profiles = await Profiles.getProfiles();

// AFTER (v21+): ApiKeySession pattern
import { ApiKeySession, ProfilesApi } from 'klaviyo-api';
const session = new ApiKeySession('pk_***');
const profilesApi = new ProfilesApi(session);
const profiles = await profilesApi.getProfiles();

Property Casing Changes

// BEFORE: Some older versions used snake_case
// { first_name: 'Jane', phone_number: '+1555...' }

// AFTER: SDK v21+ uses camelCase everywhere
{ firstName: 'Jane', phoneNumber: '+15551234567' }

Step 4: Upgrade Procedure

# 1. Create upgrade branch
git checkout -b upgrade/klaviyo-api-v21

# 2. Install new version
npm install [email protected] --save-exact

# 3. Run TypeScript compiler to find breaking changes
npx tsc --noEmit 2>&1 | grep -i "klaviyo\|error TS"

# 4. Fix all type errors, then run tests
npm test

# 5. Run integration tests against staging
KLAVIYO_TEST=1 npm run test:integration

# 6. Commit and deploy to staging first
git add package.json package-lock.json src/
git commit -m "upgrade: klaviyo-api to v21.0.0"

Step 5: Rollback Procedure

# If issues found after upgrade
npm install [email protected] --save-exact
npm test
git add package.json package-lock.json
git commit -m "revert: rollback klaviyo-api to v15.0.0"

Migration Checklist

Backup current package-lock.json
Read SDK changelog for target version
Update ApiKeySession import (if changed)
Fix property casing (camelCase in v21+)
Update response access pattern (response.body.data)
Verify all filter syntax still works
Run full test suite
Deploy to staging first
Monitor error rates for 24 hours after production deploy

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

Resources

Next Steps

For CI integration during upgrades, see klaviyo-ci-integration.