Custom Objects API overview

🚧

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.

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

Custom objects enable you to map diverse data concepts into Klaviyo with a many-to-one relationship, like multiple pets, product subscriptions, or active reservations. 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).

When the status of an object changes and you want to trigger a message, use the Custom Object API to update the object with the new information. You must include the complete object and an event to trigger a flow in each payload. Events are intended to trigger flows quickly, allowing you to send timely and relevant messaging.

Set up custom objects in your Klaviyo account

To get started with custom objects:

1. Create a data source with the Create Data Source endpoint.

2. Ingest some records from your source of data with the Bulk Create Data Source Records endpoint.

3. Define the custom object using the Object Manager. For more information about defining an object, check out Getting started with custom objects.

🚧

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

The Custom Objects API supports a number of use cases, including:

• Create data sources to ingest data records that will be used to create custom objects.
• Create a data source record job to ingest data records from your data source.
• Return all available data sources for an account.
• Delete data sources in your account.

For a quick start, download this Postman collection.

📘

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:read
• custom-objects:write

Data model

Records sent from your data source using the Bulk Create Data Source Records are stored in Klaviyo. Once a custom object is defined using the Object Manager, we map your source data into custom object records and link them to profiles. While custom object records are available for use in Klaviyo workflows and segmentation, the raw JSON file is not directly accessible in the Klaviyo UI.

All custom object records have a unique identifier, properties, and a profile relationship as defined by the Object Manager.

Unique identifier

Every object must have a unique ID. The unique ID can be any ID you choose - you must provide this ID when syncing each object record from your system’s source of truth to Klaviyo.

Object properties

Every object can have up to 15 properties (or 30 properties depending on your billing plan) and must not exceed 8 KB.

Every property on an object must be one of the following acceptable data types:

• text : The maximum size is 2 KB.
• integer
• decimal
• boolean
• timestamp : Must follow Klaviyo's acceptable timestamp formats. All datetimes are converted to UTC. Defaults to midnight if no timestamp is provided.

Relationships

All custom object records must have a relationship to a profile. When syncing each custom object record, you must provide one or more acceptable profile identifiers, like email or phone number, to identify which profile the custom object record belongs to.

Updating object records

You must provide the entire object record when you request an update to one or more properties.

🚧

If you exclude any properties, including profile identifiers, those properties are set to null.

Create Data Source(s)

Use the Custom Objects API to create a data source. Returns a unique ID to use when sending data from that source of data.

Below is an example request payload to Create a Data Source:

{
    "data": {
        "type": "data-source",
        "attributes": {
            "visibility": "private",
            "title": "Reservation Database",
            "description": "The source of truth for reservations"
        }
    }
}

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,
                                "late_cancellation_fee": 32.40,
                                "is_active": true,
                                "email": "amy.smith@klaviyo.com"
                            }
                        }
                    },
                    {
                        "type": "data-source-record",
                        "attributes": {
                            "record": {
                                "reservation_id": "AfjS8dN",
                                "created_at": "2019-08-12T09:18:52.005234+14:00",
                                "guest_count": 4,
                                "late_cancellation_fee": 21.23,
                                "is_active": false,
                                "email": "jon.jacobson@klaviyo.com"
                            }
                        }
                    }
                ]
            }
        },
        "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:

1. Max payload size - 4 MB
2. 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

Learn more about rate limits.

Troubleshooting

Common errors

Additional resources

• Getting started with custom objects

• How to use custom objects in templates

• How to use custom objects in flows

• How to use custom objects in segments