klaviyo-developer

Klaviyo Developer

Expert-level guidance for building with the Klaviyo API — custom event tracking, profile management, SDK integration, webhooks, catalog sync, and data pipeline architecture.

For marketing strategy, flow auditing, segmentation, deliverability, and campaign optimization, see the klaviyo-analyst skill.

Install

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

MCP vs. SDK: When to Use Which

This skill is SDK-first by design — you're building production integrations against the Klaviyo API, not running ad-hoc queries. That said, Klaviyo's official MCP server is the right tool for parts of integration work, and you should know when to reach for it.

| Use the SDK (klaviyo-api) when… | Use the MCP (https://mcp.klaviyo.com/mcp) when… | |---|---| | Writing production event-tracking code | Exploring an account's event schema before writing the integration | | Building bulk import / sync pipelines | Sanity-checking that events landed with the right property shape | | Implementing webhook handlers | Pulling a quick property inventory during integration design | | Catalog sync jobs | Inspecting flow trigger conditions while debugging why an event isn't firing a flow | | Anything in CI, cron, or a deployed service | Iterating on event schema design with the marketing analyst in the room |

The MCP wraps the same API this skill targets, so the schema rules, rate limits, and nesting constraints below apply equally to MCP-driven calls. The MCP is currently pinned to API revision 2026-04-15 — keep that in mind if you're versioning your own SDK code against an older revision.

For the full MCP tool inventory, OAuth setup, and read-only mode flag, see [REFERENCE.md](REFERENCE.md#mcp-server-reference). For audit/analyst work, see the klaviyo-analyst skill — it's built around the MCP.

Core Capabilities

API Authentication & Versioning

• Private API key setup and key management best practices
• Public API key usage for client-side tracking (klaviyo.js)
• OAuth 2.0 authorization flow for third-party apps
• API revision headers and version lifecycle management

Custom Event Tracking

• Server-side event tracking via Events API
• Client-side tracking with klaviyo.js
• Event schema design and property naming conventions
• Idempotent event submission patterns

Profile Management

• Profile create, upsert, and bulk import patterns
• Custom property management and data types
• Subscription management (email, SMS consent)
• Profile merge and deduplication strategies

Webhooks

• Webhook subscription setup and event types
• Payload verification and signature validation
• Retry handling and idempotent webhook processing

SDK Usage & Libraries

• Python SDK (klaviyo-api)
• Node.js SDK (klaviyo-api-node)
• Ruby, PHP, and other community SDKs
• SDK initialization, error handling, and retry configuration

Catalog & Product Feed Sync

• Catalog item create/update/delete via API
• Category and variant management
• Product feed sync architecture for recommendations
• Handling large catalogs with bulk operations

Data Export & Warehouse Sync

• Metric aggregation API for reporting
• Profile and event export patterns
• Cursor-based pagination for large datasets
• ETL pipeline design for data warehouse integration

SDK Quick Reference

| Language | Package | Install | |----------|---------|---------| | 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 |

Rate Limits

| Endpoint Category | Limit | Window | |-------------------|-------|--------| | Most endpoints | 75 requests | per second | | Bulk imports | 10 requests | per second | | Profile/Event create | 350 requests | per second | | Campaign send | 10 requests | per second |

Headers returned: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset

API Revision Timeline

| Revision | Key Changes | |----------|-------------| | 2026-01-15 | Latest. Custom Objects Ingestion, Geofencing API (beta). | | 2025-10-15 | Forms API, Flow Actions API, SMS ROI reporting. | | 2025-07-15 | Mapped Metrics API, Custom Objects API (GA). | | 2025-04-15 | Web Feeds API, Custom Metrics, Push Token registration. | | 2025-01-15 | Reviews APIs, Flows Create API, Campaign image management. | | 2024-10-15 | Universal Content API, Form/Segment Reporting, Reviews API. | | 2024-07-15 | Forms API (retrieval), Webhooks API. | | 2024-02-15 | Reporting API, Create or Update Profile (upsert). |

Always include the revision header in API requests.

Essential Developer Checklist

1. API key management — Store private keys in environment variables, never commit to source. Rotate keys periodically.
2. Revision header — Always include revision: YYYY-MM-DD header. Pin to a specific version.
3. Rate limit handling — Implement exponential backoff with jitter on 429 responses.
4. Idempotent events — Include a unique unique_id property to prevent duplicate event tracking.
5. Profile upserts — Use POST /profiles/ with existing identifier for upsert behavior (creates or updates).
6. Webhook verification — Validate webhook signatures before processing payloads.
7. Pagination — Use cursor-based pagination for list endpoints. Never assume result counts.
8. Error handling — Parse JSON:API error responses. Handle 4xx (client) and 5xx (server) differently.
9. SDK initialization — Configure SDK with API key at app startup, not per-request.
10. Testing — Use Klaviyo test/sandbox accounts. Mock API responses in unit tests.

Workflow: Custom Integration Setup

When building a custom Klaviyo integration:

1. Define requirements — What events to track, what profile data to sync, what triggers are needed
2. API key provisioning — Create a private API key with minimum required scopes
3. Event schema design — Map business events to Klaviyo metric names and properties
4. Profile sync strategy — Determine identifier (email vs phone vs external_id), upsert frequency
5. Implement tracking — Server-side event tracking with proper error handling and retries
6. Catalog sync (if applicable) — Product feed sync for recommendations and browse abandonment
7. Webhook setup — Subscribe to relevant events, implement handler with signature verification
8. Rate limit strategy — Queue and throttle API calls, implement backoff
9. Monitoring — Log API errors, track event delivery rates, alert on failures
10. Testing & validation — Verify events appear in Klaviyo, test flow triggers, validate profile data

Workflow: Integration Health Audit

When auditing an existing Klaviyo integration for health and data quality:

1. Inventory active integrations — List all configured integrations (built-in and custom). Identify active vs stale connections.
2. Map event sources — For each metric in the account, identify its source (built-in integration, custom API, Klaviyo-internal, form). Flag metrics with zero recent volume.
3. Audit event schemas — Pull property structures for key events (Placed Order, Started Checkout, Viewed Product, Added to Cart). Check for:
4. Missing standard properties (e.g., $value, ItemNames, line items)
5. Duplicate/redundant metrics (e.g., "Placed Order" and "Order Placed" from different sources)
6. Inconsistent property naming (camelCase vs snake_case across events)
7. Check profile data pipeline — Verify profile properties are being synced correctly. Look for:
8. Properties set by API vs properties set by events
9. Stale properties (set once, never updated)
10. Properties used in segmentation vs properties sitting unused
11. Review catalog sync — Verify product catalog is synced and fresh. Check:
12. Total