Migrate from v1/v2 to new Klaviyo APIs

🚧
We recently announced the deprecation plan for Klaviyo's v1/v2 Legacy APIs. Users of those APIs have a deadline of June 30, 2024 to migrate to the new APIs before v1/v2 are officially sunset.

With Klaviyo’s new APIs, we’ve added improvements to our API functionality, new endpoints, and new features to some of our existing endpoints.

If you’re a developer who is newer to our APIs and want a step-by-step overview of how to get set up with Klaviyo, please check out our Get started with Klaviyo guide.

Resources for new APIs

Consult the following docs for important information about our new APIs:

Mapping v1/v2 endpoints to new API endpoints

If you are currently using our v1/v2 APIs and are looking for equivalent endpoints in our new APIs, we have created a comparison chart that you can use to find the new endpoint. If you want to learn how to migrate to our new endpoints via use cases, read on below to learn best practices.

Migrating from v1/v2 to new APIs via use cases

Depending on what you're doing with Klaviyo’s APIs, the best migration may not be a drop-in endpoint replacement. Our new APIs offer many new features that make drop-in replacements the non-optimal solution.

For example, if you are currently using a workflow that queries events and then queries the user for each event on our v1/v2 APIs, that previously required chaining several API calls. With our new APIs, this can be done much more efficiently. Below, we'll cover a set of core use cases to help you identify the new workflows that are appropriate replacements for our v1/v2 APIs.

Events

Creating events (server-side)

You should now create events with our Events API. Previously, Events were created using our Track API.

Querying events and aggregating event data

Querying events is now accomplished through the Events API. The Events API request is designed for returning the raw data for events that meet the conditions of the request parameters.

Previously, querying event aggregates was accomplished through directly querying events and doing arithmetic operations on your end. We have improved this experience by adding new functionality to our Query Metric Aggregates endpoint. The Query Metric Aggregates API request is designed for aggregating data for events over a specified interval, e.g. to get the number of unique email clicks last month, the total purchase revenue for all Placed Order events in the last week, etc.

Profiles

Creating and updating profiles (server-side)

Creating and updating profiles is now accomplished through two distinct endpoints, which aligns with REST best practices for a more consistent experience. Previously, profiles were created and updated via the Identify API; this has been improved to distinct operations, which can help avoid accidentally overwriting profile properties. Now, to create a profile, utilize the Profiles API. To update a profile, utilize the Update Profile PATCH endpoint. We also have client-side endpoints to assist with this use case (see below).

Subscriptions (server-side)

Adding and removing subscriptions is now accomplished through two new endpoints. To subscribe a profile, use the Subscribe Profiles endpoint. If the list in the subscribe request has double opt-in enabled, the profile will receive a message requiring their confirmation before they are subscribed. To unsubscribe a profile, use the Unsubscribe Profiles endpoint. Both of these endpoints allow up to 100 profiles per API request. To add a profile to a list without changing the profile’s subscription status, you can use the Add Profile to List relationship endpoint.

Suppressions

Suppressing and unsuppressing profiles is now accomplished through two new endpoints that follow similar patterns to subscriptions, but without an accompanying list. To suppress a profile, use the Suppress Profiles endpoint. To unsuppress a profile, the Unsuppress Profiles endpoint. A profile that was suppressed due to a hard bounced email will not be unsuppressed. A hard bounce results from an invalid email (either domain or email address is invalid).

Querying profiles

Querying profiles can now be accomplished through our new Get Profiles endpoint. This endpoint allows filter operations for profiles that match the criteria, and responses for profiles that match for several fields, including id, email, phone_number, external_id, _kx, and created. This improves our old Get Profile endpoint by allowing querying of multiple profiles at once, with a maximum response of 100 profiles per request.

Deleting profiles

Deleting profiles can be accomplished by using our Request Profile Deletion endpoint. You can delete profiles based on email, phone_number, or profile_id. All profiles that match the provided identifier will be deleted. This endpoint is useful for GDPR and CCPA deletion requests.

Campaigns

Campaign creation and updating is very similar to our v1/v2 APIs. Management of campaign actions has been improved through our jobs management tooling. Sending campaigns is now accomplished through our Create Campaign Send Job endpoint. You can retrieve and manage the status of the created campaign send jobs through our Get Campaign Send Job endpoint and our Update Campaign Send Job endpoint. You can delete a campaign using the Delete Campaign endpoint.

Templates

Template creation and updating is very similar to our v1/v2 APIs with some quality-of-life improvements. Instead of formerly requiring a singular html resource, Create Template now breaks out parameters inside the data object for name, editor_type, html, text (plaintext version of email template) and the option to specify return_fields to help limit the response. Another improvement is our new Get Template endpoint to retrieve singular template resources. To test templates, you can create a metric-triggered flow and trigger an event for the metric to send the template.

Lists and segments

Checking if profiles are in a list or segment

Querying the lists and segments for profiles has gotten major upgrades in our new APIs. Previously, we did not have a straightforward way to ask “what are all the lists or segments a profile is in?”. We’ve added endpoints for Get Profile Lists and Get Profile Segments to return list and segment memberships for profiles.

Adding a profile or tag to a list

Adding a profile to a list is similar to our v1/v2 functionality. Our new endpoint Add Profile to List is more explicit in adding a related resource in the form of a profile to a list. This endpoint can also be used to add a tag to the list, as another supported type of related resource.

Client-side (browser/website) tracking

Klaviyo.js

For onsite (browser) tracking utilizing klaviyo.js, this is a javascript library fully-managed by Klaviyo, so there is no action required on your part to update it to our new APIs.

New client endpoints

Client-side functionality not using klaviyo.js, such as tracking profiles, subscriptions, and events can be accomplished through our new endpoints. For tracking events, use Create Client Event. For client-side subscriptions, use Create Client Subscription. For client-side profile creation and updating, use our Create or Update Client Profile endpoint.

Next steps

If you have a use case that is not provided here, please join Klaviyo’s developer slack channel and provide your use case to learn from our team.

We also recommend experimenting with our new APIs using our Klaviyo postman collection.