# Create a new Metric

To create a new metric, navigate to the Metric's catalog and click on `Create metric`

## Global Settings

| Field           | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| **Metric name** | This name of the metric must be unique across the entire platform. |
| **Owners**      | The list of team and individual owners for this metric.            |

> **info**
>
> Metric's global settings are shared across all versions of a metric. Future changes to those fields will apply to all existing and future versions of a metric.

## Details & Metadata

The Metric details and Metadata sections provide some advanced information about the metric. This information is version-specific and, as such, can differ between different versions of the same metric.

| Field                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**             | Providing a good description is important as it helps experiments choose the right metric.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Impact**                  | Directionality of the metric. `positive` means that increasing this metric is good. `negative` means that decreasing the metric is good. Use `unknown` if the metric has no preferred direction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Metric type**             | Describes how the metric is implemented. Choose between [`Goal Unique Count`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/goal-unique-count.md), [`Goal Count`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/goal-count.md), [`Goal Time To Achievement`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/time-to-achievement.md), [`Goal Property`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/property.md), [`Goal Property Unique Count`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/unique-property-count.md), [`Goal Retention`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/retention.md), [`Goal Activity Period Count`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/activity-per-period.md) and [`Ratio`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/ratio.md). `Custom SQL` is also available when [warehouse-native](https://docs.absmartly.com/docs/web-console-docs/warehouse-native/overview.md) is enabled. |
| **Tags** (optional)         | Makes the metric more discoverable by providing relevant [tags](https://docs.absmartly.com/docs/web-console-docs/configuration/settings.md#tags).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Category** (optional)     | The [category](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/categories.md) the metric belongs to (`conversion`, `performance`, etc). While optional, selecting a category makes it easier for experimenters to find relevant metrics.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Applications** (optional) | Select the [applications](https://docs.absmartly.com/docs/web-console-docs/configuration/applications.md) where this metric makes sense. Only experiments running on these applications should track this metric. While optional, setting the correct `Application(s)` helps experimenters find relevant metrics for their experiments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Units** (optional)        | Select the [tracking units](https://docs.absmartly.com/docs/web-console-docs/configuration/units.md) for which this metric is computed. The tracking unit of the metric should match the tracking unit of the experiments where it is tracked. While optional, setting the correct `Tracking Unit(s)` will help experimenters track relevant metrics in their experiments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Goal

In this section, you can select and configure the [goal](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/goals/overview.md) which provides the raw data for this metric.

> **info**
>
> This part of a metric’s setup is version-controlled.<br /><!-- -->To edit those fields, a new version of the metric will need to be created.

```javascript
// Triggered when a visitor buys a product
context.track("purchase", {
  price: 1000,
  currency: 'euro',
  order_number: '0000982532',
  product_id: "ABC123",
  category_id: 'ZYZ123'
});
```

### Goal

Select the [goal](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/goals/overview.md) to use as a source for this metric. In the example above, the name of the goal is `purchase`.

If you don't see a goal in the list, make sure it exists and make sure you have the correct permissions to view and use it.

> **info**
>
> Auto-created goals do not have an owner when created. For governance reasons, make sure to claim ownership of a goal before you start using it for your metric.

### Property

In the case of [`Goal Property`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/property.md) or [`Goal Property Unique Count`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/unique-property-count.md) metrics, you also need to choose which property of the metric to use. For example, a `revenue` metric built using the goal event above, would use the event property **price**.

### Property filters

Property filters let you include only the goal events whose properties match specific conditions. These filters apply to the properties inside the event payload. With the example above, we might want to create a `conversion` metric but only for product of a certain category, in that case a **category\_id** property filter can be used to filter only the relevant **purchases** events.

From that event, we could also create a `revenue (euro)` metric by filtering events by **currency**.

### Time filters

Every visitor becomes exposed to an experiment at a specific moment. We call it the **first-seen** event. That timestamp is the reference point for all time-based filters.

A time filter lets you include only the goal events that happen within a defined window after that first exposure. This ensures your metric measures behavior in a controlled, meaningful period (for example, `purchases within the first hour` or `engagement in the first 7 days`).

> **caution**
>
> If your metric uses [CUPED](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/variance-reduction-cuped.md) and has an `At least` or `Between` time filter, the lookback period must be longer than the start of the time filter. For example, if your metric measures `conversions achieved at least 2 weeks after exposure`, the CUPED lookback period must be 3 or 4 weeks.

### Outliers

Outlier limits help control the influence of extreme metric values. They reduce noise and variance by **capping each participant's metric value to a defined range**. The value capped is the participant's value for the metric, for example their total purchase revenue, not the value of each individual event.

Only participants with at least one counted event are capped, and only they are used to work out the limits. Participants with no counted events keep a value of 0. For `Goal Property` metrics, an event whose property is 0 or missing doesn't count. Neither does an event that has been cancelled.

Limits are available for `Goal Count`, `Goal Property`, `Goal Property Unique Count`, `Goal Time To Achievement` and `Goal Activity Period Count` metrics, and for the numerator and denominator of `Ratio` metrics when they use one of these types. `Custom SQL` metrics with a **Metric distribution type** of `Continuous` have their own **Outliers limit method**.

You can choose one of four methods to manage outliers:

> **caution**
>
> Outlier limits can reduce variance and make metrics more stable, but they also change the underlying data. When used incorrectly, they may hide meaningful effects or introduce bias in experiment results. Always ensure your limits reflect real-world constraints rather than engineering convenience, and avoid tuning them in response to specific experiment outcomes.

#### Unlimited

This is the default. This option applies no outlier treatment. All values are kept exactly as they are. Use this option when you want full fidelity of raw data and are not concerned about extreme values skewing results.

#### Quantile

This method caps values based on chosen quantiles. You enter a **Lower limit quantile** and an **Upper limit quantile** as percentages between 0 and 100 (for example, 5 and 95). At least one of them is required. If you enter both, the lower must be less than the upper. Values below the lower quantile or above the upper quantile are capped to the limit.

> **info**
>
> Outliers capping is done using the full experiment population, so all variants have the same capping limits. The limits only apply once more than 50 participants have at least one matching event.

How it behaves with the sample purchase event, for a metric summing `price`:

```text
If you set:
- Lower limit quantile: 5
- Upper limit quantile: 95

Then:
- A participant whose total spend falls between the 5th and 95th percentile keeps their value.
- A participant whose total spend is above the 95th percentile (for example 1000, when most participants spend between 10 and 300)
is capped to the 95th percentile value.
```

Quantile limits are useful when your data contains long tails or rare extreme highs.

#### Standard Deviation

This method caps values based on the mean and standard deviation of participants' values. You enter a **Lower limit multiplier** and an **Upper limit multiplier**. Both are required and must be 0 or more.

The limits are calculated as:

```text
- Lower limit: mean − (stdev × lower multiplier)
- Upper limit: mean + (stdev × upper multiplier)
```

Any value outside these limits is capped to the value of the boundary.

> **info**
>
> Outliers capping is done using the full experiment population so all variants have the same capping limits. The limits only apply once more than 50 participants have at least one matching event.

Example with the sample purchase event, for a metric summing `price`:

```text
Suppose across participants who purchased:
- mean total spend = 200
- standard deviation = 150

If you set:
- Lower limit multiplier = 1
- Upper limit multiplier = 2

Then:
- Lower limit = 200 − (150 × 1) = 50
- Upper limit = 200 + (150 × 2) = 500

A participant who spent 1000 in total:
- 1000 > 500 → capped to 500.
```

A multiplier of 0 puts that limit at the mean, so every value on that side of the mean is capped to the mean.

Standard deviation limits are helpful when extreme values are several standard deviations from the average.

#### Fixed

This option lets you define explicit numeric boundaries with a **Lower limit value** and an **Upper limit value**. Both are required, and the lower limit must be less than the upper limit. Any value below the lower limit or above the upper limit is capped to the limit.

Example with the sample purchase event, for a metric summing `price`:

```text
- Lower limit value: 0
- Upper limit value: 500

Then:
- A participant who spent 1000 in total → above 500 → capped to 500
- A participant who spent 300 in total → kept
```

Fixed limits are useful when you already know the acceptable bounds for your metric (e.g., total spend can never be negative or above a business-defined maximum).

### Goal Relations

Goal relations let you connect different goal events that represent follow-up actions on the same underlying item. They are useful when events such as `cancellations`, `refunds`, or `replacements` should modify the way a metric is calculated.

For example, if a purchase is later refunded, you may want the refund event to reduce the revenue metric. Or if a purchased item is replaced with a different product, you may want to adjust the associated value.

Goal relations define how one goal (the current one) is linked to another goal (the foreign one) using a shared identifier. This identifier is provided through a property in both events (for example **order\_number**, **purchase\_id**, or **transaction\_id**).

Each relation type has its own behaviour and additional fields. Refund and replacement relations are only available for [`Goal Property`](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/property.md#refunds-and-replacements) metrics, including a Goal Property numerator or denominator in a Ratio.

#### Cancellation

A cancellation relation ties a “current” goal to a cancellation event belonging to the same item. This is useful when the current goal should be counted only if it has not been cancelled. This makes it possible to create metrics such as `Net Conversions` which only accounts for purchases which were not cancelled, giving experimenters a more accurate view of the actual business impact of their changes.

![Goal Relations - Cancellation](/assets/images/goal-relation-cancellation-0aa56533ec02d444c345dd77192e0f7f.png)

Below is a sample `cancellation` events cancelling the purchase event made above.

```javascript
// Triggered when a visitor cancels a purchase
context.track("purchase_cancelled", {
  order_number: '0000982532'
});
```

To configure a cancellation relation, you need to provide:

* Current goal relation key property This is the property on the current goal event that identifies the item. Example for a **purchase** event: **order\_number**.
* Foreign goal This is the goal event that represents the cancellation. Example: **purchase\_cancelled**.
* Foreign goal relation key property This is the property on the cancellation event that refers to the same item. Example: also **order\_number**.

When both events share the same key value, the cancellation will be applied to the current goal according to the metric’s logic (for example, removing the contribution of that purchase).

#### Refund

A refund relation is used when a purchase can generate one or more refund events that should adjust the metric.

Refund relations have additional configuration, as refund events may include both an identifier and a refund amount.

![Goal Relations - Refund](/assets/images/goal-relation-refund-6fb1e00adf4d83b3f2617442d6740edc.png)

```javascript
// Triggered when a visitor gets refunded
context.track("refund", {
  order_number: '0000982532',
  refund_amount: 1000,
});
```

To configure a refund relation, you define:

* Current goal relation key property The identifier on the current goal (**order\_number**).
* Refund operation Whether the refund value is subtracted from or added to the value of the current goal: **Subtract** or **Add**.
* Foreign goal The goal event representing the refund (**refund**).
* Foreign goal relation key property Identifier on the refund event used to match the purchase.
* Foreign goal relation value property The numeric value to use for the refund adjustment, such as **refund\_amount**.
* Duplicated foreign goal aggregation Determines how to combine multiple refund events referring to the same item (sum, max, last, etc.).

This relation ensures that metrics involving values such as `revenue` reflect the impact of refunds accurately providing a more accurate view on the impact of the change.

#### Replacement

A replacement relation applies when the original event is substituted by another event of the same category. A typical use case is item replacements: a customer receives a replacement product instead of the original purchase.

Replacement relations allow the metric to use information from the new event rather than the original one.

![Goal Relations - Replacement](/assets/images/goal-relation-replacement-129fe6334962bebe62cd88d5a109294d.png)

```javascript
// Triggered when a visitor gets a replacement
context.track("replacement", {
  order_number: '0000982532',
  replacement_price: 800,
});
```

Configuration includes:

* **Current goal relation key property** Identifier on the current event (e.g., **order\_number**).
* **Foreign goal** The event representing the replacement (e.g., **replacement**).
* **Foreign goal relation key property** The matching identifier on the replacement event (e.g., **order\_number**).
* **Foreign goal relation value property** Value from the replacement event that replaces the original value. For example, **replacement\_price**.
* **Duplicated foreign goal aggregation** How the value of the foreign goal achievement will be aggregated when there are multiple foreign goal achievements that match the **Foreign goal relation key property**.

There are five options:

| Aggregation Type | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| Pick first       | The first foreign goal achievement will be used to update the value of the current goal.                 |
| Pick last        | The last foreign goal achievement will be used to update the value of the current goal.                  |
| Sum              | The sum of all foreign goal achievements will be used to update the value of the current goal.           |
| Minimum          | The minimum value of all foreign goal achievements will be used to update the value of the current goal. |
| Maximum          | The maximum value of all foreign goal achievements will be used to update the value of the current goal. |

Replacement relations allow the metric to reflect up-to-date values when items are swapped or reissued.

## Variance reduction

If applicable, you can enable [CUPED](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/variance-reduction-cuped.md) for this metric to help reduce variance. Enable [CUPED](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/variance-reduction-cuped.md) for this metric by checking the checkbox and choose a lookback period which matches the user behaviour.

## Format, scale and precisions

This section controls how your metric’s **Value** and **Mean** are displayed in the results table. It does not change how the metric is calculated: it only affects the formatting applied when values are shown in the metric's tables.

> **info**
>
> This part of a metric’s setup is version-controlled.<br /><!-- -->To edit those fields, a new version of the metric will need to be created.

![Gross Conversion Rate metric table to illustrate how Value and Mean are shown](/assets/images/gross-conversion-rate-cc26cc6c0d9d01e97f5a660b885deaa7.png)

You can customise three aspects for both **Value** and **Mean**:

* Format
* Scale
* Precision

These settings allow you to present the metric in a readable and meaningful way depending on the type of data (counts, currency, percentages, ratios, etc.).

### Value

The Value column in the results table displays the total summed value of your metric for each variant. For [ratio metrics](https://docs.absmartly.com/docs/web-console-docs/goals-and-metrics/metrics/metric-types/ratio.md), Value and Mean both show the ratio, so set both formats to suit the ratio. You can control how this number appears using:

#### Format

A string template that determines how the number is wrapped or displayed. For example:

* `{}` → shows the raw number
* `{} €` → appends a currency symbol
* `$ {}` → prefixes a dollar sign
* `{} items` → useful for quantity metrics

#### Scale

A multiplier applied before formatting the output. Common uses:

* `1` → show the value as-is
* `0.01` → convert cents to euros
* `100` → convert a ratio to a percentage during display

Example: If the raw total value is 1500.123456 and scale is 1, the displayed value might be 1,500.

#### Precision

How many decimal places to show. Examples:

* `0` → no decimals (ideal for counts)
* `2` → two decimals (useful for money)
* `3` → three decimals (fractions, averages, conversion rates)

### Mean

The Mean column displays the average metric value per participant for each variant. You can format it separately because mean values often need different formatting than totals (e.g., percentages vs absolute numbers).

#### Format

Same behaviour as for Value. Examples:

* `{}` → raw
* `{}%` → percentage
* `${}` → currency

#### Scale

Scale is especially important for means:

For conversion rate metrics, raw mean tends to be a ratio (0.0485). With scale = 100, it becomes 4.85.

For monetary means, if your underlying value is in cents, scaling by 0.01 converts to dollars or euros.

#### Precision

How many decimal places to show. Examples:

* `0` → no decimals (ideal for counts)
* `2` → two decimals (useful for money)
* `3` → three decimals (fractions, averages, conversion rates)

## Metric threshold alert

A metric threshold alert notifies you when the observed effect of a metric crosses a value you consider important. Instead of waiting for full statistical significance, the alert triggers as soon as the relative effect becomes large enough (either positively or negatively) to matter.

The alert works by watching the confidence interval (CI) of the impact.

> **info**
>
> This part of a metric’s setup is version-controlled.<br /><!-- -->To edit those fields, a new version of the metric will need to be created.

### Falls below threshold

Use this when you want to be alerted if the experiment becomes worse than a certain relative value.

For example:

* Threshold: -2%
* Alert triggers when: upper CI bound < -2%

This means even the optimistic estimate is still worse than –2 percent, so the effect could be harmful. In this case and to prevent further loss it might be worth stopping the experiment and investigating what is happening.

![Metric alert threshold](/assets/images/lower-alert-threshold-08d5af9a10fb4b072af61f8846188cfe.png)

This can help you detect dangerous regressions early.

### Rises above threshold

Use this when you want to be notified if the experiment becomes better than a certain value.

For example:

* Threshold: +5%
* Alert triggers when: lower CI bound > +5%

This indicates that even the conservative estimate of the effect exceeds your target improvement.
