Skip to main content

Get Data Into Klaviyo

Course overview
Lesson
4 min read

Try it yourself: Send a server-side event

This lesson is optional. It walks you through sending the same Booked Class event Flexie's team built in the earlier server-side API lesson, using Postman and a Klaviyo test account. If you'd rather skip the hands-on practice, you can move on to the next lesson.

This lesson is optional. It walks you through sending a Booked Class event for Flexie, using Postman and a Klaviyo test account. If you'd rather skip the hands-on practice, you can move on to the next lesson.

What you'll need

  • A Klaviyo test account. Create a free, separate account so your practice calls don't touch real data. See Create a test account.
  • Sample data. In your test account, go to Integrations > Developer tools > Sample data to add sample profiles, events, and catalog items. See Generate sample data.
  • Postman. Fork Klaviyo's latest Postman collection and add your test account's private API key. See Use Klaviyo's Postman collections.

Making API calls with Postman will change data in the account you use, so always work in your test account.

Send a booked class event when a Flexie member books a class

Step 1: Setup

Open Postman, create a new request.

  • Method: POST
  • URL: https://a.klaviyo.com/api/events/

Go to the Headers tab, add:

  • Authorization → Klaviyo-API-Key {{privateKey}}
  • Content-Type → application/json
  • revision → check developers.klaviyo.com for the current stable revision, use that exact date string (e.g. 2026-10-15)

Couple notes for your own integration:

  • Private key lives in KLAVIYO_API_KEY. Never in the repo, never in front-end code.
  • Revision pinned as a constant: KLAVIYO_REVISION. Revisions stay active for up to 2 years after release. Move to the latest stable revision every 12 to 18 months. Don't assume a revision date is permanent, check developers.klaviyo.com before shipping to production. (When a revision is retired, Klaviyo falls forward to the next supported one instead of hard-breaking the call, which can quietly mask that you've fallen behind.)
  • Metric name pinned as a constant: METRIC_BOOKED_CLASS = "Booked Class"
Step 2: Build the payload
text
POST https://a.klaviyo.com/api/events/
Authorization: Klaviyo-API-Key <private key from env>
revision: <current stable revision , check developers.klaviyo.com>
Content-Type: application/json

Before you send, replace the email address with a real email that you can access.

json
{
  "data": {
    "type": "event",
    "attributes": {
      "unique_id": "BK-4471",
      "time": "2026-09-02T18:00:00Z",
      "value": 45.00,
      "value_currency": "USD",
      "properties": {
        "booking_id": "BK-4471",
        "class_name": "Reformer 6pm",
        "gym_id": "leeds-01"
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Booked Class" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "sam@realmail.com",
            "external_id": "user_88213",
            "gym_id": "leeds-01"
          }
        }
      }
    }
  }
}
  • gym_id appears twice on purpose: on the event, it describes that specific booking. On the profile, it supports a downstream lookup for branch hours and address, which runs against the profile, not the event.
  • unique_id reuses the booking's own ID. That's already stable, which is what makes the retry in Step 3 safe.
  • time sits at the root of attributes, as a sibling of properties, not inside it.
Step 3: Retry with failure-type awareness
text
MAX_ATTEMPTS = 5

for attempt in 1..MAX_ATTEMPTS:
    r = POST(url, headers, body)

    if r.status == 202:
        return SUCCESS

    if r.status == 400:
        log_error(r.body)          # payload bug, will fail again
        return FAIL                # do not retry

    if r.status == 429 or r.status >= 500:
        wait = r.header("Retry-After") or (2 ** attempt) + random(0, 1)
        sleep(wait)
        continue

    log_error(r.status, r.body)
    return FAIL

dead_letter_queue.push(payload)     # attempts exhausted

This loop is only safe to retry because the payload already carries a stable unique_id.

Step 4: Verify

Open the account, find the Booked Class metric, and confirm the event shows up on a test profile with a real email. Not @example.com or @test.com. You can also check that profile's activity feed. Events can take a few minutes to appear, so give it a moment before you troubleshoot.

Step 5: Historical backfill

Historical bookings go through the same endpoint, with time set to when the booking actually happened, plus "backfill": true to stop the confirmation flow from firing for people already served months ago:

json
{
  "data": {
    "type": "event",
    "attributes": {
      "backfill": true,
      "unique_id": "BK-3190",
      "time": "2025-11-14T10:00:00Z",
      "value": 30.00,
      "value_currency": "USD",
      "properties": { "booking_id": "BK-3190", "class_name": "Spin 7am", "gym_id": "leeds-01" },
      "metric": { "data": { "type": "metric", "attributes": { "name": "Booked Class" } } },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": { "email": "old.member@realmail.com", "external_id": "user_55021", "gym_id": "leeds-01" }
        }
      }
    }
  }
}

With backfill: true, the event is recorded normally and stays visible in metrics, segmentation, and the Events API, only the flow trigger is suppressed. This replaces the older manual sequencing of "load history with the flow off, then remember to turn it back on." For bulk backfills, backfill: true goes once at the event-bulk-create level, not repeated per event, and watch for duplicate unique_id values in the same batch, which reject the whole batch.

Testing note (Postman or equivalent)

Hardcoded values go stale when you reuse them. Sending the same unique_id on every run gets silently dropped as a duplicate, and a fixed time stops matching when you test later. Generate fresh values with a pre-request script:

javascript
const now = new Date();

function toISOWithOffset(date, offsetHours) {
  const utc = date.getTime() + (date.getTimezoneOffset() * 60000);
  const local = new Date(utc + (3600000 * offsetHours));
  const pad = (n) => String(n).padStart(2, '0');
  return `${local.getFullYear()}-${pad(local.getMonth() + 1)}-${pad(local.getDate())}T${pad(local.getHours())}:${pad(local.getMinutes())}:${pad(local.getSeconds())}-03:00`;
}
const isoOffset = toISOWithOffset(now, -3); // this example uses UTC-3 (São Paulo)

pm.variables.set('klaviyoTime', isoOffset);
pm.variables.set('uniqueId', `order-${now.getTime()}-${Math.floor(Math.random() * 10000)}`);

Reference {{klaviyoTime}} and {{uniqueId}} in the request body. If you copy a sample payload from elsewhere, double-check the test email isn't @example.com/@test.com and that any duplicate $value/$value_currency inside properties is removed, the root-level value/value_currency fields already cover it.

Production notes

In your own integration, save the booking to your database first, then send the Booked Class event.

If you send the event before the booking is saved and the save fails, Klaviyo has an event for a booking that doesn't exist. Events can't be removed once they're in Klaviyo.

You can’t practice saving the booking first in Postman (there’s no database to save it to), so build it into your own integration.

Try it yourself: Send a server-side event