As Klaviyo rolls out its V3 API, there are significant changes that will impact how you manage customer data and interact with the platform. Whether you’re a seasoned developer or just getting started, understanding these updates is critical to maximizing the value of Klaviyo’s APIs. This blog will guide you through the key changes, best practices, and tools you’ll need to stay ahead.
What’s New in Klaviyo’s V3 API?
Klaviyo’s V3 API introduces a critical change in how customer profiles are managed. In previous versions (V1 and V2), the primary key for a customer profile was usually the email address. If an email wasn’t available, a phone number or Klaviyo ID would serve as secondary identifiers.
With V3, email addresses, phone numbers, and Klaviyo IDs are all primary keys, meaning they are equally important. This opens up new possibilities but also adds complexity. For example, using the “create or update profile” endpoint might merge profiles if an email or phone number matches an existing one, even if other data points differ.
Example
Let’s say Jane Doe signs up with the email [email protected] and phone number 555-678-9100. Later, she makes a purchase using [email protected] but the same phone number. In V1/V2, these would remain separate profiles unless explicitly merged. In V3, however, using the “create or update profile” endpoint would merge them, potentially overwriting the original profile’s email.
Why It Matters
Understanding these changes is crucial for marketers and developers relying on Klaviyo for customer data management. The new primary key structure can streamline profile management if used correctly. However, if not carefully handled, unintended profile merges could lead to inaccurate data or irrelevant customer communications, potentially harming customer relationships.
Recommendations
To ensure a smooth transition and avoid pitfalls with the new API, consider these best practices:
- New Profile Creation Process: Use the “create profile” endpoint when customers first enter their email or phone number. This prevents accidental profile overlaps.
- Manage Preferences Page: Create a page where customers can update their preferences (such as marketing preferences) without altering core identifiers like their email or phone number. Use the “create or update profile” endpoint here.
- New Profile for Critical Updates: When customers need to update sensitive information like their email or phone number, use the “create profile” endpoint to avoid unwanted merges.
You Will Learn
Before diving into Klaviyo’s APIs, it’s important to understand how API calls work. API calls enable software to communicate with Klaviyo’s databases, retrieving or sending data using structured requests. In this guide, we’ll break down REST APIs, common HTTP methods, and tools like Postman to get you started.
What is a REST API?
A REST API (Representational State Transfer and Application Programming Interface) is a set of protocols that allows one system to communicate with another by passing data through structured requests. When you make an API call to Klaviyo, you’re submitting a request to a server, which processes it and returns the requested data in JSON format.
For example, you can use a REST API to request customer data stored in Klaviyo and receive it in a readable format.
HTTP Methods
HTTP methods are the verbs used to interact with APIs. In Klaviyo’s API, you’ll primarily use two methods:
- GET: Retrieves data from an API endpoint (e.g., pulling customer profile information).
- POST: Adds new data to an API endpoint (e.g., creating a new customer profile).
Although you won’t use them as often, other methods like PUT, PATCH, and DELETE are also supported by most REST APIs for updating or removing data.
Necessary Tools
To interact with APIs, you need the right tools. While APIs can be accessed through programming languages like Python or JavaScript, a user-friendly tool like Postman makes it easier to structure and send requests without writing complex code. Postman offers a graphical interface where you can input API endpoints, parameters, and authentication details, allowing you to quickly test your API calls.
Test Klaviyo’s APIs
Now that you understand the basics of API calls, it’s time to start testing Klaviyo’s APIs for your specific business needs. Check out Klaviyo’s API reference documentation for a full list of available APIs and how to use them. Using Postman, you can follow Klaviyo’s Postman collections to make your first API call in minutes.
API Comparison Chart
If you’re migrating from V1/V2 to V3, Klaviyo’s API comparison chart is your go-to resource. It compares older endpoints to their newer equivalents, showcasing key feature improvements and newly introduced endpoints. This chart is essential for ensuring a smooth transition to the new API without disrupting your workflows.
OpenAPI and Postman
Klaviyo provides an OpenAPI specification, which you can import into tools like Postman to interact with the new APIs right away. This makes testing easier and provides a structured overview of the available API endpoints.
Authentication
Klaviyo’s APIs use three main authentication methods:
- Private Key Authentication: Used for /api endpoints with API private keys.
- Public Key Authentication: For /client endpoints, which use a public API key (company ID).
- OAuth: Recommended for tech partners for more secure, scalable integration.
Private Key Authentication
When making requests to the /api endpoints, you need to authenticate using private keys by adding the Authorization header to your request.
Company ID (Public Key Authentication)
For client-side calls, such as form submissions, you’ll use a public API key (your company ID) as the identifier.
Versioning and Deprecation
Klaviyo’s V3 API uses a versioning and deprecation policy to manage changes over time. Stay updated with these versions to avoid disruptions as older APIs are phased out.
Status Codes and Errors
When making API requests, you’ll receive a status code that indicates the success or failure of the call. Common errors (like 400 for bad requests or 401 for unauthorized access) can be troubleshooted using Klaviyo’s API documentation.
Rate Limiting
All new API endpoints are rate-limited to prevent overuse. Rate limits are tracked in both burst and steady windows, and exceeding them results in HTTP 429 errors. Make sure to manage your API traffic effectively to avoid hitting these limits.
JSON
Feature Guides
Klaviyo’s V3 API supports advanced features that align with the JSON
specification, offering powerful ways to handle complex data:
- Relationships: Manage associations between different resources using the relationships object.
- Filtering: Use the ?filter query parameter to narrow down results based on specific criteria.
- Sorting: Apply sorting to your queries using the ?sort parameter (e.g., sort by date or ID).
- Sparse Fieldsets: Retrieve only the fields you need using the ?fields parameter, improving efficiency.
- Pagination: Klaviyo’s APIs use cursor-based pagination to navigate through large datasets.
Datetimes
All datetime values in the new APIs are formatted using the ISO 8601 RFC 3339 standard. Make sure to follow this formatting in all requests and responses.
Navigating Klaviyo’s new V3 API may feel overwhelming at first, but by understanding the key updates and leveraging the right tools and practices, you can unlock a more streamlined and powerful approach to customer data management. If you need assistance, don’t hesitate to reach out to our team of Shopify & Klaviyo experts—we’re here to help!
