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
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. Native JSON type: string. Fix: Set `data.type` to `event`. | vendor.klaviyo.body.data.type.missingvendor.klaviyo.body.data.type.emptyvendor.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. Native JSON type: string. Fix: Set the metric's `type` to `metric`. | vendor.klaviyo.body.data.attributes.metric.data.type.missingvendor.klaviyo.body.data.attributes.metric.data.type.emptyvendor.klaviyo.body.data.attributes.metric.data.type.invalid |
docs |
data.attributes.metric.data.attributes.name |
required | Name of the event. Must be less than 128 characters. Native JSON type: string. Maximum decoded characters: 127. Fix: Name the metric, such as `Placed Order`, in at most 128 characters. | vendor.klaviyo.body.data.attributes.metric.data.attributes.name.missingvendor.klaviyo.body.data.attributes.metric.data.attributes.name.emptyvendor.klaviyo.body.data.attributes.metric.data.attributes.name.invalid |
docs |
data.attributes.properties |
required | Properties of this event (must not exceed 400 properties). The size of the event payload must not exceed 5 MB, and each string cannot be larger than 100 KB. For a full list of data limits on event payloads, see [Limitations](https://developers.klaviyo.com/en/reference/events_api_overview#limitations). Note any top-level property that is not an object can be used to create segments. The `$extra` property records any non-segmentable values that can be referenced later, e.g., HTML templates are useful on a segment but are not used to create a segment. Native JSON type: object. Maximum object properties: 400. Fix: Send a `properties` object. Use `{}` when there are no custom properties. | vendor.klaviyo.body.data.attributes.properties.missingvendor.klaviyo.body.data.attributes.properties.invalid |
docs |
data.attributes.time |
optional | When this event occurred. By default, the time the request was received will be used. The time is truncated to the second. The time must be after the year 1990 and can only be up to 1 year in the future. Native JSON type: string or null. Fix: Send an ISO 8601 timestamp, such as `2022-11-08T00:00:00+00:00`. | vendor.klaviyo.body.data.attributes.time.emptyvendor.klaviyo.body.data.attributes.time.invalid |
docs |
data.attributes.value |
optional | A numeric, monetary value to associate with this event. For example, the dollar amount of a purchase. Native JSON type: number or null. Fix: Send a number such as `9.99`, with no currency symbol. | vendor.klaviyo.body.data.attributes.value.invalid |
docs |
data.attributes.value_currency |
optional | The ISO 4217 currency code of the value associated with the event. Native JSON type: string or null. Fix: Use a three-letter code such as `USD`. | vendor.klaviyo.body.data.attributes.value_currency.emptyvendor.klaviyo.body.data.attributes.value_currency.invalid |
docs |
data.attributes.profile.data.attributes.email |
optional | Individual's email address Native JSON type: string or null. Maximum decoded characters: 100. | vendor.klaviyo.body.data.attributes.profile.data.attributes.email.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.email.invalid |
docs |
data.attributes.profile.data.attributes.phone_number |
optional | Individual's phone number in E.164 format Native JSON type: string or null. Fix: Send E.164, such as `+15005550006`. | vendor.klaviyo.body.data.attributes.profile.data.attributes.phone_number.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.phone_number.invalid |
docs |
data.attributes.profile.data.attributes.external_id |
optional | A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.external_id.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.external_id.invalid |
docs |
data.attributes.profile.data.id |
optional | Primary key that uniquely identifies this profile. Generated by Klaviyo. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.id.emptyvendor.klaviyo.body.data.attributes.profile.data.id.invalid |
docs |
data.attributes.profile.data.type |
required | The nested profile resource is typed `profile`. Klaviyo documents `type` as required on the profile object. Native JSON type: string. Fix: Set the profile's `type` to `profile`. | vendor.klaviyo.body.data.attributes.profile.data.type.missingvendor.klaviyo.body.data.attributes.profile.data.type.emptyvendor.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. Native JSON type: string or null. Fix: Send `anonymous_id`, or drop the empty pair. | vendor.klaviyo.body.data.attributes.profile.data.attributes.anonymous_id.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.anonymous_id.invalid |
docs |
data.attributes.profile.data.attributes._kx |
optional | Also known as the `exchange_id`, this is an encrypted identifier used for identifying a profile by Klaviyo's web tracking. You can use this field as a filter when retrieving profiles via the Get Profiles endpoint. Native JSON type: string or null. Fix: Send `_kx` from Klaviyo web tracking, or drop the empty pair. | vendor.klaviyo.body.data.attributes.profile.data.attributes._kx.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes._kx.invalid |
docs |
data.attributes.profile.data.attributes.locale |
optional | The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2) Native JSON type: string or null. Fix: Send a tag such as `en-US`. | vendor.klaviyo.body.data.attributes.profile.data.attributes.locale.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.locale.invalid |
docs |
data.attributes.profile.data.attributes.image |
optional | URL pointing to the location of a profile image Native JSON type: string or null. Fix: Send an absolute image URL, or omit the field. | vendor.klaviyo.body.data.attributes.profile.data.attributes.image.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.image.invalid |
docs |
data.attributes.profile.data.attributes.location.ip |
optional | IP Address Native JSON type: string or null. Fix: Send the raw IP in `location.ip`, not a digest. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.ip.emptyvendor.klaviyo.body.data.attributes.profile.data.attributes.location.ip.invalid |
docs |
data.attributes.unique_id |
optional | A unique identifier for an event. If the unique_id is repeated for the same profile and metric, only the first processed event will be recorded. If this is not present, this will use the time to the second. Using the default, this limits only one event per profile per second. Native JSON type: string or null. Maximum decoded characters: 255. | vendor.klaviyo.body.data.attributes.unique_id.emptyvendor.klaviyo.body.data.attributes.unique_id.invalid |
docs |
data |
optional | The vendor documents `data` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.invalid |
docs |
data.attributes |
optional | The vendor documents `data.attributes` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.invalid |
docs |
data.attributes.metric |
optional | The vendor documents `data.attributes.metric` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.metric.invalid |
docs |
data.attributes.metric.data |
optional | The vendor documents `data.attributes.metric.data` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.metric.data.invalid |
docs |
data.attributes.metric.data.attributes |
optional | The vendor documents `data.attributes.metric.data.attributes` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.metric.data.attributes.invalid |
docs |
data.attributes.profile |
optional | The vendor documents `data.attributes.profile` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.profile.invalid |
docs |
data.attributes.profile.data |
optional | The vendor documents `data.attributes.profile.data` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.profile.data.invalid |
docs |
data.attributes.profile.data.attributes |
optional | The vendor documents `data.attributes.profile.data.attributes` in the request contract. Native JSON type: object. | vendor.klaviyo.body.data.attributes.profile.data.attributes.invalid |
docs |
data.attributes.profile.data.attributes.location |
optional | The vendor documents `data.attributes.profile.data.attributes.location` in the request contract. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.invalid |
docs |
root |
optional | The vendor documents `` in the request contract. Native JSON type: object. | vendor.klaviyo.body.root.invalid |
docs |
data.attributes.backfill |
optional | When true, the event is recorded but does NOT trigger flows. Use this when backfilling historical events so existing flow definitions do not re-fire on events that already fired in the past. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: boolean or null. | vendor.klaviyo.body.data.attributes.backfill.invalid |
docs |
data.attributes.metric.data.attributes.service |
optional | This is for advanced usage. For api requests, this should use the default, which is set to api. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.metric.data.attributes.service.invalid |
docs |
data.attributes.profile.data.attributes.first_name |
optional | Individual's first name Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.first_name.invalid |
docs |
data.attributes.profile.data.attributes.last_name |
optional | Individual's last name Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.last_name.invalid |
docs |
data.attributes.profile.data.attributes.organization |
optional | Name of the company or organization within the company for whom the individual works Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.organization.invalid |
docs |
data.attributes.profile.data.attributes.title |
optional | Individual's job title Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.title.invalid |
docs |
data.attributes.profile.data.attributes.location.address1 |
optional | First line of street address Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.address1.invalid |
docs |
data.attributes.profile.data.attributes.location.address2 |
optional | Second line of street address Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.address2.invalid |
docs |
data.attributes.profile.data.attributes.location.city |
optional | City name Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.city.invalid |
docs |
data.attributes.profile.data.attributes.location.country |
optional | Country name Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.country.invalid |
docs |
data.attributes.profile.data.attributes.location.latitude |
optional | Latitude coordinate. We recommend providing a precision of four decimal places. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or number or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.latitude.invalid |
docs |
data.attributes.profile.data.attributes.location.longitude |
optional | Longitude coordinate. We recommend providing a precision of four decimal places. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or number or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.longitude.invalid |
docs |
data.attributes.profile.data.attributes.location.region |
optional | Region within a country, such as state or province Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.region.invalid |
docs |
data.attributes.profile.data.attributes.location.zip |
optional | Zip code Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.zip.invalid |
docs |
data.attributes.profile.data.attributes.location.timezone |
optional | Time zone name. We recommend using time zones from the IANA Time Zone Database. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.location.timezone.invalid |
docs |
data.attributes.profile.data.attributes.properties |
optional | An object containing key/value pairs for any custom properties assigned to this profile Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.attributes.properties.invalid |
docs |
data.attributes.profile.data.meta |
optional | Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.meta.invalid |
docs |
data.attributes.profile.data.meta.patch_properties |
optional | Specify one or more patch operations to apply to existing property data Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_properties.invalid |
docs |
data.attributes.profile.data.meta.patch_properties.append |
optional | Append a simple value or values to this property array Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_properties.append.invalid |
docs |
data.attributes.profile.data.meta.patch_properties.unappend |
optional | Remove a simple value or values from this property array Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_properties.unappend.invalid |
docs |
data.attributes.profile.data.meta.patch_properties.unset |
optional | Remove a key or keys (and their values) completely from properties Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or array or null. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_properties.unset.invalid |
docs |
data.attributes.profile.data.meta.patch_identifiers |
optional | Specify one or more patch operations to apply to existing identifier data. Currently only `email` is supported, and it is used to add or remove secondary email addresses on a profile. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object or null. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_identifiers.invalid |
docs |
data.attributes.profile.data.meta.patch_identifiers.append |
optional | Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_identifiers.append.invalid |
docs |
data.attributes.profile.data.meta.patch_identifiers.unappend |
optional | Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: object. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_identifiers.unappend.invalid |
docs |
data.attributes.profile.data.meta.patch_properties.unset[] |
optional | Applies when {"kind":"json_type","param":"data.attributes.profile.data.meta.patch_properties.unset","json_type":"array"}. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string. | vendor.klaviyo.body.data.attributes.profile.data.meta.patch_properties.unset[].invalid |
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.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 |
root |
optional | Arrays within event data contain at most 4000 items. Body scope: data.attributes.properties.**. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: string or number or boolean or object or array or null. Maximum array items: 4000. | vendor.klaviyo.body.root.invalid |
docs |
root |
optional | Integer event property values fit signed 64 bits; fractional values are not forced to integer. Body scope: data.attributes.properties.**. Applies when {"kind":"json_type","param":"","json_type":"integer"}. Presence diagnostic severity: error. Value diagnostic severity: error. Native JSON type: integer. Minimum numeric value: -9223372036854776000. Maximum numeric value: 9223372036854776000. | vendor.klaviyo.body.root.invalid |
docs |
root |
optional | The95KBprofile limit is interpreted as95KiB of compact normalized JSON for this advisory. Raw JSON whitespace/escaping and decimalKBunits are not defined by the source. Body scope: data.attributes.profile.data. Presence diagnostic severity: warning. Value diagnostic severity: warning. Native JSON type: object. Maximum compact JSON bytes: 97280. | vendor.klaviyo.body.root.invalid |
docs |
root |
optional | String size100KB is interpreted as100KiB of decoded UTF8 for this advisory. The primary source does not define KB or escaping semantics. Body scope: data.attributes.properties.**. Presence diagnostic severity: warning. Value diagnostic severity: warning. Native JSON type: string or number or boolean or object or array or null. Maximum decoded UTF-8 bytes: 102400. | vendor.klaviyo.body.root.invalid |
docs |
root |
optional | Custom event data excludes profile. This advisory compares compact property JSON to5MiB, an explicitly recorded interpretation of the source5MB limit. Body scope: data.attributes.properties. Presence diagnostic severity: warning. Value diagnostic severity: warning. Native JSON type: object. Maximum compact JSON bytes: 5242880. | vendor.klaviyo.body.root.invalid |
docs |
method |
required | This published ingestion operation uses HTTP POST. Complete HTTP capture contract. Native JSON type: string. | vendor.klaviyo.http.method.missingvendor.klaviyo.http.method.emptyvendor.klaviyo.http.method.invalid |
docs |
content_type |
required | Use a published request media type. Complete HTTP capture contract. Native JSON type: string. | vendor.klaviyo.http.content_type.missingvendor.klaviyo.http.content_type.emptyvendor.klaviyo.http.content_type.invalid |
docs |
body |
required | The request body is a JSON object. Complete HTTP capture contract. Native JSON type: object. | vendor.klaviyo.http.body.missingvendor.klaviyo.http.body.invalid |
docs |
headers.authorization |
required | This endpoint requires the documented authentication header. Complete HTTP capture contract. Native JSON type: string. | vendor.klaviyo.http.headers.authorization.missingvendor.klaviyo.http.headers.authorization.emptyvendor.klaviyo.http.headers.authorization.invalid |
docs |
headers.revision |
required | Revision is a calendar-valid date in YYYY-MM-DD[.suffix] form. Complete HTTP capture contract. Native JSON type: string. | vendor.klaviyo.http.headers.revision.missingvendor.klaviyo.http.headers.revision.emptyvendor.klaviyo.http.headers.revision.invalid |
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