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. Only the last step, raising the actual Shopify charge, needs hosting.

The whole loop, in a dozen lines

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.

await track({
  eventKey: "order_created",
  quantity: 1,
  properties: { orderId: order.id, total_price: 129.5 },
})

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 for the raw rows, and Usage by store for the per-store totals. No setup, no configuration.

Gate

Read a store’s current figure back with one key, in a render path or on the server.

const orders = getUsage("order_created")

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

Bill

Add the event to a plan in the Plan Builder 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.

The three nouns

	What it is	Where it lives
Event	A named action your app reports. The raw log, stored forever, one row per `track()`	Usage → Events
View	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

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:

// 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 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	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: defining an event, and what its page shows you.
Views: reading the same log a different way, and pricing on one.
Usage tracking: the track() call in full, with idempotency, batching, properties.
Activity and usage by store: the raw feed and the per-store breakdown.
Create a plan: attaching terms and publishing.

Concepts

Organization

Apps

Pricing plan builder

CRM

Automations

Emails

Affiliates

Hosting

AI Assistant

App Store

Access and sign-in

Usage

The whole loop, in a dozen lines

The three nouns

`quantity` is a count, not an amount

Two shapes of usage pricing

Where to go next

​The whole loop, in a dozen lines

​The three nouns

​quantity is a count, not an amount

​Two shapes of usage pricing

​Where to go next

The whole loop, in a dozen lines

The three nouns

`quantity` is a count, not an amount

Two shapes of usage pricing

Where to go next