Use objects in liquid

Learn how to reference objects and relationships using liquid.

 Currently, you can only reference object and relationship liquid in messages, not workflow actions.

Try generating liquid with AI

We know that liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}. is complicated, even moreso when you need to reference objects, relationships, and people in the same message. To make things easier, we built a tool that uses AI to generate your message and liquid for you.

This is an experimental feature. You can enable by going to the icon in the upper right corner of your workspace and clicking Experimental Features. Then you can click Generate with AI in campaigns triggered by changes to objects or relationships to generate your message and associated liquid tags.

generate a message and liquid with AI
generate a message and liquid with AI

We’ll use the object name and relationship attribute names to try and generate your message. You can copy the output into your message and continue refining it to better fit your needs.

Like other AI-based chat tools, you can refine your prompt to get the results you want. For instance, if you want to reference a specific attribute in the subject line of an email, you might modify the prompt with “add attribute_name to the subject line.” You can continue to refine your message after you copy the results into your message.

refine your AI-generated message
refine your AI-generated message

Reference trigger data

 Currently, you can only reference object and relationship liquid in messages, not workflow actions.

You can trigger campaigns based on changes to objects and relationships, so we made it possible for you to use liquid that targets the trigger object or relationship data. You can reference trigger data for object and relationship-triggered campaigns using {{trigger.<object_type>.<attribute_name>}}.

For instance, if you have an object type of “Online Classes” and set up a campaign to trigger when you update a class, you could craft an email like the following:

Liquid SyntaxRendered Liquid
Hi {{customer.first_name}}! We just added a syllabus to {{trigger.online_class.name}}.Hi Jeff! We just added a syllabus to Calculus 1A.

See the liquid examples below for more use cases.

 New to JSON?

Objects in Customer.io use JSON dot notation; if you’re not familiar with JSON, we have a quick primer to help you understand how it works.

Relationship-triggered campaigns

You can use the following liquid when a relationship triggers a campaign:

  • {{trigger.relationship.<attribute_name>}}
  • {{trigger.<object-type>.<attribute_name>}}
  • {{trigger.customer.<attribute_name>}}

Recall that a relationship-triggered campaign can have an audience that is different from the person with the relationship that triggered a campaign. You have the ability to reference both people using liquid. For instance:

Liquid SyntaxRendered Liquid
Hi {{customer.first_name}}! {{trigger.customer.first_name}} just joined your {{trigger.online_class.name}} class.Hi Jeff! Ali just joined your Calculus 1A class.

{{customer.first_name}} refers to the audience/recipient of the message, and {{trigger.customer.first_name}} refers to the person with the relationship that triggered the campaign.

Object-triggered campaigns

You can use the following liquid when an object triggers a campaign:

{{trigger.<object-type>.<attribute_name>}}

Reference non-trigger data

 Currently, you can only reference object and relationship liquid in messages, not workflow actions.

We know this isn’t the easiest to use - thanks for bearing with us! We plan on improving this experience soon.

If you’ve read the above, you may be wondering how to reference object data when an object or relationship is NOT the trigger for a campaign. You can, for instance, check if someone is related to an object or list specific attributes across all related objects in a type.

 You cannot reference more than 10 objects of the same type

If a person is related to 11 classes, {{objects.online_classes}} will render based on the date each object was created, NOT when the person became related to the object. This would mean that if you just related the oldest online class to a person with relationships to 10 other classes, then this class would not render in the list because the 10 other classes were created more recently.

The following examples imagine that you relate people to “Online Classes”.

Check if a person is related to objects

{% if objects.online_classes | size == 0 %}
    This person doesn't have any classes.
{% else %}
    This person is enrolled in at least one class.
{% endif %}

Show information for every object related to a person

{% for class in objects.online_classes %}
Your {{class.name}} begins on {{class.date}} at {{class.time}}.
{% endfor %}
Other non-trigger liquid available

