Send query results to Braze

You can send customer profile and custom attributes to Braze using a query and orchestration. Build a SQL query that returns a list of active customers, and then associate that list of active customers with the custom attributes that you want to send to Braze from Amperity. Send the results of a query for active customers as often as you need; send updates for all custom attributes on a less frequent basis.

This topic describes the steps that are required to send custom attributes to Braze from Amperity:

1. About custom attributes

2. Build a query

3. Add orchestration

4. Run orchestration

Note

Braze must be enabled before you can configure an orchestration to send query results.

About Braze attributes

Attributes in Braze describe your customers.

• Profile attributes describe who your customers are. For example: names, birthdates, email addresses, and phone numbers.

• Custom attributes describe how your customers have interacted with your brand. For example: purchase histories, loyalty status, and value tiers.

When user profile fields and custom attributes are available in Braze they can be used to build out audience segments and to apply personalization to your campaigns.

Customer profiles

Customer profiles in Braze are represented by a set of user profile fields . To update these fields in Braze you must follow a strict naming convention when sending data from Amperity. These fields are also case sensitive (and are in lowercase).

What about email and phone subscription status?

Braze uses two fields to track email and phone subscription status: email_subscribe and push_subscribe. Braze should be your source of truth for customer consent and for tracking email and phone subscription status.

An orchestration can send customer profile updates to Braze as the results of a query. For example:

SELECT
  amperity_id AS external_id
  ,given_name AS first_name
  ,surname AS last_name
  ,email
  ,phone
  ,city AS home_city
  ,country
  ,birthdate AS dob
  ,gender
FROM Customer_360

The following table describes the default user profile fields that are most commonly updated from Amperity:

Braze default field	Amperity field name	Description
external_id	varies	Required. The external_id is a unique identifer for user profiles in Braze. The external_id is a unique identifier that exists in another system, such as the Amperity ID, a loyalty ID, or some other unique customer identifier.
first_name	given_name	Optional.
last_name	surname	Optional.
email	email	Optional.
phone	phone	Optional.
home_city	city	Optional.
country	country	Optional. Must be in ISO 3166-1 alpha-2 format.
dob	birthdate	Optional. Must be in “YYYY-MM-DD” format.
gender	gender	Optional. Accepted values: “M”, “F”, “O” (other), “N” (not applicable), “P” (prefer not to say), or NULL.

Note

Default user profile fields also exist for alias_name, alias_label, current_location, date_of_first_session, date_of_last_session, email_open_tracking_disabled, email_click_tracking_disabled, email_subscribe, facebook, language, marked_email_as_spam_at, push_subscribe, push_tokens, subscription_groups, time_zone, and twitter.

These fields are not commonly sent to Braze from Amperity, but if your brand chooses to update these user profile fields from Amperity, be sure to use the exact name of the default field name, send the correct value (or values), and to use lowercase.

Custom attributes

Custom attributes in Braze are represented by a set of custom-named fields. The names of these fields are determined by your brand. They may already exist in Braze, in which case you will want to shape the output that is sent from Amperity to align to the names you already have.

The names of custom attributes that can be managed by Amperity are defined by your brand. The names are strings, may contain hyphens, spaces, or underscores, may include numbers, and may contain a mix of lowercase and uppercase letters. For example, custom attribute can have names that:

• Already exist within your organization.

• Are exactly the same as Amperity standard output, such as “One and Done” or “L12M Monetary” (the “monetary” component of an RFM score), or “Early Repeat Purchaser”.

• Align to marketing goals and/or terminology that exists within your brand’s segmentation strategy.

Verify the names of custom attributes that will be sent to Braze from Amperity. Amperity will add a custom attribute whenever there isn’t a matching name.

Tip

Avoid sending custom attributes as duplicates of default user profile fields. For example, birthdates should be sent to Braze as a user profile field named “dob”. If they are sent as “birthday”, “Birthdate”, or any other string, a custom attribute will be created and the values in the “dob” field will not be updated.

Important

Your brand’s list of custom attributes should be a list that is mostly static, remains stable over time, and is focused on your most valuable customers.

Only update custom attributes for customers to which your brand is currently engaged. Define an audience in Amperity that is some combination of “high value” (historical or predicted), “active” (has purchased recently), and are “contactable” (with an opt-in status of true for phone numbers and/or email addresses).

This will help ensure that you are only updating custom attributes for your most valuable customers. Custom attributes will be updated only for those customers have a matching “external_id” or “braze_id” within Braze.

Use in Braze segments

The list of custom attributes that is managed by Amperity is available from the Data Settings page in Braze. Click Data Settings in the left-side navigation, and then choose Custom Attributes. This will open a page similar to:

