👍

Klaviyo's new and improved APIs are now available!

Select the stable version from the dropdown in the upper left to view the most up-to-date documentation for new APIs.

🚧

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

Introduction

Klaviyo has two core sets of HTTP APIs that serve two distinct purposes.

Track & Identify. Used to send event & profile data to your Klaviyo account. These APIs are designed for high volume & low latency, do not adhere to REST principles, and require your Public API key/Site ID.

RESTful APIs. Used to manage objects & query data within your Klaviyo account. These APIs are organized around REST, and use your Private API Keys for authentication. The following Klaviyo resources can be accessed using our RESTful APIs:

Back in Stock. Learn how to implement the back in stock endpoint using the following guides. This API endpoint is only valid for Shopify integrations, BigCommerce integrations, or accounts with inventory-aware custom catalog feeds.

Front End Subscribe. The following guides offer implementations of our front end subscribe endpoint.

OpenAPI + Postman

You can find our latest OpenAPI Spec here

You can import this spec into your favorite API tool, such as Postman, to start interacting with our API right now.

You can also navigate to our Postman Workspace, where you will find our latest Collection of requests, along with the API definition.

Authentication

Track & Identify

Authenticate Track & Identify requests using your 6-character Public API key / Site ID. This can be found in your Account Settings > API Keys tab. This ID must be set as the token key in the base64-encoded payload of your request. For more details, see Track & Identify.

RESTful APIs

Authenticate RESTful API requests by providing one of your private API keys as part of each request. You can manage your private API keys from Account Settings > API Keys tab as well. Your account can have multiple private API keys. Your private API key is passed using the query parameter api_key with each request.

🚧

Do Not Publicize Private API Keys

Your private API Keys carry many account privileges, and should not be shared or posted on public-facing resources, including public webpage bodies. As such, please avoid calling our RESTful APIs directly from client-side assets.

Errors

Our API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error from information provided as part of the request (e.g. the requested object doesn't exist, an invalid setting, etc.), and codes in the 5xx range indicate an error on Klaviyo's end.

The response of all API errors contain a message parameter which has developer-facing information about why the request failed.

See the table below for a list of error codes and their corresponding descriptions:

CodeSummaryDescription
200OKThe request completed successfully
400Bad RequestRequest is missing or has a bad parameter
400Not AuthorizedRequest is missing or has an invalid API key
401Not AuthorizedKey is valid, but account does not have permissions to perform this action
403ForbiddenRequest is missing or has an invalid API key
404Not FoundThe requested resource doesn't exist
429Rate LimitYou hit the rate limit for this endpoint (different endpoints have different rate limits)
500Server ErrorSomething is wrong on Klaviyo's end

Rate Limits

All of these endpoints are rate limited. You should be sure to check the response codes and retry requests that exceed the rate limit at a later time. If you hit rate limits, we recommend adjusting your request-rate using an exponential backoff.

Additional Resources

Versioning

When we make backwards incompatible changes to the API, we release new API versions, which are reflected in the API endpoints. Please note that certain features that have not needed to be updated are still under the v1 path. All endpoints, both v1 and v2, that are not deprecated, are part of the latest Klaviyo API release (see top of page for OpenAPI spec + Postman Collection).

Deprecation

Occasionally, we deprecate an endpoint upon releasing a new version. Though we continue to support deprecated endpoints for our customers with existing implementations, we recommend that all new implementations use our latest endpoints.

For customers working with legacy implementations, you can find the OpenAPI spec describing our deprecated endpoints here.

SDKs

We currently support SDKs for the following languages: Python, Ruby, Node, & PHP.

You can read more about our SDKs and where to find them here.