Klaviyo's V3 API is rolling out, and there are a few key changes that could significantly impact how you manage your customer data. With the new API, creating and updating customer profiles has evolved, bringing both opportunities and challenges. As Klaviyo's strategic partner, we're here to guide you through what’s changing, why it matters, and how to adapt effectively.

What’s New in Klaviyo’s V3 API?

The biggest shift is that email addresses, phone numbers, and Klaviyo IDs are now all primary keys. This means they are all equally important, and you can use any of them to create or update a profile.

In the V1 and V2 APIs, the primary key for customer profiles was the email address. If no email address was available, the phone number would serve as a primary key. If there was no email address and no phone number (for instance, if there was only cookie or pixel tracking data) then the Klaviyo ID acted as the primary key. Otherwise, the Klaviyo ID was third in the hierarchy behind email and phone number.

Now, email addresses, phone numbers, and Klaviyo IDs are all on the same level, potentially leading to unexpected outcomes if you are not aware of the change.

For instance, the “create profile” endpoint in V3 will always create a new profile, even if the email, phone number, or Klaviyo ID already exists in your database. On the other hand, the “create or update profile” endpoint might overwrite an existing profile if the provided email or phone number is already in use.

Example:

Let’s say Jane Doe signs up with the email jane.doe@example.com and phone number 555-678-9100.

If Jane later makes a purchase using a different email, jane@shoppingworld.com, but the same phone number, the old API versions would treat these as separate profiles unless explicitly merged.

However, with V3, using the “create or update profile” endpoint with the new email and the same phone number could overwrite the original profile's email, merging them based on the phone number.

While this simplifies profile management, it can also lead to unintentional merges if you’re not aware of the changes.

Why It Matters

Understanding the changes to Klaviyo's V3 API is crucial for anyone relying on Klaviyo for their marketing and customer data management. These adjustments have a direct impact on how you manage and use your customer data.

The new approach to profile identifiers in the V3 API means that managing customer information can become more streamlined if handled correctly.

The ability to update profiles using different identifiers (email, phone, or Klaviyo ID) can be useful. Likewise, attributing multiple accounts to a single customer based on shared identifiers can be a powerful tool.

However, if not carefully managed, the “create or update profile” endpoint could merge profiles based on shared identifiers like phone numbers or email addresses, even when other data points suggest they should remain separate.

This could mix up the histories of two distinct customers into one profile, leading to confusing or irrelevant communications being sent to customers, potentially harming customer relationships and trust.

Recommendations

Here are our top recommendations to ensure a smooth transition to Klaviyo's V3 API:

Implement a New Profile Creation Process

Employ the “create profile” endpoint wherever customers enter their email address or phone number. This ensures that every new entry generates a distinct customer profile, preventing unwanted overlaps.

Create a 'Manage Preferences' Page

Set up a page where customers can adjust their preferences. Use the “create or update profile” endpoint here to allow updates to profile properties, like marketing preferences or addresses, without altering core identifiers such as email or phone numbers.

Establish a New Profile for Critical Updates

When customers need to update sensitive information like their email address or phone number, use the create profile endpoint to start a new profile. This method avoids merging information across different customer profiles, which can lead to significant data confusion and errors.

Need a Hand with Klaviyo V3? We're Here to Help

Navigating API changes can be complex, but you don’t have to do it alone. Feel free to get in touch with our team of data experts anytime if you need any guidance or support.