Solved

v1/v2 vs v3 event payload data formats?

  • 19 March 2024
  • 3 replies
  • 46 views

Badge

Hello,

We have a completely custom integration where we post JSON data to the /track API to create events and trigger customer notification emails, etc.

We’re now faced with migrating to the new APIs. The documentation around the migration from v1/v2 to the new APIs is ver clear on the new endpoints such as /api/events and new functionality etc.

However what’s not so clear to me is any change between the data format of the original API payloads vs new API payloads?

The Track API reference (https://developers.klaviyo.com/en/v1-2/docs/track-api-reference#back-end-tracking-events-server-side) refers to special fields such as $event_id, $value, $email$first_name etc. However I cannot find any reference to these in the new documentation. For example the documentation for Create Event (https://developers.klaviyo.com/en/reference/create_event) gives the example payload JSON below:
 

{
"data": {
"type": "event",
"attributes": {
"properties": {
"newKey": "New Value"
},
"time": "2022-11-08T00:00:00",
"value": 9.99,
"value_currency": "USD",
"metric": {
"data": {
"type": "metric",
"attributes": {
"name": "Viewed Product"
}
}
},
"profile": {
"data": {
"type": "profile",
"id": "01GDDKASAP8TKDDA2GRZDSVP4H",
"attributes": {
"email": "sarah.mason@klaviyo-demo.com",
"phone_number": "+15005550006",
"external_id": "63f64a2b-c6bf-40c7-b81f-bed08162edbe",
"_kx": "J8fjcn003Wy6b-3ILNlOyZXabW6dcFwTyeuxrowMers%3D.McN66",
"first_name": "Sarah",
"last_name": "Mason",
"organization": "Example Corporation",
"title": "Regional Manager",
"image": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg",
"location": {
"address1": "89 E 42nd St",
"address2": "1st floor",
"city": "New York",
"country": "United States",
"region": "NY",
"zip": "10017",
"timezone": "America/New_York",
"ip": "127.0.0.1"
},
"properties": {
"newKey": "New Value"
}
},
"meta": {
"patch_properties": {
"append": {
"newKey": "New Value"
},
"unappend": {
"newKey": "New Value"
},
"unset": "skus"
}
}
}
}
}
}
}

In this, there is no $event_id field, no $value or $email etc…. so is the data format for create event payloads completely different from event payloads using the old /track API?

Can anybody point me to the documentation/specification for event payloads to /api/events, or something that explains the differences between old and new?

 

Many thanks in advance, 

Mat

icon

Best answer by saulblum 19 March 2024, 14:55

View original

3 replies

Userlevel 4
Badge +7

Hi, here are value and unique ID in the new API Create Event call:

 

 

The profile’s email is under the profile block:

You can set first and last name and other native profile properties using the properties shown just further down in the profile/attributes object:

 

 

Hello,

Quick follow up question:

Why in the Klaviyo documentation do some of the example API calls and responses have a $ symbol in front of certain fields?
 

For example are $value and value the same fields?

Many thanks to anyone who can enlighten me!

Tom

Userlevel 4
Badge +7

The fields with $ in front are reserved Klaviyo properties, see https://help.klaviyo.com/hc/en-us/articles/115005074627

For the API calls I’d use whatever properties are given in the examples, e.g. first_name.

Reply