Frequently asked questions about custom objects

You will learn

Learn about frequently asked questions related to custom objects in Klaviyo. If you don’t see your question in the resource below, please reach out on our Community forum.

General questions about objects

Do I need a developer to create an object?

You need a developer to send custom data through APIs. You can create the data source and configure the object in Klaviyo.

Can I create custom objects using Klaviyo forms or CSV uploads?

Klaviyo forms and CSV uploads do not send custom object records. Use the API to send your custom data, then map it to an object in Klaviyo.

When should I use a custom object versus a profile property or event?

You should use custom objects when you have a many-to-one relationship between the category that your custom object represents and your profiles. For example, if you want to keep information about your customer’s pets, and your customer may have more than one pet, representing these as a custom object works much better than profile properties or events.

When tracking items like a membership status, where a profile can only have one status at a time, a profile property is a better fit. However, if you’d like to store other details about a profile’s membership as well, an object can work better.

When tracking something broad, like how many times a recipient has opened an email, we recommend using events.

Can I update my custom object after creation?

Yes, you can add non-required properties up to your account’s object property limit. For more, read about updating a custom object.

When should I emit an event versus updating the custom object’s properties?

Events are intended to trigger flows quickly, allowing you to send timely and relevant messaging. When the status of an object changes and you want to trigger a message as a result of this, you should update the object with the new information and send us an event to trigger the flow.

You can personalize templates with the object information in the event triggered flow. There are two ways to achieve this:

1. Include the properties you need in the event data, then reference them in your template. For example, if the event includes a pet_name property, use {{ event.pet_name }}. This works well when timeliness is important.
2. Include the object’s ID in the event data, then retrieve the object in the template. For an object named Pet with a Name property and an event property named pet_id, use {% customobject event.pet_id object_type_title="Pet" as pet %}{{ pet.Name }}{% endcustomobject %}. Replace these names with your own object, property, and event field names. It can take time for object updates to become available, so a flow message may send before the object has the latest values.

Questions about sending object data

How do I start sending my data for custom objects?

1. Create a new data source using our API.
2. Define your data structure using the example JSON in Bulk Create Data Source Records.
3. Send your data source records to Klaviyo via API.
4. Create your custom object using that data source. Choose a unique object ID and map the properties you want to use.
5. Create the relationship between your custom object and your profiles by mapping the profile identifiers in your data, such as email or phone number.
6. Review your mappings, click Create object, then click Create object again to confirm.

How are data sources created and used?

When you create a data source through the API, Klaviyo returns a unique identifier as part of the response to your API request. This allows Klaviyo to identify data sources, especially in cases where an account has multiple data sources (e.g., 1 for each custom integration, data warehouse, or custom 3rd party integration that the brand relies on for their business).

With this unique identifier, your developer can then create data source records through Klaviyo’s API.

How should I format my data?

Your developer will need to send JSON-formatted data to Klaviyo. For a property with multiple text values, send an array of strings and map it as List (Text). You can filter these values in segments and flows. See the segment conditions reference for more information on filtering.

Supported data types in custom objects:

• Text
• Number (Integer)
• Number (Decimal)
• Timestamp: Dates and times are stored in UTC. A value without a time zone, such as 2025-04-03, is treated as 2025-04-03 00:00:00 UTC. A value with an offset, such as 2025-04-03T00:00:00+03:00, is converted to 2025-04-02 21:00:00 UTC.
• Boolean
• List (Text)

List (Text) supports arrays of strings, such as ["dog", "cat"]. It does not support arrays of numbers, nested lists, or objects. For an example payload for the data source record API, see Bulk Create Data Source Records.

What are the data limits for custom objects?

Each mapped custom object property can contain up to 2 KB, and each mapped custom object record can contain up to 8 KB.

Can I map with nested data?

We recommend defining your JSON object without nesting the properties you want to use for your custom object. For nested data, select a property from the Data source property dropdown, or enter its JSON path manually. For a list of text values, map the list itself as List (Text). To map a single item from an array, use its position, such as [0] for the 1st item or [1] for the 2nd.

Can I associate multiple identifiers with a profile?

Yes, if you want to use 2 or more profile identifiers (e.g., email and phone number) to associate your custom object records to a profile, ensure you include both of those properties in every sync, even if the value of one of them is null.

Questions about using objects with flows

If my object didn’t trigger a flow and I don’t have an object id from an event, can I still personalize my messaging?

Yes, you can use object filters to find the right object when personalizing your messaging.

Can I preview flow messages when an object triggers a flow?

Yes. You can preview messages that use {{ object }} data in a date-triggered flow based on a custom object, before setting the flow live.

To preview an email:

1. Open an email in a date-triggered flow based on a custom object, then click Preview in the email editor.
2. Select a profile associated with a record for that object, then review the personalized message.

The preview uses a sample object associated with the selected profile. If none is available, it uses a sample record of the same object type. Check the displayed values: the preview does not confirm which record will trigger the flow. If no records are available, there is no object data to preview.

Can I update my objects using flow actions like webhooks and Klaviyo code?

At this time, we advise you to update your original data source first and then send the revised object back to Klaviyo in the permitted format. If these two systems fall out of sync, you risk sending an out of date record back to Klaviyo from your system, reverting it to the original value.