Best practice 1: Test in a separate Klaviyo account.
You can flag an account as a test account in Klaviyo. A test account has the same features and functionality as a production account, with minor visual changes and a label in the top left corner so you can tell the two apart. There is no separate test environment that behaves differently from production. To set one up, follow the instructions in Create a test account.
If you've already been testing in the production account, you'll want to delete test metrics before syncing real data. This is a manual step.
Use a real, deliverable test email address, not @example.com or @test.com. Those domains return 202, but the event is dropped in the background, so it will make a working integration look broken if events are dropped.
Billing stays on for test accounts, so keep an eye on profile, email, and SMS usage.
Best practice 2: Pick one durable primary identifier and send it on every call from every system alongside email and phone.
When different systems use different keys (the web SDK uses email, the mobile app uses an internal ID), a customer's data splinters across multiple profiles. Flows misfire, segments undercount, and an unsubscribe on one profile doesn't protect the others, which puts you at risk of compliance issues.
The fix is to pick one identifier strategy and use it in every system. Once a profile exists, the Klaviyo profile ID never changes, so use it to reference that profile. Before then, identify people with their email or phone number.
If you want to use an external ID, make sure your source system owns a durable, person-level customer ID. It also needs an upstream record that explicitly connects that ID to the person's email or phone number. Without that, mixing external ID and email-only calls creates duplicate profiles that Klaviyo will not automatically merge.
Before ingesting data from more than one system, confirm:
- Does every system that touches this customer send the same durable identifier?
- Is there a point where the customer is anonymous (a guest checkout, a pre-login session)? If so, does an identify() call bridge that anonymous activity onto the known profile once it exists?
- If a system currently authenticates by email alone, what happens when that email changes?
- Are the identifiers on an event and the identifiers on its accompanying profile actually the same, in the same call? A mismatch here creates a second profile just as easily as two different systems do.
- Does every part of this identifier actually get set where you think it does? A 202 response means Klaviyo received your request. It doesn't mean the change was applied. Open the profile in Klaviyo and confirm the identifier is correct and no duplicates were created. To change an identifier on an existing profile, use a server-side call with your private key.
See Klaviyo's profile identifiers documentation for the full mechanics.
Best practice 3: Align with your marketing team on trigger timing before you ingest data for a flow
Whether you send data as a real-time API event or a batch-synced property decides whether a flow can trigger on it correctly.
The fix is to pick one identifier strategy and use it in every system. Once a profile exists, the Klaviyo profile ID never changes, so use it to reference that profile. Before then, identify people with their email or phone number.
If you want to use an external ID, make sure your source system owns a durable, person-level customer ID. It also needs an upstream record that explicitly connects that ID to the person's email or phone number. Without that, mixing external ID and email-only calls creates duplicate profiles that Klaviyo will not automatically merge.
Before ingesting data from more than one system, confirm:
- Does every system that touches this customer send the same durable identifier?
- Is there a point where the customer is anonymous (a guest checkout, a pre-login session)? If so, does an identify() call bridge that anonymous activity onto the known profile once it exists?
- If a system currently authenticates by email alone, what happens when that email changes?
- Are the identifiers on an event and the identifiers on its accompanying profile actually the same, in the same call? A mismatch here creates a second profile just as easily as two different systems do.
- Does every part of this identifier actually get set where you think it does? A 202 response means Klaviyo received your request. It doesn't mean the change was applied. Open the profile in Klaviyo and confirm the identifier is correct and no duplicates were created. To change an identifier on an existing profile, use a server-side call with your private key.
See Klaviyo's profile identifiers documentation for the full mechanics.
Best practice 4: Check the documented rate-limit tier for the specific endpoint you're calling.
Rate limits are assigned per endpoint, not per use case. Klaviyo uses tiers from XS through XL, but similar-sounding endpoints can have very different throughput limits. Bulk endpoints are not automatically higher-throughput alternatives.
For example:
Tier | Burst | Steady |
|---|---|---|
XS | 1/s | 15/m |
S | 3/s | 60/m |
M | 10/s | 150/m |
L | 75/s | 700/m |
XL | 350/s | 3,500/m |
This means batching is not always an optimization. Moving to bulk can reduce your throughput ceiling and introduce 429 errors that unbatched event calls would not have encountered.
Before implementing, validate:
- Endpoint tier: Confirm the rate-limit tier for the exact endpoint you plan to use.
- Bulk behavior: Check whether the bulk endpoint improves throughput or trades it for lower request capacity.
- Retry handling: On a 429, honor the Retry-After header instead of using a guessed backoff interval.
- Duplicate handling: Check how unique_id behaves in single versus bulk requests. Duplicate handling can differ, including cases where one duplicate causes an entire bulk batch to fail.
- Error classification: Do not retry every non-202 response the same way. A 400 needs a payload fix; 429s and some 5xx responses generally need controlled retries.
See Klaviyo's rate limits documentation for the current tier assignments per endpoint.