> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Braze Catalogs

> Compare the APIs, convert requests, and migrate Braze Catalog data and integrations to the Notifly Catalog REST API.

Braze Catalogs and Notifly Catalogs use similar paths and request structures for catalogs, items, fields, and selections. They differ in **base URLs and authentication**, **project paths**, **response envelopes**, **synchronous and asynchronous status codes**, and **data classification declarations**. Changing the URL alone is not enough to migrate an integration.

This guide compares the official Braze Catalog API and the Notifly Catalog REST API as of August 4, 2026. Before migration, also check the REST endpoint for your Braze cluster and the latest Braze documentation.

## Review the differences

| Item | Braze Catalog API | Notifly Catalog API |
| - | - | - |
| Base URL | REST endpoint for the workspace's cluster | `https://api.notifly.tech` |
| Authentication | REST API key sent as a Bearer token | Bearer token issued with an Access Key and Secret Key, valid for one hour |
| Project identification | Determined by the API key's workspace | Every path includes `/v1/projects/{projectId}` |
| Data classification | No separate field in the creation request | Requires `data_classification: "non_personal"` |
| Response | Primarily `message`, `catalogs`, `items`, and `errors` | `{ "data": ..., "error": ... }` envelope |
| Catalog and item deletion, bulk item writes, and field and selection writes | Synchronous or asynchronous depending on the endpoint, usually `202` on success | Processed within the request, returns `200` |
| Catalog field limit | Up to 500 through the REST API. CSV uploads support up to 1,000 columns | Up to 500 for API catalogs, including `id` |
| Item pages | 50 items, with a `Link` header and cursor | 50 items, with a `Link` header and `data.next_cursor` |
| Selection input | Includes `external_id` and `source` | Does not accept either field. Identifies selections by `name` |
| Dedicated rate limits | Synchronous catalog endpoints share 50 req/min. Synchronous item endpoints share a separate 50 req/min. Asynchronous field and selection endpoints share another 50 req/min. Asynchronous bulk item endpoints share 16,000 req/min | The public API contract does not specify shared endpoint limits equivalent to Braze's |

> [!WARNING]
>
> Do not migrate data unchanged if it contains personal information such as names, email addresses, phone numbers, or external user IDs.
> Notifly API catalogs support only non-personal reference data.

## Change the endpoints

Add the Notifly project prefix before each Braze path.

```text theme={null}
Braze:   https://{BRAZE_REST_ENDPOINT}/catalogs/{catalog_name}/items
Notifly: https://api.notifly.tech/v1/projects/{projectId}/catalogs/{catalogName}/items
```

Braze path parameters `catalog_name`, `item_id`, and `field_name` are written as `catalogName`, `itemId`, and `fieldName` in Notifly. Their URL values and purpose remain the same.

### Catalogs

| Operation | Method and suffix | Notifly success status |
| - | - | - |
| List | `GET /catalogs` | `200` |
| Create | `POST /catalogs` | `201` |
| Delete | `DELETE /catalogs/{catalogName}` | `200` |

### Items

| Operation | Method and suffix | Notifly success status |
| - | - | - |
| List a page | `GET /catalogs/{catalogName}/items` | `200` |
| Get one item | `GET /catalogs/{catalogName}/items/{itemId}` | `200` |
| Create one item | `POST /catalogs/{catalogName}/items/{itemId}` | `201` |
| Replace or upsert one item | `PUT /catalogs/{catalogName}/items/{itemId}` | `200` |
| Partially update one item | `PATCH /catalogs/{catalogName}/items/{itemId}` | `200` |
| Delete one item | `DELETE /catalogs/{catalogName}/items/{itemId}` | `200` |
| Create up to 50 items | `POST /catalogs/{catalogName}/items` | `200` |
| Replace or upsert up to 50 items | `PUT /catalogs/{catalogName}/items` | `200` |
| Partially update up to 50 items | `PATCH /catalogs/{catalogName}/items` | `200` |
| Delete up to 50 items | `DELETE /catalogs/{catalogName}/items` | `200` |

