Iterate over contextual data personalization-contexts

Learn how to use Handlebars iteration syntax to display dynamic lists of data from various sources in your messages, including events, custom action responses, and other contextual data.

Overview overview

Journey Optimizer provides access to contextual data from multiple sources during message personalization. You can iterate over arrays from these sources using Handlebars syntax in native channels (email, push, SMS) to display dynamic content like product lists, recommendations, or other repeating elements.

Available context sources:

This guide shows you how to iterate over arrays from each of these sources in your messages, and how to work with arrays when configuring journey activities. Start with Handlebars iteration syntax to understand message personalization basics, or jump to Work with arrays in Journey expressions to learn how to pass array data to custom actions and dataset lookups.

Handlebars iteration syntax syntax

Handlebars provides the {{#each}} helper to iterate over arrays. The basic syntax is:

{{#each arrayPath as |item|}}
  <!-- Access item properties here -->
  {{item.property}}
{{/each}}

Key points:

Iterate over event data event-data

Event data is available when your journey is triggered by an event. This is useful for displaying data that was captured at the moment the journey started, such as cart contents, order items, or form submissions.

Context path for events

context.journey.events.<event_ID>.<fieldPath>

Example: Cart items from an event

If your event schema includes a productListItems array (standard XDM format), you can display cart contents as detailed in the sample below.

{{#each context.journey.events.event_ID.productListItems as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    <p>Quantity: {{product.quantity}}</p>
    <p>Price: ${{product.priceTotal}}</p>
  </div>
{{/each}}

Example: Nested arrays in events

For nested structures, use nested {{#each}} blocks.

{{#each context.journey.events.event_ID.categories as |category|}}
  <h2>{{category.name}}</h2>
  <ul>
    {{#each category.items as |item|}}
      <li>{{item.title}}</li>
    {{/each}}
  </ul>
{{/each}}

Learn more about nesting in Best practices.

Iterate over custom action responses custom-action-responses

Custom action responses contain data returned from external API calls. This is useful for displaying real-time information from your systems, such as loyalty points, product recommendations, inventory status, or personalized offers.

Context path for custom actions

context.journey.actions.<actionName>.<fieldPath>

Example: Product recommendations from an API

To iterate over an array of product recommendations returned from a custom action and display them as individual cards in your message, see the example below.

{
  "recommendations": [
    {
      "productId": "12345",
      "productName": "Summer Jacket",
      "price": 89.99,
      "imageUrl": "https://example.com/jacket.jpg"
    },
    {
      "productId": "67890",
      "productName": "Running Shoes",
      "price": 129.99,
      "imageUrl": "https://example.com/shoes.jpg"
    }
  ]
}

<h2>Recommended for You</h2>
<div class="recommendations">
  {{#each context.journey.actions.GetRecommendations.recommendations as |item|}}
    <div class="product-card">
      <img src="{{item.imageUrl}}" alt="{{item.productName}}" />
      <h3>{{item.productName}}</h3>
      <p class="price">${{item.price}}</p>
    </div>
  {{/each}}
</div>

Example: Nested arrays from custom actions

To iterate over a custom action response containing nested arrays (an array of objects, where each object contains another array), see the example below. This demonstrates using nested {{#each}} loops to access multiple levels of data.

{
  "id": "84632848268632",
  "responses": [
    { "productIDs": [1111, 2222, 3333] },
    { "productIDs": [4444, 5555, 6666] },
    { "productIDs": [7777, 8888, 9999] }
  ]
}

<h2>Product Groups</h2>
{{#each context.journey.actions.GetProducts.responses as |response|}}
  <div class="product-group">
    <ul>
      {{#each response.productIDs as |productID|}}
        <li>Product ID: {{productID}}</li>
      {{/each}}
    </ul>
  </div>
{{/each}}

For more complex nesting patterns, see Best practices.

Example: Loyalty tier benefits

To display dynamic benefits based on loyalty status, see the below example.

{
  "loyaltyTier": "gold",
  "benefits": [
    { "name": "Free shipping", "icon": "truck" },
    { "name": "20% discount", "icon": "percent" },
    { "name": "Priority support", "icon": "headset" }
  ]
}

<h2>Your {{context.journey.actions.GetLoyaltyInfo.loyaltyTier}} Member Benefits</h2>
<ul class="benefits">
  {{#each context.journey.actions.GetLoyaltyInfo.benefits as |benefit|}}
    <li>
      <span class="icon-{{benefit.icon}}"></span>
      {{benefit.name}}
    </li>
  {{/each}}
</ul>

Iterate over dataset lookup results dataset-lookup

The Dataset Lookup activity allows you to retrieve data from Adobe Experience Platform datasets during journey runtime. The enriched data is stored as an array and can be iterated over in your messages.

Learn more about configuring the Dataset Lookup activity in this section. Dataset lookup is particularly powerful when combined with event data - see Example: Event data enriched with dataset lookup for a practical use case.

Context path for dataset lookups

context.journey.datasetLookup.<activityID>.entities

Example: Product details from a dataset

If you’re using a Dataset Lookup activity to retrieve product information based on SKUs, see sample below.

<h2>Product Details</h2>
<table>
  <thead>
    <tr>
      <th>Product Name</th>
      <th>Category</th>
      <th>Price</th>
    </tr>
  </thead>
  <tbody>
    {{#each context.journey.datasetLookup.3709000.entities as |product|}}
      <tr>
        <td>{{product.name}}</td>
        <td>{{product.category}}</td>
        <td>${{product.price}}</td>
      </tr>
    {{/each}}
  </tbody>
</table>

Example: Filtered iteration with dataset data

To filter dataset lookup results during iteration and display only items matching specific criteria (e.g., products from a particular category), use conditional {{#if}} statements within your {{#each}} loop. See the example below.

<h2>Household Products</h2>
{{#each context.journey.datasetLookup.3709000.entities as |product|}}
  {{#if product.category = "household"}}
    <div class="product">
      <h3>{{product.name}}</h3>
      <p>Price: ${{product.price}}</p>
    </div>
  {{/if}}
{{/each}}

Learn more about conditional filtering in Best practices.

Example: Calculate totals from dataset lookup

To calculate and display totals while iterating over dataset lookup results, see the example below.

{% let householdTotal = 0 %}
{{#each context.journey.datasetLookup.3709000.entities as |product|}}
  {%#if product.category = "household"%}
    {% let householdTotal = householdTotal + product.price %}
  {%/if%}
{{/each}}

<p>Your household products total: ${{householdTotal}}</p>

Use journey technical properties technical-properties

Journey technical properties provide access to metadata about the journey execution, such as the journey ID and supplemental identifiers. These can be useful when combined with iteration patterns, especially for filtering arrays based on specific journey instances.

Available technical properties

context.journey.technicalProperties.journeyUID
context.journey.technicalProperties.supplementalId

Example: Filter array items using supplemental identifier

When using supplemental identifiers in event-triggered journeys with arrays, you can filter to show only the relevant item for the current journey instance. Learn more about supplemental identifiers in this guide.

Scenario: A journey is triggered with multiple bookings, but you want to display information only for the specific booking (identified by supplemental ID) that triggered this journey instance.

{{#each context.journey.events.event_ID.bookingList as |booking|}}
  {%#if booking.bookingInfo.bookingNum = context.journey.technicalProperties.supplementalId%}
    <div class="booking-details">
      <h3>Your Booking: {{booking.bookingInfo.bookingNum}}</h3>
      <p>Destination: {{booking.bookingInfo.bookingCountry}}</p>
      <p>Date: {{booking.bookingInfo.bookingDate}}</p>
    </div>
  {%/if%}
{{/each}}

Example: Include journey ID for tracking

To include the journey ID in your message for tracking purposes, see the example below.

<footer>
  <p>Journey Reference: {{context.journey.technicalProperties.journeyUID}}</p>
</footer>

Combine multiple context sources combine-sources

You can combine data from different sources in the same message to create rich, personalized experiences. This section shows practical examples of using multiple context sources together.

Context sources you can combine:

Example: Cart items with real-time inventory

To combine event data (cart contents) with custom action data (inventory status), view the sample below.

<h2>Your Cart</h2>
{{#each context.journey.events.cartEvent.productListItems as |product|}}
  <div class="cart-item">
    <h3>{{product.name}}</h3>
    <p>Quantity: {{product.quantity}}</p>
    <p>Price: ${{product.priceTotal}}</p>
  </div>
{{/each}}

<h2>We Also Recommend</h2>
{{#each context.journey.actions.GetRecommendations.items as |recommendation|}}
  <div class="recommendation">
    <h4>{{recommendation.name}}</h4>
    <p>${{recommendation.price}}</p>
    {{#if recommendation.inStock}}
      <span class="badge">In Stock</span>
    {{else}}
      <span class="badge out-of-stock">Out of Stock</span>
    {{/if}}
  </div>
{{/each}}

Example: Event data enriched with dataset lookup

To combine event SKUs with detailed product information from a dataset lookup, view the sample below.

<h2>Your Order Details</h2>
{{#each context.journey.events.orderEvent.productListItems as |item|}}
  <div class="order-item">
    <p><strong>SKU:</strong> {{item.SKU}}</p>
    <p><strong>Quantity:</strong> {{item.quantity}}</p>

    <!-- Enrich with dataset lookup data -->
    {{#each context.journey.datasetLookup.1234567.entities as |enrichedProduct|}}
      {{#if enrichedProduct.SKU = item.SKU}}
        <p><strong>Product Name:</strong> {{enrichedProduct.name}}</p>
        <p><strong>Category:</strong> {{enrichedProduct.category}}</p>
        <img src="{{enrichedProduct.imageUrl}}" alt="{{enrichedProduct.name}}" />
      {{/if}}
    {{/each}}
  </div>
{{/each}}

Example: Combine multiple sources with technical properties

To combine multiple context sources (profile data, event data, custom actions, and technical properties) in a single message, view the sample below.

<div class="personalized-content">
  <!-- Profile data -->
  <h1>Hello {{profile.person.name.firstName}},</h1>

  <!-- Event data iteration -->
  <h2>Your Recent Purchases</h2>
  {{#each context.journey.events.purchaseEvent.items as |purchase|}}
    <div class="purchase">
      <p>{{purchase.productName}} - ${{purchase.price}}</p>
    </div>
  {{/each}}

  <!-- Custom action response iteration -->
  <h2>Recommended for You</h2>
  {{#each context.journey.actions.GetPersonalizedRecs.recommendations as |rec|}}
    <div class="recommendation">
      <h3>{{rec.title}}</h3>
      <p>{{rec.description}}</p>
    </div>
  {{/each}}

  <!-- Technical properties -->
  <footer>
    <p class="fine-print">Journey ID: {{context.journey.technicalProperties.journeyUID}}</p>
  </footer>
</div>

Other context types other-contexts

While this guide focuses on iteration over arrays, other context types are available for personalization that typically don’t require iteration. These are accessed directly rather than looped over:

For complete personalization syntax and examples using these sources, refer to:

Work with arrays in Journey expressions arrays-in-journeys

While the previous sections focus on iterating over arrays in message personalization using Handlebars, you also work with arrays when configuring journey activities. This section explains how to use array data from events in Journey expressions, particularly when passing data to custom actions or using arrays with dataset lookups.

Pass array values to custom action parameters arrays-to-custom-actions

When configuring custom actions, you often need to extract values from event arrays and pass them as parameters. This section covers common patterns.

Learn more about passing collections in Pass collections into custom action parameters.

Extract a single value from an array

Use case: Get a specific field from an event array to pass as a query parameter in a GET request.

{
  "commerce": {
    "productListItems": [
      { "SKU": "SKU-1", "priceTotal": 10.0 },
      { "SKU": "SKU-2", "priceTotal": 0.0 },
      { "SKU": "SKU-3", "priceTotal": 20.0 }
    ]
  }
}

@event{YourEventName.commerce.productListItems.first(currentEventField.priceTotal > 0).SKU}

Build a list of values from an array

Use case: Create a comma-separated list of IDs to pass as a query parameter (e.g., /products?ids=sku1,sku2,sku3).

serializeList(
  @event{YourEventName.commerce.productListItems.all(currentEventField.priceTotal > 0).SKU},
  ",",
  true
)

Pass an array of objects to a custom action

Use case: Send a complete array of objects in a request body (for POST or GET with body).

{
  "ctxt": {
    "products": [
      {
        "id": "productA",
        "name": "Product A",
        "price": 20.1,
        "color": "blue"
      }
    ]
  }
}

Use arrays with dataset lookups arrays-with-dataset-lookup

When using the Dataset Lookup activity, you can pass an array of values as lookup keys to retrieve enriched data.

Example: Look up product details for all SKUs in an event array.

list(@event{purchaseEvent.productListItems.SKU})

Limitations and patterns array-limitations

Be aware of these limitations when working with arrays in journeys:

No dynamic looping over arrays in journey flow

Journeys cannot create dynamic loops where one action node is executed multiple times for each item in an array. This is intentional to prevent runaway performance issues.

What you cannot do:

Recommended patterns instead:

Learn more in Guardrails and limitations.

Array size considerations

Large arrays can impact journey performance:

Complete example: Event array to custom action complete-example

Here’s a complete workflow showing how to use an event array with a custom action.

Scenario: When a user abandons their cart, send cart data to an external recommendation API to get personalized suggestions, then display them in an email.

{
  "cartItems": [
    {
      "sku": "string",
      "price": 0,
      "quantity": 0
    }
  ]
}

{
  "recommendations": [
    {
      "productId": "string",
      "productName": "string",
      "price": 0,
      "imageUrl": "string"
    }
  ]
}

<h2>We noticed you left these items in your cart</h2>
{{#each context.journey.events.cartAbandonment.productListItems as |item|}}
  <div class="cart-item">
    <p>{{item.name}} - Quantity: {{item.quantity}}</p>
  </div>
{{/each}}

<h2>You might also like</h2>
{{#each context.journey.actions.GetCartRecommendations.recommendations as |rec|}}
  <div class="recommendation">
    <img src="{{rec.imageUrl}}" alt="{{rec.productName}}" />
    <h3>{{rec.productName}}</h3>
    <p>${{rec.price}}</p>
  </div>
{{/each}}

Best practices best-practices

Follow these best practices when iterating over contextual data to create maintainable, performant personalization.

Use descriptive variable names

Choose variable names that clearly indicate what you’re iterating over. This makes your code more readable and easier to maintain. Learn more about personalization syntax:

<!-- Good -->
{{#each products as |product|}}
{{#each users as |user|}}
{{#each recommendations as |recommendation|}}

<!-- Less clear -->
{{#each items as |item|}}
{{#each array as |element|}}

Expression fragments in loops

When using expression fragments within {{#each}} loops, be aware that you cannot pass loop-scoped variables as fragment parameters. However, fragments can access global variables that are defined in your message content outside of the fragment.

{% let globalDiscount = 15 %}

{{#each context.journey.actions.GetProducts.items as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    {{fragment id='ajo:fragment123/variant456' mode='inline'}}
  </div>
{{/each}}

{{#each products as |product|}}
  <!-- This will NOT work as expected -->
  {{fragment id='ajo:fragment123/variant456' currentProduct=product}}
{{/each}}

Learn more about using expression fragments inside loops, including detailed examples and additional workarounds.

Handle empty arrays

Use the {{else}} clause to provide fallback content when an array is empty. Learn more about helper functions:

{{#each context.journey.actions.GetRecommendations.items as |item|}}
  <div>{{item.name}}</div>
{{else}}
  <p>No recommendations available at this time.</p>
{{/each}}

Combine with conditional helpers

Use {{#if}} within loops for conditional content. Learn more about conditional rules and see examples in Custom action responses and Dataset lookup sections.

{{#each context.journey.actions.GetProducts.items as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    {{#if product.onSale}}
      <span class="badge">On Sale!</span>
    {{/if}}
    {{#if product.newArrival}}
      <span class="badge">New</span>
    {{/if}}
  </div>
{{/each}}

Limit iteration for performance

For large arrays, consider limiting the number of iterations:

<!-- Display only first 5 items -->
{{#each context.journey.actions.GetProducts.items as |product|}}
  {{#if @index < 5}}
    <div>{{product.name}}</div>
  {{/if}}
{{/each}}

Access array metadata

Handlebars provides special variables within loops that help with advanced iteration patterns:

{{#each products as |product|}}
  <div class="product {{#if @first}}featured{{/if}}">
    {{@index}}. {{product.name}}
  </div>
{{/each}}

Troubleshooting troubleshooting

Having issues with iteration? This section covers common problems and solutions.

Array not displaying

Issue: Your array iteration isn’t showing any content.

Syntax errors

Issue: Expression validation fails or message doesn’t render.

Expression fragments not working in loops

Issue: An expression fragment doesn’t display expected content when used inside an {{#each}} loop, or shows empty/unexpected output.

Testing your iterations

Use journey test mode to verify your iterations. This is especially important when using custom actions or dataset lookups:

Related topics related-topics

Personalization fundamentals: Get started with personalization | Add personalization | Personalization syntax | Helper functions | Create conditional rules

Journey configuration: About events | Configure custom actions | Pass collections into custom action parameters | Use API call responses in custom actions | Troubleshoot your custom actions | Use Adobe Experience Platform data in journeys | Use supplemental identifiers in journeys | Guardrails and limitations | Test your journey

Journey expression functions: Advanced expression editor | Collection management functions (first, all, last) | List functions (serializeList, filter, sort) | Array functions (head, tail)

Personalization use cases: Cart abandonment email | Order status notification

Message design: Get started with email design | Create push notifications | Create SMS messages | Preview and test your content