> ## 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

Usage is Meridian's metering primitive. Your app reports an action; Meridian records it per store; four things read it back: your dashboard, your app, your automations, and, if you want it, the merchant's bill.

Only public apps can report usage or charge merchants for it: for private apps, `POST /api/public/events` returns HTTP 403 with `FEATURE_NOT_AVAILABLE_FOR_PRIVATE_APP`. If you switch your app to private, queued usage charges stop and existing usage data is preserved.

Nothing here requires you to charge for anything, and nothing requires your app to be [hosted on Meridian](/sdk-hosting). Only the last step, raising the actual Shopify charge, needs hosting.

## The whole loop, in a dozen lines

<Steps>
  <Step title="Track">
    Report the action, not the money. `quantity` is how many of the thing happened; anything measured (an amount, a byte count, a duration) goes in `properties`.

    ```ts theme={null}
    await track({
      eventKey: "order_created",
      quantity: 1,
      properties: { orderId: order.id, total_price: 129.5 },
    })
    ```
  </Step>

  <Step title="See">
    Everything you just sent is on the event's page under **Usage → Events**: its lifetime totals, a volume chart over the period you pick (by day up to 90 days, by month for a year or for all time), [Activity](/usage-activity) for the raw rows, and **Usage by store** for the per-store totals. No setup, no configuration.
  </Step>

  <Step title="Gate">
    Read a store's current figure back with one key, in a render path or on the server.

    ```ts theme={null}
    const orders = getUsage("order_created")

    if (orders && orders.includedQuantity != null && orders.usedThisPeriod >= orders.includedQuantity) {
      return <UpgradePrompt />
    }
    ```
  </Step>

  <Step title="Bill">
    Add the event to a plan in the [Plan Builder](/create-a-plan) with an included quantity, an overage rate and a monthly cap. Meridian does the arithmetic per billing period and raises the Shopify usage charges. Nothing in your `track` call changes.
  </Step>
</Steps>

## The three nouns

| | What it is | Where it lives |
| - | - | - |
| **[Event](/introduction-6)** | A named action your app reports. The raw log, stored forever, one row per `track()` | **Usage → Events** |
| **[View](/usage-views)** | A saved way to read one event's log: a count, or a total of a number in its properties, over a window | On the event's page |
| **Plan terms** | What a store gets free and what an overrun costs, per plan | [Plan Builder](/create-a-plan) |

An event is what happened. A view is a question about it. Plan terms are what it costs.

## `quantity` is a count, not an amount

This is the one convention worth getting right at the start, because it decides what you can ask later.

`quantity` is **how many whole units of the event occurred**: almost always `1`, and more only when you are batching (`quantity: 50` for one call reporting fifty sent emails). It is a whole number.

Money and measurements go in `properties`, as numeric values:

```ts theme={null}
// One order worth $129.50. Not `quantity: 129.5`.
await track({
  eventKey: "order_created",
  quantity: 1,
  properties: { orderId: order.id, total_price: 129.5, weight_kg: 2.4 },
})
```

Why it matters: `properties` is stored exactly as you send it and is **never** interpreted, which makes it the only part of a `track()` call you cannot backfill. A [view](/usage-views) added six months from now reads your whole history, but only the properties that were actually in it. A property you never sent is gone for good, and a `quantity` you overloaded with dollars can never be separated back out into "how many orders" and "how much were they worth".

## Two shapes of usage pricing

A plan meters **one** usage subject (Shopify allows a single usage line item per subscription), and that subject can be either kind:

| Shape | Subject | Example |
| - | - | - |
| **Per unit** | An event key | \$0.01 per 1,000 emails sent, first 5,000 free |
| **Percentage of value** | A [view](/usage-views) | 2% of GMV, first \$1,000 free |

The second is a view: a **total of `properties.total_price`** on `order_created`, measured over the **billing period**, priced at `0.02` per `1` unit. Once it is on a plan, it behaves exactly like a metered event: a per-period allowance, an overage charge, and a merchant-approved monthly cap.

Only a **billing-period** view can be priced. Shopify bills app usage per 30-day cycle, so "the overage of a rolling 7-day metric" has no meaning. A rolling view stays perfectly useful for display and gating, it just cannot carry a price.

## Where to go next

* **[Usage events](/introduction-6)**: defining an event, and what its page shows you.
* **[Views](/usage-views)**: reading the same log a different way, and pricing on one.
* **[Usage tracking](/events)**: the `track()` call in full, with idempotency, batching, properties.
* **[Activity and usage by store](/usage-activity)**: the raw feed and the per-store breakdown.
* **[Create a plan](/create-a-plan)**: attaching terms and publishing.


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