> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/catalog/use.md).

# Using Catalogs

Learn how to load catalog data into a message to personalize it.

This feature loads a catalog you have set up in advance into the message body at send time. Data that many users share — such as product information, store lists, and content metadata — can be managed separately from user properties.

{% hint style="info" %}
**Before you start**

To use a catalog in a message, the catalog and its data must be ready first.

For catalog creation and item uploads, see [Catalog Management](https://docs.hackle.io/en/development-guide/http-api/catalog.md).
{% endhint %}

### Basic Syntax

{% code overflow="wrap" %}

```liquid
{% catalog_items <catalog_name> <item_id> [item_id] [item_id] %}
```

{% endcode %}

The lookup result is stored in the **`items` variable**, which you then use in the body as `items[index].field_name`.

{% code overflow="wrap" %}

```liquid
{% catalog_items Games 1234 %}{{ items[0].title }} is now {{ items[0].price }} won
→ Super Mario is now 49000 won
```

{% endcode %}

#### Parameter Details

<table><thead><tr><th width="178.9375">Parameter</th><th width="416.46875">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>&#x3C;catalog_name></code></td><td>Name of the catalog to look up</td><td>✅</td></tr><tr><td><code>&#x3C;item_id></code></td><td>ID of the item to look up. Separate with spaces, <strong>up to 3</strong></td><td>At least 1 required</td></tr></tbody></table>

***

### Supported Features

**Looking up multiple items** — up to 3 in a single tag

{% code overflow="wrap" %}

```liquid
{% catalog_items Games 1234 1235 1236 %}{{ items[0].title }}, {{ items[1].title }}, {{ items[2].title }}
```

{% endcode %}

**Using personalization variables for item IDs**

{% code overflow="wrap" %}

```liquid
{% catalog_items Games {{ user_properties["last_viewed_item"] }} %}{{ items[0].title }}
```

{% endcode %}

**Applying filters**

{% code overflow="wrap" %}

```liquid
{{ items[0].price | default: "Contact us for pricing" }}
```

{% endcode %}

**Using values that match the field type** — values are passed through as-is according to the catalog field type

| Field Type | Value in the Message                           |
| ---------- | ---------------------------------------------- |
| STRING     | String                                         |
| NUMBER     | Number (calculations and filters can be used)  |
| BOOLEAN    | `true` / `false` (can be used in conditionals) |
| TIME       | ISO-8601 string (e.g., `2026-08-20T00:00:00Z`) |

**Referencing the item ID itself** — `{{ items[0].id }}`

***

### Response Handling Rules

| Situation                                     | Behavior                                                        |
| --------------------------------------------- | --------------------------------------------------------------- |
| Successful lookup                             | The items are stored in `items`                                 |
| The requested item is not in the catalog      | **Only that position is empty**; the other items are unaffected |
| The lookup fails (a temporary error, etc.)    | Everything is empty                                             |
| The variable in the item ID position is empty | **Only that position is empty**                                 |
| The catalog name is empty                     | The entire tag is skipped (`items` is empty)                    |
| Four or more item IDs are specified           | The entire tag is skipped                                       |

{% hint style="warning" %}
Whether or not a response is returned, the message send does not fail. If a value cannot be retrieved, the message is sent with that position left empty.

Before sending the message, check the value with an `if` statement and display a fallback text.
{% endhint %}

#### Positions do not shift when an item is missing

The order and position of the requested item IDs are preserved as-is. Even if the item in the middle is deleted, the index of the items after it is not pulled forward.

{% code overflow="wrap" %}

```liquid
{% catalog_items Games 1234 MISSING_ID 1236 %}[{{ items[0].title }}] [{{ items[1].title }}] [{{ items[2].title }}]
→ [Super Mario] [] [The Legend of Zelda]
```

{% endcode %}

`items[2]` is always the third item you specified. When one item is deleted, another product's information is never displayed in its place.

***

### Error Handling and Defensive Patterns

Because a value may be empty, we recommend the following two approaches.

**1. Set a fallback value — the `default` filter**

{% code overflow="wrap" %}

```liquid
{% catalog_items Games 1234 %}Check out {{ items[0].title | default: "our popular products" }}
```

{% endcode %}

**2. Branch on a condition — the `if` statement**

{% code overflow="wrap" %}

```liquid
{% catalog_items Games 1234 %}{% if items[0] %}  {{ items[0].title }} is {{ items[0].price }} won!{% else %}  Check out this week's new releases{% endif %}
```

{% endcode %}

When you use multiple items, you can check each position separately.

{% code overflow="wrap" %}

```liquid
{% catalog_items Games 1234 1235 %}{% if items[1] %}Meet {{ items[1].title }} as well{% endif %}
```

{% endcode %}

If you need the total count, use the `size` filter. Empty positions are included in the count.

{% code overflow="wrap" %}

```liquid
{{ items | size }}
```

{% endcode %}

***

### Practical Examples

**1. Introducing a single product**

{% code overflow="wrap" %}

```liquid
{% catalog_items Products SKU-1001 %}{{ items[0].name }} is available for {{ items[0].discount_price }} won
```

{% endcode %}

**2. The product the user last viewed**

{% code overflow="wrap" %}

```liquid
{% catalog_items Products {{ user_properties["last_viewed_sku"] }} %}{% if items[0] %}  Still thinking it over? {{ items[0].name }} is waiting for you{% else %}  Check out this week's recommended products{% endif %}
```

{% endcode %}

**3. Announcing the ordered product with an event property**

{% code overflow="wrap" %}

```liquid
{% catalog_items Products {{ event_properties["sku"] }} %}Your order for {{ items[0].name }} is complete
```

{% endcode %}

**4. Three products at once**

{% code overflow="wrap" %}

```liquid
{%- catalog_items Products SKU-1001 SKU-1002 SKU-1003 -%}
This week's Top 3
No.1: {{ items[0].name }}
No.2: {{ items[1].name }}
No.3: {{ items[2].name }}
```

{% endcode %}

**5. Branching on a BOOLEAN field**

{% code overflow="wrap" %}

```liquid
{% catalog_items Products SKU-1001 %}{% if items[0].on_sale %}  🔥 {{ items[0].name }} special offer in progress{% else %}  Come and see {{ items[0].name }}{% endif %}
```

{% endcode %}

**6. Using an image URL**

An image URL field can also be stored and used as a string. When you enter it in an image area, do not put a space or a line break between the tag and the URL output.

{% code overflow="wrap" %}

```liquid
{% catalog_items Products SKU-1001 %}{{ items[0].image_url }}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/en/catalog/use.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
