Klaviyo

Lightweight, dependency-free, in-memory fake of the Klaviyo HTTP REST API for testing application code that talks to Klaviyo directly with the axios HTTP client (the documented integration path). Speaks the exact JSON:API wire protocol the real service uses, with zero cost and zero side effects. State is in-memory, ephemeral, and resettable.

Default port: 4658

Quick start

Start the server:

import { KlaviyoServer } from "./services/klaviyo/src/server.js";

const server = new KlaviyoServer(4658);
await server.start();
// ... run your app / tests ...
await server.stop();

Point the real axios client at it. Klaviyo's modern API lives under /api, authenticates with a Klaviyo-Key header, and requires a revision header on every request:

import axios from "axios";

const klaviyo = axios.create({
  baseURL: "http://127.0.0.1:4658/api", // point at the parlel fake
  headers: {
    Authorization: `Klaviyo-Key ${process.env.KLAVIYO_API_KEY}`,
    revision: "2024-10-15",
    "Content-Type": "application/json",
    Accept: "application/json",
  },
});

// Create a profile (JSON:API body shape)
const { data } = await klaviyo.post("/profiles/", {
  data: { type: "profile", attributes: { email: "ada@parlel.test", first_name: "Ada" } },
});
// data.data.id => a generated profile id

// Track an event (returns HTTP 202, empty body)
await klaviyo.post("/events/", {
  data: {
    type: "event",
    attributes: {
      metric: { data: { type: "metric", attributes: { name: "Viewed Product" } } },
      profile: { data: { type: "profile", attributes: { email: "ada@parlel.test" } } },
      properties: { ProductName: "Widget" },
      value: 9.99,
    },
  },
});

For the public, browser/SDK-facing endpoints (/client/*), authenticate with the public key via the company_id query parameter instead of a header:

await axios.post(
  "http://127.0.0.1:4658/client/events/?company_id=PARLEL",
  { data: { type: "event", attributes: { /* metric + profile */ } } },
);

Every write is captured in memory and can be inspected/reset via the /__parlel/* endpoints (see below).

Implemented operations

Profiles

Lists

Segments

Events

Metrics

Campaigns

Templates

Tags

Flows

Accounts

Client (public) endpoints

Authenticate with ?company_id=<PUBLIC_KEY>. All return HTTP 202 with an empty body.

parlel control / inspection

Authentication

• Private API (/api/*): Authorization: Klaviyo-Key <pk_...> header. A plain Bearer <token> is also accepted for flexibility. Missing/invalid auth returns 401 with code not_authenticated.
• Public API (/client/*): ?company_id=<PUBLIC_KEY> query parameter. Missing returns 400.
• Every modern request normally carries a revision header (e.g. 2024-10-15); the fake accepts any value.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes / shapes

Errors use the Klaviyo JSON:API error envelope:

{
  "errors": [
    {
      "id": "<uuid>",
      "status": "400",
      "code": "invalid",
      "title": "Invalid Input",
      "detail": "Invalid email address.",
      "source": { "pointer": "/data/attributes/email" },
      "links": {},
      "meta": {}
    }
  ]
}

Successful writes return JSON:API documents { data, links, meta }. Create operations return 201; updates return 200 (or 204 for tags); deletes return 204; event/bulk/send operations return 202 with no body.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

KLAVIYO_API_KEY=pk_parlel_test_private_key
KLAVIYO_PUBLIC_API_KEY=PARLEL
KLAVIYO_BASE_URL=http://parlel-bridge:4658
KLAVIYO_API_BASE_URL=http://parlel-bridge:4658/api
KLAVIYO_API_REVISION=2024-10-15