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.

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. 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

Rate Limits

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

API Revision Timeline

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:
   • Missing standard properties (e.g., $value, ItemNames, line items)
   • Duplicate/redundant metrics (e.g., "Placed Order" and "Order Placed" from different sources)
   • Inconsistent property naming (camelCase vs snake_case across events)
4. Check profile data pipeline — Verify profile properties are being synced correctly. Look for:
   • Properties set by API vs properties set by events
   • Stale properties (set once, never updated)
   • Properties used in segmentation vs properties sitting unused
5. Review catalog sync — Verify product catalog is synced and fresh. Check:
   • Total