API Overview (Beta)

This overview details the new functionality offered by Klaviyo's new API endpoints, which are currently in a limited availability beta release.

Join Klaviyo's API Beta Program! If you would like to request access to the beta APIs, please click the button below.

Quickstart

  • Install one of our new SDKs now available in beta (optional)
  • Check out the beta API collection in our Postman workspace. Open the collection labeled Klaviyo API (Beta) and create your own fork to get started.
  • Begin exploring and utilizing our revamped endpoints. There are many new API resources (Flows, Catalogs, Metrics, Segments), and entirely new API features and patterns that these new endpoints offer. Start playing around with these APIs to understand how they could meet your development needs and test out new features such as relationships, filters, and sparse fieldsets!
    • Any private keys you have generated will now work for our new APIs in addition to our V1/V2 APIs.
    • You do not need to generate any new keys to enable beta access. Let us know what you think! Schedule time with Klaviyo Product Managers to provide feedback here, or send an email to [email protected] with any questions or feedback.

🚧

These APIs are unstable, and will be subject to breaking changes throughout the duration of both limited-availability phases in order to adapt to feedback we receive from you. As a result, we do not recommend that any production workflows be built on top of these APIs until the initial stable general-availability release. Read more about our versioning and deprecation policy.

What's new?

Read more about what's new with the beta APIs and how they differ from our V1 and V2 legacy APIs.

Authentication

All /api endpoints use API private keys to authenticate requests. You can generate each of these credentials just as you would for our V1 and V2 APIs. Please refer to this guide for more details on how to generate private keys.

All /client endpoints use a public API key, your 6-character company ID, also known as a site ID.

API key scopes

Klaviyo's APIs support the use of API scopes, which allow you to restrict access for third parties using a private API key. Adding a scope helps you protect your and your customers’ data by limiting what third parties can access.

You can add any of the following scopes to any new private API key in Klaviyo:

  • Read-only
    Only allows third parties to view all data associated with the endpoint
  • Full
    Allows third parties to create, delete, or make changes to anything associated with that endpoint
  • Custom
    Allows you to decide how much access to give the third party

Note that you cannot add a scope to an existing private key, which have full access by default. You also cannot edit a private API key after it’s been created. If you need to remove access to a key based on its current scope, delete it and then create a new key with the correct scope.

For more information about the supported scopes for each endpoint and how to add a scope to an API key, please refer to the how to create a scope for a private API key guide.

Private key authentication

Private key authentication for /api endpoints is performed by setting the following request header:

Authorization: Klaviyo-API-Key {your-private-api-key}

Company ID

Because our /client endpoints are designed to only be called from publicly-browsable client-side environments, these endpoints do not accept private keys, but instead only use public API keys to authorize and route requests. These endpoints are specifically designed to limit functionality to object creation of specific types of objects and do not respond with any potentially sensitive response data. For security reasons, this data must be accessed using private key endpoints only (i.e. /api).

Public API keys are passed to /client endpoints using a query parameter:

curl --request POST \
  --url 'https://a.klaviyo.com/client/events/?company_id=COMPANY_ID'
  --header 'Content-Type: application/json'
  --data '{DATA}'

Versioning & deprecation

Check out our API versioning and deprecation policy to learn more about how Klaviyo handles versioning with the new APIs and deprecations of old versions and legacy APIs.

Rate limiting

All new API endpoints are rate limited on a per-account basis, and used a fixed-window rate limiting algorithm with two distinct windows: burst (short) and steady (long). All API traffic will be subject to these rate limits, and will receive HTTP 429 errors in event either a burst or steady rate limit is reached.

Unless otherwise documented, all API endpoints use one of the following rate limits:

  • 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

All non-rate-limited (i.e. non 429) responses will contain the following HTTP response headers that indicate the state of the steady rate limit window to the client:

  • RateLimit–Limit: The number of requests allowed per time period
  • RateLimit-Remaining: The approximate number of requests remaining within a window
  • RateLimit-Reset: Number of seconds remaining before current window resets

JSON API feature guides

Relationships

Klaviyo’s modern APIs offer powerful new functionality via the relationships object, a thorough set of syntax offered by JSON:API for modeling relationships between resources. This syntax allows developers to efficiently query specific groups of related resources, eliminating the need to perform redundant queries.

Check out our guide to JSON API's Relationships feature for more information on how use, create, modify, and delete resource relationships.

Filtering

Filter operation support

This section refers to general filtering syntax and and all possible supported operations across all new APIs. Support for specific operators and fields, however, is highly specific to each endpoint. Please refer to the filter query parameter documentation in each endpoint reference for specific operator and field support.