`PUT` replaces all values of each submitted item and creates the item if it does not exist. `PATCH` changes only the submitted fields of an existing item and returns `404` for an unknown ID. Array fields support the same `$add` and `$remove` operations as Braze.

```json theme={null}
{
  "items": [
    {
      "id": "sku-001",
      "tags": {
        "$add": ["sale"],
        "$remove": ["new"]
      }
    }
  ]
}
```

### Fields and selections

| Operation | Method and suffix | Notifly success status |
| - | - | - |
| Add fields | `POST /catalogs/{catalogName}/fields` | `200` |
| Delete a field | `DELETE /catalogs/{catalogName}/fields/{fieldName}` | `200` |
| Create a selection | `POST /catalogs/{catalogName}/selections` | `200` |
| Delete a selection | `DELETE /catalogs/{catalogName}/selections/{selectionName}` | `200` |

Remove Braze's `external_id` and `source` fields from Notifly selection creation requests. Filter values cannot be `null`. For the operators allowed for each field type, see [Get started with the Catalog REST API](https://docs.notifly.tech/en/api-reference/catalogs/getting-started.md#selection-filters).

```diff theme={null}
 {
   "selection": {
     "name": "sale-products",
     "description": "할인 상품",
-    "external_id": "sale-products-v1",
-    "source": "custom",
     "filters": [
       { "field": "discount", "operator": "greater than", "value": 0 }
     ],
     "results_limit": 20,
     "sort_field": "discount",
     "sort_order": "desc"
   }
 }
```

## Change the authentication code

Instead of sending a Braze REST API key with every request, obtain an authentication token from Notifly's `/authenticate` endpoint and reuse it. The token is valid for one hour.

```javascript theme={null}
async function issueNotiflyToken() {
  const response = await fetch("https://api.notifly.tech/authenticate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      accessKey: process.env.NOTIFLY_ACCESS_KEY,
      secretKey: process.env.NOTIFLY_SECRET_KEY
    })
  });

  const body = await response.json();
  if (!response.ok || typeof body.data !== "string") {
    throw new Error(`Notifly authentication failed: ${response.status}`);
  }
  return body.data;
}
```

