From klaviyo-pack
Upgrades klaviyo-api SDK versions and migrates from v1/v2 legacy APIs to current REST API, handling breaking changes between revisions.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin klaviyo-packThis skill is limited to using the following tools:
Guide for upgrading the `klaviyo-api` SDK, migrating from legacy v1/v2 APIs, and handling breaking changes between Klaviyo API revisions.
Guides Klaviyo migrations from v1/v2 APIs, Mailchimp/SendGrid, or full re-platforming via strangler fig pattern. Includes complexity tables, API mappings, and TypeScript SDK examples.
Plans and executes customerio-node SDK upgrades/migrations, assessing versions, handling legacy CustomerIO to TrackClient/APIClient changes, and validating updates.
Guides Documenso API v1 to v2 upgrades and TypeScript/Python SDK migrations with code examples and bash commands.
Share bugs, ideas, or general feedback.
Guide for upgrading the klaviyo-api SDK, migrating from legacy v1/v2 APIs, and handling breaking changes between Klaviyo API revisions.
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 |
# Check current SDK version
npm list klaviyo-api
# e.g., klaviyo-api@15.0.0
# 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
# 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/
// 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: 'user@example.com' } } },
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: 'user@example.com',
firstName: 'Jane',
properties: { plan: 'pro' },
},
},
});
// 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();
// BEFORE: Some older versions used snake_case
// { first_name: 'Jane', phone_number: '+1555...' }
// AFTER: SDK v21+ uses camelCase everywhere
{ firstName: 'Jane', phoneNumber: '+15551234567' }
# 1. Create upgrade branch
git checkout -b upgrade/klaviyo-api-v21
# 2. Install new version
npm install klaviyo-api@21.0.0 --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"
# If issues found after upgrade
npm install klaviyo-api@15.0.0 --save-exact
npm test
git add package.json package-lock.json
git commit -m "revert: rollback klaviyo-api to v15.0.0"
package-lock.jsonApiKeySession import (if changed)response.body.data)| 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 |
For CI integration during upgrades, see klaviyo-ci-integration.