Filtering syntax for new APIs has been standardized to use the ?filter query parameter for all endpoints that support filter operations. We have implemented a specific syntax to allow for more complex filtering operations across all endpoints, as illustrated below:

filteringfiltering

URL encoding

Filter expressions can contain non-URL-safe characters, and as such we recommend always URL-encoding your request URLs in order to ensure filter expressions function properly.

All new API filter operations

  • equals
    • Example: ?filter=equals(last_name,"Smith").
    • Supported field types: string, boolean, number, datetime, array
  • less-than
    • Example: ?filter=less-than(value,25).
    • Supported field types: number, datetime
  • less-or-equal
    • Example: ?filter=less-or-equal(datetime,2001-01-01T11:00:00Z).
    • Supported field types: number, datetime
  • greater-than
    • Example: ?filter=greater-than(datetime,2022-04-01T11:30:00Z).
    • Supported field types: number, datetime
  • greater-or-equal
    • Example: ?filter=greater-or-equal(percentage,33.33).
    • Supported field types: number, datetime
  • contains
    • Example: ?filter=contains(description,"cooking").
    • Supported field types: string
  • ends-with
    • Example: ?filter=ends-with(description,"End").
    • Supported field types: string
  • starts-with
    • Example: ?filter=starts-with(description,"Start").
    • Supported field types: string
  • any
    • Example: ?filter=any(chapter,["Intro","Summary","Conclusion"]).
    • Supported field types: string, number, datetime, boolean
  • not
    • Example: ?filter=not(equals(last_name,null)).
    • Accepts other operator functions as arguments, and cannot accept nested functions
    • not(equals(name,Ben)) is fine, not(or(equals(name,Tim),equals(name, Bob))) is not
  • or
    • Example: ?filter=or(equals(last_name,"Smith"),equals(last_name,"qwerty")).
    • Accepts other operator functions as arguments, and cannot accept nested functions beyond 1 level deep
  • and
    • Example: ?filter=and(equals(first_name,"Jane"),equals(email,"[email protected]")).
    • Accepts other operator functions as arguments, and cannot accept nested functions beyond 1 level deep

For simplicity's sake, we also interpret comma-separated filter expressions as an alias for an and wrapper function. For example, filter=and(equals(field1,"foo"),or(equals(field2,"bar"),equals(field2,"foobar"))) can be simplified to filter=equals(field1,"foo"),or(equals(field2,"bar"),equals(field2,"foobar"))

Comparison literals

  • string: Arguments representing string literals are expressed with quotation marks (we will accept either single quoted or double quoted strings). Single or double quoted characters within strings quoted with like quote characters MUST be escaped with a single back slash (i.e. ‘Tony\’s ball’)
    • Comparisons to all string literals are case-sensitive, unless otherwise noted in endpoint specific documentation
  • boolean: Booleans are expressed as unquoted true and false literal values
  • number: Numbers are expressed as standard integer or float representations
  • datetime: Datetimes are expressed as unquoted ISO-8601 RFC-3339 formatted strings(e.g. 2012-04-21T11:30:00-04:00)
  • array: Array literals are be expressed using square brackets ([ ])
  • null: null is a reserved literal to represent null values for fields of any type

Sorting

Where supported, sorting is handled using the ?sort query parameter followed by a field name. Reverse sorting is specified using a - prefix.

Example
GET /api/events/?sort=datetime sorts events by datetime ascending; GET /api/events/?sort=-datetime sorts by datetime descending.

Sparse fieldsets

Several endpoints support sparse fieldsets to allow developers to select only requested fields of resources, rather than having to retrieve entire resources (which may be very large).

Sparse fieldsets are specified using the ?field[TYPE]=field1,field2 query parameter, where TYPE is the resource type from which to select only field1 and field2.

Example: GET /api/catalog-items?fields[catalog-item]=title,description will retrieve only the title & description attributes for all catalog-item resources.

Pagination

Our APIs support cursor-based pagination with the query parameter ?page[cursor].

Paginated resource responses will contain a specific set of pagination cursor helper links in their top-level links object, like the following:

{
  "data": [
    ...
  ],
  "links" : {
    "next" : "https://a.klaviyo.com/api/profiles/?page%5Bcursor%5D=bmV4dDo6aWQ6Ok43dW1iVw",
    "prev" : null,
    "self" : "https://a.klaviyo.com/api/profiles"
  }
}

Use these links to navigate to next and previous pages.

Datetimes

Datetime formatting

All datetimes across all new APIs in URLs, request, and response bodies must be formatted as ISO 8601 RFC 3339 datetime strings.
Example:
1985-04-12T23:20:50.52Z