> [!NOTE]
>
> In production, cache the token in memory until it expires instead of issuing a new token for every request.
> Do not log the Access Key, Secret Key, token, or authentication response body.
> See [API overview](https://docs.notifly.tech/en/api-reference/getting-started.md).

## Convert catalog creation requests

Add `data_classification` to Braze's `catalogs[0]` object. Preserve the field order and make sure that the first field is `id:string`.

```diff theme={null}
 {
   "catalogs": [
     {
       "name": "products",
       "description": "Product catalog",
+      "data_classification": "non_personal",
       "fields": [
         { "name": "id", "type": "string" },
         { "name": "name", "type": "string" },
         { "name": "price", "type": "number" }
       ]
     }
   ]
 }
```

Before creating a catalog, check these constraints.

* If there are more than 500 fields, remove unused fields or split the catalog.
* Catalog identifiers, field identifiers, and item IDs can contain up to 250 characters. Use only English letters, digits, hyphens, and underscores.
* An `array` value is an array of up to 100 strings.
* A `geo` value uses `[longitude, latitude]` order.
* A `time` value is an ISO 8601 string or Unix seconds. It is normalized to a UTC ISO 8601 string when stored.
* Keys in an `object` cannot contain periods (`.`) or dollar signs (`$`).
* A string value can contain up to 5,000 characters. An item can be up to 1 MiB.

## Change response handling

### Success responses

Braze returns a success message when it creates a single item.

```json theme={null}
{ "message": "success" }
```

Notifly returns the created or retrieved resource in `data`.

```json theme={null}
{
  "data": {
    "id": "sku-001",
    "name": "에브리데이 백팩",
    "price": 59000
  },
  "error": null
}
```

Successful bulk, field, selection, and deletion requests return an empty success response.

```json theme={null}
{ "data": null, "error": null }
```

If your code checks only `response.message === "success"` or `status === 202`, change it to check `response.error === null` and the endpoint's expected status, `200` or `201`.

### Error responses

Replace code that parses Braze's `errors[]` with code that reads Notifly's `error.code`, `error.message`, and optional `error.details`.

```json theme={null}
{
  "data": null,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid bulk item request.",
    "details": [
      {
        "field": "items[0].unknown_field",
        "path": ["items", 0, "unknown_field"],
        "code": "invalid-fields",
        "message": "Unrecognized field: unknown_field."
      }
    ]
  }
}
```

Handle errors by HTTP status and `error.code`, rather than comparing error message strings. When `details` is present, use `field` or `path` to identify invalid input.

### Pagination

Both APIs return up to 50 items per page. Notifly provides the next cursor in both the response body and the `Link` header.

```json theme={null}
{
  "data": {
    "items": [],
    "next_cursor": "eyJhZnRlciI6InNrdS0wNTAifQ",
    "links": {
      "next": "/v1/projects/.../catalogs/products/items?cursor=..."
    }
  },
  "error": null
}
```

Code that follows Braze's `Link` header can continue to use the header. A new implementation can instead request pages until `data.next_cursor` is `null`. Cursor values use an internal API format. Do not interpret them or construct them yourself.

## Migrate the data

### 1. Inventory your Braze assets

Record the following information.

* Catalog names, descriptions, field order, and field types.
* Item counts and total data size.
* The `catalog_items` and `catalog_selection_items` Liquid tags used in messages.
* Selection names, filters, sort settings, and result limits.
* Batch jobs, webhooks, operational tools, and API key permissions that use the catalogs.
* Whether each catalog has no more than 500 fields, including `id`, and JSON nesting is no deeper than 50 levels.
* Whether object keys contain `.` or `$`, and whether any data contains personal information.

The public Braze API does not have an endpoint to list selections. Retrieve selection definitions separately from the Braze Dashboard and your existing configuration sources.

### 2. Export Braze items

Call `GET /catalogs/{catalog_name}/items` and collect items in pages of 50 until the `Link` header no longer contains `rel="next"`. Keep the exported JSON and item count as an unchanged record of the source data.

Store migration files in encrypted storage and grant the migration team only the access they need. Set a retention period and delete the files after the verification and rollback periods end. If you find personal information, stop the migration and isolate the files. Remove those fields or move them to user properties before continuing. Do not paste file contents or credentials into tickets, chats, or application logs.

### 3. Create Notifly catalogs

Add `data_classification: "non_personal"` to the Braze catalog definition and send it to `POST /v1/projects/{projectId}/catalogs`. Creating a catalog with the same name again causes a conflict. Before rerunning the operation, check whether the catalog already exists.

### 4. Import items

Keep Braze as the source of truth until migration is complete. Split the exported items into batches of up to 50. Reduce the batch size further if the request body approaches 4 MiB.

For a full copy that you may need to repeat, use bulk `PUT /catalogs/{catalogName}/items`. It replaces existing items with the same IDs and creates missing items. Use `POST` only when you want to accept new items and treat duplicates as errors.

For each batch, record the catalog name, method, sorted item IDs, item count, request body hash, start and completion times, and result status in a checkpoint. Changes within one request are transactional. Mark the batch as complete only after you receive `200`.

If you receive no response or a `500` response, do not immediately repeat the same `POST`. Use single-item `GET /items/{itemId}` requests to check which items in the batch were applied, then resend only missing items. For `PUT`, you can reapply the full request body. Use exponential backoff with jitter and handle retries as follows.

* `401`: Obtain a new authentication token, then retry.
* Network timeout or `500`: Check whether the changes were applied, then retry a limited number of times.
* `400`, `403`, `404`, `409`, or `413`: Do not retry automatically until you fix the input, permissions, target resource, duplicate, or batch size.

### 5. Recreate selections

After all items are loaded, recreate the selections recorded in the inventory with `POST /catalogs/{catalogName}/selections`, one at a time. Remove `external_id` and `source` from the Braze request. Apply the operator rules for each field type and the restriction on `null` values.

After each `200` response, record the selection name and request hash in the checkpoint. The public Notifly API has no endpoint to list or update selections. If a timeout leaves the result unknown, first test Liquid that uses the selection to check whether it exists and returns the expected results. Delete and recreate a selection only if its definition is wrong, after checking the impact of deletion.

When you subsequently change items or fields, stored selection results are recalculated within the same request.

### 6. Verify the migration

* Check that `num_items` from Notifly's `GET /catalogs` matches the number of items exported from Braze.
* Retrieve every page again and compare the sets of IDs, request body hashes, and key field values.
* Run the Liquid used in production in message previews.
* Test edge cases, including missing IDs, empty arrays, `null`, Korean text, emoji, and `time`, `geo`, object, and array values.
* Compare item counts and sort results for each selection. Selections without a sort setting return random results, so do not expect the same order.
* Confirm that no batch or selection checkpoint remains unresolved.

### 7. Switch the integration

1. Continue to use Braze for reads and message rendering. Apply writes to Braze first, then send the same changes to Notifly. Add failed Notifly writes to a retry queue.
2. During a predefined observation period, compare item counts, hashes, key values, selection results, and API errors.
3. When there are no mismatches or unresolved retries, switch reads and message Liquid to Notifly.
4. If mismatches, persistent API errors, or Liquid rendering errors occur after the switch, restore reads to Braze. Stop writes that go only to Notifly and resynchronize from the checkpoints.
5. Stop writing to Braze after the rollback period has ended and both systems continue to match.
6. Delete Braze Catalogs only after separate approval and backup verification.

> [!WARNING]
>
> Do not delete Braze Catalogs during migration. First verify Notifly's item counts, key values, and Liquid rendering.
> Remove the Braze catalogs in a separate change after verification.

## Migrate Liquid

The basic syntax is the same. If you keep the catalog and field names, most Liquid can remain unchanged.

```liquid theme={null}
{% catalog_items products {{ user["favorite_product_id"] }} %}
{% if items.size > 0 %}
  {{ items[0].name }} - {{ items[0].price }}원
{% endif %}
```

```liquid theme={null}
{% catalog_selection_items products sale-products %}
{% for item in items %}
  {{ item.name }}
{% endfor %}
```

> [!WARNING]
>
> If a value rendered with `:rerender` in Braze contains another `catalog_items` or `catalog_selection_items` tag,
> remove the nested tag or flatten it to one level before migration. Notifly treats recursive catalog tags as rendering errors.

Matching Liquid syntax does not mean the API responses match. Update the Catalog REST client's authentication, URLs, status code handling, and response parser separately, as described above.

## Official resources

* [Braze Catalog API](https://www.braze.com/docs/api/endpoints/catalogs)
* [Braze: Create catalog](https://www.braze.com/docs/api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog)
* [Braze: List multiple catalog item details](https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk)
* [Braze: Create catalog items in bulk](https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/asynchronous/post_create_catalog_items_bulk)
* [Braze: Create catalog selection](https://www.braze.com/docs/api/endpoints/catalogs/catalog_selections/asynchronous/post_create_catalog_selections)
* [Braze API rate limits](https://www.braze.com/docs/api/api_limits)
* [Notifly catalog guide](https://docs.notifly.tech/en/user-guide/catalogs/guide.md)
* [Get started with the Notifly Catalog REST API](https://docs.notifly.tech/en/api-reference/catalogs/getting-started.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.