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:
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:
{
"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.