Claude Code + Klaviyo: A Beginner's Guide

A client's welcome flow sent 57,000 emails last August and 17,000 the August before. Was that more people signing up, or more emails per person? Answering that inside Klaviyo means exporting flow data and rebuilding it in a spreadsheet. We asked Claude Code instead, and it came back in about a minute: both, but mostly more people. About 2.5 times as many people entered the flow, and each one got about 1.5 times as many emails.

That's Claude Code connected to a Klaviyo account. This guide shows how to set up Claude Code with Klaviyo from scratch in about 10 minutes using our free starter repo, then walks through three questions we've asked it on real client accounts. You won't write any code.

What You Need

• Claude Code, running in a terminal or in VS Code.
• A Klaviyo account where you can create API keys.
• An empty folder to work in.

That's it. The Klaviyo + Claude Code starter brings everything else: the folder structure, a set of skills (playbooks Claude follows for bigger jobs), example segment definitions, and our open-source Klaviyo CLI, which gives Claude a fast, safe way to read from and write to Klaviyo.

How to Set Up Claude Code With Klaviyo

Step 1: Create a Klaviyo API key

In Klaviyo, click your organization name in the bottom left, then Settings > API keys > Create Private API Key. Name it something you'll recognize in six months.

Choose Full access. That's what we used in the video, and it lets Claude run everything in this guide, including building segments and drafting campaigns. Treat the key like a password, and know the guardrails: the tool can't delete anything, and Claude shows you every change and waits for your yes before making it (more on that below). If you only want to ask questions for now, a Read-only key works for that and can't change anything.

Copy the key as soon as Klaviyo shows it (it starts with pk_). Klaviyo won't show it again, and you can't change a key's access level after creating it, so a new level means a new key (Klaviyo's guide to private API keys).

Step 2: Clone the starter

Open Claude Code in your empty folder and paste this:

Clone https://github.com/BeauchampAndrew/klaviyo-claude-code-starter into this folder and set it up.

Claude clones the repo, installs uv if it's missing, creates your .env file and tells you when to paste in your key. Paste the key into .env, not into the chat. That file is gitignored, so the key never ends up anywhere else.

Step 3: Test the connection

Claude runs a connection test as part of setup. If you're doing it by hand, this lists your profiles, lists and metrics:

bin/klaviyo account-health

If that comes back clean, you're connected. Everything from here is asking questions in plain English.

Three Questions We Asked It on Real Accounts

These come from client accounts we manage, with names and customer details kept out. Each one is possible in Klaviyo's interface, but slow: exports, spreadsheets and guesswork.

1. "Our welcome flow sent 57,000 emails vs. 17,000 last year. More people, or more emails each?"

This matters because the two answers lead to opposite conclusions. More people entering means list growth is working. More emails per person means the flow got longer or something changed in its filters, and you'd want to know whether conversion held up.

Claude compared the two Augusts and split the change into those two parts. The answer was both, mostly people: about 2.5 times as many people entered the flow, and each one got about 1.5 times as many emails. The first email alone went from about 4,300 recipients to about 10,000. That took about a minute.

2. "Build a segment of my top customers in Dallas."

A client once asked us who their best customers were in a specific city. In Klaviyo that's a fiddly segment: a location condition plus a spend or order threshold, and you have to guess what "top" means for that brand.

Claude proposed a definition (city is Dallas, region is Texas, and either 3 or more orders or $250 or more in lifetime spend) and said the $250 was a guess. So we asked it to check:

Can you pull a 1,000-person sample of recent buyers to calculate what a top customer's spend actually looks like?

It sampled 1,000 buyers from the last 30 days, reported only aggregate percentiles so no customer data showed on screen, and used those to set the threshold. Then it built the segment. The result was small, about 14 people, which is what you'd expect from one city's top buyers and exactly the list you'd want for a VIP invite. If you build audiences this way, purchase behavior beats engagement as the starting point.

3. "What was our best sale this year?"

With Black Friday planning starting, we asked Claude to pull the year's sales, group the campaigns by sale, and tell us which structure made the most revenue. It took about a minute and a half. Memorial Day, 25% off sitewide, was the best-performing sale by far.

The same prompt works for any historical question about campaigns: which offer types work, which segments respond, how a tagged campaign series performed. Klaviyo can show you each campaign. Claude can group and compare them.

Want these answers for your account without running them yourself? That's what we do.

Is It Safe to Point at Your Real Klaviyo Account?

Three layers keep it safe:

• The key. With a read-only key, Claude can't change anything in Klaviyo. If you only want answers, that's all you need.
• The tool. The Klaviyo CLI blocks deletes. Claude can't delete profiles, lists, segments, campaigns or flows, even with a full-access key. Suppressing or unsubscribing people needs an explicit confirmation.
• The instructions. The starter's CLAUDE.md tells Claude to read before it writes, show you every change before making it, and never schedule a send without your yes.

We run the same tools across our client accounts. They're behind Jarvis, our AI account manager, and how we cleaned up 28,000 profiles with a stale subscription status.

Prompts to Copy

The starter's prompts.md has every prompt from the video, grouped by level. You never need to name a command. Swap in your own products, cities and dates.

Read-only key

What flows are live right now, and what did each one make in the last 90 days?

Do my three biggest segments overlap? How many people are in more than one?

Across the last year, which promo drove the most revenue? Break it down by campaign, revenue, and revenue per recipient so I can decide what kind of sale to run for Black Friday.

This flow made money last year and nothing this year. What happened to it?

Write access

Build me two audiences. One is everyone who has ever bought [your main product]. The other is people who have bought other things but never [your main product].

Clone last month's best-performing campaign into a new draft.

Check this week's drafts before they go out: subject lines, from address, audiences, and whether the discount codes are live.

When an answer doesn't match what you know about the business, say so. Claude re-runs with your context. And with write access, open Klaviyo and look at anything it built before it goes out. Claude builds it; you send it.

Claude Code + Klaviyo FAQ

Do I need to know how to code?

No. You ask questions in plain English and Claude runs the commands. Setup is one pasted prompt and one pasted API key.

What kind of Klaviyo API key does Claude Code need?

Full access, with the usual care: keep the key in .env, never in the chat. It lets Claude build segments, edit drafts and schedule campaigns, and the tool blocks deletes while Claude confirms every change. If you only want answers, Read-only works and can't change your account.

Can Claude Code delete things in my Klaviyo account?

Not through this setup. The Klaviyo CLI blocks deletes of profiles, lists, segments, campaigns and flows at the tool level, and any other change needs your confirmation first.

Does it work with more than one Klaviyo account?

Yes. Instead of a single key in .env, use the Klaviyo CLI's profiles to store one key per account, then tell Claude which brand you're asking about.

What does it cost?

The starter repo and the Klaviyo CLI are free and open source (MIT). You need your own Claude Code access and a Klaviyo account.