Operators Guide
Configure purchase events for Braze¶
Braze is a leading marketing automation platform for creating custom experiences based on sophisticated customer attributes and segments, and then mapping those experiences to campaigns.
Send purchase events to Braze using the Braze REST API. Each row returned by your query is sent as a single Braze purchase object to the /users/track endpoint and is matched to a Braze user profile by the identifier you choose. See the purchase object reference for more information.
Caution
Braze records and bills for every purchase you send as a data point. Amperity sends each row in the query result on every run and does not de-duplicate purchases against previous runs. Bound your query to recent purchases and avoid re-sending rows you have already sent, or Braze counts the revenue more than once. A row with a quantity greater than 100 is sent as more than one purchase object — for example, 250 becomes 100, 100, and 50 — and Braze bills each object as a separate data point.
Beta
The Braze Purchases connector is currently in beta. Contact your Amperity representative to learn more.
Get details¶
Review the following details before configuring credentials for Braze and before configuring Amperity to send purchase events to Braze.
|
Credential settings REST API key
|
|
|
Braze settings Instance
User identifier
Update existing profiles only?
|
|
|
Request properties
|
Configure credentials¶
Configure credentials for Braze before adding a destination.
An individual with access to Braze should use SnapPass to securely share “REST API key” details with the individual who configures Amperity.
To configure credentials for Braze Purchases
|
From the Settings page, select the Credentials tab, and then click the Add credential button. |
|
In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Braze Purchases. Note Amperity provides more than one Braze connector. Select Braze Purchases to send purchase events to the Braze REST API. Braze (profile attribute sync) and Braze Cohorts (audience membership) are separate connectors. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination. |
|
The settings that are available for a credential vary by credential type. For the “braze-purchases” credential type, configure settings, and then click Save. REST API key
|
Add destination¶
Use a sandbox to configure a destination for Braze. Before promoting your changes, send a sample audience, and then verify the results in Braze. After verifying the end-to-end workflow, push the destination from the sandbox to production.
To add a destination
|
|
Open the Destinations tab to configure a destination for Braze. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Braze purchases” and “Send purchase events to Braze.”. |
|
|
Credentials allow Amperity to connect to Braze. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box. |
|
|
In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows. |
|
Configure the following settings, and then click “Save”. Instance
User identifier
Update existing profiles only?
|
|
After configuring this destination users may use orchestrations to send query results Braze. |
|
Validate the audience with Braze by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Braze. Send the sample audience to Braze and verify the sample audience is correct in Braze. Make adjustments if necessary. Only send full audiences after validation is complete. |
Build a query¶
Use a query to build a combination of data — typically from the Unified Itemized Transactions and Customer 360 tables — that returns one row per purchase to send to Braze. Each row must include a column for the selected User identifier and columns for the purchase’s product_id, price, currency, and purchase_time. A quantity column is optional.
Review the Purchase object fields section for the columns your query must and may return, and the User identifiers section for the columns each identifier option requires.
Bound the query to recent purchases so each orchestration sends new purchases instead of re-sending purchases you have already sent. A query that returns recent purchases keyed by external_id is similar to:
1SELECT
2 c360.customer_id AS external_id
3 ,uit.product_id AS product_id
4 ,uit.unit_revenue AS price
5 ,uit.item_quantity AS quantity
6 ,uit.currency AS currency
7 ,uit.order_datetime AS purchase_time
8FROM Unified_Itemized_Transactions uit
9JOIN Customer_360 c360 ON uit.amperity_id = c360.amperity_id
10WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)
11 AND COALESCE(uit.is_return, false) = false
12 AND COALESCE(uit.is_cancellation, false) = false
Note
This example sends the per-unit unit_revenue column as price, because Braze computes revenue as price multiplied by quantity — map a per-unit price rather than a line total. When your data has only a line total, divide it by the quantity and guard against a zero or missing divisor, for example line_total / NULLIF(quantity, 0) AS price, or send quantity as 1 with the line total as price.
Note
The example filters out returns and cancellations so they are not sent as purchases and counted as revenue. A return can also carry a negative unit_revenue, which Amperity sends as a negative price (validation accepts it), so decide deliberately what to send.
Note
Map currency to a three-character ISO 4217 alphabetic code, such as USD. Amperity checks each value against the ISO 4217 code list and drops rows whose currency is not on it, so a source column that stores a value like “dollar” or “US Dollar” fails every row.
User identifiers¶
The User identifier setting selects how Amperity matches each purchase to a Braze user profile. Choose the identifier your Braze profiles are keyed on — typically the same one the Braze connector uses to sync profile attributes — so that purchases land on the right profiles.
braze_id — the Braze-assigned user ID. The query must return a braze_id column.
external_id — your own customer identifier. The query must return an external_id column.
user_alias — a Braze user alias, which is a name and label pair. The query must return both an alias_name and an alias_label column.
A row whose identifier value is empty is reported as failed. If the query does not return the column or columns for the selected identifier at all, the orchestration fails validation before sending anything.
Data validation¶
Amperity validates each row before sending and drops rows that Braze would reject, so that one invalid row does not cause the rest of a request to be rejected. Dropped rows are reported as failed with the reason. A row is dropped when:
the value for the selected User identifier is empty (for user_alias, either alias_name or alias_label is empty).
product_id is missing or is longer than 255 characters.
currency is not a valid ISO 4217 alphabetic currency code.
price is not a number.
purchase_time is missing or cannot be parsed as a date or timestamp.
quantity is present but is not a whole number, is less than 1 (including 0), or is larger than 7,500 (the most units Amperity can split one row into).
Purchase object fields¶
The following table describes each column Amperity sends to Braze as part of a purchase object . A query must return columns with the same name as listed in the “Amperity name” column; Amperity maps them to the Braze purchase object automatically.
Important
A query must return one row per purchase, including a column for the selected User identifier and columns for product_id, price, currency, and purchase_time. A quantity column is optional.
Amperity name |
Braze field |
Description |
|---|---|---|
Identifier column(s) |
external_id, braze_id, or user_alias |
Required The column or columns for the selected User identifier: an external_id column, a braze_id column, or an alias_name and alias_label pair. See User identifiers. |
product_id |
product_id |
Required An identifier for the purchase, such as a product name or product category. Maximum 255 characters. Braze shows up to 5,000 distinct values, so a product name or category is more useful than a SKU. |
price |
price |
Required The price for a single unit, as a number. Braze computes revenue as price multiplied by quantity. |
currency |
currency |
Required A three-character ISO 4217 alphabetic currency code. For example: “USD”. |
purchase_time |
time |
Required When the purchase occurred. Accepts a date- or time-typed column, a full ISO 8601 timestamp string, a date-only string, or an epoch-seconds value. A string timestamp must include a UTC offset, such as “2026-07-20T10:00:00Z” — a warehouse form without one, such as “2026-07-20 10:00:00”, is not accepted and the row is dropped. A date-only string, such as “2026-07-20”, is treated as midnight UTC. The column is named purchase_time because time is a reserved word in many warehouses. |
quantity |
quantity |
Optional A whole number of units. Braze defaults an absent quantity to 1. A quantity greater than 100 is split across multiple purchase objects (for example, 250 becomes 100, 100, and 50), which preserves the row’s total revenue; a single row can carry up to 7,500 units. |
Workflow actions¶
A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.
Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.
|
|
You may receive a notifications error for a configured Braze destination. This appears as an alert in the notifications pane on the Destinations tab. 
If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page. |
|
|
On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error. 
|
|
|
A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Braze, including: |
|
|
Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow. |
Note
Braze can accept a request and still reject individual purchases within it. Those rows are reported as failed with the message Braze returned for each, while the workflow itself succeeds — the state behind “the orchestration succeeded but some rows failed.” Amperity lists up to 10 such errors per request, followed by a summary line naming how many more were dropped. If Braze rejects an entire request, the workflow reports the error with Braze’s message for the whole request — review the purchase field values returned by your query. If sends are rate limited, Amperity retries automatically; reduce the volume of purchases sent per orchestration if the limit persists.
Invalid credentials¶
Braze rejected the REST API key. Braze returns the same error for a REST API key that is not valid and for a key used against the wrong instance, so verify that the key is still active, has the users.track permission, and belongs to the same Instance the destination is configured for.
To resolve this error, verify the credentials and instance configured for this workflow in Amperity.
Open the Credentials page and review the REST API key used with this workflow. Verify that it is still active and has the users.track permission.
Open the Destinations page and verify that the Instance setting for the Braze destination matches the instance the REST API key belongs to.
Return to the workflow action, and then click Resolve to retry this workflow.