Send purchases to 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.

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.

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.

Add orchestration¶

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

To add an orchestration

Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.
From the Object type dropdown, select Query.
From the Object dropdown, select the query for which results is sent to Braze.
From the Destination dropdown, select a destination that is configured for sending data to Braze.
Verify all settings.
Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.
Click Save.

Run orchestration¶

Run the orchestration manually to validate that it works.

To run the orchestration

Open the Activations page, select the Orchestrations tab, and then open the menu for the Braze orchestration. Select Run.
The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.
When the orchestration has run successfully, the status is updated to “Completed”.

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.