klaviyo-developer

Klaviyo 开发

关于使用 Klaviyo API 构建应用的专家级指南——自定义事件跟踪、档案管理、SDK 集成、Webhook、目录同步和数据管道架构。

关于营销策略、流程审查、细分、送达率和营销活动优化，请参阅 klaviyo-analyst 技能。

安装

git clone https://github.com/thatrebeccarae/claude-marketing.git && cp -r claude-marketing/skills/klaviyo-developer ~/.claude/skills/

MCP 与 SDK：何时使用哪种方式

此技能的设计以 SDK 为先——你要构建的是基于 Klaviyo API 的生产级集成，而不是执行临时查询。话虽如此，Klaviyo 官方 MCP 服务也适用于集成工作中的某些环节，你应了解何时使用它。

在以下情况下使用 SDK（klaviyo-api）……	在以下情况下使用 MCP（https://mcp.klaviyo.com/mcp）……
编写生产级事件跟踪代码	在编写集成之前探索账户的事件架构
构建批量导入／同步管道	检查事件是否以正确的属性结构写入
实现 Webhook 处理程序	在集成设计期间快速获取属性清单
目录同步任务	调试事件未触发流程的原因时检查流程触发条件
在 CI、cron 或已部署服务中执行的任何操作	与营销分析师一起迭代事件架构设计

MCP 封装了此技能所针对的同一 API，因此以下架构规则、速率限制和嵌套约束同样适用于 MCP 驱动的调用。MCP 当前固定使用 API 修订版 2026-04-15——如果你自己的 SDK 代码使用较早的修订版，请留意这一点。

有关完整的 MCP 工具清单、OAuth 设置和只读模式标志，请参阅 REFERENCE.md。如需进行审计／分析工作，请参阅以 MCP 为核心构建的 klaviyo-analyst 技能。

核心能力

API 身份验证与版本管理

• 私有 API 密钥设置和密钥管理最佳实践
• 用于客户端跟踪的公开 API 密钥（klaviyo.js）
• 第三方应用的 OAuth 2.0 授权流程
• API 修订版请求头和版本生命周期管理

自定义事件跟踪

• 通过 Events API 进行服务端事件跟踪
• 使用 klaviyo.js 进行客户端跟踪
• 事件架构设计和属性命名约定
• 幂等事件提交模式

档案管理

• 档案创建、更新或插入以及批量导入模式
• 自定义属性管理和数据类型
• 订阅管理（电子邮件、SMS 同意）
• 档案合并和去重策略

Webhook

• Webhook 订阅设置和事件类型
• 负载验证和签名验证
• 重试处理和幂等 Webhook 处理

SDK 用法与库

• Python SDK（klaviyo-api）
• Node.js SDK（klaviyo-api-node）
• Ruby、PHP 和其他社区 SDK
• SDK 初始化、错误处理和重试配置

目录与产品 Feed 同步

• 通过 API 创建／更新／删除目录项目
• 分类和变体管理
• 用于推荐的产品 Feed 同步架构
• 使用批量操作处理大型目录

数据导出与数据仓库同步

• 用于报告的指标聚合 API
• 档案和事件导出模式
• 大型数据集的基于游标的分页
• 面向数据仓库集成的 ETL 管道设计

SDK 快速参考

语言	软件包	安装
Python	klaviyo-api	pip install klaviyo-api
Node.js	klaviyo-api	npm install klaviyo-api
Ruby	klaviyo-api-sdk	gem install klaviyo-api-sdk
PHP	klaviyo/api	composer require klaviyo/api

速率限制

端点类别	限制	时间窗口
大多数端点	75 个请求	每秒
批量导入	10 个请求	每秒
档案／事件创建	350 个请求	每秒
营销活动发送	10 个请求	每秒

返回的请求头：RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset

API 修订时间线

修订版本	主要变更
2026-01-15	最新版本。自定义对象数据导入、地理围栏 API（测试版）。
2025-10-15	表单 API、流程操作 API、短信 ROI 报告。
2025-07-15	映射指标 API、自定义对象 API（正式发布）。
2025-04-15	Web Feed API、自定义指标、推送令牌注册。
2025-01-15	评价 API、流程创建 API、营销活动图片管理。
2024-10-15	通用内容 API、表单/细分群体报告、评价 API。
2024-07-15	表单 API（检索）、Webhook API。
2024-02-15	报告 API、创建或更新个人资料（插入或更新）。

API 请求中始终包含 revision 标头。

开发者必备检查清单

