klaviyo-developer

Klaviyo 開発者向けガイド

Klaviyo API を使った開発のための専門的なガイダンスです。カスタムイベントのトラッキング、プロファイル管理、SDK の統合、ウェブフック、カタログ同期、データパイプラインのアーキテクチャを扱います。

マーケティング戦略、フローの監査、セグメンテーション、配信到達率、キャンペーンの最適化については、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）を使用します…
本番環境向けのイベントトラッキングコードを記述する	統合を記述する前に、アカウントのイベントスキーマを調べる
一括インポート／同期パイプラインを構築する	イベントが適切なプロパティ構造で取り込まれたかを確認する
ウェブフックハンドラーを実装する	統合の設計中にプロパティの一覧を手早く取得する
カタログ同期ジョブを実行する	イベントでフローが実行されない原因をデバッグするため、フローのトリガー条件を調べる
CI、cron、またはデプロイ済みサービスで何かを実行する	マーケティングアナリストとともにイベントスキーマの設計を反復する

MCP は、このスキルが対象とする API と同じ 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 の同意）
• プロファイルの統合と重複排除の戦略

ウェブフック

• ウェブフックのサブスクリプション設定とイベント種別
• ペイロードの検証と署名の検証
• 再試行処理と冪等性のあるウェブフック処理

SDK の使用とライブラリ

• Python SDK（klaviyo-api）
• Node.js SDK（klaviyo-api-node）
• Ruby、PHP、その他のコミュニティ製 SDK
• SDK の初期化、エラー処理、再試行設定

カタログと商品フィードの同期

• API によるカタログ項目の作成／更新／削除
• カテゴリとバリエーションの管理
• レコメンデーション向け商品フィード同期のアーキテクチャ
• 一括操作による大規模カタログの処理

データエクスポートとデータウェアハウスとの同期

• レポート作成向けのメトリクス集計 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 リクエスト	1 秒あたり
一括インポート	10 リクエスト	1 秒あたり
プロファイル／イベントの作成	350 リクエスト	1 秒あたり
キャンペーンの送信	10 リクエスト	1 秒あたり

返されるヘッダー：RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset

API 改訂タイムライン

改訂	主な変更点
2026-01-15	最新版。カスタムオブジェクトの取り込み、ジオフェンシング API（ベータ版）。
2025-10-15	Forms API、Flow Actions API、SMS ROI レポート。
2025-07-15	Mapped Metrics API、Custom Objects API（GA）。
2025-04-15	Web Feeds API、カスタムメトリクス、プッシュトークン登録。
2025-01-15	Reviews APIs、Flows Create API、キャンペーン画像管理。
2024-10-15	Universal Content API、フォーム／セグメントレポート、Reviews API。
2024-07-15	Forms API（取得）、Webhooks API。
2024-02-15	Reporting 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 の初期化 — SDK はリクエストごとではなく、アプリの起動時に API キーを設定して初期化してください。
10. テスト — Klaviyo のテスト／サンドボックスアカウントを使用してください。単体テストでは API レスポンスをモックしてください。

ワークフロー：カスタム連携のセットアップ

カスタムの Klaviyo 連携を構築する場合：

1. 要件を定義する — トラッキングするイベント、同期するプロフィールデータ、必要なトリガーを決定します
2. API キーを発行する — 必要最小限のスコープを持つプライベート API キーを作成します
3. イベントスキーマを設計する — ビジネスイベントを Klaviyo のメトリクス名とプロパティに対応付けます
4. プロフィール同期戦略を決める — 識別子（メールアドレス、電話番号、external_id のいずれか）とアップサートの頻度を決定します
5. トラッキングを実装する — 適切なエラー処理と再試行を備えたサーバーサイドのイベントトラッキングを実装します
6. カタログを同期する（該当する場合）— レコメンデーションとブラウズ放棄対策のために、商品フィードを同期します
7. Webhook を設定する — 関連イベントをサブスクライブし、署名検証を備えたハンドラーを実装します
8. レート制限戦略を立てる — API 呼び出しをキューに入れてスロットリングし、バックオフを実装します
9. モニタリングする — API エラーを記録し、イベント配信率を追跡して、失敗を検知したらアラートを出します
10. テストと検証を行う — イベントが Klaviyo に表示されることを確認し、フロートリガーをテストして、プロフィールデータを検証します

