Usage metrics
Usage metrics aggregate usage events into an overall measure of usage
A usage metric is a formula that aggregates a set of events into a single number representing total usage. To create a usage metric in the Sequence dashboard, click “Add new” and select “Usage metric”:
Give the metric a name and the type of usage events you want to aggregate – this should match the eventType in the usage event object. Then select how you want to aggregate the events; Sequence currently supports 3 aggregation types:
| Aggregation type | Requires aggregation property | Description | SQL equivalent |
|---|---|---|---|
COUNT | no | Total number of events | COUNT(*) |
SUM | yes | Sum of a numeric property | SUM(properties[‘property_name’]) |
UNIQUE | yes | Count of unique values of a property | COUNT(DISTINCT properties[‘property_name’]) |
SUM and UNIQUE require you to specify an event property as the argument of the aggregation, enter the name of this property in the “Aggregation property” field.
When the billing engine runs, it calculates all usage metrics for each of your customers over the last billing period. This calculated value is then combined with a price to determine the charge that will appear on the invoice.
Filtering
You can further refine the scope of a usage metric using filters. A filter limits the aggregation input to events that match a specific event property value. For example, if your events have a property called method,
you can filter your metric to events where method = card_payment:
If multiple filters are specified, only events matching all filters are included in the metric calculation.
Grouping
Use grouping to customize the layout of a usage-based charge on an invoice by breaking down usage by an event property.
For example, grouping by method will let you display the usage for method = card_payment and method = direct_debit on separate lines on the invoice.
To learn more about customizing your invoice layout via grouping, reach out to the Sequence team.
Editing metrics
Updating and deleting usage metrics is currently only supported via the API. Making changes to a metric will not retroactively affect invoices already created. To update or correct existing invoices after changing a metric, recalculate a draft invoice, or issue a credit note against an issued invoice.
Usage calculation methods
Choose between current-period or cumulative usage tracking, ideal to bill for monthly overages over a running total of customer usage.
Billing period calculation (default): Charges are based on usage in each billing period.
Cumulative calculation: Usage is counted from the billing start date and accumulates with each billing period to determine the pricing tier. Only the net new usage in the period is billed for.
Custom metrics
Sequence supports custom usage metric formulas and parameters for more advanced usage aggregation scenarios. Ingest raw usage data and let Sequence handle complex data mapping and calculation logic. Speak to our team to learn more about custom metrics.
Custom metrics: Custom metrics allow for advanced usage aggregations expressed as formulas.
Parameters: Parameters can be used in custom metrics as variables that can be set when a price is configured for a customer. For example, if you have a custom metric to calculate a ratio, you can optionally include a parameter to set the specific ratio on a per-customer basis.