Skip to main content
Usage tracking measures how much each customer uses your product: for usage-based billing, adoption reporting, or health signals. You define a usage module that binds a product object to a customer object, record usage events between their records, and surface the totals with usage blocks anywhere in Custral.

​
How it works

Usage module

A named binding between a product object and a customer object. The two sides every event connects.

Usage events

Each event ties a product record to a customer record with a quantity, e.g. “Customer A used 40 of Product X.”

Usage blocks

Blocks that read a module and display its events or a rolled-up total, on record pages or dashboards.

​
Set it up

1

Create a usage module

Give it a name (e.g. “Subscription Usage”) and pick the product object and the customer object whose records the events connect.
2

Send usage events

Record events against the module. Each carries a product, a customer, and a quantity. Send them from your own systems to the usage ingest endpoint (see the API reference). If you’d rather not send Custral record IDs, point the module at an identifier property so your own product/customer keys resolve to the right records.
3

Show usage in the app

Add a usage block to a record page or a dashboard and point it at the module.

​
The usage blocks

Usage Event Log

A paginated log of a module’s events. Placed on a record page, it auto-scopes to that record. Its role decides which events show.

Usage Stat

A single aggregated metric for a module (Count of events or Sum of their quantities) scoped the same way on a record page.
Roles. A record is either the product or the customer side of a module. When a usage block sits on a record page, it filters to that record’s role automatically, so a customer’s page shows their usage, and a product’s page shows usage of it. Leave the role empty for a global, unscoped view.

​
What usage can and can’t drive

The figure is computed when a record is read, and it is also written to the search index, so it works both where a record is rendered and where a set of records is queried.
The indexed figure is a snapshot. It is refreshed overnight, and whenever the record is next saved, so a view can be up to a day behind a burst of events. A grade is not: it aggregates the events live every time it recomputes.
To compare accounts, sort a view by the usage column or by a grade that reads it. A Usage Stat or a report on a dashboard still answers the aggregate question, “how much did everyone use this month”.

​
Troubleshooting

A usage block is empty. Either no events have been recorded for that module yet, the block points at the wrong module, or you’re on a record whose object isn’t the module’s product or customer type (so nothing scopes to it). Events aren’t landing on the right records. If you send your own keys instead of Custral record IDs, the module needs an identifier property set for that side. The ingest endpoint matches incoming keys against that property’s value. A customer’s page shows product-wide numbers. The block’s role is empty (global). Set the block’s Record Role so it scopes to the open record.