> 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/manage.md).

# Manage Catalogs

This page covers how to keep a Catalog you have already created up to date. This includes adding new products, updating prices and stock, cleaning up discontinued products, adding fields, and deleting a Catalog itself.

For how to create a Catalog for the first time, see Create a Catalog, and for how to use it in messages, see Use a Catalog in Messages.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-f1600b85936db3b7489133798676deb518f5c127%2Fscreenshot-2026-09-21-pm-6.53.43.png?alt=media" alt=""><figcaption><p>Catalog detail screen</p></figcaption></figure>

## Edit items <a href="#undefined" id="undefined"></a>

You can edit items one at a time or change them all at once with a CSV. Use direct editing when you need to quickly fix just a few; otherwise a CSV is faster and less error-prone. Both start from the **Items tab > Edit items** button.

### **Add manually**

* Add an item: Edit items > Add manually → enter field values → Save.\
  \* `id` is required and cannot be duplicated.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-2cd6fbb51493864f275e3653a33a995db6a98da7%2Fscreenshot-2026-09-21-pm-5.27.35.png?alt=media" alt=""><figcaption></figcaption></figure>

#### **Edit directly in the list**

* Double-click the value you want to change in the list to edit it directly.
* After editing, click \[Save] at the top to save your changes.\
  \* `id` cannot be edited.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-5c3685cab549c6b2c62a66115284729639b0c09a%2Fscreenshot-2026-09-22-am-10.01.06.png?alt=media" alt=""><figcaption><p>Edit directly in the list</p></figcaption></figure>

* Delete an item: Select it with the checkbox on the left of the list, then delete it.

### CSV upload

When you click **Edit items > CSV upload**, you first choose an upload method. The behavior differs depending on whether the CSV `id` already exists in the Catalog, so choosing the wrong method produces unintended results.

When uploading an item CSV, the CSV header must include all of the fields you defined beforehand.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-0991fa8662759a872a8707d768a1cbb55a352a76%2Fscreenshot-2026-09-21-pm-5.31.04.png?alt=media" alt=""><figcaption></figcaption></figure>

Item uploads run in the background. They continue even if you close the screen, and you can check the result in the Catalog details once complete. Only one CSV upload can run at a time for a single Catalog.

{% hint style="info" %}
**If the CSV has rows with the same id, they are handled as follows.**

* Add new items only: The value of the row that appears earlier is applied.
* Update existing items only: The value of the row that appears later is applied.
* Add and update: The value of the row that appears later is applied.
  {% endhint %}

#### CSV file preparation checklist <a href="#csv-checklist" id="csv-checklist"></a>

Before uploading, make sure your file meets all of the conditions below. If even one is missing, the upload fails or values are uploaded empty.

<table><thead><tr><th width="153.296875">Item</th><th>Requirement</th></tr></thead><tbody><tr><td>Header</td><td>The first row contains the field names. These names become the Catalog's field names as they are.<br>Field names can use only letters, numbers, <code>-</code>, and <code>_</code>.</td></tr><tr><td><code>id</code> column</td><td>Required. The name must be exactly <code>id</code>, and the column order does not matter.</td></tr><tr><td><code>id</code> value</td><td>No duplicates · up to 300 characters · only letters, numbers, <code>-</code>, and <code>_</code> can be used.</td></tr><tr><td>Number of columns</td><td>Up to 50</td></tr><tr><td>Value format</td><td>The values in each column must match the type (string, number, boolean, time).<br>Number columns must not contain units or commas, and date columns must be in ISO 8601 format with a time zone offset.</td></tr><tr><td>Undefined values</td><td>Empty cells are allowed.<br>Values such as <code>NULL</code>, <code>null</code>, and <code>-</code> are stored as text, not as empty values, so leave the cell blank instead.</td></tr><tr><td>File format</td><td>CSV, UTF-8 encoding</td></tr><tr><td>File size</td><td>Up to 500MB</td></tr><tr><td>Number of items</td><td>Up to 1 million (based on <code>id</code>)</td></tr></tbody></table>

#### Catalog data types <a href="#catalog-data-types" id="catalog-data-types"></a>

Catalogs support a variety of data types that help you organize and structure your data effectively.

<table><thead><tr><th width="98.30078125">Data type</th><th width="168.7890625">Format</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>String</td><td>Text</td><td>Free-form text. Korean characters, special characters, and spaces are allowed (up to 750 characters)</td><td><code>"Hello World"</code></td></tr><tr><td>Number</td><td>Integer or decimal</td><td>A number you can calculate with. Integers, decimals, and signs are allowed (20 digits for the integer part · 10 digits for the decimal part)</td><td><code>42000</code> or <code>19.99</code></td></tr><tr><td>Boolean</td><td><code>true</code> or <code>false</code></td><td>A value that is one of two. true/false (case-insensitive) or 1/0</td><td><code>true</code></td></tr><tr><td>Time</td><td>ISO 8601</td><td>A valid ISO 8601 format with a time zone specified</td><td><code>"2026-09-15T09:00:00Z"</code></td></tr></tbody></table>

## Manage fields

Fields are managed in the **Fields tab**. You can add fields, edit descriptions, and delete fields, but **once a field is created, its name and type cannot be changed.** This is because messages look up values by field name.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-79ab167237d150551caafa8f36427b92811a386b%2Fscreenshot-2026-09-21-pm-7.07.03.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-c8f072b30d40b2ce0f94b6c6f6f67502007d4300%2Fscreenshot-2026-09-21-pm-5.25.37.png?alt=media" alt=""><figcaption><p>Add field input window</p></figcaption></figure>

* **Add a field**: Possible at any time. However, once you add a field, the item CSV headers you upload afterward must also include that field.
  * A new field starts as empty for all existing items. Upload a CSV containing only the `id` and the new field column with **Update existing items only** to fill in the values all at once.
* **Delete a field**: Possible, but if you delete a field while items exist, **all values in that field are lost and this cannot be undone.** First check whether any messages reference that field.
* **Change a field type**: Not possible. You must delete the field and create it again.

{% hint style="warning" %}
**Do not delete a field that is used by a message being sent.**

A message that references a deleted field is sent with that spot empty. Before deleting, first clean up the messages that use this field.
{% endhint %}

## Delete a Catalog

Click the trash icon at the top right of the Catalog detail screen and a deletion confirmation window appears. The Catalog and all items in it are deleted, and they disappear from both the production and development Environments. This cannot be undone.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-46bd8be37075389808347b56e6ec24bcb92f9e84%2Fscreenshot-2026-09-22-am-10.41.48.png?alt=media" alt=""><figcaption></figcaption></figure>


---

# 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/manage.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.
