vendor/klaviyo · vendor documented

Klaviyo events are JSON:API, not a flat track call

data.type has to be event. The metric name lives at data.attributes.metric.data.attributes.name, and Klaviyo documents fewer than 128 characters. properties is required; use an empty object when there are none. Copying a Segment or Mixpanel body here fails the resource type before anything else runs.

A profile identifier is required: id, email, phone number, or external id. Phone is E.164. time is ISO 8601. value and value_currency travel together.

What this pack matches

Hosts: klaviyo.com
Paths: …/api/events…
Vendor docs: developers.klaviyo.com/en/reference/create_event

Rules

Codes are stable. A finding in CI, MCP, or the playground lands on the same id.

Field	Required	What it checks	Rule ids	Source
`data.type`	required	JSON:API resource type, which Klaviyo documents as `event` for this endpoint. Fix: Set `data.type` to `event`.	`vendor.klaviyo.body.data.type.missing` `vendor.klaviyo.body.data.type.empty` `vendor.klaviyo.body.data.type.invalid`	docs
`data.attributes.metric.data.type`	required	The nested metric resource is typed `metric`. Klaviyo documents `type` as required on the metric object. Fix: Set the metric's `type` to `metric`.	`vendor.klaviyo.body.data.attributes.metric.data.type.missing` `vendor.klaviyo.body.data.attributes.metric.data.type.empty` `vendor.klaviyo.body.data.attributes.metric.data.type.invalid`	docs
`data.attributes.metric.data.attributes.name`	required	It is the name of the metric the event is recorded against. Klaviyo documents fewer than 128 characters. Fix: Name the metric, such as `Placed Order`, in at most 128 characters.	`vendor.klaviyo.body.data.attributes.metric.data.attributes.name.missing` `vendor.klaviyo.body.data.attributes.metric.data.attributes.name.empty` `vendor.klaviyo.body.data.attributes.metric.data.attributes.name.invalid`	docs
`data.attributes.properties`	required	Klaviyo documents `properties` as required on the event attributes object. An empty object is allowed when there are no custom properties. Fix: Send a `properties` object. Use `{}` when there are no custom properties.	`vendor.klaviyo.body.data.attributes.properties.missing`	docs
`data.attributes.time`	optional	It is when the event occurred. Klaviyo documents an ISO 8601 datetime and defaults to request time when it is omitted. Fix: Send an ISO 8601 timestamp, such as `2022-11-08T00:00:00+00:00`.	`vendor.klaviyo.body.data.attributes.time.empty` `vendor.klaviyo.body.data.attributes.time.invalid`	docs
`data.attributes.value`	optional	It is a numeric monetary value for the event. Klaviyo documents it together with `value_currency`. Fix: Send a number such as `9.99`, with no currency symbol.	`vendor.klaviyo.body.data.attributes.value.empty` `vendor.klaviyo.body.data.attributes.value.invalid`	docs
`data.attributes.value_currency`	optional	It is the ISO 4217 currency of `value`. Fix: Use a three-letter code such as `USD`.	`vendor.klaviyo.body.data.attributes.value_currency.empty` `vendor.klaviyo.body.data.attributes.value_currency.invalid`	docs
`data.attributes.profile.data.attributes.email`	optional	One of email, phone number, external id, or id identifies the profile.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.email.empty`	docs
`data.attributes.profile.data.attributes.phone_number`	optional	It is the profile phone number. Klaviyo documents E.164. Fix: Send E.164, such as `+15005550006`.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.phone_number.empty` `vendor.klaviyo.body.data.attributes.profile.data.attributes.phone_number.invalid`	docs
`data.attributes.profile.data.attributes.external_id`	optional	One of email, phone number, external id, or id identifies the profile.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.external_id.empty`	docs
`data.attributes.profile.data.id`	optional	One of email, phone number, external id, or id identifies the profile.	`vendor.klaviyo.body.data.attributes.profile.data.id.empty`	docs
`data.attributes.profile.data.type`	required	The nested profile resource is typed `profile`. Klaviyo documents `type` as required on the profile object. Fix: Set the profile's `type` to `profile`.	`vendor.klaviyo.body.data.attributes.profile.data.type.missing` `vendor.klaviyo.body.data.attributes.profile.data.type.empty` `vendor.klaviyo.body.data.attributes.profile.data.type.invalid`	docs
`data.attributes.profile.data.attributes.anonymous_id`	optional	It is an anonymous profile identifier. Klaviyo documents `anonymous_id` on the event profile object. Fix: Send `anonymous_id`, or drop the empty pair.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.anonymous_id.empty`	docs
`data.attributes.profile.data.attributes._kx`	optional	It is Klaviyo's encrypted web-tracking exchange id, also called `exchange_id`. Fix: Send `_kx` from Klaviyo web tracking, or drop the empty pair.	`vendor.klaviyo.body.data.attributes.profile.data.attributes._kx.empty`	docs
`data.attributes.profile.data.attributes.locale`	optional	It is the profile locale. Klaviyo documents an IETF BCP 47 tag like `en-US` (ISO 639 plus ISO 3166 alpha-2). Fix: Send a tag such as `en-US`.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.locale.empty` `vendor.klaviyo.body.data.attributes.profile.data.attributes.locale.invalid`	docs
`data.attributes.profile.data.attributes.image`	optional	It is a URL pointing at a profile image. Klaviyo documents it as a URL. Fix: Send an absolute image URL, or omit the field.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.image.empty` `vendor.klaviyo.body.data.attributes.profile.data.attributes.image.invalid`	docs
`data.attributes.profile.data.attributes.location.ip`	optional	It is the profile IP address. Klaviyo documents `location.ip` as an IP address, unhashed. Fix: Send the raw IP in `location.ip`, not a digest.	`vendor.klaviyo.body.data.attributes.profile.data.attributes.location.ip.empty`	docs
`data.attributes.unique_id`	optional	Klaviyo deduplicates on it, so a retried request is not counted twice.	`vendor.klaviyo.body.data.attributes.unique_id.empty`	docs
`body.profile_needs_an_identifier`	required	The event carries no profile identifier. Klaviyo documents at least one of id, email, phone number, or external id as required. Fix: Add an identifier under `data.attributes.profile.data`.	`vendor.klaviyo.body.profile_needs_an_identifier`	docs
`body.value_requires_currency`	required	The event sends `value` without `value_currency`. Klaviyo documents the ISO 4217 code together with the monetary value. Fix: Add `value_currency`, such as `USD`.	`vendor.klaviyo.body.value_requires_currency`	docs
`body.currency_requires_value`	required	The event sends `value_currency` without `value`. Klaviyo documents both together. Fix: Add `value` as a number, with no currency symbol.	`vendor.klaviyo.body.currency_requires_value`	docs
`body.hashed_plaintext_field`	required	This field looks like a SHA-256 digest, but Klaviyo documents email and `location.ip` as unhashed. Fix: Send the raw email address or IP. Hashing it makes the profile unmatchable.	`vendor.klaviyo.body.hashed_plaintext_field`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/klaviyo

Try this failing payload in the playground. Klaviyo event missing properties.

{"data":{"type":"event","attributes":{"metric":{"data":{"type":"metric","attributes":{"name":"Placed Order"}}},"value":129.99,"value_currency":"USD","profile":{"data":{"type":"profile","attributes":{"email":"buyer@example.com"}}}}}}

cargo install pixellint · npm install pixellint