These endpoints are in beta and are subject to change.
A beta revision header (
2025-04-15.pre) is required to use these beta APIs. Klaviyo APIs in beta are not intended for use in production. See our versioning and deprecation policy for more information.
You will learn
Before you can create custom objects in Klaviyo, you’ll need to create a data source in Klaviyo and begin sending data with the new Custom Objects API. This guide will walk you through how to use the API.
Background
Custom objects enable you to map diverse, multi-relational data concepts into Klaviyo. Use custom object data to:
- Personalize templates for your flow and campaign sends (i.e., use object personalization tags to pull custom object data into your templates).
- Create granular customer segments (e.g., a segment of profiles that have more than 3 pets, to target with rewards for bulk pet supplies).
- Configure date-triggered flows based on an object’s date properties (e.g., a pet’s birthday).
- Set conditional splits in flows (e.g., add a text block to an email with a sign-up form for birthday rewards if the data has not been provided).
Custom objects is a paid feature in Klaviyo, only available to customers with a paid email plan. To request access to custom objects, submit this form.
Use cases
- Create a data source record job to ingest data records from third-party sources into Klaviyo.
- Return all available data sources for an account.
For a quick start, download this Postman collection and import it to Postman.
If you have feedback or encounter issues using this API, please let us know using this form.
This API requires the following scopes:
custom-objects:readcustom-objects:write
Bulk Create Data Source Records
Use the Custom Objects API to bulk create data source records. Below is an example request payload to Bulk Create Data Source Records where each record represents a reservation:
{
"data": {
"type": "data-source-record-bulk-create-job",
"attributes": {
"data-source-records": {
"data": [
{
"type": "data-source-record",
"attributes": {
"record": {
"reservation_id": "4d5j4dH",
"created_at": "2019-07-29T09:18:52.005234+14:00",
"guest_count": 6
}
}
},
{
"type": "data-source-record",
"attributes": {
"record": {
"reservation_id": "AfjS8dN",
"created_at": "2019-08-12T09:18:52.005234+14:00",
"guest_count": 4
}
}
}
]
}
},
"relationships": {
"data-source": {
"data": {
"type": "data-source",
"id": "01JKV3YV229CP2NVMXHM5SD9N5"
}
}
}
}
}
This endpoint creates data source records asynchronously, so it may be a while (~15 minutes) before you notice data source records in your account.
Get Data Sources
When making a request to Get Data Sources, here's an example of how a data source should look in your response:
{
"data": [
{
"type": "data-source",
"id": "01JKV3YV229CP2NVMXHM5SD9N5",
"attributes": {
"title": "My Reservation Data Source",
"visibility": "shared",
"description": "Data source for reservation data"
},
"links": {
"self": "https://a.klaviyo.com/api/data-sources/01JKV3YV229CP2NVMXHM5SD9N5/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/data-sources",
"next": null,
"prev": null
}
}
Limitations
Payload limits
We enforce the following limits on payload size:
- Max payload size - 4 MB
- Max records per request - 500 records (1500 records per second)
Rate limits
These endpoints use the following rate limits:
- Burst: 3/s
- Steady: 60/m
Troubleshooting
Common errors
| Status code | Reasons |
|---|---|
| 400 |
|
| 413 |
|
| 429 |
|