What we do
Tools
Industries
Department
How we workLet's talk →
Home/Klaviyo/Klaviyo API
Klaviyo

The Klaviyo API at Endpoint Level: Requests That Work and the Responses That Mislead

This is the working detail for developers: the headers every server call needs, a Create Event body Klaviyo accepts, which endpoint to use for profiles versus subscriptions, and the responses that look like success but aren't. For which Klaviyo API handles which kind of data, start with our Klaviyo APIs overview.

Every server-side call

Base URL https://a.klaviyo.com/api/, with Content-Type: application/vnd.api+json on writes.

Auth header Authorization: Klaviyo-API-Key your-private-key. Make the key under Settings, API keys, with only the scopes this integration needs.

Settings API keys

Version header revision: YYYY-MM-DD, set to the dated API version you've tested against. It's required, and it decides the request and response shape.

Send one order event to Klaviyo

POST to /api/events. The key needs the events:write scope.

  1. 1

    Wrap it in a JSON:API envelope

    The body is { "data": { "type": "event", "attributes": { ... } } }. Inside attributes, properties, metric and profile are required.

  2. 2

    Name the metric and point at the profile

    The metric is { "data": { "type": "metric", "attributes": { "name": "Wholesale Order Placed" } } }, under 128 characters. The profile is { "data": { "type": "profile", "attributes": { "email": "..." } } }, identified by email, phone_number or Klaviyo id. If the profile doesn't exist, Klaviyo creates it.

    Watch for: the metric name is created on first use. A typo makes a new metric, and flows built on the right name never see those events.

  3. 3

    Add value, time and a unique_id

    Set value and value_currency for revenue reporting, time as the real order time (it defaults to when Klaviyo received it), and unique_id as your order number. Put line items and anything a flow will filter on in properties.

  4. 4

    Read the 202 correctly

    A 202 Accepted means Klaviyo validated the request and queued it, not that the event is on the profile. Check the profile's activity in Klaviyo for your first few, and log the request bodies you sent until you trust the feed.

Profile upsert or subscription job: they do different things

The most expensive Klaviyo API mistake is treating these as the same call.

POST /api/profile-import

Create or update a profile

  • Returns 201 when it created the profile and 200 when it updated one.
  • Fields you leave out stay as they were. Sending null clears a field.
  • Doesn't record marketing consent and doesn't add the profile to any list.
  • Scope profiles:write.
POST /api/profile-subscription-bulk-create-jobs

Record consent to email or SMS

  • Up to 1,000 profiles per call, returns 202, optionally into one list.
  • Respects double opt-in on that list, unless you set historical_import with a consented_at date.
  • Clears unsubscribe, spam-report and user suppressions on the profiles you send.
  • To add someone to a list without touching consent, use Add Profile to List instead.

Send a subscription only when the person actually opted in. Running everyone through the subscribe job quietly re-subscribes people who opted out.

The Klaviyo endpoint for each job

The job Endpoint Rate tier and the catch
An order, shipment or renewal from your own system POST /api/events 350/s burst, 3,500/min steady. Without unique_id, Klaviyo only keeps one event per profile per metric per second.
Years of past orders POST /api/events with backfill: true, or a bulk event job Backfill records the event without triggering flows. Leave it off and every historical order can fire your live post-purchase flow.
Profile details from a CRM or loyalty tool POST /api/profile-import 75 requests a second in bursts, with a lower per-minute steady limit (check the endpoint page). Map your fields to custom properties once and keep the names stable.
Signup from a form you host Subscription job from your server, or the client endpoints from the page The subscribe job sits in the same rate-limit tier. Send the list ID if a specific list's opt-in settings should apply.
Browsing or cart activity from the storefront POST /client/events?company_id=YOUR_PUBLIC_KEY Public key only, never a private one, still with a revision header. Returns 202 like the server call.

What goes wrong in the first month of a Klaviyo API feed

Two integrations, one quota

How you'll know: The order feed starts getting 429s the day someone adds a loyalty sync.

Fix: Every integration on a private key shares one rate-limit quota per account (OAuth apps get their own per install). Read the Retry-After header on a 429, wait that many seconds, then retry the same request.

Resent orders counted twice

How you'll know: Revenue in Klaviyo runs ahead of your order system after a retry or a re-run.

Fix: Always send unique_id. Klaviyo keeps the first event with a given ID for that profile and metric and drops the repeats.

The revision header drifted

How you'll know: A response field your code reads is suddenly missing, or shaped differently.

Fix: Hard-code one revision date in your client, upgrade deliberately, and test the new date against a copy of your requests first.

Event time left blank on a delayed send

How you'll know: Orders replayed from a queue all show today's date, and timing-based flows fire late.

Fix: Set time to when the order really happened. It's truncated to the second and can't be before 1990 or more than a year ahead.

SDKs, webhooks and the part that takes longest

Klaviyo publishes official SDKs for several languages, Python and Node among them, which set the headers, page through results and back off on rate limits for you. They track revisions too, so pin the SDK version the same way you'd pin the header.

Data leaving Klaviyo goes through webhooks: a Webhook action placed in a flow sends a POST when a profile reaches it, and account-level system webhooks report events such as unsubscribes where your account has them. Either way your endpoint should answer fast and treat a repeat as normal.

The calls themselves are quick to write. What takes time is the event design: names, properties and IDs that flows and segments can rely on for years, plus the retries, the backfill and the alert when the feed goes quiet. n-frames builds and runs that layer for stores whose orders, subscriptions or shipping data sit outside Klaviyo's native integrations. Off-the-shelf options are on our Klaviyo integrations page, and flow design on Klaviyo flows.

Questions people ask

Where do I get a Klaviyo API key?

In Klaviyo, open Settings, then API keys, and create a private key. Pick Read-only, Full or Custom scopes for exactly the endpoints you'll call, and copy it right away, since the full key is only shown once.

Does Klaviyo have an SDK?

Yes, official SDKs for several languages including Python and Node. They handle authentication, the revision header, pagination and rate-limit retries, so you mostly work with typed request objects rather than raw HTTP.

How do I send a custom event to Klaviyo?

POST to /api/events with a metric name, a profile identified by email, phone number or ID, and a properties object, plus a unique_id and the real event time. The new metric then shows up as a flow trigger and a segment condition.

Does Klaviyo support webhooks?

Yes. A flow's Webhook action sends a POST to your URL when a profile reaches that step, and system webhooks report account events where your plan or app access includes them. Klaviyo doesn't wait for your system to act, so build the receiver to answer quickly.

Is the Klaviyo API free to use?

API access comes with your Klaviyo account at no extra charge. What limits you is the rate tier of each endpoint, and the fact that all your private-key integrations share one quota.

Why does the Klaviyo API return 202 instead of 201?

Events and subscription jobs are processed asynchronously. A 202 means the request was valid and queued, not that it's on the profile yet. Profile import, by contrast, answers 201 or 200 straight away.

Can someone build and run our Klaviyo API feed for us?

n-frames does. We design the events and profile properties, write the feed from your order, subscription or fulfilment system, handle backfills without re-firing flows, and monitor it so a stalled feed is caught early.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.