Skip to main content

Get Data Into Klaviyo

Course overview
Lesson
6 min read

Push data into Klaviyo: client-side APIs

Flexie uses server-side APIs for anything that needs the private key, like membership details from their backend. But what about the customer who keeps checking the reformer class pack and hasn't signed up for anything yet? Flexie tracks that browsing client-side, then nudges her toward the newsletter. That browsing signal, no money involved, no identifier changing hands, is exactly what client-side is for.

Every client-side request uses the public key, and that key is genuinely public. Anyone can read it from page source and replay or forge a request with it. So what Klaviyo lets you do from the client is deliberately narrower than what the private key allows. You can create things, but you can't update an existing identifier, and responses never leak sensitive data back to the browser.

Build on klaviyo.js, not a custom pixel. A custom pixel runs its own visitor ID, which drifts from Klaviyo's cookie-based one, so an anonymous visitor's events can miss merging into their profile once they identify.

Klaviyo's client-side JS captures the visitor's identity and browsing behavior.

Klaviyo provides baseline scaffolding for most client-side calls, or automatically includes them in native ecommerce integrations. If you need customization, you can build those calls yourself.

For example, Klaviyo's native Added to Cart events only include the most recently added item, not the entire cart state. Want to reference the full cart in your abandoned cart email? Easily done with some light modification of our default recommended call.

Differentiate the three client-side API calls

You will likely work with these three client-side API calls when building in Klaviyo:

Differentiate the three client-side API calls

API type

Summary (what it is)

When to use it

Concrete use cases/examples

Single Create Client Event

Tracks one event for one visitor from the browser. Auth uses the public key (company_id) as a query parameter. Limits: 350/s burst, 3,500/min steady.

Behavioral signals that don't need guaranteed delivery. If the browser closes mid-request, that's an acceptable loss for this kind of data.

Viewed Product, Added to Cart, Started Checkout, any on-page interaction that should feed a flow or segment

Bulk Create Client Events

Several events for one visitor in one request. One profile per request, from one browser or device. Limits: 10/s burst, 150/min steady.

A small queue of events from one browser or device, sent together. Not for traffic across many visitors.

A mobile app sending offline actions for one user on reconnect, or a page flushing a short queue for one visitor.

Profile API (Create/Update Client Profile)

Creates or updates non-identifier properties on a profile from the browser. No event tracked. Same public-key auth as the Event API.

Enriching an already-identified profile without changing who it is.

Recording a size preference from an on-page quiz, setting a loyalty tier from a third-party widget

Subscription API (Create Client Subscription)

Creates a subscription and consent record for email and/or text messaging. The subscriptions object controls which channels actually get subscribed, so you can update contact info without opting anyone in you didn't mean to.

The exact moment and place consent is captured.

Newsletter signup, text opt-in checkbox at checkout, a discount-code popup

Two more client-side endpoints worth knowing, even though they don't fit the table above:

  • Back In Stock Subscription (client): lets a visitor subscribe to a restock alert for a catalog item, same public-key pattern
  • Push Token (client): registers or unregisters a mobile push token against a profile. This is what mobile SDKs use under the hood, not something you'd typically call directly

Klaviyo object vs. calling /client endpoints directly

Use the Klaviyo object (klaviyo.js, exposing identify() and track()) or the mobile SDKs for identifying visitors and tracking events. The Klaviyo object has no subscribe function, so subscribing a visitor still means calling the Create Client Subscription endpoint directly.

A direct call to the /client endpoints makes sense when the SDK genuinely doesn't fit your environment: a non-browser client, a custom mobile flow the official SDK doesn't cover, a server-rendered page proxying a client-scoped request. Go that route, and you're responsible for reimplementing the identity and consent handling the SDK would otherwise give you for free.

Common mistakes

Select a mistake to expand it.

Trying to update an existing identifier client-side.

Returns 202, but the change never happens. Updating an identifier always needs the private key, server-side.

Client-side request body. Returns 202, but the email stays the same:

json
{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "new.address@example.com"
    }
  }
}

Send the same change with your private key from your server, and the email updates.

Treating client-tracked events as trustworthy.

The public key is public by design. Never gate anything money- or trust-sensitive on a client-side event, it can be forged from devtools.

Racing identify() and track().

Fire track() before identify() resolves, and the event can land on the wrong (still-anonymous) profile. Pass a callback to identify() so the event fires after it finishes, or check isIdentified() first. If anonymous visitor activity backfill is turned on in the account, Klaviyo can also connect earlier activity once the visitor is identified.

Assuming a subscription worked because it returned 202.

A 202 means Klaviyo accepted the request for processing, not that the subscription is complete. With double opt-in, the subscriber still has to confirm. Klaviyo's list bombing IP protections can also flag or block an IP address that makes many subscribe calls in a short time. Check your list's opt-in setting and look for a sudden spike in sign-ups. If a subscriber still doesn't appear, check the Understanding list bombing help article before assuming a code bug.

  • Many subscribe calls from one IP address in a short window, such as a test script, a retry loop, or repeatedly testing the same form
  • A sudden spike in new subscribers with no list growth campaign behind it
  • Unconventional first and last names, or many submissions that look alike
  • Bot submissions from third-party forms synced to Klaviyo through the API
Blocking Klaviyo with your site's Content Security Policy.

If your CSP doesn't allow Klaviyo's domains, klaviyo.js never loads and nothing gets tracked. Domains that commonly need to be allowed include static.klaviyo.com, static-tracking.klaviyo.com, a.klaviyo.com, and images.klaviyo3.com. Some Klaviyo images also load from a CloudFront domain, so an allowlist that looks complete can still break images.

Assuming every client-side event arrives.

Ad blockers, privacy extensions, and cookie blockers can stop klaviyo.js from loading, or stop its calls from sending. A dropped connection, a closed tab, or a weak mobile signal can also lose an event, and the browser won't retry it. Send money-related or critical events from your server.

Activity: which endpoint fits the volume?

Sort each scenario by how many events are being sent and how many visitors they come from. Single Create Client Event sends one event as it happens. Bulk Create Client Events sends several events for one visitor or device in one request. If the traffic spans many profiles, neither client endpoint fits, so use a server-side endpoint. klaviyo.js calls these same endpoints, so the same limits apply.
One visitor's page queues interaction events and flushes them every few seconds.
A flash sale drives roughly 200 Viewed Class events per second across many visitors.
A quiz result page fires one Completed Quiz event per visitor, a handful of times per minute at most.
A mobile app batches 15 to 20 offline actions for one user and sends them when the device reconnects, a few times a day.
A kiosk syncs check-ins for 40 different members at closing, once a day.
Single Create Client Event
Bulk Create Client Events
Neither client endpoint fits (use a server-side endpoint)
Push data into Klaviyo: client-side APIs