Getting started with custom objects

You will learn

Learn about custom objects, including how to set up an object and how you can use objects across Klaviyo.

Before you begin

You must have access to custom objects to use this functionality. 

What are custom objects?

Custom objects are a type of data structure in Klaviyo that enable you to map diverse, multi-relational data concepts into Klaviyo that can’t be stored using profile properties. For example, say you want to store data about customers’ pets in Klaviyo. Each pet has a number of attributes about it (e.g., name, age, breed. etc.) making it challenging to store this information with profile properties when a profile has multiple pets. 

You can then use this object data in flows, templates, and segments across Klaviyo to better personalize your marketing. 

Example use cases

Below are some examples that demonstrate how custom objects are flexible in the data you can store in Klaviyo. 

Appointment

If you are a business where customers can schedule appointments, you can use an Appointment object to store appointment data for profiles.  

Within each object record for the Appointment object, some examples of data you may want to include are:

• Appointment ID 
• Appointment date
• Appointment person (e.g., specific doctor, instructor, etc.)
• Appointment location
• Appointment type 

Profiles can have multiple object records if they have multiple appointments, and you can use this object data to create segments and send personalized messages and flows. 

Subscription 

If you are a business where customers can sign up for a subscription, you can use a Subscription object to store subscription data for profiles.  

Within each object record for the Subscription object, some examples of data you may want include are:

• Subscription ID 
• Subscription product
• Subscription price
• Subscription status 
• Next billing date

Profiles can have multiple object records if they have multiple subscriptions, and you can use this object data to create segments and send personalized messages and flows. 

Reservation

If you are a business where customers can book reservations, you can use a Reservation object to store reservation data for profiles.  

Within each object record for the Reservation object, some examples of data you may want include are:

• Reservation ID
• Reservation date
• Reservation location
• Reservation occasion 
• Reservation guest count 

Profiles can have multiple object records if they have multiple reservations, and you can use this object data to create segments and send personalized messages and flows. 

Pet

If you are a business that serves pet owners, you can use a Pet object to store data about profiles’ pets.  

Within each object record for the Pet object, some examples of data you may want include are:

• Pet microchip ID
• Pet name 
• Pet type (e.g., dog or cat)
• Pet breed
• Pet birthday 

Profiles can have multiple object records if they have multiple pets, and you can use this object data to create segments and send personalized messages and flows. 

Account limits 

Custom objects have 3 sets of account limits: 

• Object limit
  Total number of objects that an account can have.
• Object property limits 
  The number of properties an account can have per object.
  
• Object record limits
  The number of object records allowed for an account.

The number of available objects and object records are based on the total number of active profiles across all your accounts. Record limits are shared across all accounts, while object limits apply to each account separately. 

For example, if you have an account family with 5 child accounts where each account has 100,000 active profiles, your total active profiles equal 500,000. As shown in the chart below, accounts with over 400,000 profiles have an object record multiplier of 10. As a result, these accounts can store a combined maximum of 5 million records (500,000 x 10). This means you could have 1 account with 3 million records so long as the remaining 4 accounts have fewer than 2 million object records combined. As for the number of objects per account, since the combined profile count is over 400,000, each account can have up to 5 objects.

Additionally, all accounts have the following limits: 

• Maximum of 500 records per profile per object.
• Every custom object must be no more than 8 KB.
• Every custom object record must be no more than 2 KB.

Create an object 

To get started with creating an object in Klaviyo, navigate to Content > Objects. 

Follow the steps to create and sync a data source for your custom object. Once these steps are completed, select the Create custom object button to create the object. 

From here, you can either create an object from scratch or select a recommended object template. To create an object from scratch, select the Build your own button.

The first part of the object creation workflow requires to set the following information for your object:

• Name
  A name to identify your object
• Description (optional)
  A description of the data your object represents
• Data source
  The data source to get object data from. At least 1 record must be sent to Klaviyo using the custom object API for it to appear as an option in the dropdown. 

Set the object ID

Once you set a name for your object and pick the data source, the next step is to set an object ID and map your desired object properties. During this step, you’ll be able to preview the data associated with the data source that was sent to Klaviyo through the custom object API.

Setting the object ID is necessary to distinguish object records from each other. You’ll need to specify a data source property to be used for the unique object ID. 

The object ID should be a unique data source property that can be used to identify specific instances of an object record. For example, with a gift card object, you can use something like the unique discount code as the object ID. This is unique for each instance of the data source, and will exist for all every object record. 

Whenever Klaviyo receives data from your data source with the same object ID, the associated object record will be updated. For this reason, it is important the object ID is unique so the appropriate record is updated.

Send object data

