Comparison between v1/v2 and new APIs

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

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

General improvements

  • All endpoints now follow the JSON:API standard
  • All endpoints have been rigorously vetted to ensure adherence to consistent URL, request, and response syntactical standards
  • The URL topology has been reorganized to promote strong-typing, clear resource separation, and consistency with the Klaviyo UI (see comparison chart)
  • There is a new versioning and deprecation policy
  • There are now explicitly-documented rate limits for all endpoints with standard, informative HTTP headers for retry control-flow

What's coming next?

The following endpoints/functionality are currently in development for our new APIs:

All of the above functionality is still available via our v1-2 APIs, which can be found by selecting v1-2 from the dropdown in the upper left and navigating to the API Reference.

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 200 results per page
  • 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
    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
    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/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
    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
    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/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

    New endpoints without corresponding v1/v2 endpoints

    New endpointSupported features
    Catalogs (all endpoints)
    • See API reference for details
    Flows (all endpoints)
    • See API reference for details
    GET /api/templates/{id}/
    • Get a template with the given template ID
      Request specific fields using sparse fieldsets
    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 maximum of 20 profiles per page, 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