> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traits

> Traits calculate values that aren't already available as fields in your customer data. Use them for values such as lifetime spend, purchase count, most recent product, or days since last order, then use those values in audiences or syncs.

## Before you begin

* A [defined schema](https://docs.hightouch.com/customer-studio/schema.md) with at least one parent model

## How traits fit into audience building

Audience filters decide **who qualifies**. Traits calculate **values you can use to make that decision**.

For example, suppose you want to reach high-value customers. Your warehouse may contain individual purchase records but no `Lifetime value` field. Instead of rebuilding the calculation every time you create an audience, you can create a trait that sums each customer's purchases.

You could then filter on:

* `Lifetime value > 500`
* `Lifetime value is in the top 10%`
* `Lifetime value > Average order value`

Marketers can select an existing trait in the visual audience builder or ask the [Agent](https://docs.hightouch.com/customer-studio/agents.md) to find and apply one while drafting audience conditions.

Traits can also add data you want to send with an audience. For example, an abandoned-cart audience could include each customer's most recently abandoned product so a messaging tool can personalize the follow-up.

Use a trait when the value you need must be calculated from customer attributes, related records, events, or other model data.

If your company already maintains the calculation as a shared business metric, such as an official LTV or churn score, keep it in your warehouse and expose it as a model column instead. See [Plan your data model](https://docs.hightouch.com/customer-studio/data-model.md) for guidance on where calculations should live.

## Use traits where you need them

You may already have saved traits available to use. Data teams can create reusable traits, such as `90-day purchase value`, that marketers can use across audiences and syncs.

You can also create calculations while working in an audience:

* **Need a value to decide who qualifies?** Create a [custom trait](https://docs.hightouch.com/customer-studio/traits.md#create-a-custom-trait-in-an-audience) directly in the audience builder.
* **Need to add data to the people who already qualify?** Add an [audience trait](https://docs.hightouch.com/customer-studio/traits.md#add-audience-traits), such as each customer's most recently abandoned product.
* **Keep rebuilding the same calculation?** Create a [saved trait](https://docs.hightouch.com/customer-studio/traits.md#create-a-saved-trait) so it can be reused across audiences and syncs.
* **Keep creating variations of the same calculation?** Create a [trait template](https://docs.hightouch.com/customer-studio/traits.md#reuse-trait-logic-with-templates) and use it to build related traits such as `30-day`, `90-day`, and `12-month` purchase value.

## Create a saved trait

Create a saved trait when the same calculated value should be available across audiences or syncs.

1. Go to **Customer Studio > Traits**.
2. Select **Create > New trait**.
3. Choose the model the trait belongs to.
4. Choose the calculation method.
5. Configure the calculation.
6. Preview the results.
7. Name and save the trait.

![Create a trait](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-create.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=c88636c3b9c1bd4ed42bcbc9cb516908)

Most reusable customer-level traits belong on the parent model. You can also create traits on related or event models when the calculation belongs to those records instead.

![Choose a parent, related, or event model for the trait](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-model-picker.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=bcfb3785ffaa692dd21588b24159d9fd)

## Configure the calculation

The calculation method determines what value the trait produces.

### Choose a calculation method

| Method | Calculates... | Example |
| - | - | - |
| **Aggregation** | Sum or average across related or event records | Total purchase value |
| **Count** | Number of matching records | Purchases in the last 30 days |
| **Occurrence** | First, last, most frequent, or least frequent value | Most recently purchased category |
| **List** | A list of values or objects | Recently viewed product IDs |
| **SQL Aggregation** | Custom aggregation logic across related records | Product data as an array or JSON value |
| **SQL Formula** | A value from columns and other traits already on the model | Loyalty status flag |
| **Audience Membership** | A list of all audiences a user belongs to | Inclusion among 5 Brand audiences |

![Choose a trait method](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-method.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=27cf7a24cff5eeca505add9b38e8e279)

Depending on your workspace configuration, you may also see **Prediction**, **Catalog Recommendation**, **Lookalike Audience**, and **Audience membership** methods. See [Predictive traits](https://docs.hightouch.com/customer-studio/predictive-traits.md) for the prediction, catalog recommendation, and lookalike methods.

> [!NOTE]
>
> Traits used in realtime audiences support a subset of methods: **Aggregation**
> (Sum only), **Count**, and **Occurrence** (First or Last). The other methods
> are available for batch traits only.

### Choose which records contribute to the trait

Most calculation methods let you choose a related or event model and optionally filter the records before calculating the trait.

For example, a `90-day purchase value` trait could use:

* model: `Purchases`
* input filter: purchases from the last 90 days
* method: **Sum**
* field: `order_value`

> [!TIP]
>
> Trait filters and audience filters do different jobs. **Trait filters** decide
> which records contribute to the calculated value, and **audience filters**
> compare that resulting value to decide who qualifies. For example, a trait can
> calculate spend from completed purchases only, then an audience can include
> customers where that trait is greater than \$500.

Select **Preview results** to confirm the trait returns the values you expect before saving it.

## Configure each method

### Aggregation

Use **Aggregation** to calculate the sum or average of a numeric field across related or event records.

For example:

`Sum order_value across completed purchases`

Configure:

* related or event model
* optional input filters
* **Sum** or **Average**
* field to aggregate

### Count

Use **Count** to count matching records.

For example:

`Number of purchases in the previous 30 days`

Configure:

* related or event model
* optional input filters
* optional field to count by

### Occurrence

Use **Occurrence** to return a value based on position or frequency.

Choose an occurrence type:

* **First / Min**
* **Last / Max**
* **Most frequent**
* **Least frequent**

For example:

`Most frequently purchased product category`

Configure:

* related or event model
* optional filters
* occurrence type
* value to return
* ordering, where applicable

### List

Use **List** to return multiple values from related or event records.

For example:

`Product IDs viewed in the last 7 days`

Configure:

* field or fields to return
* optional filters
* deduplication
* ordering
* optional list length

Depending on workspace configuration, list traits can return individual values or objects containing multiple fields.

> [!NOTE]
>
> For value lists, if you turn on deduplication, **Order by** must match the
> column you're returning. For object lists, ordering and deduplication can't be
> used together.

### SQL Aggregation

Use **SQL Aggregation** when the built-in aggregation methods don't cover the calculation you need across related records.

For example:

```sql theme={null}
ARRAY_AGG(DISTINCT {{column "product_id"}})
```

Use the column syntax shown in the SQL editor when referencing fields: double curly braces around the keyword `column`, followed by the column name in quotes. Column names are case-sensitive.

You also configure:

* a default value
* the resulting property type

### SQL Formula

Use **SQL Formula** to calculate a value from fields and traits already available on the model.

Unlike SQL Aggregation, SQL Formula doesn't aggregate data from a related or event model. It works with values already available on the current row.

Use autocomplete in the SQL editor to insert fields and traits. To reference a merged field, use its dot path. To reference another trait, prefix it with `trait.`.

For example:

* Combine columns: `CONCAT({{"first_name"}}, ' ', {{"last_name"}})`
* Create a Boolean flag from a merged column: `CASE WHEN {{"merged.pets.animal"}} LIKE 'dog' THEN true ELSE false END`
* Reference another trait: `CASE WHEN {{"trait.lifetime_total_value"}} > 1000 THEN 'high' ELSE 'low' END`

> [!NOTE]
>
> References to fields or traits that don't exist appear as a red pill in the
> editor. Use autocomplete to insert valid references.

## Name and describe the trait

Give the trait a name that tells marketers what the value means.

Prefer:

`90-day purchase value`

over:

`ltv_90d_v2`

Use the description for details that aren't obvious from the name, such as:

* which records are included
* the time window
* currency or units
* important exclusions

Clear names and descriptions make traits easier to find in the audience builder and easier for the Agent to interpret.

![Finalize a trait](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-finalize.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=af42ca8d6d2c9f3ef39dd0907b67cdd8)

## Audience membership traits

Audience membership traits help you list the audiences a user currently belongs to as a column on the parent model. The trait's value is a list of audiences, so you can sync a user's audience memberships to a destination alongside their other traits — for example, to pass loyalty tier or winback eligibility into an ad platform or CRM.

> [!NOTE]
>
> Audience membership is only available on **parent models** — source must have
> **[Audience snapshots](https://docs.hightouch.com/customer-studio/audience-snapshots.md)** enabled. Turn it
> on from the source's **Sync logs** tab.

### Configure the trait

To build an audience membership trait, [configure a trait](#create-a-trait) as follows:

> [!NOTE]
>
> Audience Membership Traits must be enabled by Hightouch. [Contact us](#pylon-chat) to turn it on.

1. Choose which audiences to track:
   * **All audiences** tracks every audience on the parent model, including ones created later.
   * **Select audiences** tracks only the audiences you pick.
2. Choose an **Output format**:
   * **ID only** produces an array of audience IDs as strings.
   * **Object** produces an array of `{audience_id, audience_name, split_group}` JSON objects, with the latter 2 keys based on your selection.
3. Set the **Update frequency** — how often membership is refreshed even when the tracked audiences aren't syncing.
4. Name the trait and finalize.

![Audience Membership](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/audience-membership-trait.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b0a7f99a667f84ae5e53bb63caae1a57)

### Output formats

With **ID only**, the trait resolves to a list of IDs:

```
["1234", "5678"]
```

With **Object**, each entry can carry the the audience name, and/or the split the user landed in, which lets a destination distinguish treatment from holdout:

```
[
  { audience_id: "1234", audience_name: "Best users", split_group: "treatment" },
  { audience_id: "5678", audience_name: "Could be best users", split_group: "holdout" }
]
```

### Update frequency

Membership status comes from each audience's most recent snapshot. A snapshot is taken every time an audience syncs, so frequently synced audiences stay current on their own. The **Refresh at least every N days** setting adds a floor: if a tracked audience hasn't synced within that window, Hightouch takes a snapshot so the membership value doesn't go stale. The default is 3 days, and you can set anything from 1 to 365. Shorter intervals keep membership fresher but run more queries against your warehouse.

> [!NOTE]
>
> Tracking a large number of audiences increases warehouse load, especially if those audiences sync infrequently and rely on the refresh interval for their snapshots.

## Use a saved trait in an audience

Saved traits appear in the **Traits** filter group in the audience builder.

For example:

`Lifetime value > 500`

You can compare traits with fixed values or, where supported, other fields and traits.

> [!TIP]
>
> If you're not sure which trait to use, select **Ask an agent** while adding a
> filter. Describe what you want to filter on, and the Agent can suggest an
> available trait. See the [Audience builder prompting
> guide](https://docs.hightouch.com/customer-studio/agents.md).

See [Audience filters](https://docs.hightouch.com/customer-studio/audience-filters.md) for available operators and more advanced filter logic.

![Use a trait in an audience](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/trait-filter-option.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=fcdc093ad47114d0bc2ffab323035c2d)

## Create a custom trait in an audience

If you need a calculated value while building one audience, create a custom trait directly in the audience builder.

1. Select **Add filter**.
2. Open **Custom traits**.
3. Select **Create a custom trait**.
4. Choose the related or event model.
5. Configure the calculation.
6. Use the resulting value as part of the audience condition.

![Custom trait calculation](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/custom-trait-calculation.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1c561ba3cfba0fa2744524c57f6c7d60)

If you later need the calculation in other audiences, save it as a reusable trait.

## Add audience traits

Use an audience trait when you want to add data to audience members without using that data to decide who qualifies.

> [!NOTE]
>
> Audience traits were previously called trait enrichments.

For example, an abandoned-cart audience might qualify based on cart activity, then include each customer's most recently abandoned `Product_ID` for use in a follow-up message.

![Create an audience trait from the audience's Traits tab](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-audience-trait-create.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=92b538c518d5c120b95413466d0c9516)

To add an audience trait:

1. Open the saved audience.
2. Go to the **Traits** tab.
3. Select **Create audience trait**.
4. Choose a calculation method:
   * **Trait template** — calculate a value from an existing template, with optional conditions for this audience.
   * **Static value** — assign the same text or number to every audience member, such as campaign code `SPRING26`.
5. Name the audience trait. This name appears when you configure sync mappings.
6. Save the audience trait.

> [!NOTE]
>
> Static value audience traits must be enabled by Hightouch. [Contact us](#pylon-chat) to turn it on.

![Configure an audience trait from a template or a static value](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-audience-trait-panel.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=216b0759204dfd0d439d237bc813d406)

The audience trait appears in audience preview and can be used in supported sync mappings.

![The saved audience trait in the audience's Traits tab](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-audience-traits-list.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=7f356ab54da0c0e960e83aa91f8b974b)

### Create an audience trait from an event

You can also create an audience trait from an event condition after saving the audience.

For example, capture the `Product_ID`, `SKU`, or `Brand` from the last qualifying cart event.

Open the event condition's **...** menu and select **Sync a trait from this filter**. Choose the value you want to capture, then save the audience trait.

![Select Sync a trait from this filter in an event condition's menu](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-audience-trait-from-event.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6877a95c242b55adc2fb7d8cbc1b7433)

## Reuse trait logic with templates

Create a trait template when your team repeatedly builds variations of the same calculation.

For example, one template could calculate completed purchase value over a configurable time window. Your team could use it to create:

* `30-day purchase value`
* `90-day purchase value`
* `12-month purchase value`

Saved templates appear on the **Templates** tab of the **Traits** page.

![The Templates tab in the Traits list](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-templates-list.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d801248e8055c3bb9211bf79ea26f6a6)

To create a template:

1. Go to **Customer Studio > Traits**.
2. Select **Create > New template**.
3. Choose the trait model and calculation method.
4. Configure the reusable calculation.
5. Name and save the template.

To create a trait from a template, select **Create > Start with a template**, choose the template, add any conditions specific to the new trait, preview the result, and save it.

A trait created from a template inherits the template's model, calculation method, and calculation settings. You can still change its filters, name, and description.

Changes to a template update the shared calculation for every trait created from it. Each trait keeps its own filters. Before changing a template, review which traits use it.

## Manage saved traits

Saved traits appear in **Customer Studio > Traits**. The list shows each trait's name, type, trait model, what it's calculated from, and when it was last updated.

![Traits list](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-listview.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d79105a0da52124ea16b7e1673cbf180)

Open a trait to view its configuration and see where it's used.

![A trait's Configuration tab](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-configuration.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1412e70275eae9d6fb008c0a8d2aa2f2)

### Review usage before changing a trait

A saved trait can be used by multiple audiences or syncs.

Before changing a shared calculation, check the Usage tab to see which workflows depend on it.

![Trait usage](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/cs-traits-usage.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d1773d64b41b820ae809287a13f87d85)

## Create traits on related and event models

Most traits used for customer targeting belong on the parent model. You can also create traits on related or event models when the calculated value belongs to those records.

For example, on a `Purchase` model you could calculate:

* how many high-value items each purchase contains
* whether a purchase happened on a weekend

You can then use those values while filtering through the relationship.

Traits on related or event models can be used in filters, but they aren't directly available as parent-level fields for destination syncs. To send the value to a destination, create the trait on the parent model or add it as an [audience trait](#add-audience-traits).

## Suggest trait values in the audience builder

String traits can suggest common values in the audience builder, so marketers pick from real values instead of typing them.

For example, a `Most recent city` trait might suggest `San Francisco`, `Los Angeles`, or `New York`.

Value suggestions are available only for traits that return a string.

To configure them, open the trait and go to the **Suggestions** tab. Turn suggestions on, then choose how often Hightouch refreshes the values or refresh them manually.

![Enable trait value suggestions](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/hightouch-audiences/traits/trait-value-suggestions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=bf1691a9afc5cbd15910f80508e22321)

## Permissions

Creating, editing, and deleting saved traits and trait templates requires the **Manage traits** grant.

Admins can assign this grant across all parent models or for individual parent models without giving users permission to configure the full Customer Studio schema.

See [Roles](https://docs.hightouch.com/workspace-management/roles.md#parent-models) for details.

## Next steps

* [Build an audience](https://docs.hightouch.com/customer-studio/usage.md) to use traits in the visual audience builder.
* [Audience filters](https://docs.hightouch.com/customer-studio/audience-filters.md) to learn how to compare traits and other customer data.
* [Audience builder prompting guide](https://docs.hightouch.com/customer-studio/agents.md) to use the Agent to find and apply traits.
* [Sync audiences](https://docs.hightouch.com/customer-studio/syncs.md) to send parent-model traits and audience traits to destinations.