使用 Klaviyo API 集成电商邮件/SMS…

适用于需要用 Klaviyo 做 email/SMS 营销集成，管理 profiles、events、lists、campaigns、flows、webhooks 与分段的场景。

适用场景

解决思路

1. 配置服务端私有 API：请求 `https://a.klaviyo.com/api`，在 header 中设置 `Authorization: Klaviyo-API-Key pk_xxxxxxxxxxxxxxxxxxxxxxxx`、`Content-Type: application/json`、`revision: 2024-10-15`。
2. 配置客户端公开 API：请求 `https://a.klaviyo.com/client`，用 6 位 public key 作为 query param `?company_id=XXXXXX`。
3. 按用途选择 API Key scope：Read-only 仅读，Full 读写（默认），Custom 按需授权。
4. Node.js 安装与初始化：运行 `npm install klaviyo-api`；在 `lib/klaviyo.ts` 中 import `ApiClient, EventsApi, ProfilesApi, ListsApi`，`client.setApiKey(process.env.KLAVIYO_PRIVATE_KEY!)`，导出 `eventsApi`、`profilesApi`、`listsApi`。
5. Python 安装与初始化：运行 `pip install klaviyo-api`；在 `lib/klaviyo.py` 中从 `klaviyo_api` import `KlaviyoAPI`，用 `KLAVIYO_PRIVATE_KEY`、`max_delay=60`、`max_retries=3` 初始化。
6. 任意语言直接 HTTP 调用：定义 `KLAVIYO_BASE_URL = "https://a.klaviyo.com/api"`，封装 `klaviyoRequest(endpoint, method, body)`；使用 fetch 发请求，带上私有 key、Content-Type、revision；非 2xx 时解析 JSON 并抛出错误。
7. 创建/更新 profile（upsert）：POST `/profiles`，body 为 `data.type: "profile"`，attributes 填 email、phone_number（E.164 如 `+1234567890`）、first_name、last_name、properties（如 lifetime_value、plan、signup_source）、location（city、region、country、zip）。
8. Python 创建/更新 profile：调用 `klaviyo.Profiles.create_or_update_profile`，传入 `data.type: "profile"` 和 attributes（email、first_name、last_name、properties 如 plan）。
9. 按 email 查询 profile：GET `/profiles?filter=equals(email,"${email}")`，取 `response.data[0]`。
10. 按 profile ID 查询 profile：GET `/profiles/${profileId}`。
11. 更新 profile properties：PATCH `/profiles/${profileId}`，body 为 `data.type: "profile"`、`id: profileId`、`attributes.properties`；例如更新 `last_purchase_date`、`total_orders`、`vip_status`。
12. 服务端 track event：POST `/events`，body 为 `data.type: "event"`，attributes 包含 `profile.data`（email/phone_number/external_id）、`metric.data`（name 为事件名）、`properties`、`value`（收入跟踪）、`unique_id`（去重）、`time`（ISO 时间或当前时间）。
13. 跟踪 Viewed Product：调用 trackEvent，eventName 为 `Viewed Product`，properties 包含 `ProductID`、`ProductName`、`ProductURL`、`ImageURL`、`Price`、`Categories`。
14. 跟踪 Added to Cart：eventName 为 `Added to Cart`，properties 包含 `ProductID`、`ProductName`、`Quantity`、`Price`、`CartTotal`、`ItemNames`，value 为 `product.price * quantity`。
15. 跟踪 Started Checkout：eventName 为 `Started Checkout`，properties 包含 `CheckoutURL`、`ItemCount`、`Categories`、`ItemNames`，value 为 `cart.total`。
16. 跟踪 Placed Order：eventName 为 `Placed Order`，properties 包含 `OrderId`、`ItemCount`、`Categories`、`ItemNames`、`Items`（每项含 ProductID、ProductName、Quantity、Price、ImageURL、ProductURL）、`BillingAddress`、`ShippingAddress`，value 为 `order.total`，uniqueId 为 `order.id` 防重复。
17. 跟踪 Fulfilled Order：eventName 为 `Fulfilled Order`，properties 包含 `OrderId`、`TrackingNumber`、`TrackingURL`、`Carrier`。
18. 跟踪 Cancelled Order：eventName 为 `Cancelled Order`，properties 包含 `OrderId`、`Reason`，value 为 `-order.total` 表示退款。
19. 客户端 JS 跟踪：在站点引入 `<script async src="https://static.klaviyo.com/onsite/js/klaviyo.js?company_id=XXXXXX"></script>`；调用 `klaviyo.identify({email, first_name, last_name})` 识别用户；调用 `klaviyo.track("事件名", {...})` 跟踪事件；收入用 `$value`。
20. 添加 profile 到 list：POST `/lists/${listId}/relationships/profiles`，data 数组可用 email 对象或 profile ID 对象（`{type: "profile", id: profileId}`）。
21. 从 list 移除 profile：DELETE `/lists/${listId}/relationships/profiles`，body data 数组包含 `{type: "profile", id: profileId}`。
22. 获取 list 成员：GET `/lists/${listId}/profiles?page[size]=100`，如果有 cursor 则设置 `page[cursor]`。
23. 创建 list：POST `/lists`，body 为 `data.type: "list"`、`attributes.name`。
24. 获取 campaigns：GET `/campaigns?filter=equals(status,"draft|scheduled|sent")`，按状态过滤。
25. 获取 campaign 表现：GET `/campaign-recipient-estimations/${campaignId}`。
26. 获取 flows：GET `/flows`；按 ID 获取：GET `/flows/${flowId}`。
27. 配置常见 flow 触发：Welcome Series 用 Added to List；Abandoned Cart 用 Added to Cart + No Purchase；Browse Abandon 用 Viewed Product + No Cart；Post-Purchase 用 Placed Order；Winback 用 No Order in X Days；Review Request 用 Fulfilled Order。
28. 创建 webhook：POST `/webhooks`，body 为 `data.type: "webhook"`，attributes 填 `name`、`endpoint_url`、`secret_key`、`topics`（如 `profile.created`、`event.created`）。
29. 订阅 webhook topics：可用 `profile.created`、`profile.updated`、`profile.merged`、`event.created`、`list.member.added`、`list.member.removed`。
30. 验证 webhook 签名：用 HMAC SHA256，以 secret 对 payload 计算 digest base64；与 `klaviyo-webhook-signature` header 做 `crypto.timingSafeEqual` 比较；失败返回 401。
31. 处理 webhook 事件：在 Express `app.post('/webhooks/klaviyo')` 中校验签名后，按 `type` switch 处理，如 `profile.created` 调用 `handleNewProfile(data)`，`event.created` 调用 `handleNewEvent(data)`，最后返回 200。
32. 遵守 rate limit：burst 75 requests/second，steady 700 requests/minute。
33. 处理 429：封装 `klaviyoRequestWithRetry`，最多重试 3 次；遇到 429 读取 `Retry-After` header，等待对应秒数后 continue；非 2xx 抛错；重试耗尽抛 `Max retries exceeded`。
34. 分页拉取所有 profiles：循环 GET `/profiles?page[size]=100`，若有 cursor 则加 `page[cursor]`；收集 `response.data`；从 `response.links.next` 解析下一个 `page[cursor]`，直到无 cursor。
35. 过滤与排序：按日期过滤用 `/events?filter=greater-than(datetime,2024-01-01T00:00:00Z)`；按属性过滤用 `/profiles?filter=equals(properties.vip_status,true)`；多条件 AND 用 `/profiles?filter=and(equals(properties.plan,"pro"),greater-than(properties.ltv,1000))`；排序用 `/profiles?sort=-created`；稀疏字段用 `/profiles?fields[profile]=email,first_name,properties`。
36. 订单同步集成：下单后依次 1) upsert customer profile；2) 用 email 查 profile ID 后更新 `last_order_date`、`total_orders`、`lifetime_value`；3) track `Placed Order` 事件，properties 含 `OrderId`、`Items` 等，value 为 `order.total`，uniqueId 为 `order.id`。
37. 订阅状态同步：更新 profile properties 的 `subscription_status`、`subscription_plan`、`subscription_updated_at`；track `Subscription ${status}` 事件，properties 含 `plan`、`mrr`，value 为取消时 `-user.mrr`，否则 `user.mrr`。
38. 配置环境变量：在 `.env` 设置 `KLAVIYO_PRIVATE_KEY=pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`、`KLAVIYO_PUBLIC_KEY=XXXXXX`、`KLAVIYO_WEBHOOK_SECRET=your_webhook_secret`。
39. 在 `credentials.md` 添加密钥正则：`'KLAVIYO_PRIVATE_KEY': r'pk_[a-f0-9]{32}'`、`'KLAVIYO_PUBLIC_KEY': r'[A-Z0-9]{6}'`。
40. 完成 setup checklist：创建 Klaviyo 账号；生成 private API key；记录 public API key（company ID）；在 header 设置 API revision。
41. 完成 integration checklist：注册/更新时同步 profile；跟踪关键事件（view、cart、order）；订单事件包含 Items 数组；用 `$value` 跟踪收入；用 unique IDs 去重。
42. 完成 testing checklist：测试 profile 创建；测试事件跟踪；在 Klaviyo dashboard 验证事件；测试 webhook 投递；测试 rate limit 处理。
43. 实施时避免反模式：确保每个 profile 至少有 email 或 phone；订单/交易用 unique_id 防重复；订单事件包含 Items 数组；不要只依赖客户端跟踪，服务端跟踪更可靠；不要忽略 rate limit，要实现指数退避；不要硬编码 API key，用环境变量；不要漏掉收入跟踪，用 $value 支持 ROI 归因。

适用边界 · 注意事项

• 没有 Klaviyo 账号、private/public API key 或 webhook secret 时，不能直接使用。
• 不需要 Klaviyo 的事件触发分群、flows、email/SMS 统一营销，或不能用第三方营销平台处理客户数据时，不适合。
• 仅做简单事务邮件且不涉及客户 profile、事件跟踪、收入归因时，用更轻量邮件服务即可。