Skip to content

Data types

This page consolidates the supported data types for custom attributes, event properties, and catalogs. Each custom data type has slightly different data type support and constraints.

Definitions

Use this table to see which data types you can use for user profile attributes, event data, or catalog items. Refer to the sections that follow for usage and constraints for each type.

Important considerations

  • Array: Custom attributes and event properties have size limits. Datetimes are not supported inside arrays in event properties. Catalogs support only string arrays, with a maximum of 100 elements.
  • Object: In Braze, this appears as “nested custom attributes” for custom attributes, “nested objects” for event properties, and “JSON object” for catalogs.
  • Time: In event properties, this type is labeled “Datetime.”

Custom attribute data types

Custom attributes support the data types listed in the Definitions table. The following describes usage and segmentation for each supported data type.

You can blocklist custom attributes individually in the actions menu, or you can select and blocklist up to 100 attributes in bulk. If you block a custom attribute, no data is collected regarding that attribute, existing data is unavailable unless reactivated, and blocklisted attributes do not show up in filters or graphs. Additionally, if the attribute is currently referenced by filters or triggers in other areas of the Braze dashboard, a warning modal appears explaining that all instances of the filters or triggers that reference it are removed and archived.

Marking as personally identifiable information (PII)

Administrators can also create custom attributes and mark them as PII from this page. These attributes are visible only to admins and dashboard users with the “View Custom Attributes Marked as PII” permission.

Adding descriptions

You can add a description to a custom attribute after it’s created if you have the Manage Events, Attributes, Purchases user permission. Edit the custom attribute and input whatever you like, such as a note for your team.

Adding tags

You can add tags to a custom attribute after it’s created if you have the “Manage Events, Attributes, Purchases” user permission. You can then use the tags to filter the list of attributes.

Removing custom attributes

There are two ways you can remove custom attributes from user profiles:

Setting the null value

  • null removes the attribute from the user profile entirely. It does not appear in the profile or match any IS NOT BLANK filter.
  • "" sets the attribute to an empty string value. The attribute appears on the profile with an empty string value, but does not match IS NOT BLANK filters (it is treated as blank).

Additionally, "" is only valid for string-type attributes. If the attribute’s data type is set to a non-string type (such as Boolean, number, or time) in the dashboard, sending "" does not clear the value—use null instead.

Exporting data

To export the list of custom attributes as a CSV file, select Export all at the top of the page. The system generates a CSV file and emails you a download link.

Viewing usage reports

The usage report lists all the Canvases, campaigns, and segments using a specific custom attribute. This list doesn’t include uses of Liquid.

You can view up to 100 usage reports at a time by selecting the checkboxes next to the respective custom attributes and then selecting View usage report.

Values tab

When viewing a usage report, select the Values tab to view the top values of the selected custom attributes based on a sample of approximately 250,000 users. Note that because the results are sampled from a subset of users, the sample doesn’t include all existing values. This means the Values tab shouldn’t be used for troubleshooting or for use cases that require incorporating data from all users.

Usage report for selected custom attributes with an opened "Values" tab showing a pie chart of country attribute values, such as "US" and "PR".

Setting custom attributes

The following lists methods across various platforms that are used to set custom attributes.

Expand for documentation by platform

Custom attribute storage

All data stored on the User Profile, including custom attribute data, is retained indefinitely as long as each profile is active.

Custom attribute data types

Custom attributes are extraordinarily flexible tools that allow for great targeting.

The following data types may be stored as custom attributes:

Booleans (true/false)

Boolean attributes are useful for storing simple binary data about your users, like subscription statuses. You can find users that explicitly have a variable set to a true or false value, in addition to those that don’t have any record of that attribute recorded yet.

For Boolean attributes, the following segmentation options are available.

For Number attributes, the following segmentation options are available.

Number attribute details

  • “Exactly 0” and “Less Than” filters include users with NULL fields
    • To exclude users without a value for custom attributes, you need to include the is not blank filter.

String attributes can be up to 255 characters long. Note that if you input any values with spaces in between, before, or after words, Braze will also check for the same spaces.

For String attributes, the following segmentation options are available.

Arrays have a maximum size of 100 KB. The default length for an attribute is up to 500 items (for example, if you’re sending an attribute such as “Movies Watched” set to 500, when a user watches a 501st movie, the first movie is removed and the most recent is added). Note that if you input any values with spaces in between, before, or after words, Braze will also check for the same spaces.

Array-type custom attributes cannot be imported via CSV import. To upload array values, use the /users/track endpoint or Cloud Data Ingestion.

For Array attributes, the following segmentation options are available.

Time attributes are useful for storing the last time a specific action was taken, so you can offer content specific re-engagement messaging to your users.

