> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom event is tracked

**Custom event is tracked** (`usage_event.tracked`) fires when a store's app reports one of your [usage events](/introduction-6) through the [SDK](/events). It's how metered usage becomes something a flow can react to: a first successful action, a milestone, a spike.

## When it fires

Whenever your app calls `track()` for a store and Meridian records the usage. The event is resolved against your [Usage](/introduction-6) catalog by its **key**, so an automation and a usage report always agree on which catalog event was tracked.

It fires for **recent** events only: one recorded as it happens, or [dated](/events#dated-events) less than 24 hours before Meridian received it. An event dated further back (a delayed sync catching up, a replay after an incident) is recorded, counted if it falls in the store's current billing period, and fires nothing. A replay of last week's orders therefore sends no burst of "new order" emails, and the store's first order stays its first. An event dated just before a billing period rolled over and received just after still fires if it is less than 24 hours old, even though it is not counted in either period.

An event de-duplicated by its idempotency key fires nothing either: only the first call that recorded it did.

Dispatch is deliberately non-fatal: if the automation can't be queued, the usage is still recorded and billed. Metering is your billing data, and it never fails because a flow failed.

## Watching one event or any

* **A specific event**: the flow only runs when that catalog event is tracked.
* **Any of your custom events**: the flow runs whenever a store tracks any of them.

## What it carries

The store's [variables](/automation-variables), plus three event variables:

| Variable | Example | Notes |
| - | - | - |
| `event_key` | `orders_synced` | The key your app reported |
| `event_name` | `Orders synced` | The event's name in your Usage catalog. Falls back to the raw key for an event the catalog doesn't define |
| `event_quantity` | `25` | The quantity reported in this call |

All three are available to emails and to [variable conditions](/condition-variable).

### The properties

Whatever object your app passed to `track()` comes with the event. Every scalar property in it is a variable named `properties.<property>`:

```ts theme={null}
await client.track({
  eventKey: "orders_processed",
  quantity: 1,
  properties: { total_price: 512.5, gift: true },
})
```

lets a condition read `properties.total_price is greater than 500`, and the email on that branch print `{{properties.total_price}}`.

Nested properties work by dot path (`properties.customer.tier`), up to three levels. A property you didn't send is **absent, not zero and not empty**: it satisfies no comparison but **is empty**, so the branch goes No rather than on a guess. Full rules: [Event properties](/automation-variables#event-properties), with a worked example [from `track()` to the inbox](/automation-variables#from-track-to-the-inbox).

The variables are `properties.<name>`, with no prefix in front. Templates written for Mantle use `usageEvent.properties.<name>`, which Meridian does not know and renders as nothing. See [Coming from Mantle](/automation-variables#coming-from-mantle) for the mapping.

<Tip>
  This is the cheapest way to make a busy trigger quiet: instead of running on every tracked event, run on the ones that matter: `properties.total_price` over a threshold, `properties.gift` true.
</Tip>

## Building on it

* Send a "you're up and running" email the first time a store tracks your core event.
* Branch on `event_key` when one flow serves several events.
* Write the milestone into a [custom field](/populate-custom-field) so [segments](/segments) and [reports](/report-builder) can use it.

<Note>
  This trigger fires on **every** tracked event, and a busy store can track thousands. Gate the flow with a condition, or watch a specific, rare event, rather than emailing on every occurrence.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.