1. API 密钥管理 — 将私有密钥存储在环境变量中，切勿提交到源代码。定期轮换密钥。
2. 修订版本标头 — 始终包含 revision: YYYY-MM-DD 标头。固定到特定版本。
3. 速率限制处理 — 收到 429 响应时，实施带抖动的指数退避。
4. 幂等事件 — 添加唯一的 unique_id 属性，以防止重复跟踪事件。
5. 个人资料插入或更新 — 使用现有标识符调用 POST /profiles/，实现插入或更新行为（创建或更新）。
6. Webhook 验证 — 处理负载前验证 Webhook 签名。
7. 分页 — 对列表端点使用基于游标的分页。切勿假设结果数量。
8. 错误处理 — 解析 JSON:API 错误响应。对 4xx（客户端）和 5xx（服务端）错误采取不同处理方式。
9. SDK 初始化 — 在应用启动时使用 API 密钥配置 SDK，而不是在每次请求时配置。
10. 测试 — 使用 Klaviyo 测试/沙盒账户。在单元测试中模拟 API 响应。

工作流：设置自定义集成

构建自定义 Klaviyo 集成时：

1. 定义需求 — 要跟踪哪些事件、要同步哪些个人资料数据、需要哪些触发器
2. 配置 API 密钥 — 创建具有最低必要权限范围的私有 API 密钥
3. 设计事件架构 — 将业务事件映射到 Klaviyo 指标名称和属性
4. 制定个人资料同步策略 — 确定标识符（电子邮件与电话号码与 external_id）和插入或更新频率
5. 实现跟踪 — 在服务端跟踪事件，并妥善处理错误和重试
6. 同步目录（如适用）— 同步产品 Feed，以用于推荐和浏览放弃场景
7. 设置 Webhook — 订阅相关事件，并实现带签名验证的处理程序
8. 制定速率限制策略 — 对 API 调用进行排队和限流，并实施退避
9. 监控 — 记录 API 错误、跟踪事件交付率，并在失败时发出警报
10. 测试与验证 — 确认事件显示在 Klaviyo 中，测试流程触发器，并验证个人资料数据

工作流：集成健康状况审计

审计现有 Klaviyo 集成的健康状况和数据质量时：

1. 盘点活跃集成 — 列出所有已配置的集成（内置和自定义）。区分活跃连接与陈旧连接。
2. 梳理事件来源 — 确定账户中每项指标的来源（内置集成、自定义 API、Klaviyo 内部、表单）。标记近期数据量为零的指标。
3. 审计事件架构 — 获取关键事件（Placed Order、Started Checkout、Viewed Product、Added to Cart）的属性结构。检查：
   • 缺少标准属性（例如，$value、ItemNames、商品行项目）
   • 重复或冗余的指标（例如，不同来源产生的“Placed Order”和“Order Placed”）
   • 属性命名不一致（不同事件中混用 camelCase 和 snake_case）
4. 检查用户资料数据管道 — 验证用户资料属性是否正确同步。检查：
   • 通过 API 设置的属性与通过事件设置的属性
   • 陈旧属性（仅设置过一次，从未更新）
   • 用于细分的属性与闲置未使用的属性
5. 审查商品目录同步 — 验证商品目录已同步且数据最新。检查：
   • 商品目录项目总数与预期商品数
   • 上次同步时间戳
   • 变体覆盖范围（同步的是变体还是仅父商品？）
   • 类别结构是否完整
6. 评估流程触发架构 — 梳理流程的触发方式：
   • 直接通过指标触发（可靠）与通过 API 同步属性触发细分条件（脆弱）
   • 单点故障（如果 API 同步中断，是否所有流程都会停止？）
   • 触发冗余和备用模式
7. 识别数据可访问性缺口 — 检查事件载荷中存在但无法使用的数据：
   • 事件属性中的嵌套对象（可在模板中使用，但不能用于细分或分支）
   • 事件中可用但未同步到用户资料的属性（无法据此进行细分）
   • 已跟踪但未用于任何流程或细分的事件
8. 生成集成健康状况报告 — 按严重程度记录调查结果：
   • 严重：集成故障、事件跟踪中断、数据丢失
   • 高：缺少标准事件、指标重复、流程触发机制脆弱
   • 中：未使用的事件、商品目录不完整、用户资料属性陈旧
   • 低：命名不一致、优化机会

事件架构最佳实践

属性命名约定

• 标准 Klaviyo 属性使用 PascalCase：ProductName、ItemPrice、OrderId
• 自定义属性使用 snake_case：business_type、account_id、reorder_count
• 单个事件中切勿混用命名约定——选定一种并保持一致
• 为自定义属性添加前缀，避免与 Klaviyo 保留名称冲突

