Klaviyo

@hollowpoint-io/medusa-plugin-klaviyo

Klaviyo for Medusa v2: Started Checkout / Placed Order events, consent sync, and a honeypot newsletter endpoint.

Authored by Billy Mahmood. Maintained by Hollowpoint. MIT licensed.

Install

npm install @hollowpoint-io/medusa-plugin-klaviyo

1// medusa-config.ts
2module.exports = defineConfig({
3  plugins: [
4    {
5      resolve: "@hollowpoint-io/medusa-plugin-klaviyo",
6      options: {
7        api_key: process.env.KLAVIYO_API_KEY,
8        list_id: process.env.KLAVIYO_LIST_ID,
9        storefront_url: process.env.STOREFRONT_URL,
10        // revision: "2026-07-15",
11        // source_name: "Medusa",
12        // product_path: "/products/{handle}",
13        // checkout_path: "/checkout",
14        // order_path: "/account/orders/{order_id}",
15        // rate_limit: { max: 5, window_ms: 60_000 },
16      },
17    },
18  ],
19})

No migrations. If the plugin is installed without api_key / list_id / storefront_url, subscribers no-op and the subscribe route returns 503.

Built and tested against Medusa >=2.17 <3.

What you get

• cart.updated → Started Checkout (once the cart has metadata.checkout_started_at)
• order.placed → Placed Order
• Idempotency stamps on cart/order metadata (klaviyo_started_checkout_sent_at, klaviyo_placed_order_sent_at)
• Consent bulk jobs, including Shopify shopify_email_marketing_state fallback for migrated stores
• POST /store/klaviyo/subscribe with a honeypot company field
• Error bodies are never logged (they can echo PII)

Options

*Required for the plugin to actually send. Missing options degrade silently.

Subscribe

1POST /store/klaviyo/subscribe
2{ "email": "a@b.com", "source": "homepage", "company": "" }

source is homepage or product-unavailable. A non-empty company is treated as a bot and returns 202 without calling Klaviyo.

Rate limiting

This package does not ship a shared rate-limiter. Rate-limit at your edge, or set rate_limit for a naive in-memory cap (not safe across multiple backend instances).

Develop

1npm install
2npm test
3npm run build
4npm run dev

Need this installed and wired on a live Medusa store? Hollowpoint does Medusa migrations and plugin work.