You can use the following object liquid in any campaign or broadcast in your workspace, but consider the warning below.

 You may not be able to reference a specific object or relationship across all people in your campaign

Referencing an object is relative to:

  1. the number of objects a person is related to in your object type and
  2. the order the objects were created in

This is a lot to take in, so let’s dive in with some examples!

Say you have a segment-triggered campaign. In your workspace, you have 1 object type of “Online Classes” and 11 objects, each representing a class. The liquid available to you includes:

  1. {{objects.online_classes}}
  2. {{objects.online_classes[#]}}
  3. {{objects.online_classes[#].<attribute_name>}}
  4. {{objects.online_classes[#].relationship.<attribute_name>}}

where [0] corresponds to the most recently created object that a person is related to (NOT how recently a person was related to the object) and [9] corresponds to the oldest object that a person is related to. More on this below.

 You cannot reference more than 10 objects of the same type

If a person is related to 11 classes, {{objects.online_classes}} will render based on the date each object was created, NOT when the person became related to the object. This would mean that if you just related the oldest online class to a person with relationships to 10 other classes, then this class would not render in the list because the 10 other classes were created more recently.

1. {{objects.<object_type>}}: Reference all object data for up to 10 objects a person is related to.

If you have an object type called “Online Classes,” then you could use {{objects.online_classes}} to show all attributes related to each class a person is related to. For instance, if a person were related to two classes, then {{objects.online_classes}} could render the following:

{
    "_created_in_customerio_at"=>1685030419,
    "cio_object_id"=>"oba886080104",
    "created_at"=>1685030405,
    "name"=>"English Literature",
    "object_id"=>"ae3000-145"
}
{
    "_created_in_customerio_at"=>1681491863,
    "cio_object_id"=>"oba886080102",
    "created_at"=>1681491859,
    "name"=>"Calculus 1A",
    "object_id"=>1
}

Keep in mind, you cannot reference more than 10 objects related to a person of a single object type.

2. {{objects.<object_type>[#]}}: Reference all object data for an object.

Imagine that you created two classes as objects, English Literature and Calculus 1A, in that order. If a person enrolled in both classes, which related them to the objects, you’d reference the person’s Calculus enrollment with {{objects.online_classes[0]}} and the person’s English class with {{objects.online_classes[1]}}.

Note that {{objects.online_classes[0]}} would show all of the attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. for the Calculus class! For example:

{"_created_in_customerio_at"=>1685030419, "cio_object_id"=>"oba886080104", "created_at"=>1685030405, "name"=>"Calculus 1A", "object_id"=>"ae3000-145"}

Keep in mind: {{objects.online_classes[0]}} is not necessarily be the same class across all people who receive a message. That is, if Matthew were related to English Literature only and Clarice were related to Calculus 1A only, then [[objects.online_classes[0].name}} would render the data for each class respectively.

If you wanted to reference just the class name, you’d use {{objects.online_classes[0].name}}. See below.

3. {{objects.<object_type>[#].<attribute_name>}}: Reference a specific attribute for an object.

If you wanted to reference just the class name, you’d use something like {{objects.online_classes[0].name}}.

Keep in mind: {{objects.online_classes[0].name}} is not necessarily be the same class across all people who receive a message. That is, if Matthew were related to English Literature only and Clarice were related to Calculus 1A only, then [[objects.online_classes[0].name}} would render the data for each class name respectively.

4. {{objects.<object_type>[0].relationship.<attribute_name>}}: Reference a relationship attribute for an object.

If you wanted to reference relationship data for a class object, you’d use {{objects.online_classes[#].relationship.<attribute_name>}}.

Keep in mind: {{objects.online_classes[#].relationship.<attribute_name>}} is not necessarily be the same class across all people who receive a message. That is, if Matthew were related to English Literature only and Clarice were related to Calculus 1A only, then [[objects.online_classes[0].relationship.<attribute_name>}} would render the data for each class respectively.

Copied to clipboard!
  Contents
Is this page helpful?