API versioning and deprecation policy
Read more about how Klaviyo handles API versioning and how legacy APIs are deprecated.
v1 / v2 legacy APIs are scheduled to be end-of-lifed on Jan 1, 2024.
Klaviyo’s APIs follow a versioning system that allows for clearer specification of precise API releases containing backwards-incompatible changes:
- All new APIs (
/clientendpoints) do not contain version numbers in their path.
- Versions are now formatted as ISO 8601 dates and passed using the HTTP request header
A new revision date will be created for every breaking change to the API. New revision dates are also created when new API endpoints are released. Be sure to specify the exact revision date you wish to use in your application.
View list of valid revision headers.
If a date is passed to the revision header that does not exactly match a known valid revision date, the user will receive the most recent revision date prior to their requested date. To stay up to date, we always recommend checking for the specific revision date to allow you to more easily reconcile the API version you use with the available revisions in Klaviyo’s changelog.
Klaviyo’s stable APIs, including our V1 and V2 APIs, are not versioned with revisions.
To view documentation associated with different revisions, select the drop down in the top left of the nav bar and select the relevant revision.
What is a breaking change?
Klaviyo defines a breaking change as any modification to or deletion of functionality within an API that may cause integrations or applications to function abnormally or break.
Examples of breaking changes include, but are not limited to:
- Renaming of a URL, request or response field, HTTP header or query parameter
- Removal of a request or response field, HTTP header or query parameter
- Downward adjustment to a rate limit
All breaking changes are tracked within the API Changelog and are clearly labeled as a breaking change. You can also be notified of breaking changes by joining our Developer Community Group. If you would like to receive monthly email notifications on the latest breaking changes, subscribe to our Developer Newsletter.
We recommend pinning your application to a specific revision date in order to avoid inheriting breaking changes as they are released. When you are ready to upgrade, review the release notes and changelog carefully to stay up-to-date on any breaking changes that might affect your app. Note that revisions are retired after 1 year when a new revision is released, and you will be required to upgrade.
Breaking changes due to security & site reliability concerns
Klaviyo reserves the right to introduce immediate breaking changes without notice when it is necessary to address platform security and site reliability vulnerabilities.
Beta APIs breaking changes
Beta APIs are subject to breaking changes during the beta testing period. During this period, older revisions that have replacement revisions will be retired without the benefit of our full 1-year deprecation window. Beta revisions that enter GA are deprecated up to 1 month after GA release.
When APIs are released to General Availability (GA), the 1-year deprecation window will apply to all future revisions to the GA endpoints, as stated in our breaking change policy.
For example, a beta API has the revision 2022-09-01.pre:
- When a new revision – 2022-10-01.pre – is released to the beta API, the prior revision – 2022-09-01.pre – is retired within weeks or months
- The prior revision’s end-of-life will be communicated to beta testers only
When the beta API is released into GA on 2022-11-01:
- The 2022-11-01 revision will be end-of-life’d 1 year following the release of its replacement
- When the next GA revision for this endpoint is released on 2023-03-01, the 2022-11-01 revision will be marked for deprecation on that date
- On 2024-03-01, Klaviyo officially retires the 2022-11-01 revision
What is not considered a breaking change?
Additions or modifications to APIs which do not have the potential to break applications, such as a new field or a new key in response bodies, are not considered breaking changes. Non-breaking changes will be reflected in the API Changelog (coming soon) and the Developer Newsletter. Sign up to receive updates here.
Deprecation & End-of-Life policy
An endpoint begins the deprecation process when a new endpoint, which replaces it or offers net new functionality, is released to general availability.
An endpoint is considered deprecated when:
- the endpoint is still available, but has been replaced with a new endpoint
- the endpoint is no longer supported and will not receive any further updates or bug fixes
- documentation is updated with the new endpoint or notifies users that the documented method is deprecated
When an API is deprecated, Klaviyo provides a minimum of one calendar year for developers to update their apps and integrations. After one year, the endpoint is end-of-lifed and access to it is removed.
An endpoint is considered end-of-lifed or retired when:
- the endpoint is unavailable; calling the endpoint results in a 404
- all documentation and reference materials about this endpoint/version are removed or redirected to new resources
The following release phase criteria applies only to new API endpoints released after 10/19/2022.
|Alpha||Beta||General Availability (GA) / Stable|
|Definition||Feature-flagged APIs that may be experimental and very unstable. Not intended for use in production.||Publicly-discoverable APIs accessible via beta API documentation. Not intended for use in production.||Stable APIs suitable for use in production. GA APIs adhere to the versioning & deprecation policy.|
|Timing||Varies by endpoint||1 - 2 months||Lasts for an endpoint until a replacement or breaking change is released, then moves to deprecation*|
|Documentation||No||Yes (labelled ||Yes|
*GA phase lasts indefinitely, unless an endpoint is replaced by a new endpoint or breaking change. A replaced endpoint enters the deprecation flow.
General Availability / Stable Revisions
|Revision||Deprecated?||Planned retirement date||Retired?|
|v1/v2 Legacy APIs||Yes||January 1st, 2024||No|
|Yes||~January 24th, 2024||No|
|Yes||~February 23rd, 2024||No|
|Revision||Deprecated?||Planned retirement date||Retired?|
|Yes||~December 14th, 2022||Yes|
|Yes||~January 15th, 2023||Yes|
|Yes||~February 25th, 2023||No|
|Yes||~March 23rd, 2023||No|
Updated 14 days ago