API versioning and deprecation policy

🚧

v1 / v2 legacy APIs are scheduled to be end-of-lifed on Jan 1, 2024.

Klaviyo’s APIs may evolve and change over time. While we do our best to notify developers of major changes in advance, we reserve the right to modify our APIs, cease to offer support for our APIs, or require you to use our APIs in a different manner at any time without notice. For more information, please refer to our API Terms of Use.

Versioning

Klaviyo’s APIs follow a versioning system that allows for clearer specification of precise API releases containing backwards-incompatible changes:

• All new APIs (/api and /client endpoints) do not contain version numbers in their path.
• Versions are now formatted as ISO 8601 dates and passed using the HTTP request header revision, e.g. revision: 2022-04-15

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:

1. 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
2. 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:

3. The 2022-11-01 revision will be end-of-life’d 1 year following the release of its replacement
4. 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
5. 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

Release phases

The following release phase criteria applies only to new API endpoints released after 10/19/2022.

*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

Beta Revisions