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 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.