Changelog
Review new and breaking changes to Klaviyo's APIs.
Welcome to Klaviyo's API changelog! We frequently release exciting features to our APIs under new revisions to best support our developer community. Note that while we encourage you to update your API usage regularly, no immediate action is required with each release. Each revision is supported for 2 years after its release. Revisions with breaking changes have entries marked with Breaking changes. We recommend connecting your apps to our latest revision every 12-18 months.
Review our updated API versioning and deprecation policy for more information.
Revision 2024-06-15
(GA)
2024-06-15
(GA)Date revision is no longer supported: 2026-06-15
New endpoints
Segments API
- Create, retrieve, update, and/or delete segments including their segment definitions via our Segments API. For more information, see our Segments API overview.
Delete Flow API
- You can use the new Delete Flow endpoint to delete a flow with a provided flow ID. See the API reference documentation for more information.
Revision 2024-05-15
(GA)
2024-05-15
(GA)Date revision is no longer supported: 2026-05-15
New endpoints
Bulk Create Events API
- We have added support for creating events in bulk via the Bulk Create Events API.
- Create multiple events for new and existing profiles and/or update profile properties in a single API call. For more information, see our Events API overview.
Improved endpoints
Account API
- The Get Accounts and Get Account APIs have been updated to return the account's
locale
, e.g. "en-US".
Breaking changes
Subscribe API Synchronous Validation ImprovedTo provide better feedback for handling SMS subscriptions, we’ve added improved validation behavior to the Subscribe Profiles API. In prior revisions, such requests may appear as 202s but will fail to update SMS consent. To handle this issue, 400 validation errors are returned for the following cases:
- If a profile is subscribed to SMS marketing and age-gating is enabled but
age_gated_date_of_birth
is not provided, or the DOB does not meet the region's requirements.- If the account does not have a sending number in the phone number’s region.
- If the phone number is in a region not supported by Klaviyo.
- If
consented_at
is set and the list or global setting is double opt-in.
Revision 2024-05-15.pre
(Beta)
2024-05-15.pre
(Beta)Endpoints in beta are subject to change and should not be used in production. To learn more see our API versioning and deprecation policy. If you have feedback about these endpoints, please reach out in our developer community.
New Endpoints
Segments API
- Create, retrieve, and/or update segments via our Segments API. For more information, see our Segments API beta docs.
Webhooks API
- We have added support to create, retrieve, update, and delete webhooks via API. Check out the Webhooks API overview for more information.
Revision 2024-02-15
(GA)
2024-02-15
(GA)Date revision is no longer supported: 2026-02-15
From now on, we will only support documented revision headers.
A full list of documented revision headers is available in the dropdown at the top left of the developer portal.
Any revision request header that does not match one of our documented revisions will not be supported. If you receive a 404 error for an invalid revision, make sure to update your revision request header to one of our documented revisions.
New Endpoints
Reporting API for Campaign and Flow Performance Data
- Our new Reporting API allows you to request campaign and flow performance data that you can view in the Klaviyo UI.
- Request for campaign values data with Query Campaign Values, or request for flow values data with Query Flow Values. Query Flow Series allows you to fetch flow series data for a specific interval and timeframe, for example, a flow performance report on weekly click rates during the past 12 months.
Create or Update Profile API
- We have added support for creating and/or updating a profile depending on whether or not a profile exists via the Create or Update Profile endpoint. This endpoint operates synchronously and offers an upsert pattern similar to the v1/v2 Identify API.
Breaking changes
Get Event(s) APIWe have removed the
$attribution
field fromevent_properties
starting with this revision. To include this data in your request, add?include=attributions
to your request URL.
Update 2024-05-03
Webhooks API (Beta)
- OAuth app partners and CDP users can create, read, update, and delete webhooks via API (now available in beta). For more information, see our Webhooks API overview.
Update 2024-04-22
Private API keys are no longer viewable in Klaviyo
To protect your account from unauthorized access, we have removed the ability to view private API keys in Klaviyo. After creating a private API key, you should copy it to a secure location.
Update 2024-03-29
The
Unsubscribed
metric has been renamedThe
Unsubscribed
metric was renamed toClicked email to unsubscribe
. Note that this change may cause breakages in your app depending on whether or not your app relies on thename
field for metrics. We recommend using theUnsubscribed from email marketing
metric which emits for all instances in which a customer unsubscribes from email marketing.
Revision 2023-12-15
(GA)
2023-12-15
(GA)Date revision is no longer supported: 2025-12-15
New Endpoints
Bulk Profile Import API
- We have added support for creating and updating profiles in bulk via the Bulk Profile Import API to keep Klaviyo up-to-date with external systems of record.
- These new endpoints can help you speed up initial onboarding, update profile properties regularly, or add a batch of profiles to a list when you don't have the Klaviyo profile ID. See our guide on the Bulk Profile Import API for more information and use cases.
Improved Endpoints
Subscribe Profiles API
- The
list
relationship object on the Subscribe Profiles API is now optional. When alist
is not provided, the opt-in process uses the account's default opt-in settings. - We have added improved validation behavior to the Subscribe Profiles API.
Revision 2023-10-15
(GA)
2023-10-15
(GA)Date revision is no longer supported: 2025-10-15
Improved Endpoints
List Suppression Filtering
We now support filtering on list suppression with the Get Profiles endpoint, which brings us to parity with the v2 Get All Exclusions for a List endpoint.
Examples:
- Get all profiles that were suppressed for email marketing since 10/1/2023:
GET /api/profiles?filter=greater-than(subscriptions.email.marketing.suppression.timestamp,2023-10-01T01:00:00Z)
- Get all profiles that had a list suppression created for the given LIST_ID since 10/1/2023:
GET /api/profiles?filter=greater-than(subscriptions.email.marketing.list_suppressions.timestamp,2023-10-01T01:00:00Z),equals(subscriptions.email.marketing.list_suppressions.list_id,”LIST_ID”)
- Get all profiles that were suppressed with a "user_suppressed" reason since 10/1/2023:
GET /api/profiles?filter=greater-than(subscriptions.email.marketing.suppression.timestamp,2023-10-01T01:00:00Z),equals(subscriptions.email.marketing.suppression.reason,"user_suppressed")
Optionally Retrieve Subscription Status on Get List Profiles, Get Segment Profiles, Get Event Profile
Now you can retrieve subscription status on any endpoint that returns profiles, including Get List Profiles, Get Segment Profiles and Get Event Profile. Use ?additional-fields[profile]=subscriptions
on these endpoints to include subscription information.
Breaking changes
Profile Subscription Request Structure ChangedThe request structure to subscribe a profile to a list has changed:
"subscriptions": { "email": [ "MARKETING" ], "sms": [ "MARKETING" ] }
"subscriptions": { "email": { "marketing": { "consent": "SUBSCRIBED" } }, "sms": { "marketing": { "consent": "SUBSCRIBED" } }
Profile Subscription Response Fields RenamedIn the interest of providing more clarity and information on the subscription object, we have renamed and added several fields. This will provide more context on a contact’s subscriptions and consent, as well as boolean fields to simply see who you can or cannot message.
For SMS marketing:
timestamp
is nowconsent_timestamp
.last_updated
is a new field that mirrorsconsent_timestamp
.can_receive_sms_marketing
is a new field that shows whether a profile can receive SMS marketing.For email marketing:
timestamp
is nowconsent_timestamp.
can_receive_email_marketing
is a new field that shows whether a profile can receive SMS marketing.suppressions
is nowsuppression.
last_updated
is a new field that is the most recent of all the dates on the object.
Subscription Object Not Returned by Default on Get Profile / Get ProfilesThe subscription object is now optional for the Get Profile and Get Profiles endpoints. It will not be returned by default, but can be included in the request by adding
?additional-fields[profile]=subscriptions
to the request. This change will allow for a more performant experience when making requests to Get Profiles without including the subscriptions object. Check out our consent guide for information on oursubscriptions
object, filtering rules, and more.
Revision 2023-09-15
(GA)
2023-09-15
(GA)Date revision is no longer supported: 2025-09-15
New Endpoints
Coupons APIs
We have added support for creating coupons and coupon codes for use in messaging via our APIs. Check out the Coupons API guide for more information.
View the coupons and coupon codes in your account with Get Coupons and Get Coupon Codes. Create coupons and coupon codes with Create Coupon and Create Coupon Code. You can also create bulk jobs for coupon codes using our bulk endpoints.
Images APIs
Upload new images to your account from an image file with Upload Image from File or from a remote URL or data URI with Upload Image from URL.
Retrieve one or more images from your account using Get Image and Get Images endpoints. You can also update an existing image’s name, or update the hidden status of an image with Update Image.
Merge Profile API
You can now merge an existing profile with another given profile with Merge Profiles. Pass the profile you wish to merge via the relationships object (the "source" profile) to a profile with the given profile ID as the base data object (the "destination" profile).
Improved Endpoints
List and Segment Membership Sorting and Filtering
Get List Profiles, Get Segment Profiles, Get List Relationships Profiles, Get Segment Relationships Profiles now include a joined_group_at
field in the payload that can be used for sorting and filtering by a profile’s most recent join date. For example, you can get the profiles that have joined a list after 2023-09-14T00:00Z with GET /api/lists/LIST_ID/profiles?sort=joined_group_at&filter=greater-than(joined_group_at,2023-09-14T00:00Z)
.
Raised Maximum Page Size for List and Segment Relationships Profile Endpoints
Get List Relationships Profiles and Get Segment Relationships Profiles now support a page size of 1,000 profiles, e.g. GET /api/lists/1/relationships/profiles?page[size]=1000
.
To access the new Images and Coupons APIs, you'll need to generate a new private API key
The Images and Coupons APIs require new private API key scopes, so you will need to generate a new private API key that includes these scopes in order to use them. Note that you will need to generate a new private API key even for previously created Full Access scoped keys if the scopes were not available when you generated that key.
Revision 2023-08-15
(GA)
2023-08-15
(GA)Date revision is no longer supported: 2025-08-15
New Endpoints
Flow Message Templates
- You can now retrieve the templates associated with flow messages using Get Flow Message Template or Get Flow Message Relationships Template. You’re also able to include the template HTML for a flow message using
GET /api/flow-messages/FLOW_MESSAGE_ID?include=template
.
Create or Update Push Tokens
- We have added an endpoint to create push tokens, Create or Update Push Token. This endpoint can be used to migrate profiles and their push tokens from another platform to Klaviyo. If you’re looking to register push tokens from users’ devices, please use our mobile SDKs.
Revision 2023-08-15.pre
(Beta)
2023-08-15.pre
(Beta)Endpoints in beta are subject to change and should not be used in production. To learn more see our API versioning and deprecation policy.
If you have feedback about these endpoints, please reach out in our developer community or fill out this form to provide feedback.
New Endpoints
Coupon APIs
- We have added support for creating coupons and coupon codes for use in messaging via our APIs. Check out the Coupons API guide for more information.
Revision 2023-07-15
(GA)
2023-07-15
(GA)Date revision is no longer supported: 2025-07-15
New endpoints
Back in stock APIs
- We have added support for subscribing to back in stock in our latest API revision. Not only can you subscribe profiles to back in stock notifications for email, but also you can subscribe profiles to back in stock for SMS. To learn more, check out our guide to setting up back in stock.
Campaign APIs: SMS support + relationships support
- Get Campaigns and Create Campaign: CRUD support for SMS campaigns is now available. You can also now retrieve all messages for a campaign to easily view performance data on campaigns where you’re running A/B tests. To support this functionality, we introduced a relationship between campaigns and campaign messages, and campaign messages and templates.
Bulk Create Client Events API
- Bulk Create Client Events: It is now easier and more performant to track activity for a profile from client-side contexts, such as the browser. Send events in a batch for a single profile, saving data and battery for your end-users’ devices.
Push Token Registration APIs
- Create or Update Client Push Token and Unregister Client Push Token: Register and unregister push tokens. If you have a native iOS or Android app, we highly recommend that you use our mobile SDKs directly (Swift SDK, Android SDK).
Improved Endpoints
- Update Profile now supports appending, unappending, and unsetting profile properties in the
meta.patch_properties
section of the request payload usingappend
unappend
andunset
keys.
Breaking changes
Relationship standardizationWe are making a number of changes across endpoints to standardize how we handle relationships in our APIs and ensure consistently typed objects across endpoints.
For example, now you can create a profile in our APIs in the same shape, whether you’re calling the profiles endpoint or the events endpoint to do so.
This update makes a number of breaking changes to endpoints including but not limited to:
- Create Client Event and Create Event
- Get Events and Get Event
- Create Client Subscription and Subscribe Profiles
- Request Profile Deletion
- Unsubscribe Profiles
For more information about how to handle relationships with this revision and a comprehensive list of endpoints that need to be upgraded due to breaking changes, check out our relationships migration guide.
Relationship standardization changes include:
Updating 1:1 relationships to use singular tense and an object (instead of plural and an array)
- Example:
GET https://a.klaviyo.com/api/flow-actions/1/?include=flows
(now "flow")Moving related object IDs from the attributes payload to relationships
- Example:
POST https://a.klaviyo.com/api/tags/
Specifying a relationship between two Klaviyo objects to allow for improved consistency and greater interoperability across endpoints
- Example:
POST https://a.klaviyo.com/api/events/
. You can now create/update a profile for an event in the same way you would when using the Profiles API directly.These changes improve the connectivity and consistency across our API surface and make it much easier to accomplish tasks that involve relationships across resources. Previous to this revision, getting the template content for a campaign required 3 API calls. After this release, you can do it in just one:
GET /api/campaigns/:id/campaign-messages/?include=template
.
Removedcompany_id
from Get Template(s)We removed the
company_id
from the response for Get Template and Get Templates. If you need to obtain the company ID / public API key for an account, please use the Accounts API.
Update 2023-07-20
- Added
reply_to_email
,cc_email
, andbcc_email
field options in the following places:- The Create Campaign endpoint
- The Update Campaign Message endpoint
- Any campaign message response
Revision 2023-06-15
(GA)
2023-06-15
(GA)Date revision is no longer supported: 2025-06-15
New endpoints
Accounts: Use our new Accounts API endpoints to retrieve account-specific data (contact information, timezone, currency, Public API key, etc.) or test if a private API key belongs to the correct account prior to performing subsequent actions with the API.
Get List and Segment member count
- Get List and Get Segment now support returning the count of members in the response by including
?additional-fields[segment]=profile_count
or?additional-fields[list]=profile_count
in the request parameters.
Rate limit increases
- Get List Profiles, Get Segment Profiles, and Get Profiles were increased to the L rate limit tier.
Framework Improvements
- Implemented Query Param Rate Limits
To access the new accounts scope, you’ll need to generate a new Private API Key
Get Account and Get Accounts require a new private API key scope (Account Read), so you will need to generate a new private API key that includes the scope in order to use the endpoint. You will need to generate a new private API key even for previously created Full Access scoped keys if the scope was not available when you generated that key.
Revision 2023-02-22
(GA)
2023-02-22
(GA)New endpoints
- Campaigns: Use our new Campaigns API endpoints to programmatically create, update, delete, and send email campaigns. See the API reference documentation for more info. We plan to introduce SMS support in the future.
Breaking changes
- Updated Flows endpoints to use cursor-based pagination. This change brings flows pagination to parity with our other API endpoints. You can learn more about cursor-based pagination in our API Overview.
- Profile fields can now be nulled out by passing
null
into a profile field via the Update Profile endpoint.
Update 2023-06-06
- The steady rate limit for Create Client Subscription has increased to
700/m
.
Update 2023-05-30
- Get Profiles now support filtering by a
datetime
range. You can filter adatetime
range by using thegreater-than
andless-than
filters in combination, similar to this example:https://a.klaviyo.com/api/profiles/?filter=less-than(updated,2023-04-26T00:00:00Z),greater-than(updated,2023-04-19T00:00:00Z)
.
Update 2023-04-06
- The Get Profile and Get Profiles endpoints now allow you to request predictive analytics such as customer lifetime value (CLV), along with other profile information. You can request these new fields by appending
?additional-fields[profile]=predictive_analytics
to the request URL. - Each
relationship
endpoint has been split to make a specific endpoint URL for each unique related resource field. Note, this is only a documentation change. For example, theGet Profile Relationships
endpoint is now split into Get Profile Relationships Lists and Get Profile Relationships Segments endpoints in the documentation. The URLs for these endpoints remain unchanged.
Update 2023-03-28
- You can now
filter
events using theprofile_id
field in Get Events. This allows you to retrieve all the events for a given profile for all metrics or retrieve events for a specific metric if paired with themetric_id
filter.
Update 2023-03-07
- The Get Profile and Get Profiles endpoints now include each profile’s email and SMS subscription information, including:
- Their current consent status.
- When and how they subscribed or unsubscribed.
- Their global and list-specific suppressions (email only).
- You can now
filter
andsort
profiles using theupdated
field in Get Profiles.
Revision 2023-01-24
(GA)
2023-01-24
(GA)New endpoints
- Tags: Use our new Tags API endpoints to create, read, update, and delete tags on various Klaviyo objects such as campaigns, flows, lists and segments. See the API reference documentation for more info.
- Data Privacy - Request Profile Deletion: Use our new Data Privacy - Request Profile Deletion API endpoint to delete profiles with a provided identifier (i.e.
profile_id
,email
,phone_number
). See the API reference documentation for more info.
Breaking changes
- Changed url path for Create Template Render from
https://a.klaviyo.com/api/templates/{id}/render/
tohttps://a.klaviyo.com/api/template-render/
- Changed url path for Create Template Clone from
https://a.klaviyo.com/api/templates/{id}/clone/
tohttps://a.klaviyo.com/api/template-clone/
Update 2024-01-24
This revision is deprecated.
You should plan to update your apps to our latest stable revision, before the revision is retired on January 24, 2025 to avoid breakages in your app. See our updated API versioning and deprecation policy for more information.
Update 2023-02-14
- The
price
field can now be optionally supplied in the payload for Create Catalog Item and Update Catalog Item endpoints. This field can be used to set the price on the catalog item.
Update 2023-02-07
-
A
channels
object can now be optionally supplied in the payload for the Subscribe Profiles endpoint. Whenchannels
is provided, only the specified channels and message types will be subscribed. Ifchannels
is not provided, we will subscribe all channels for which identifiers (i.e.phone_number
oremail
) are provided. -
The
profile_id
field can now be optionally supplied in the payload for the Subscribe Profiles endpoint. This will be the id of the profile to subscribe.
Revision 2022-10-17
(GA)
2022-10-17
(GA)- Welcome to our new API changelog! This log will be kept up-to-date on the latest changes, bug fixes, and breaking changes to Klaviyo's APIs. Please note that this changelog only includes changes to new APIs released after 10/19/2022.
- For further information about revisions and breaking changes, please review the API versioning & deprecation policy.
- Kickstart your migration to Klaviyo's new APIs with the API comparison chart, a detailed overview of what's changed from the v1/v2 endpoints to the new endpoints.
Update 2024-01-24
This revision is deprecated.
You should plan to update your apps to our latest stable revision, before the revision is retired on October 17, 2024 to avoid breakages in your app. See our updated API versioning and deprecation policy for more information.
Update 2023-01-20
- The
list_id
attribute for the Unsubscribe Profiles endpoint is now an optional attribute instead of a required.
Update 2023-01-11
- The Create Profile and Update Profile endpoints now accept a phone number as an identifier even if SMS is not set up in the associated Klaviyo account. A successful call requires one other profile identifier attribute (
email
,external_id
, oranonymous_id
), in addition to a phone number.
Update 2022-12-19
- The reference documentation and OpenAPI Spec (OAS) for the Create Template Render and Create Template Clone endpoints have been updated to reflect the correct required fields. This update resolves a minor bug in our documentation where a required field needed to call the endpoints successfully was missing. No changes have been made to these endpoints.
Update 2022-11-02
Breaking change
- Removed the
updated
filter parameter from the Get Profiles endpoint. This filter parameter was not intended for GA release and is not officially supported.- This change takes effect immediately due to site reliability concerns. Please refer to the breaking change policy for more information.
Updated about 2 months ago