各事件的必需属性

事件	必需属性	收入属性
Placed Order	$value、OrderId、Items[]（商品行项目）	$value
Started Checkout	$value、CheckoutURL、Items[]	$value
Viewed Product	ProductName、ProductID、URL、ImageURL	—
Added to Cart	$value、AddedItemProductName、AddedItemProductID、Items[]	$value
Fulfilled Order	$value、OrderId	—

嵌套规则和限制

Klaviyo 对嵌套对象的处理方式取决于访问位置：

上下文	访问级别	示例
电子邮件/SMS 模板	通过 Jinja 完全访问——可以循环遍历数组、访问嵌套属性	{% for item in event.Items %}{{ item.ProductName }}{% endfor %}
Flow 条件分支	仅限顶层属性——无法访问嵌套对象字段	可以按 event.OrderId 拆分，不能按 event.Items[0].ProductName 拆分
细分	仅限顶层属性——无法按嵌套对象字段筛选	可以按“完成过 Placed Order 且 $value > 100”进行细分，不能按“Items 包含 ProductName = X”进行细分
Flow 触发器	触发器筛选条件仅支持顶层属性	与条件分支相同

嵌套数据的解决方法：如果需要按嵌套数据进行细分或拆分，请将其展平为顶层属性：

# Instead of relying on Items[] array for segmentation:
properties = {
    "$value": 149.99,
    "OrderId": "ORD-123",
    "Items": [{"ProductName": "Wireless Headphones", "Category": "Electronics"}],
    # Flatten for segmentation:
    "ItemCategories": "Electronics,Accessories",  # Comma-joined for "contains" filter
    "HasElectronics": True,                        # Boolean flag for split
    "TopItemCategory": "Electronics"               # Top category for split
}

自定义事件模式（DTC / 订阅 / Marketplace）

标准 Shopify/电商架构之外的其他事件：

事件名称	触发条件	关键属性
Account Created	注册新账户	account_type、referral_source、signup_channel
Subscription Started	激活周期性订单	$value、frequency、product_ids、plan_name
Subscription Cancelled	停止周期性订单	reason、plan_name、lifetime_charges
Reorder Placed	再次购买消耗品	$value、OrderId、days_since_last_order、reorder_items
Wishlist Added	将商品保存以便日后查看	ProductName、ProductID、Categories、Price
Catalog Browsed	类别/搜索活动	category、search_term、results_count

将关键客户属性同步到个人资料，以便进行细分：

profile_properties = {
    "customer_type": "Subscriber",
    "interests": ["Skincare", "Wellness"],
    "subscription_plan": "Monthly Box",
    "account_tier": "VIP",
    "first_order_date": "2024-03-15",
    "lifetime_order_count": 8,
    "avg_order_value": 72.50,
    "preferred_categories": ["Skincare", "Supplements"]
}

数据可访问性诊断

当 Klaviyo 中存在数据，但无法在预期位置使用时：

症状

• “我们跟踪了 [event]，但无法按 [property] 进行细分”
• “Flow 分支看不到我们发送的属性”
• “个人资料中有数据，但细分无法识别”

根本原因和解决方案

症状	根本原因	解决方案
无法按事件属性进行细分	属性嵌套在数组/对象中	将其展平为事件的顶层属性
无法按事件属性拆分 Flow	属性已嵌套	将其展平，或改用个人资料属性
细分不匹配任何个人资料	属性位于事件中，而非个人资料中	通过 API 或“Update Profile Property”Flow 操作将属性同步到个人资料
个人资料属性存在，但细分结果为空	属性值格式不匹配（字符串 "true" 与布尔值 true）	在 API 同步中统一数据类型
已跟踪事件，但没有 Flow 触发	指标名称不匹配（区分大小写）	确认 Klaviyo 中的指标名称与 API 调用完全一致
Flow 已触发，但筛选器排除了所有人	用作 Flow 筛选器的细分条件判断错误	检查细分条件——可能引用了过时或类型不正确的属性

诊断工作流

1. 检查指标是否存在：使用 GET /metrics/ 验证是否显示该事件名称
2. 检查事件属性：使用 GET /events/?filter=... 获取近期事件，并检查属性结构
3. 检查个人资料属性：使用 GET /profiles/{id}/ 验证个人资料中是否包含预期属性
4. 测试细分条件：将细分定义与实际个人资料数据进行比较——检查类型不匹配、大小写敏感问题
5. 测试 Flow 触发器：发送测试事件，并追踪 Flow 是否触发、在哪一步停止以及原因

