POST to /api/events/ with a JSON:API body: type is event, attributes includes metric.name (e.g., Viewed Product), profile (with email or phone_number for identification), properties (event payload), and time (ISO 8601)
For identified profiles use the email or external_id in the profile object; for anonymous events use a cookie-based anonymous_id that can be later merged via the profile merge API
Set the value attribute on the event to a numeric revenue figure when tracking purchase events — Klaviyo uses this for revenue attribution in flows and reports
Verify the event appears in Klaviyo's Activity Feed for the profile and that the associated flow triggers fire as expected in a test environment before deploying to production
Use your private API key in the Authorization: Klaviyo-API-Key <key> header; server-side events use the private key, not the public site ID used for pixel events
Known gotchas
Klaviyo rate-limits the Events API per account; high-volume event streams (e.g., page views for every visitor) should be batched or sampled rather than sent individually per request
If both email and phone_number are provided in the profile object and they belong to different Klaviyo profiles, Klaviyo will merge them — this is usually desired but can be surprising if the data is noisy
Event time is accepted in the past (backfilling historical events is allowed) but events too far in the future are rejected; always send accurate timestamps rather than defaulting to the current server time for events that occurred earlier
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp