| name | klaviyo-migration-deep-dive |
| description | Use when you are moving an email/CDP stack onto Klaviyo — off the deprecated v1/v2 APIs, off a competitor ESP (Mailchimp, SendGrid), or re-platforming gradually with the strangler fig pattern — and need field mapping, batch import, and post-migration validation.
Trigger with phrases like "migrate to klaviyo", "klaviyo migration",
"switch to klaviyo", "klaviyo replatform", "mailchimp to klaviyo",
"legacy to klaviyo", "v1 to v2 klaviyo".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(node:*) |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","klaviyo","email-marketing","cdp"] |
| compatibility | Designed for Claude Code |
Klaviyo Migration Deep Dive
Overview
Comprehensive guide for migrating to Klaviyo from legacy APIs (v1/v2), competing ESPs (Mailchimp, SendGrid, etc.), or re-platforming with the strangler fig pattern. Covers data migration, API mapping, batch import, and post-migration validation.
This SKILL.md is the high-level workflow. The full, copy-paste code for every step
lives in references/implementation.md; worked
end-to-end scenarios live in references/examples.md.
Prerequisites
- Target Klaviyo account configured
klaviyo-api SDK installed (npm install klaviyo-api)- Source system access for data export
- Feature flag infrastructure (for gradual rollout)
- Auth: a Klaviyo private API key (
pk_***) exported as KLAVIYO_PRIVATE_KEY — used by the SDK's ApiKeySession. Legacy v1/v2 calls used a public token in the request body; the current REST API uses the private key in the session header. See references/implementation.md.
Migration Types
| Migration | Complexity | Duration | Risk |
|---|
| Klaviyo v1/v2 to current API | Low-Medium | 1-2 weeks | Low |
| Mailchimp/SendGrid to Klaviyo | Medium | 2-4 weeks | Medium |
| Custom ESP to Klaviyo | High | 4-8 weeks | High |
| Full re-platform | High | 2-3 months | High |
Instructions
Pick your migration type from the table above, then work the five steps. Each step
has full code in references/implementation.md.
-
Legacy v1/v2 to current API — replace deprecated track / identify / v2 subscribe HTTP calls with the klaviyo-api SDK (createOrUpdateProfile, createEvent, subscribeProfiles). The session skeleton every step builds on:
{ , , } ;
session = (process..!);
profilesApi = (session);
eventsApi = (session);
