> ## 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.
# Usage events
A usage event is a named, keyed action your app reports (an email sent, a page translated, an API call). Meridian records every one per store, so you can see what your app is actually doing out there. Attaching a price to an event is one thing you can do with that; it is not the reason to define one.
Events live under **Usage** at the app level. Public apps have them, whether or not they are [hosted on Meridian](/sdk-hosting) and whether or not they charge for anything. Usage is unavailable for private apps: `POST /api/public/events` returns HTTP 403, and queued usage charges stop while the app is private. Existing usage data is preserved when you switch an app to private.
## Defining one
Go to **Usage → Events** and select **Create event**.
| Field | What it's for |
| - | - |
| **Name** | Shown in Meridian, in the [Plan Builder](/introduction-1), and on merchant billing if you price the event |
| **Key** | What your app reports against. Auto-filled from the name, lowercase snake\_case, **fixed after creation** |
| **Unit** | What you're counting: email, profile, run, call. Used in pricing labels like "\$0.10 per 1000 characters" |
| **Description** | Internal: when is this emitted |
The **Usage → Events** list is your catalog: every event you have defined, with its name, key and unit. Search it by name or key, and click the **Name** or **Key** header to sort it alphabetically, in either direction. A third click returns to the default order, and the sort lives in the URL, so a sorted view can be shared.
There is no pricing on this form. An event's included quantity, overage rate and cap are **per-plan** terms (the same event can be free on one plan and billed on another), so you set them on the plan, not on the event.
The events list is searchable by **name**, **key**, or **unit**. [Global search](/global-search) ranks an exact key match first when you are chasing a `track()` call.
## Reporting usage
Your app calls `track()` with the event's key through the [SDK](/events). The event page shows the exact emit snippet.
```ts theme={null}
await meridian.track({
eventKey: "emails_sent",
quantity: 1,
properties: { orderId: order.id, amount: order.total },
})
```
Send `properties`. Meridian stores them as-is, and stored properties are the only thing a [view](/usage-views) can read, so object ids and numeric values (amounts, byte counts, durations) are the ones worth sending. A property you never sent cannot be recovered after the fact: a view added next month reads your whole history, but only the properties that were actually in it.
An event key that isn't in your catalog is still accepted and still recorded: a `track()` call never fails because you haven't defined the metric yet. Those rows show up in [Activity](/usage-activity) flagged as not-in-catalog, with a one-click way to declare them.
## Seeing what came in
* The event's own page charts its **daily reported volume** across every store.
* **[Activity](/usage-activity)**: every reported event, newest first, filterable by event, store and date.
* **[Usage by store](/usage-activity)**: what each store has reported, all time or over a date range.
* The [report builder](/report-builder) reads usage as a dataset, so you can group it by month, by store, or against a segment.
* Tracking fires the [Custom event is tracked](/usage-event-tracked) automation trigger, so a milestone can send an email.
## Reading it another way
By default an event reports the quantity you tracked, summed over each store's billing period. Add a **[view](/usage-views)** on the event to read the same log differently: how many times it fired, or the total of a number in its properties, over a window you choose. Views are computed over your whole history, and `getUsage()` resolves a view key exactly as it resolves an event key.
A plan can also **price** a view rather than the event itself, which is how percentage-of-value pricing works. See [Two shapes of usage pricing](/usage).
## Billing on it (optional)
If you want a usage charge, add the event to a plan in the [Plan Builder](/create-a-plan) and give it terms there:
* **Included quantity**: how many units are free per billing cycle.
* **Overage rate**, and the **number of units** that rate covers, so "\$0.10 per 1000" is a rate and a divisor, not a per-unit price you have to convert.
* **Monthly cap**: the ceiling on usage charges for that plan, so a merchant is never surprised by the bill.
The cap is the amount the merchant approves when they subscribe. Meridian can't charge past it, so it's a real limit, not a warning, which is why Shopify emits an [approaching-the-cap event](/approaching-capped-amount) and Meridian turns it into an automation trigger. That flow is how you ask a merchant to raise the cap before usage stops being billable.
The same four terms can be set on a **[view](/usage-views)** instead: "2% of GMV" is a view that totals `properties.total_price`, priced at `0.02` per `1` unit. A plan meters one subject in total, an event or a view, because a Shopify subscription carries one usage line item.
`quantity` is a **count of whole units of the event**: `1` for one order, `50` for one call reporting fifty sent emails. Money and measurements belong in `properties`, as numeric values. An amount squeezed into `quantity` can never be separated back out into "how many" and "how much", and a property you never sent cannot be recovered.
The **charge** needs your app [hosted on Meridian](/sdk-hosting), because raising it reads the app's session store. Recording usage does not: `track()` succeeds and the row is stored either way, so a non-hosted app still gets its metering, just no invoice line.
## The Shopify constraints
These apply to **billing** on an event, not to metering it. Shopify's model sets two rules the Plan Builder enforces:
* **One usage line item per subscription**, so a plan charges overage on **one** event.
* **Usage is billed monthly**, so a plan with a usage event can't also offer an [annual price](/billing-interval).
You can define and track as many events as you like regardless. The limit is on what a single plan bills.
Deleting an event removes it from every plan that includes it, and takes its [views](/usage-views) with it: the delete confirmation lists them first. If a plan prices one of those views, the event can't be deleted, and Meridian answers a `422` naming each priced view and the plans pricing it. The usage rows already recorded against its key stay, and go back to reading as not-in-catalog.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.