API versioning and deprecation policy

Read more about how Klaviyo handles API versioning and how legacy APIs are deprecated.

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:

  • Each primary API root contains a major path version; /api/
  • Minor revisions are passed as HTTP headers, formatted as ISO dates, to request a specific API release; 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. We recommend specifying the exact revision date you wish to use in your application.

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 the API changelog 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.

For example, if the revision date revision: 2022-04-20 is used, but no revision exists that is an exact match, Klaviyo will use the latest revision less than or equal to the desired revision, such as revision: 2022-04-15.

Klaviyo’s stable APIs, including our V1 and V2 APIs, are not versioned with revisions.

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
  • Adjustment to a rate limit

All breaking changes are tracked within the API Changelog (coming soon) 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 deprecated 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. 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:

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

Legacy APIs

The deprecation window for these endpoints will begin, at the earliest, after all new APIs have been released to General Availability (GA). Klaviyo will notify users when the deprecation window begins.

The legacy V1 endpoints will be deprecated for 6 months after new APIs are released to GA, then end-of-lifed.

The legacy V2 endpoints will be deprecated for 1 year after new APIs are released to GA, then end-of-lifed.


Did this page help you?