Review the differences
Change the endpoints
Add the Notifly project prefix before each Braze path.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
Adddata_classification to Braze’s catalogs[0] object. Preserve the field order and make sure that the first field is id:string.
- 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
arrayvalue is an array of up to 100 strings. - A
geovalue uses[longitude, latitude]order. - A
timevalue is an ISO 8601 string or Unix seconds. It is normalized to a UTC ISO 8601 string when stored. - Keys in an
objectcannot 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.data.
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’serrors[] with code that reads Notifly’s error.code, error.message, and optional error.details.
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 theLink header.
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_itemsandcatalog_selection_itemsLiquid 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.
2. Export Braze items
CallGET /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
Adddata_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 bulkPUT /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, or413: 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 withPOST /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_itemsfrom Notifly’sGET /catalogsmatches 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, andtime,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
- 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.
- During a predefined observation period, compare item counts, hashes, key values, selection results, and API errors.
- When there are no mismatches or unresolved retries, switch reads and message Liquid to Notifly.
- 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.
- Stop writing to Braze after the rollback period has ended and both systems continue to match.
- Delete Braze Catalogs only after separate approval and backup verification.
