Usage is whatever your backend reports. Each time an end user consumes something you meter, your backend reports a usage event for their buyer organization and a capability; your application's region counts it against the allowance that the organization's plan grants for that capability.
What a usage event is
A usage event names five things:
| Field | What it says |
|---|---|
usage_event_id | Your own unique ID for the event. The region drops repeats, so an event sent twice is counted once |
organization_id | Which buyer organization consumed it, taken from the verified session token |
capability_key | What was consumed, as a capability you defined, such as report_exports |
quantity | How much, a number greater than 0 |
occurred_at | When it happened |
Your backend reports it with reportUsage() after the work is done. The Server SDK buffers events and sends them in batches; while the region is unreachable they wait in a backlog. The region accepts or refuses each event on its own: a refused event, for example one without a quantity or for an organization that is not a customer of your application, is passed to your on_rejected callback and does not hold up the others. Report usage has the code; the refusal reasons are in the Server SDK reference.
When the cost is known only afterwards
Some work has a cost you learn only when it is done, such as a call whose size depends on the answer. Reserve an amount first with reserve(), then settle what was actually used with confirm(), or give the whole reservation back with release(). A reservation that is neither confirmed nor released before it expires is reclaimed by the region. The reference has an example.
How usage meets the allowance
A plan version grants capabilities through its entitlement rules, one per capability: an allowance, and whether it resets every month or never. The region counts the buyer organization's accepted events against the allowance of the current period, and starts a new period at each reset.
Your backend sees the result in every ruling: limit is the allowance of the current period and remaining is what is left of it. What happens once nothing is left depends on the capability's overage policy; see Entitlements.
Where usage shows up
| Who | Where |
|---|---|
| You, in the operator console | Metering & Events shows the events of each customer as they arrive; operations analytics show usage across your customers |
| Your systems | The Management API returns usage totals for all buyer organizations, and the raw event stream |
| Your end users | The React component UsageMeter shows their organization's usage inside your own pages |
Where to go from here
Report usage from your backend
Send a first usage event
Reserve, confirm and release
Refused usage events
The objects of this product, and how they meet the other three on one buyer organization, are in How ShipRev works. The product page is Metering.