Access JSON objects with Liquid

Overview

You can use Liquid to access JSON objects and output values as needed. JSON objects often contain arrays of data, such as multiple products, events, or items tied to a single activity.

With Liquid, you can:

Loop through all items in an array
Access a specific item by its position

Loop through items in an array

For example, you have a custom activity called "Pre-order placed" where one of the attributes is a JSON object called "Products". In the "Products" attribute is an array of product values.

To output a "Products" attribute value using Liquid, you can use one of the following approaches:

Option A: Assign the array of values to a variable (e.g. "Products"). This option is recommended if you want to provide other fields in the JSON payload along with the array of values.
Option B: Provide the values as an array (not mapped to a variable). This option is recommended if you simply want to provide the array of values.

Below examples of each approach in an activity request body sent via the Ortto API.

Option A – Example activity event request with array of product values assigned to a variable called "products"

json
 {
    "activities":[
    {
        "activity_id":"act:cm:pre-order-placed",
        "attributes":{
            "obj:cm:products":{
                "products": [
                    {
                    "item_id": "12345",
                    "item_name": "Laminate stand up desk",
                    "price": 800,
                    "currency": "USD",
                    "item_brand": "Standy",
                    "supplier": "Standy",
                    "item_variant": "walnut/white",
                    "quantity": 1,
                    "item_category": "Stand up desks"
                    }
                ]
            }
        },
        "fields":{
            "str::first": "Contact",
            "str::last": "Person",
            "str::email":"contact@email.com"
        }
    }
],
    "merge_by":[ "str::email"
    ]
}

Option B – Example activity event request with array of product values

json
 {
    "activities":[
    {
        "activity_id":"act:cm:pre-order-placed",
        "attributes":{
            "obj:cm:products": [
                    {
                    "item_id": "12345",
                    "item_name": "Laminate stand up desk",
                    "price": 800,
                    "currency": "USD",
                    "item_brand": "Standy",
                    "supplier": "Standy",
                    "item_variant": "walnut/white",
                    "quantity": 1,
                    "item_category": "Stand up desks"
                    }
                ]
        },
        "fields":{
            "str::first": "Contact",
            "str::last": "Person",
            "str::email":"contact@email.com"
        }
    }
],
    "merge_by":[ "str::email"
    ]
}

Once your JSON object is ready, you can output array values using Liquid. The syntax for this will differ depending on whether your values are structured according to Option A or Option B described above.

For example, in an email confirming a customer’s product pre-order, you can output the item name with:

	Liquid syntax	Description
Option A – Values assigned to a variable	`{% for item in activity.custom.pre-order-placed.products.products %} {{ item.item_name }} {% endfor %}`	In this example, we’ve assigned the variable `item` to a single product from the `products` array, then identified the product value to output using the variable (`item`) plus the value’s key (`item_name`). NOTE: `products` is repeated in the syntax because we are referencing the attribute named `products` (`obj:cm:products` from the activity definition shown above), then the variable named `products`. You can name the Liquid syntax variable whatever you want (e.g. `product` instead of `item`), we’ve used item in this example to make identification of each element clearer.
Option B – Values in an array	`{% for item in activity.custom.pre-order-placed.products %} {{ item.item_name }} {% endfor %}`	In this example, we’ve assigned the variable `item` to the `products` attribute (`obj:cm:products` from the activity definition shown above), then identified the product value to output using the variable (`item`) plus the value’s key (`item_name`). You can name the variable whatever you want (e.g. `product` instead of `item`), we’ve used item in this example to make identification of each element clearer.

Liquid syntax

Description

Option A – Values assigned to a variable

{% for item in activity.custom.pre-order-placed.products.products %} {{ item.item_name }} {% endfor %}

In this example, we’ve assigned the variable item to a single product from the products array, then identified the product value to output using the variable (item) plus the value’s key (item_name).

NOTE: products is repeated in the syntax because we are referencing the attribute named products (obj:cm:products from the activity definition shown above), then the variable named products.

You can name the Liquid syntax variable whatever you want (e.g. product instead of item), we’ve used item in this example to make identification of each element clearer.

Option B – Values in an array

{% for item in activity.custom.pre-order-placed.products %} {{ item.item_name }} {% endfor %}

In this example, we’ve assigned the variable item to the products attribute (obj:cm:products from the activity definition shown above), then identified the product value to output using the variable (item) plus the value’s key (item_name).

You can name the variable whatever you want (e.g. product instead of item), we’ve used item in this example to make identification of each element clearer.

The for tag is an iteration tag, which loops over the array in the JSON object and provides an expression (output) for the specified item. As such, using the example above, if the customer pre-ordered 2 items (seen in your products array for Option A, or the array without a variable for Option B):

Option A – Example multiple ‘products’ arrays of product values