Time filters using relative dates (for example, more than 1 day ago, less than 2 days ago) measure 1 day as 24 hours. Any campaign that you run using these filters will include all users in 24-hour increments. For example, last used app more than 1 day ago will capture all users who “last used the app more than 24 hours” from the exact time the campaign runs. The same will be true for campaigns set with longer date ranges—so five days from activation will mean the prior 120 hours.

To target users who have a time attribute that falls within a time range, use two audience filters: in more than for the lower bound and in less than for the upper bound. A single filter can’t express both sides of that range. For example, to target users with a time attribute in the next 24 hours (between now and one day from now), apply in more than 0 days and in less than 1 day.

For Time attributes, the following segmentation options are available.

Time attribute details

  • Day of Recurring Event
    • When using the “Day of Recurring Event” filter, and are then prompted to select the “Calendar Day of Recurring Event”, if you select IS LESS THAN or IS MORE THAN, the current date will be counted for that segmentation filter.
    • For example, if on March 10, 2020, you selected the date of the attribute to be LESS THAN ... March 10, 2020, attributes will be considered for the days up to, and including March 10, 2020.
  • Less than X Days Ago: The “Less than X Days Ago” filter includes dates between X days ago and the current date/time.
  • Less than X Days in the Future: Includes dates between the current date/time and X days in the future.

You can use nested custom attributes to send objects as a data type for custom attributes. For more information, refer to Nested custom attributes.

Use an array of objects to group related attributes. For more details, refer to Array of objects.

You can change the data type of your custom attribute, but you should be aware of the impacts. Refer to Changing custom attribute or event data type for more.

Consolidated operators

We’ve consolidated the list of operators available to use in attribute filters, custom attribute filters, and nested custom attribute filters. If you have existing filters using these operators, they will be automatically updated to use the new operators.

Event property data types

When you log an event, you can attach extra information (for example, product name or price) as event properties. Each property has a name and a value. Event property values support the data types in the Definitions table (Time is labeled “Datetime” in event properties).

Expected format

Property values are sent as an object: keys are the property names, and values are the property values. Property names must be non-empty strings, 255 characters or fewer, with no leading dollar signs ($).

Event-property-specific rules:

  • Time (Datetime): Use ISO 8601 or yyyy-MM-dd'T'HH:mm:ss:SSSZ format. Not supported within arrays.
  • Array: Datetimes are not supported within arrays.
  • Nested object: See Nested objects.
  • Payload: Event property objects that contain array or object values can be up to 102,400 bytes (100 KiB).

You can change the data type of your custom event property, but be aware of the impacts of changing data types after data has been collected.

For full event property behavior, reserved keys, and usage in triggers and personalization, see Custom event properties.

Purchase events and revenue

Purchase and revenue data is recorded through purchase events or recommended eCommerce events.

Logging purchase events establishes the Lifetime Value (LTV) for each user profile, and this data is viewable on the revenue page in time-series. You can segment on money spent, last purchase date, number of purchases in a time window, and more.

Purchase event property data types

Purchase event property values (the properties object on a purchase) support the data types in the Definitions table, with the same structure and naming rules as event properties.

The properties values must be an object up to 50 KB where the keys are the property names and the values are the property values. Property names must be strings, 255 characters or fewer, with no leading dollar signs ($).

Property values can be any of the following data types:

The following keys are reserved and cannot be used as property names: time, product_id, quantity, event_name, price, and currency. Using a reserved key in the properties object returns the error “Invalid ‘properties’ field”.

For the full purchase object schema and examples, see Purchase object. For logging purchase events, segmentation filters, and full details, refer to Purchase events.

Changing custom attribute or event data type

To change the data type of a custom attribute or event:

  1. Go to Data Settings and select either Custom Attributes or Custom Events.
  2. Find your attribute or event from the list, and select More actions.
  3. Select a new Data type from the dropdown.
  4. Select Save.

If you change the data type of a custom attribute or event (for example, changing time to string), consider the following:

  • Filters are not automatically updated. Segments, campaigns, Canvases, or other locations that use the changed attribute or event are not updated. Before you change the data type, stop any campaigns or Canvases that use the attribute in segments or filters, and remove the attribute from filters that reference it.
  • Existing user data is not retroactively updated. If the changed attribute was on a user profile before the change, that value remains the old data type. Users can fall out of segments that contain the changed attribute because the filter looks for the new data type. Update those user profiles (for example, with the /users/track endpoint) so they match the new type and re-enter the segment if needed.
  • New data must match the new type. API calls that send the previous data type for the changed attribute are not accepted. Send the new data type.

Catalog data types

Catalogs support the types listed in the Definitions table. The following table lists each type, how it can be created or updated, and format and examples.

Format and examples

For creating and updating catalogs, see Create a catalog.
New Stuff!