如何使用此技能

可以向我提问，例如：

• “如何从我的 Node.js 后端跟踪自定义事件？”
• “帮我设置批量资料导入脚本”
• “Klaviyo 的速率限制是多少？我该如何处理？”
• “如何验证 Klaviyo Webhook 签名？”
• “为我的自定义电商平台设置目录同步”
• “如何为 Klaviyo 应用实现 OAuth？”
• “设计一个将 Klaviyo 数据导出到 BigQuery 的数据管道”
• “帮我从 Klaviyo v1/v2 API 迁移到当前 API”
• “审核我的集成——事件结构是否正确？”
• “为什么无法按我在事件中跟踪的属性进行细分？”

集成示例

如需完整的集成模式、附带示例输出的完整示例和代码片段，请参阅 EXAMPLES.md。

脚本

此技能包含用于 API 交互和集成管理的实用脚本：

开发者客户端

# Track a custom event
python scripts/klaviyo_client.py --action track-event \
    --email [email protected] --event "Placed Order" \
    --properties '{"value": 99.99, "OrderId": "ORD-123"}'

# Upsert a profile
python scripts/klaviyo_client.py --action upsert-profile \
    --email [email protected] \
    --properties '{"first_name": "Jane", "loyalty_tier": "Gold"}'

# List catalog items
python scripts/klaviyo_client.py --action catalog-items --format table

# Export profiles to CSV
python scripts/klaviyo_client.py --action export-profiles \
    --max-pages 10 --format csv --output profiles.csv

开发者工具

# Integration health check
python scripts/dev_tools.py --tool health-check

# Validate event tracking
python scripts/dev_tools.py --tool validate-events \
    --events "Placed Order,Started Checkout,Viewed Product"

# Test webhook endpoint
python scripts/dev_tools.py --tool test-webhook \
    --webhook-url https://example.com/webhooks/klaviyo

# Import profiles from CSV
python scripts/dev_tools.py --tool import-csv \
    --file contacts.csv --list-id LIST_ID

# Export data with pagination
python scripts/dev_tools.py --tool export-data \
    --resource profiles --max-records 5000 --output profiles.csv

这些脚本会处理 API 身份验证、速率限制和 JSON:API 格式化。我会帮助解读结果并提供实现指导。

故障排除

身份验证错误：请确认：

• 已将 KLAVIYO_API_KEY 设置为环境变量或写入 .env 文件
• 密钥以 pk_ 开头（私有 API 密钥，而非公开密钥）
• 密钥具有所需操作范围的权限（例如，跟踪需要 events:write，导入需要 profiles:write）

速率限制错误（429）：SDK 会自动处理重试（最多重试 3 次，最长延迟为 60s）。如果仍然触及限制：

• 将批量操作加入队列并进行节流（导入最多 10 req/s）
• 主动检查 RateLimit-Remaining 标头
• 对原始 HTTP 请求实现带抖动的指数退避

批量导入错误：请检查：

• 每个作业的批次大小不超过 10,000 个资料
• 为每个资料提供电子邮件或电话号码（至少一个标识符）
• CSV 列名与预期字段名称相符

导入错误：安装所需的软件包：

pip install klaviyo-api python-dotenv pandas

安全说明

• 切勿将 API 密钥硬编码到代码中或提交到版本控制系统
• 将密钥存储在环境变量或 .env 文件中
• 将 .env 添加到 .gitignore
• 使用最低限度的必要权限范围——仅在需要时启用写入权限
• 定期在 Klaviyo 设置中轮换 API 密钥
• 对于 OAuth 集成，请安全存储客户端密钥，并在令牌过期前刷新令牌

数据隐私

此技能会与 Klaviyo API 交互，以支持集成开发。使用写入操作时：

• 发送数据前先进行验证，避免资料记录损坏
• 切勿以纯文本形式记录或存储 API 密钥、Webhook 密钥或 PII
• 使用幂等键防止重复事件
• 实现 Webhook 签名验证以防止伪造
• 处理资料数据时遵守 GDPR/CCPA 要求
• 对删除权请求使用 Data Privacy Deletion 端点

所有操作均通过官方 Klaviyo API 并使用适当的身份验证执行。

如需详细的 API 端点参考、代码模式、身份验证说明和架构图，请参阅 REFERENCE.md。

如需营销策略、流程优化和营销活动审核，请使用 klaviyo-analyst 技能。