Skip to main content
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 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. 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 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. The event page shows the exact emit snippet.
Send properties. Meridian stores them as-is, and stored properties are the only thing a view 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 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: every reported event, newest first, filterable by event, store and date.
  • Usage by store: what each store has reported, all time or over a date range.
  • The 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 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 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.

​
Billing on it (optional)

If you want a usage charge, add the event to a plan in the Plan Builder 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 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 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, 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.
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 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.
Last modified on October 2, 2026