Best practices for migrating from v1/v2 to new APIs

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 suboptimal 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, this requires chaining several API calls. With our new APIs, this can be done much more efficiently. Below, we'll cover the 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 Get Events endpoint 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 a new Reporting API that allows you to query the same service that powers the Klaviyo app to get 1:1 matches of your campaign and flow data.

Profiles

Creating and updating profiles (server-side)

Previously, profiles were created and updated via the Identify API; this has been improved to align with REST best practices and avoid accidentally overwriting profile properties. Now, to create a profile, utilize the Create or Update Profile endpoint. We also have client-side endpoints to assist with this use case (see Client-side tracking below).

We've added a new Bulk Profile Import API that updates matching profiles if they already exist in your account or creates profiles if no matching profiles are found. You can also optionally add these profiles to a list.

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, use 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).

Use the subscriptions object to fetch profiles by suppression data like reason or time of suppression.

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. Check out our Profiles API overview for more information.

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. Check out our Data Privacy API overview for more information.

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. Check out our Campaigns API overview for more information.

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 Group and provide your use case to learn from our team.

We also recommend experimenting with our new APIs using our Postman collection.