Out With Old, In With The New Klaviyo API

It's always exciting when one of your favorite platforms releases a new API (well, for us API nerds it's exciting). Plus, we get to enjoy that new API smell 😉

Klaviyo Developers just released a new API featuring new endpoints and changes to headers, rate limits and more. Our API development team is ready to see what this new system has in place so let's check it out together.

The API Has Gone To Its Head(ers)

The most obvious change is the new dependencies in the request headers. The API version and authentication key are now passed in the headers so you have to update your code if you were using the previous configuration. In the "old" API, the version was passed in the URL and the authentication uses a different key-name for the auth. Depending on how you developed your integration, this shouldn't be too major of a change, assuming you have proper abstraction in place for URLs and headers. Here's what you need to change:

Versioning

In the older API, we would add "v1" or "v2" to the URL to select the desired version. For example, to get the current Lists using the v2 API, we would format our URL like this:

https://a.klaviyo.com/api/v2/lists

Notice that the "v2" is part of the request URL. This is no longer the case. Klaviyo has switched to passing the version via the HTTP header. You no longer add the version within the URL. The API version is sent with a "revision" parameter in the header of the request. Klaviyo has also switched to a date-based ISO 8601 convention. The request header will use this parameter specifically for passing the API version. To better illiustrate this change, let's look at a standard CURL request to demonstrate how this works. So now if we want to call the Lists endpoint, this is how we configure the header:

In the above example, we're using the "2022-10-17" version of the Klaviyo API. We love this change as our development team can quickly see if a project is using an old version by simply looking at the date. This aligns with the common convention used by most enterprise companies. Tracking your API version is much easier to follow.

Authentication

The next change comes to the authentication process. In order to use the Klaviyo API, you must generate a private key to authenticate your requests (check our previous Klaviyo API blog for instructions on how to get your private key.) You have to pass this private key within the header of your request. In the new API, the auth key has changed from "api_key" to "Klaviyo-API-Key". This is what your request header should like with the new authorization key value:

This is a subtle change but an important one as your current implementation will have to adapt to this new key-value. Since authentication is required for all API calls, this should be one of te first things to check. Your existing private key will still work so you don't have to spin-up a new one. So, now that you have the API version and authentication set, let's review the other changes

API Comes, API Goes

Part of any good API versioning strategy is to deprecate older versions. This is critical for keeping the features and functionality up-to-date. When an API is deprecated, Klaviyo provides a minimum of one calendar year for developers to fix their integrations. After one year, the endpoint is removed so staying on top of versions is important to ensure apps don't break. Since Klaviyo has a consistent cycle of updates, your projects and deployments will need to follow a similar maintenance pattern. Our web maintenance team follows a strict cycle of code and API reviews to look out for just such deprecations.

Hold Your Horses, There's a Rate Limit

The new API endpoints are rate limited on a per-account basis. This means each of your Klaviyo accounts will have a separate rate limit for making calls. In addition, the system uses a fixed-window limiting algorithm with two distinct types:

1. Burst (short/quick calls) per second

2. Steady (longer stream of calls) per minute

So what does that mean? Every endpoint will provide a value for how quickly you can send calls over a specified timeframe of seconds and/or minutes. Klaviyo provides a basic chart where all endpoints fall somewhere inbetween:

• S: 3/s burst; 60/m steady

• M: 10/s burst; 150/m steady

• L: 75/s burst; 700/m steady

• XL: 350/s burst; 3500/m steady

While that is a general chart, you need to view a specific endpoint to see where it falls in the above range. To do this, checkout the Klaviyo API guide, each endpoint will document the Burst and Steady rate limit for that specific call. For example, here is the Get Profiles API page:

You will see the rate limit for that call (we highlighted it in yellow) displayed on the page. So, in the example above, we would not be able to send more than 10 calls per second (burst) however we can do 150 calls per minute (steady.) It may seem confusing at first but once you take a look at a few endpoints it's super easy to understand and very helpful for planning recurring services and background processes. 

You'll receive a standard HTTP 429 error in event you breach any of the limits. Make sure your code is checking the HTTP response codes for each call.

Klaviyo provides a great list of SDKs in various languages that are a big help in getting started with their API. We'll cover using a Klaviyo SDK in our next blog.

Need a Klaviyo Expert?

If all of this is a bit too technical, don't worry, Sunrise Integration is here to help with your project. If you're looking for an experienced partner to help with your Klaviyo development or integration, you're in the right place!