Custom attributes are listed alphabetically and are case-sensitive. For example, One and Done, one and done, and One_and_Done are unique custom attributes within Braze.

Custom attributes are available from a filter when you build segments in Braze. Add a filter, and then choose Custom Attributes:

and then select any of your Amperity-managed custom attributes for use in your Braze segment:

About data points

Braze uses data points to determine when to update segment membership, to identify which types of messages should be sent, and how to apply message personalization.

You can send custom attributes to Braze from Amperity by attaching attributes from your customer profiles in Amperity, such as first and last names, email addresses, phone numbers, physical locations, SMS and email consent status, purchase histories, and so on.

Amperity tracks changes as they are sent to Braze and only sends list membership and attribute that have changed since the previous update.

Note

Data points are part of the billing and pricing structure in your Braze contract. Some data points are non-billable; many data points are billable.

Review the lists of non-billable and billable data points , and then review those lists against the attributes you will send to Braze from Amperity to understand which of those attributes are considered billable or non-billable data points.

Important

Connected Content does not write data to user profiles, which means you can use Connected Content to dynamically populate values into messages without consuming data points.

Build query

Use the query editor to filter by the user identifier associated with your segment in Braze – “external_id” or “braze_id” – and then return the list of custom attributes. Use an orchestration to send the results of this query to Braze.

For example, ACME wants to manage custom attributes in Braze by sending customer profile attributes, along with set of purchase history attributes. The following example uses the following standard output tables:

1. Merged Customers for customer profile attributes; the table uses the Amperity ID to ensure the Braze table is unique by Amperity ID and also to provide to Braze the Amperity ID as the “extern_id”, which is a required attribute

   Note

   The following query shows a field in Merged Customers that returns a customer’s opt status. This field might be somewhere else in your tenant. It’s important to filter your query to include only customers who are opted in to reduce the number of data points that are updated when you send custom attributes to Braze.

2. Transaction Attributes Extended for purchase history attributes

3. Customer Attributes for historical purchaser lifecycle status

SELECT
  mc.amperity_id AS external_id
  ,mc.given_name AS first_name
  ,mc.surname AS last_name
  ,mc.email
  ,mc.phone
  ,mc.city AS home_city
  ,mc.country
  ,mc.birthdate AS dob
  ,mc.gender
  ,ta.L30D_purchase_channels
  ,ta.L30D_order_revenue
  ,ta.L30D_order_frequency
  ,ta.L3M_purchase_channels
  ,ta.L3M_order_revenue
  ,ta.L3M_order_frequency
  ,ta.L12M_rfm_score
  ,ta.L12M_recency
  ,ta.L12M_frequency
  ,ta.L12M_monetary
  ,ta.lifetime_order_revenue
  ,ta.one_and_done
  ,ta.multi_purchase_channel
  ,ta.first_to_second_order_days
  ,ta.days_since_latest_order
  ,ta.latest_order_datetime
  ,ca.historical_purchaser_lifecycle_status
  ,ta.early_repeat_purchaser
FROM Merged_Customers mc
LEFT JOIN Transaction_Attributes_Extended ta ON mc.amperity_id = ta.amperity_id
LEFT JOIN Customer_Attributes ca ON mc.amperity_id = ca.amperity_id

The external_id does not need to be associated with the Amperity ID. For example, if your brand has an internal identifier that you have pulled into Amperity, you can associate that identifier with the external_id.

Note

You can make the query results available to campaigns if the query results are unique by Amperity ID. This will allow users of campaigns to select Braze attributes when configuring which attributes are sent to Braze for sub-audiences within your campaigns.

What can you use custom attributes with in Braze?

You can use custom attributes directly within segments, and then use those segments to engage with your customers across a variety of channels, including:

• Content cards

• Email

• In-app messaging

• Push

• SMS and MMS

• WhatsApp

• Custom webhooks

Add orchestration

An orchestration defines the relationship between query results and a destination, including the location to which those query results will be sent and the frequency at which the orchestration will be run.

To add an orchestration

1. From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.

2. From the Object Type drop-down, select Query.

3. From the Object drop-down, select the query for which results will be sent to Braze.

4. From the Destination drop-down, select a destination that is configured for sending data to Braze.

5. Verify all settings.

6. Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)

7. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

1. From the Destinations tab, under Orchestrations, open the    menu for the Braze orchestration, and then select Run.

2. The Status column for the orchestration will update to say “Waiting to start…”, after which the notifications pane will update to include a notification that shows the current status.

3. When the orchestration has run successfully, the status is updated to “Completed”.