ワークフロー：インテグレーションの健全性監査

既存のKlaviyoインテグレーションの健全性とデータ品質を監査する場合：

1. 有効なインテグレーションを一覧表示する — 設定済みのインテグレーション（組み込みおよびカスタム）をすべて一覧表示します。有効な接続と古い接続を特定します。
2. イベントソースをマッピングする — アカウント内の各メトリックについて、そのソース（組み込みインテグレーション、カスタムAPI、Klaviyo内部、フォーム）を特定します。最近のイベント量がゼロのメトリックにフラグを付けます。
3. イベントスキーマを監査する — 主要なイベント（注文確定、チェックアウト開始、商品閲覧、カート追加）のプロパティ構造を取得します。次の点を確認します。
   • 標準プロパティの欠落（例：$value、ItemNames、明細項目）
   • 重複または冗長なメトリック（例：異なるソースから送信された「注文確定」と「注文完了」）
   • プロパティ名の不統一（イベント間でのキャメルケースとスネークケースの混在）
4. プロフィールデータパイプラインを確認する — プロフィールプロパティが正しく同期されていることを確認します。次の点を調べます。
   • APIによって設定されたプロパティと、イベントによって設定されたプロパティ
   • 古いプロパティ（一度だけ設定され、その後更新されていないもの）
   • セグメンテーションで使用されているプロパティと、未使用のままのプロパティ
5. カタログ同期を確認する — 商品カタログが同期され、最新の状態であることを確認します。次の点を確認します。
   • カタログ内のアイテム総数と予想される商品数
   • 最終同期のタイムスタンプ
   • バリエーションの網羅状況（バリエーションも同期されているか、親商品だけか）
   • カテゴリー構造の完全性
6. フロートリガーの構成を評価する — フローのトリガー方法をマッピングします。
   • メトリックの直接トリガー（堅牢）と、API同期されたプロパティを介したセグメント登録トリガー（脆弱）
   • 単一障害点（API同期が停止した場合、すべてのフローが停止するか）
   • トリガーの冗長性とフォールバックのパターン
7. データのアクセシビリティに関するギャップを特定する — イベントペイロードには存在するものの、利用できないデータを確認します。
   • イベントプロパティ内のネストされたオブジェクト（テンプレートでは使用できるが、セグメントや分岐では使用できない）
   • イベントでは利用できるがプロフィールに同期されていないプロパティ（それらを使ったセグメント作成ができない）
   • トラッキングされているものの、どのフローやセグメントでも使用されていないイベント
8. インテグレーションの健全性レポートを作成する — 重大度の評価を付けて調査結果を記録します。
   • 重大：インテグレーションの障害、イベントトラッキングの破損、データ損失
   • 高：標準イベントの欠落、メトリックの重複、フロートリガーの脆弱性
   • 中：未使用のイベント、不完全なカタログ、古いプロフィールプロパティ
   • 低：命名の不統一、最適化の機会

イベントスキーマのベストプラクティス

プロパティの命名規則

• Klaviyo標準プロパティにはパスカルケースを使用します：ProductName、ItemPrice、OrderId
• カスタムプロパティにはスネークケースを使用します：business_type、account_id、reorder_count
• 1つのイベント内で命名規則を混在させないでください。どちらかを選び、一貫して使用します。
• Klaviyoの予約名との衝突を避けるため、カスタムプロパティにはプレフィックスを付けます。

イベントごとの必須プロパティ

イベント	必須プロパティ	収益プロパティ
注文確定	$value、OrderId、Items[]（明細項目）	$value
チェックアウト開始	$value、CheckoutURL、Items[]	$value
商品閲覧	ProductName、ProductID、URL、ImageURL	—
カート追加	$value、AddedItemProductName、AddedItemProductID、Items[]	$value
注文の履行	$value、OrderId	—

ネストのルールと制限事項

Klaviyo では、アクセスする場所によってネストされたオブジェクトの扱いが異なります。

