HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us

Comparison chart: v1/v2 to new endpoints

Learn about the differences between our v1/v2 APIs and our new APIs.

📘

We've updated our API versioning and deprecation policy

Review our updated API versioning and deprecation policy to learn about our date-versioned APIs, non-breaking and breaking changes, our API lifecycle, and more to effectively manage your API usage.

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

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 endpointSupported featuresNew endpointSupported 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
    /api/identify
    • Track and update properties about an individual without tracking an associated event
    POST
    /api/profile-import/{id}/
    • Given a set of profile attributes and optionally an ID, create or update a profile
    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
    GET
    /api/v2/list/{list_id}/
    exclusions/all
    • Gets all of the emails and phone numbers that have been excluded from a list along with the exclusion reasons and exclusion time.
    GET
    /api/profiles
    ?additional-fields
    [profile]=
    subscriptions&filter=
    equals(subscriptions.
    email.marketing.
    list_suppressions.
    list_id,"LIST_ID")
    • Get all profiles that have been excluded from a list.
    • Filter profiles by suppression fields.
    GET
    /api/v2/people/search
    • Get a profile's Klaviyo ID given exactly one corresponding identifier, e.g., email
    GET
    /api/profiles
    ?filter=equals
    (email,"EMAIL")
    • Get all profiles in an account
    • Sort profiles by id, created, updated, email
    • Filter profiles by email, phone_number, etc.
    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-subscription-
    bulk-delete-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/profile-bulk-import-jobs/
    • Add profiles 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
    DELETE
    /api/lists/{id}
    /relationships/
    {related_resource}/
    • 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/template-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/template-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
    • Creates 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 endpoint filters (GET /api/campaigns).
    GET
    /api/v1/campaign/
    {campaign_id}
    GET
    /api/v1/email-templates/
    • Gets a campaign's info including its template id.
    • Returns a list of all email templates which can be searched by template id.
    GET
    /api/campaigns/{id}/
    campaign-messages/
    ?include=template
    • Returns the messages for a given
      campaign including each
      message's template details.

    New endpoints without corresponding v1/v2 endpoints

    New endpointSupported features
    Catalogs (all endpoints)
    • See API reference for details
    Coupons (all endpoints)
    • See API reference for details
    Flows (all endpoints)
    • See API reference for details
    Images (all endpoints)
    • See API reference for details
    Reporting (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-suppression-bulk-delete-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}/profile/
    • Get the profile 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.
    POST /api/push-tokens/
    • Creates or updates a push token.