klaviyo-migration-deep-dive

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 <[e-mail]>
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.

1. 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);