There are now explicitly-documented rate limits for all endpoints with standard, informative HTTP headers for retry control-flow
Comparison chart: v1/v2 and corresponding new API endpoints
This table covers improved functionality for endpoints in Klaviyo’s new APIs that have corresponding endpoints in our v1/v2 APIs. New endpoints that have no corresponding older version are listed in a separate table below. Note that some v1/v2 endpoints correspond to multiple new endpoints for different uses.
v1/v2 endpoint
Supported features
New endpoint
Supported features
GET
/api/v1/metrics
Get all metrics in an account
Returns 50 to 100 results per page
Returns a page based on a specified integer
GET
/api/metrics
Get all metrics in an account
Request specific fields with sparse fieldsets
Filter requests by specific fields, including integration.category and integration.name
Returns a maximum of 200 events per page, which can be paginated with cursor-based pagination
GET
/api/v1/metrics/timeline
Returns a batched timeline of all events in your account
Number of events to return in a batch: default = 50, max = 100
Sort order for timeline either descending or ascending
GET
/api/events
Get all events in an account
Requests can be sorted by the following fields: datetime, timestamp
Use filters to narrow your results to specific metrics
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: metrics, profiles
Returns a maximum of 200 events per page, which can be paginated with cursor-based pagination
GET
api/v1/metric/{metric_id}/
timeline
Returns a batched timeline for one specific metric
Number of events to return in a batch, max = 100
Sort order for timeline either descending or ascending
GET
/api/events?filter=equals
(metric_id,”{metric_id}”)
Get all events for a single metric
Requests can be sorted by the following fields: datetime, timestamp
Use filters to narrow your results to specific metrics
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: metrics, profiles
Returns a maximum of 200 events per page, which can be paginated with cursor-based pagination
GET
/api/v1/metric/{metric_id}/
export
Exports event data from Klaviyo, optionally filtering and segmenting on available event properties.
Note that the only comparison operator currently supported is =
POST
/api/metric-aggregates
Query and aggregate event data associated with a metric, including native Klaviyo metrics, integration-specific metrics, and custom events
Query passed in JSON request body
Major bug fix for long-standing issue with dimensions with greater than 1000 values
Results can be filtered and grouped by time, event, or profile dimensions
Request specific fields using sparse fieldsets
Simplified filter syntax consistent with other endpoints
POST
/api/track
Create a new event to track a profile’s activity
Can accept payloads up to approximately 1 MB
POST
/client/events
Create a new event to track a profile’s activity, designed to be called from publicly-browseable, client-side environments only
To create events from server-based applications, please use POST /api/events
Accepts plain application/json, rather than application/x-www-form-urlencoded payloads, like the old endpoints
POST
/api/track
Create a new event to track a profile’s activity
Can accept payloads up to approximately 1 MB
POST
/api/events
Create a new event, designed to be called from a server-based application
To create events called from a publicly-browsable, client-side environment, please use POST /client/events
POST
/api/identify
Track and update properties about an individual without tracking an associated event
POST
/client/profiles
Create and update properties about a profile without tracking an associated event, designed to be called from publicly-browseable, client-side environments
To create profiles from server-based applications, please use POST /api/profiles
Accepts plain application/json, rather than application/x-www-form-urlencoded payloads, like the old endpoints
POST
/api/identify
Track and update properties about an individual without tracking an associated event
POST
/api/profiles
Create and update profiles, designed to be called from a server-based application
To create profiles called from publicly-browseable, client-side environments, use POST /client/profiles
POST
/api/identify
Track and update properties about an individual without tracking an associated event
PATCH
/api/profiles/{id}/
Update a profile with the given profile ID
Profile fields can be nulled out by passing null into the associated profile field
POST
/ajax/subscriptions
This endpoint was never publicly documented
POST
/client/subscriptions
Create a new subscription for the given list ID and channel: Email isemail, SMS is phone_number
Designed to be called from publicly-browseable, client-side environments
To create subscriptions from server-based applications, use POST /api/profile-subscription-bulk-create-jobs
POST
/ajax/subscriptions
This endpoint was never publicly documented
POST
/api/profile-subscription-
bulk-create-jobs
Subscribe one or more profiles to email marketing, SMS marketing, or both
Designed to be called from server-based applications
To create subscriptions from publicly-browseable, client-side environments, use POST /client/subscriptions
POST
/api/v1/people/exclusions
Marks a person as excluded from all email
This works the same way as manually excluding someone via the excluded people page
Someone who is excluded will no longer receive any campaigns or flow emails
POST
/api/profile-suppression-
bulk-create-jobs/
Suppress one or more profiles
This works the same way as manually excluding someone via the excluded people page
Suppressed profiles will not receive email marketing
Not supported for SMS marketing
POST
/api/v2/people/exchange
Klaviyo's web tracking uses an encrypted identifier. However, there are many use cases that require developers to have access to a given profile's email or phone number
In such cases, developers can use this operation to exchange an encrypted identifier for a profile ID, which they can then use to retrieve the full profile data (by making a subsequent request to the get-profiles operation)
GET
/api/profiles?filter=equals
(_kx,"{kx_token}")
Get all profiles in an account
Profiles can be sorted by the following fields in ascending and descending order: id, created, email
Use filters to narrow your results
Request specific fields using sparse fieldsets
Use filtering by the Klaviyo _kx identifier
PUT
/api/v1/person/{person_id}
Add or update one or more attributes for a Person, based on the Klaviyo Person ID. If a property already exists, it will be updated. If a property is not set for that record, it will be created
For creating or updating a profile in v1/v2, you should be using the Identify API instead
The best use case for this endpoint is changing a profile's email address or other primary identifier after a profile already exists in Klaviyo
POST
/api/profiles/
Create and update profiles, designed to be called from a server-based application
To create profiles called from publicly-browseable, client-side environments, use POST /client/profiles
PUT
/api/v1/person/{person_id}
Add or update one or more attributes for a Person, based on the Klaviyo Person ID. If a property already exists, it will be updated. If a property is not set for that record, it will be created
For creating or updating a profile in v1/v2, you should be using the Identify API instead
The best use case for this endpoint is changing a profile's email address or other primary identifier after a profile already exists in Klaviyo
PATCH
/api/profiles/{id}/
Update a profile with the given profile ID
Profile fields can be nulled out by passing null into the associated profile field
GET /api/v1/person/{person_id}
Retrieves all the data attributes for a person, based on the Klaviyo Person ID
GET
/api/profiles/{id}/
Get a profile with the given profile ID
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: lists, memberships, segments memberships
GET /api/v1/person/{person_id}/
metric/{metric_id}/timeline
Returns a person's batched timeline for one specific event type.
GET
/api/events?filter=
equals(profile_id,PROFILE_ID),
equals(metric_id,METRIC_ID)
Filter events using profile_id and metric_id to retrieve events for a specific metric for a given profile.
GET
/api/v1/person/{person_id}/
metrics/timeline
Returns a batched timeline of all events for a person.
GET
/api/events?filter=
equals(profile_id,PROFILE_ID)
Filter events using profile_id to retrieve all the events for a given profile for all metrics.
GET
/api/v2/group/
{list_or_segment_id}/
members/all
Gets all of the emails, phone numbers, and push tokens for profiles in a given list or segment
GET
/api/lists/{list_id}/profiles/
Get all profiles within a list with the given list ID
Retrieves full profile information for each list member (not just emails, phone numbers, and push tokens)
Use filters to narrow your results
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET
/api/v2/group/
{list_or_segment_id}/
members/all
Gets all of the emails, phone numbers, and push tokens for profiles in a given list or segment
GET
/api/segments/
{segment_id}/profiles/
Get all profiles within a segment with the given segment ID
Retrieves full profile information for each segment member (not just emails, phone numbers, and push tokens)
Filter to request a subset of all profiles. Profiles can be filtered by email, phone_number, and push_token fields
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
POST
/api/v2/list/{list_id}/
subscribe
Subscribe profiles to a list
Profiles will be single or double opted into the specified list in accordance with that list’s settings. Note: If you have double opt-in enabled (default behavior), users will not be added to the list until they opt in, and so the API will respond with an empty list
POST
/api/profile-subscription-
bulk-create-jobs/
Subscribe one or more profiles to email marketing, SMS marketing, or both
Profiles will be single or double opted into the specified list in accordance with that list’s settings. Note: If you have double opt-in enabled (default behavior), users will not be added to the list until they opt in, and so the API will respond with an empty list
DELETE
/api/v2/list/{list_id}/
subscribe
Unsubscribe and remove profiles from a list
POST
/api/profile-unsubscription-bulk-
create-jobs/
Unsubscribe one or more profiles from email marketing, SMS marketing, or both
POST
/api/v2/lists
Create a new list
POST
/api/lists/
Create a new list
GET
/api/v2/lists
Return a listing of all the lists in an account
GET
/api/lists/
Get all lists in an account
Use filters to narrow your results
Request specific fields using sparse fieldsets
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET
/api/v2/list/{list_id}
Return information about a list
GET
/api/lists/{id}/
Get a list with the given list ID
PUT
/api/v2/list/{list_id}
Update a list's name
PATCH
/api/lists/{id}/
Update the name of a list with the given list ID
POST
/api/v2/list/{list_id}/
members
Add profiles to a list with the given list ID
POST
/api/lists/{id}/relationships/
{related_resource}/
Add a profile to a list with the given list ID
DELETE
/api/v2/list/{list_id}/
members
Remove profiles from a list with the given list ID
Remove a profile from a list with the given list ID
DELETE
/api/v2/list/{list_id}
Delete a list with the given list ID
This is a destructive operation and cannot be undone
It will also remove flow triggers associated with the list
DELETE
/api/lists/{id}/
Delete a list with the given list ID
GET
/api/v1/email-templates
Return a list of all the email templates you've created
The templates are returned in sorted order by name
GET
/api/templates
Get all templates in an account
Filter to request a subset of all templates. Templates can be sorted by the following fields, in ascending and descending order: id, name, created, updated
Request specific fields using sparse fieldsets
Returns a maximum of 20 results per page. Results can be paginated with cursor-based pagination
POST
/api/v1/email-templates
Create a new custom HTML email template
POST
/api/templates
Create a new custom HTML email template
Request specific fields using sparse fieldsets
PUT
/api/v1/email-
template/{template_id}
Update a template with the given template ID
Only updates imported HTML templates; does not update drag and drop templates
PATCH
/api/templates/{id}/
Update a template with the given template ID
Request specific fields using sparse fieldsets
Only updates imported HTML templates; does not update drag and drop templates
DELETE
/api/v1/email-template/
{template_id}
Delete a template with the given template ID
DELETE
/api/templates/{id}/
Deletes a template with the given template ID
POST
/api/v1/email-template/
{template_id}/clone
Create a clone of a template with the given template ID
POST
/api/templates/{id}/clone/
Create a clone of a template with the given template ID
Request specific fields using sparse fieldsets
POST
/api/v1/email-template/
{template_id}/render
Render the specified template with the provided data and return HTML and text versions of the email
This endpoint does not yet support our new template editor
POST
/api/templates/{id}/render/
Render a template with the given template ID and context attribute
Returns the HTML and plain text versions of the email template
Request specific fields using sparse fieldsets
POST
/api/v2/data-privacy/deletion-request
Request a deletion for the profiles corresponding to an email address, phone number, or person identifier (profile ID)
Note that only one identifier (email, phone_number, or person_id) can be specified
POST
/api/data-privacy-deletion-jobs/
Request a deletion for the profiles corresponding to one of the following identifiers: email, phone_number, or profile_id. If multiple identifiers are provided, we will return an error
GET
/api/v1/campaigns
Get all campaigns in an account
Returns 0 to 100 results per page
Offset pagination
Results are sorted by descending created_at timestamp
GET
/api/campaigns/
Get all campaigns in an account.
Cursor-based pagination.
Ability to specify sort order.
Ability to filter by various attributes.
POST
/api/v1/campaigns
Create a new campaign in draft mode.
POST
/api/campaigns/
Creates a new campaign in draft mode.
More granular send and tracking options.
GET
/api/v1/campaign/
{campaign_id}
Get details for a specific campaign.
GET
/api/campaigns/{id}/
Get details for a specific campaign.
PUT
/api/v1/campaign/
{campaign_id}
Update details of a campaign.
You can update a campaign's name, subject, from email address, from name, template or list.
PATCH
/api/campaigns/{id}/
Update details of a campaign.
Ability to configure more granular send and tracking options.
POST
/api/v1/campaign/
{campaign_id}/send
Queues a campaign for immediate delivery.
POST
/api/campaign-send-
jobs/
Trigger a campaign to send asynchronously.
POST
/api/v1/campaign/
{campaign_id}/schedule
Schedules a campaign for a time in the future.
POST
/api/campaigns/
Creates a campaign given a set of parameters, then returns it.
POST
/api/v1/campaign/
{campaign_id}/cancel
Cancels a campaign send.
Marks a campaign as canceled.
PATCH
/api/campaign-send-
jobs/{id}/
Permanently cancel the campaign, setting the status to CANCELED or revert the campaign, setting the status back to DRAFT.
POST
/api/v1/campaign/
{campaign_id}/clone
Create a copy of a campaign.
The new campaign starts as a draft.
POST
/api/campaign-clone/
Clones an existing campaign, returning a new campaign based on the original with a new ID and name.
GET
/api/v1/campaign/
{campaign_id}/recipients
Returns summary information about email recipients for the campaign specified that includes each recipient’s email, customer ID, and status.
GET
/api/campaigns/
GET /api/segments/
{segment_id}/profiles/
GET
/api/lists/{list_id}/profiles/
Returns some or all campaigns based on /v2 endpoi filters (GET /api/campaigns).
New endpoints without corresponding v1/v2 endpoints
New endpoint
Supported features
Catalogs (all endpoints)
See API reference for details
Flows (all endpoints)
See API reference for details
Tags (all endpoints)
See API reference for details
GET /api/segments
Get all segments in an account
Filter to request a subset of all segments
Segments can be filtered by name, created, and updated fields
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET /api/segments/{id}/
Get a segment with the given segment ID
PATCH /api/segments/{id}/
Update the name of a segment with the given segment ID
GET /api/segments/{id}/relationships/{related_resource}/
Get all profile membership relationships for the given segment ID
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET /api/lists/{id}/relationships/{related_resource}/
Get profile membership relationships for a list with the given list ID
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET /api/profiles/{id}/relationships/{related_resource}/
Get list membership or segment membership relationships for a profile with the given profile ID
GET /api/profiles/
Get all profiles in an account
Profiles can be sorted by the following fields, in ascending and descending order: id, created, email
Use filters to narrow your results. Request specific fields using sparse fieldsets
Returns a minimum of 20 and a maximum of 100 profiles per page using the page[size] query parameter, which can be paginated with cursor-based pagination
GET /api/profiles/{profile_id}/lists/
Get list memberships for a profile with the given profile ID
GET /api/profiles/{profile_id}/segments/
Get segment memberships for a profile with the given profile ID
POST /api/profile-unsuppression-bulk-create-jobs/
Unsuppress one or more profiles
Only manually suppressed profiles will be unsuppressed and able to receive email marketing
Not supported for SMS marketing
GET api/metrics/{id}/
Get a metric with the given metric ID
Request specific fields using sparse fieldsets
GET /api/events/{id}/
Get an event with the given event ID
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: metrics, profiles
GET /api/events/{id}/metrics/
Get the metric for an event with the given event ID
Request specific fields using sparse fieldsets
GET /api/events/{id}/profiles/
Get all profiles associated with an event with the given event ID
GET /api/events/{id}/relationships/{related_resource}/
Get metrics or profile relationships for an event with the given event ID
GET /api/templates/{id}/
Get a template with the given template ID
Request specific fields using sparse fieldsets
DELETE /api/campaigns/{id}/
Delete a campaign with the given campaign ID.
GET /api/campaign-messages/{id}/
Returns a specific message based on a required id.
PATCH /api/campaign-messages/{id}/
Update a campaign message.
GET /campaigns/{campaign_id}/tags/
Return all tags that belong to the given campaign.
GET /api/campaign-send-jobs/{id}/
Get a campaign send job.
GET /api/campaign-recipient-estimation-jobs/{id}/
Retrieve the status of a recipient estimation job triggered with the Create Campaign Recipient Estimation Job endpoint.
GET /api/campaign-recipient-estimations/{id}/
Get the estimated recipient count for a campaign with the provided campaign ID. You can refresh this count by using the Create Campaign Recipient Estimation Job endpoint.
POST /api/campaign-message-assign-template/
Creates a non-reusable version of the template and assigns it to the message.
POST /api/campaign-recipient-estimation-jobs/
Trigger an asynchronous job to update the estimated number of recipients for the given campaign ID. Use the Get Campaign Recipient Estimation Job endpoint to retrieve the status of this estimation job. Use the Get Campaign Recipient Estimation endpoint to retrieve the estimated recipient count for a given campaign.
GET /api/campaigns/{id}/relationships/{related_resource}/
If the related_resource is tags, returns the IDs of all tags associated with the given campaign.
