Skip to main content

Get Data Into Klaviyo

Course overview
Lesson
5 min read

Push data into Klaviyo using server APIs

Flexie's developers have MindBody talking to Klaviyo, and the migration is underway. They send their historical class bookings through Bulk Create Events, 800 at a time. One batch comes back with a 400. The log only says "request rejected."

The team digs in. Two migrated bookings shared the same unique_id, so Klaviyo kept the first and silently discarded the second. The team also found that a batch was rejected with a 400, and the cause was a payload structure error.

In this lesson, you'll learn how to execute a server-side API call with a correctly structured payload, plus the nuances that keep Klaviyo from silently dropping your event.

Verify AI-generated payloads against current docs

Using AI to help build your payload? Double check the endpoints it gives you. Some models pull from older documentation and default to the deprecated v1 track/identify endpoints instead of the current ones. Anything that calls /api/track or /api/identify is the old v1 API, which Klaviyo retired on June 30, 2024.

Sending a server-side API request:

Authenticate with a private API key

What it is: Every request needs two headers:

text
Authorization: Klaviyo-API-Key {your-private-key}
revision: {revision-date}

Private keys start with pk_ followed by an alphanumeric string. There's no pk_live_ / pk_test_ pattern like some other APIs use. Keys are created in account settings and can be scoped to specific endpoints.

Why it matters: The private key can read and write customer data, so it lives only in a server-side environment, never anywhere else. The revision header pins the API version, so field names and payload shapes don't shift under you until you deliberately switch revisions.

Common mistakes:

  • Shipping the private key in front-end JS or a mobile bundle
  • Confusing the private key with the public Site ID (client-side only)
  • Copying a deprecated revision date from an old blog post or AI-generated snippet, which can point to different field names than the current docs
Payload structure and required fields

What it is: Events use JSON:API format. Everything nests under data.attributes. Inside that, you've got properties, a metric object (the metric name), and a profile object (the identifiers).

time, value / value_currency, unique_id, and backfill are siblings of properties at the data.attributes level. Not nested inside properties.

Why it matters: The nesting is strict: a missing data wrapper or a wrong type value returns 400 and writes nothing.

Common mistakes:

  • Flat payloads copied from the old v1 API
  • Putting email inside properties instead of profile
  • Duplicating the monetary value inside properties (like a custom $value field) when the root-level value field already covers it
  • Putting the event's real timestamp in a custom property (like starts_at) instead of the root time field. Time controls when Klaviyo thinks the event happened. A custom property doesn't.
unique_id behavior

What it is:

unique_id is how Klaviyo tells a genuine repeat event from an accidental duplicate. It accepts 1 to 255 characters and it's your responsibility to generate it, usually from something like a booking ID or order ID.

Why it matters: If you send an event with a unique_id Klaviyo has already seen for the same profile and metric, Klaviyo keeps the first one and silently discards the duplicate. That's what makes retries safe: send the same unique_id on every retry, and Klaviyo won't double count.

Common mistakes:

  • Duplicates are dropped per event. If two events share a unique_id for the same profile and metric, Klaviyo keeps the first and discards the duplicate. Check your batch for duplicate IDs, because the drop is silent and the response won't show it.
  • Retrying with a new unique_id each time. Klaviyo sees every retry as a new event, so one booking can turn into three. Generate the ID once per booking, and send that same ID on every retry.
Upsert behavior for profiles

What it is:

Sending a profile alongside an event creates it if nothing matches, or updates it if something does. Matching runs on external_id, email, and phone_number. There's no lookup call before the write. That removes a round trip and a race condition, but it also means every event call is a chance to overwrite profile data you didn't mean to touch.

Events work differently. Once written, they can't be corrected. You can't fix a typo in a property or metric name after the fact.

Why it matters:

Store attributes you'll segment on as they are today, like loyalty tier or preferred location, on the profile. Event properties record what was true when the event happened, and you can't correct them afterward. And if you send identifiers inconsistently (email in one call, external_id in another) for the same real person, you get two profiles instead of one.

Common mistakes:

  • Assuming you can correct an event after it's written. The only fix is sending a new event and living with the old one, or deleting the metric and replaying the history.
  • Sending email from one system and external_id from another for the same person, which creates duplicate profiles instead of one clean record.

A 202 on an event-with-profile call tells you the request was well-formed. It doesn't tell you whether the profile matched an existing record or created a new one. If your identifiers are inconsistent across systems, you can be shipping duplicate profiles for weeks and the response code will never flag it. The only way to catch it is checking the profile record itself, not the event response.

Ready to practice? The next lesson, Try it yourself, walks you through sending a Booked Class event in Postman.

Push data into Klaviyo using server APIs