When you update an existing object record, the entire object is replaced. Therefore, it is critical to send the entire object every time, even if you only want to update 1 record. 

For example, say you want to update just 1 out of 5 records in an object. If you send updated data with the ID and just the 1 record you want to update, the other 4 records will be set to null. If one of the newly null fields was used in your profile relationship (e.g. a profile identifier like an email address), then the object will no longer be related to that profile.

Map object properties 

By mapping object properties, you can select which information within the data source will be available within an object in Klaviyo.

However, for this reason, we recommend sending object data through the object ingestion API in standardized formats. If the value for a specific property is not known, you can set a null value for it.

To map object properties:

1. In the Data source property column select the data source property you’d like to include in your object. 
2. In the Mapped property column, enter the name you’d like the data source property to have in the object. 
3. In the Data type column, select the appropriate data type of your data source property.
4. In the Required column, select the checkbox if you’d like this property to be required in the object.
5. Select the Add mapping button if you need to map additional object properties. 

Nested data in mapping

By default, the object manager interface supports 1 level of nesting. To access deeper data, you must manually enter in the path of your choice.

As an example, look at the data source below. 

{
   “type”: “data-source-record”,
   “attributes”: {
   “record”: {
    “child_id”: “d64b8458”,
    “child”: { 
     “name”: {
      “first”: “Theodore”,
      “last”: “Customer”
     }
    }
    “birth_date”: “2022-04-12”,
    “email”: “jon.customer@klaviyo.com”,
    “phone_numbers”: [
     “+11234567899”,
     “+13456789123"
    ]
   }
  }
 }
]

To access data about a child's first name, you can enter the following path, since the data is otherwise nested too far to access with the interface.

If you have an array in your source data, you can find properties to map by position. For example, you could pull the first phone number within the phone_numbers array by including [0] at the end of your path. 

Add relationship 

After setting an object ID and mapping your object properties, the next step is to add a relationship to your object. 

Relationships connect your object to relevant profiles. Define the following information to set a relationship: 

• Relationship name
  Set a name for your relationship. For example, if you have a pet object, you may want to set the relationship name to be something like “Pet owner”. 
• Source data
  Select the data source properties that you’d like to associate with a profile. 
• Profile identifier
  Set the profile identifier (i.e., email, phone number, etc.). This needs to be included in the data source for an object to be associated with a profile. Use the Link another property button to add additional property and identifier pairs.

Confirm mappings and create object

Once you have finished mapping the object properties and setting the relationship, confirm the mappings on the confirmation modal and select the Create object button. Note that existing mappings cannot be edited once the object is created, and data will start syncing immediately. 

You’ll see your object listed on the Objects page in Klaviyo, along with the following information: 

• Object name
• Created date
• Last updated date
• Status 

Objects on profile pages

Relevant objects will also appear on a profile page so you can view the object records that pertain to a profile. To view the object records, navigate to the Objects tab on a profile page. You can switch between objects using the dropdown menu above the object cards. 

To view a full object record, select the 3 dot menu and click View. A side panel will appear that contains the full object record. 

Update an object 

If you want to start sending new data for an object, add the additional object properties to your data source, then edit your object mapping to include this new property. All previously created objects will return a null for this property since that data is not available, but going forward, objects will be created and updated with this property.

If you send new object properties that have not yet been mapped to an object, you can update your custom object to include it. All custom object records are then reprocessed to include this data.

To update an object:

1. Click Content > Objects in the Klaviyo sidebar.
2. Select the name of the object you want to edit. 
3. Click Next in the top right corner.
4. From the Map object properties section, click Add mapping.

   This option is only available if your object has additional properties that can be added.

5. In the Data source property column select the data source property you’d like to include in your object. 
6. In the Mapped property column, enter the name you’d like the data source property to have in the object. 
7. In the Data type column, select the appropriate data type of your data source property.

   Newly mapped properties cannot be marked as required.

   
8. Click Next in the top right corner. 
9. Click Next in the top right corner. You will not have to make changes to your relationships.
10. Click Publish changes.

Once you have completed this process, all records from your data source will be reprocessed and existing custom object records will be updated accordingly. 

Delete an object 

To delete an object: 

1. Click Content > Objects in the Klaviyo sidebar.
2. In the menu to the right of your object, click Delete. 
   
3. Click Delete again to confirm the object removal. 
4. The object and all associated custom object records are deleted. 

If you create a new custom object using a previous object’s data source, new custom object records will be generated using the data you have already synced. Although it uses the same data, it is considered a new object with new records, so all segments, flows, templates, and campaigns must be updated to use this new object.

Additional resources 

How to use custom objects in templates

How to use custom objects in segments

How to use custom objects in flows

Custom Objects API overview