Skip to main content
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

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

Items

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.

Fields and selections

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.

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

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.
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.
Notifly returns the created or retrieved resource in data.
Successful bulk, field, selection, and deletion requests return an empty success response.
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.
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.
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.
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.
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