コンテキスト	アクセスレベル	例
メール／SMS テンプレート	Jinja 経由でフルアクセス可能 — 配列をループ処理し、ネストされたプロパティにアクセスできます	{% for item in event.Items %}{{ item.ProductName }}{% endfor %}
フローの条件分岐	トップレベルのプロパティのみ — ネストされたオブジェクトのフィールドにはアクセスできません	event.OrderId で分岐できますが、event.Items[0].ProductName では分岐できません
セグメント	トップレベルのプロパティのみ — ネストされたオブジェクトのフィールドではフィルタリングできません	「$value > 100 の Placed Order を実行したことがある」でセグメント化できますが、「Items に ProductName = X が含まれる」ではセグメント化できません
フロートリガー	トリガーフィルターにはトップレベルのプロパティを使用します	条件分岐と同様です

ネストされたデータの回避策: ネストされたデータでセグメント化または分岐する必要がある場合は、トップレベルのプロパティにフラット化してください。

# 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／サブスクリプション／マーケットプレイス）

標準的な Shopify／eコマースのスキーマに加えて、次のイベントを使用できます。

イベント名	トリガー	主なプロパティ
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 にデータが存在するのに、想定した場所で利用できない場合：

症状

• 「[イベント] は追跡していますが、[プロパティ] でセグメント化できません」
• 「フローの分岐で、送信しているプロパティが認識されません」
• 「プロフィールにデータはありますが、セグメントに反映されません」

根本原因と解決策

症状	根本原因	解決策
イベントプロパティでセグメント化できない	プロパティが配列／オブジェクト内にネストされている	イベントのトップレベルプロパティにフラット化します
イベントプロパティでフローを分岐できない	プロパティがネストされている	フラット化するか、代わりにプロフィールプロパティを使用します
セグメントがプロフィールに一致しない	プロパティがプロフィールではなくイベントにある	API または「Update Profile Property」フローアクションを使って、プロパティをプロフィールに同期します
プロフィールプロパティが存在するのにセグメントが空	プロパティ値の形式が一致していない（文字列の「true」とブール値の true など）	API 同期でデータ型を統一します
イベントは追跡されているのにフローが起動しない	メトリック名が一致していない（大文字と小文字を区別）	Klaviyo のメトリック名が API 呼び出しと完全に一致することを確認します
フローは起動するが、フィルターによって全員が除外される	フローフィルターとして使用されたセグメントが正しく評価されていない	セグメント条件を確認します。古いプロパティや型が正しくないプロパティを参照している可能性があります

診断ワークフロー

1. メトリックの存在を確認する：GET /metrics/ を使用して、イベント名が表示されることを確認します
2. イベントプロパティを確認する：GET /events/?filter=... を使用して最近のイベントを取得し、プロパティの構造を調べます
3. プロフィールプロパティを確認する：GET /profiles/{id}/ を使用して、想定したプロパティがプロフィールにあることを確認します
4. セグメント条件をテストする：セグメント定義を実際のプロフィールデータと比較し、型の不一致や大文字と小文字の区別に関する問題を確認します
5. フロートリガーをテストする：テストイベントを送信し、フローが起動するか、どこで停止するか、その理由を追跡します

このスキルの使い方

次のような質問をしてください。

• 「Node.js バックエンドからカスタムイベントを追跡するにはどうすればよいですか？」
• 「一括プロフィールインポートスクリプトの設定を手伝ってください」
• 「Klaviyo のレート制限と、その対処方法を教えてください」
• 「Klaviyo の Webhook 署名を検証するにはどうすればよいですか？」
• 「カスタムの E コマースプラットフォーム用にカタログ同期を設定してください」
• 「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 回、最大遅延 60 秒）。それでも制限に達する場合は、次の対応を行ってください。

• 一括操作をキューに入れてスロットリングする（インポートは最大 10 req/s）
• RateLimit-Remaining ヘッダーを事前に確認する
• 生の HTTP ではジッター付きの指数バックオフを実装する

一括インポートエラー：次の点を確認してください。

• 1 つのジョブあたりのバッチサイズが 10,000 プロフィールを超えていない
• 各プロフィールにメールアドレスまたは電話番号が指定されている（識別子が少なくとも 1 つある）
• 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 スキルを使用してください。