json
 {
"obj:cm:products": {
    "products": [
        {
            "item_id": "12345",
            "item_name": "Laminate stand up desk",
            "price": 800,
            "currency": "USD",
            "item_brand": "Standy",
            "supplier": "Standy",
            "item_variant": "walnut/white",
            "quantity": 1,
            "item_category": "Stand up desks"
        }
        {
            "item_id": "67890",
            "item_name": "Plywood stand up desk",
            "price": 850,
            "currency": "USD",
            "item_brand": "Standy",
            "supplier": "Standy",
            "item_variant": "maple/black",
            "quantity": 1,
            "item_category": "Stand up desks"
        }
    ]
}

Option B – Example multiple arrays of product values

json
 {
 "obj:cm:product-array":[
                    {
                "item_id":"12345",
                "item_name":"Timber stand-up desk",
                "price": 1000,
                "currency": "USD",
                "item_brand": "Standy",
                "supplier": "Standy",
                "item_variant": "walnut/black",
                "item_category": "Stand up desks"
                    },
                    {
                "item_id":"12346",
                "item_name":"Laminate stand-up desk",
                "price": 800,
                "currency": "USD",
                "item_brand": "Standy",
                "supplier": "Standy",
                "item_variant": "walnut/white",
                "item_category": "Stand up desks"
             }
        ]
  }

then the Liquid syntax {% for item in activity.custom.pre-order-placed.products.products %} {{ item.item_variant }} {% endfor %} (Option A), or {% for item in activity.custom.pre-order-placed.products %} {{ item.item_variant }} {% endfor %} (Option B) would loop through the array to output both variants.

For emails, you can also use the for loop as a display condition for content rows to customize your content, like so (example shows Option A syntax):

This allows you to then customize the row to output the relevant content, such as outputting key product details in the text box and adding a dynamic image.

In this case, the image URL is a value for the key image_url in the JSON object (e.g. :"image_url": "https://product_variant_image"). The merge tag for the image URL is then added to the content properties. Note that a sample image has been uploaded to provide the image width, and the image height will be determined by the ratio of the dynamic image.

In the email message preview, you can see that a contact who has pre-ordered 2 items will see both items displayed, as the Liquid has looped through each product array (Option A) or unassigned array (Option B) in the activity associated with the contact.

Access a specific item in an array

If you only need one item, you can access it using its index.

This can be helpful when you want to:

Show a featured or primary item only
Reference a specific position (for example, first or most recent item)
Simplify your template when only one object is needed

Arrays are zero-indexed, meaning 0 refers to the first item and 1 refers to the second item.

Below examples of each approach in an activity request body sent via the Ortto API.

Option A – Example activity event request with array of product values assigned to a variable called "products"

json
 {
    "activities": [
        {
            "activity_id": "act:cm:pre-order-placed",
            "attributes": {
                "obj:cm:products": {
                    "products": [
                        {
                            "item_id": "12345",
                            "item_name": "Laminate stand up desk",
                            "price": 800,
                            "currency": "USD",
                            "item_brand": "Standy",
                            "supplier": "Standy",
                            "item_variant": "walnut/white",
                            "quantity": 1,
                            "item_category": "Stand up desks"
                        },
                        {
                            "item_id": "67890",
                            "item_name": "Plywood stand up desk",
                            "price": 850,
                            "currency": "USD",
                            "item_brand": "Standy",
                            "supplier": "Standy",
                            "item_variant": "maple/black",
                            "quantity": 1,
                            "item_category": "Stand up desks"
                        }
                    ]
                }
            },
            "fields": {
                "str::first": "Contact",
                "str::last": "Person",
                "str::email": "contact@email.com"
            }
        }
    ],
    "merge_by": ["str::email"]
}

Option B – Example activity event request with array of product values

json
 {
    "activities": [
        {
            "activity_id": "act:cm:pre-order-placed",
            "attributes": {
                "obj:cm:product-array": [
                    {
                        "item_id": "12345",
                        "item_name": "Timber stand-up desk",
                        "price": 1000,
                        "currency": "USD",
                        "item_brand": "Standy",
                        "supplier": "Standy",
                        "item_variant": "walnut/black",
                        "item_category": "Stand up desks"
                    },
                    {
                        "item_id": "12346",
                        "item_name": "Laminate stand-up desk",
                        "price": 800,
                        "currency": "USD",
                        "item_brand": "Standy",
                        "supplier": "Standy",
                        "item_variant": "walnut/white",
                        "item_category": "Stand up desks"
                    }
                ]
            },
            "fields": {
                "str::first": "Contact",
                "str::last": "Person",
                "str::email": "contact@email.com"
            }
        }
    ],
    "merge_by": ["str::email"]
}

The syntax for this will differ depending on whether your values are structured according to Option A or Option B described above.

For example, in an email confirming a customer’s product pre-order, you can output the second item's name with:

	Liquid syntax	Description
Option A – Values assigned to a variable	`{% assign varItem = activity.custom.pre-order-placed.products.product[1] %}` `{{ varItem.item_name }}`	In this example, you can assign a specific product from the `products` array using its index (`1` = second item). You then output the value using the variable (`varItem`) and the key (`item_name`). Note: `products` appears twice because you are referencing the attribute (`obj:cm:products`) and the nested array (`products`).
Option B – Values in an array	`{% assign varItem = activity.custom.pre-order-placed.products[1] %}` `{{ varItem.item_name }}`	In this example, you can assign a specific item directly from the array using its index. You then output the value using the variable (`varItem`) and the key (`item_name`).

Liquid syntax

Description

Option A – Values assigned to a variable

{% assign varItem = activity.custom.pre-order-placed.products.product[1] %}

{{ varItem.item_name }}

In this example, you can assign a specific product from the products array using its index (1 = second item). You then output the value using the variable (varItem) and the key (item_name). Note: products appears twice because you are referencing the attribute (obj:cm:products) and the nested array (products).

Option B – Values in an array

{% assign varItem = activity.custom.pre-order-placed.products[1] %}

{{ varItem.item_name }}

In this example, you can assign a specific item directly from the array using its index. You then output the value using the variable (varItem) and the key (item_name).

NOTE: You can name the variable whatever you prefer so long as it begins with 'var' in the assignment. Learn more about assigning variables.

TIP: You can include a conditional statement at the top of the liquid to check if the item exists. This can be helpful for formatting if the items need to be displayed in specific columns only if they exist.

For example:

{% if activity.custom.pre-order-placed.products[1] %}

{% assign varItem = activity.custom.pre-order-placed.products[1] %}

{{ varItem.item_name }}

{% endif %}

﻿Overview

Loop through items in an array

Access a specific item in an array

Overview