Access JSON objects with Liquid

You can access JSON objects with Liquid to output values as required.

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 need to firstly ensure that the array of values is assigned to a variable (e.g. "Products"). The following is an example of how this looks in an activity request body sent via the Ortto API:

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

{
    "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"
        },
        "location":{
            "source_ip":"172.217.4.1",
            "custom":null,
            "address":null
        }
    }
],
    "merge_by":[ "str::email"
    ]
}

Once your JSON object is ready, you can output array values using Liquid. For example, in an email confirming a customer’s product pre-order, you can output the item name with:

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

In this Liquid example, we’ve assigned the variable item to the products array, 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):

Example array of multiple product values

{
    "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"
        }
    ]
}

then the Liquid code {% for item in activity.custom.pre-order-placed.products.products %} {{ item.item_variant }} {% endfor %} 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:

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 in the activity associated with the contact.