Usage
Overview
Usage-based billing charges what was actually used: API calls, hours, gigabytes, seats. Every report is a usage line with customer, metric, quantity and time. Open lines flow into the customer's billing preview on the next run, summed up per metric; afterwards they are Billed.
Normally the lines arrive through the API — from the system that measures the usage. Manual entry is for what has to be added afterwards. The page sits in the menu as a sub-item of Billing.
Core tasks
Check usage. The list shows time, customer, metric with description, quantity with unit, unit price and status Open or Billed. You can filter by customer, metric, Billed and subject. If Price from the plan is shown instead of a price, the billing plan's price applies.
Record usage. Record usage creates a line by hand. Customer, metric and quantity are required.
Correct. Once recorded, a usage line can be neither changed nor deleted — not through the API either. You balance an over-recorded quantity with a negative line of the same metric.
Go to billing. Go to billing leads to the list of previews.
Fields in detail
Record usage
| Field | Required | Values / format | What it does |
|---|---|---|---|
Customer customerId | yes | existing customer | Who the usage is charged to. |
Metric metric | yes | text, max. 60 characters, e.g. api_calls | The billed measure. Lines of the same metric are summed up in the preview — so always spell it the same way. |
Unit unit | no | text, max. 50 characters | Hours, pieces, GB … Shown next to the quantity in the list. |
Quantity quantity | yes | number with up to four decimal places, not 0 | How much was used. A negative value corrects an over-recorded quantity. |
Unit price (net) unitPriceAmount | no | amount | Price per unit. Empty = the billing plan's price applies. |
When occurredAt | no | date and time; empty = now | Decides which billing period the line falls into. |
Subject subjectType | no | licence, contract, order or none | What the usage refers to. |
Subject reference subjectRef | no | text, max. 100 characters | Which licence, contract or order is meant. |
External reference externalRef | no | text, max. 100 characters | Identifier in the reporting system. The same reference never creates a second line; the API then returns the existing one. This lets a system repeat a report safely. |
Description description | no | text, max. 255 characters | Shown below the metric in the list. |
Only via API and automation
| Field | Values / format | What it does |
|---|---|---|
brandId | brand; empty = no brand | Brand of the line. Only someone who may manage billing in that brand can set it. |
Settings & permissions
- Module
module.finance. - View:
finance.billing.view. Record:finance.recurring.manage— without it the *Record
usage* button is missing.
- API:
POST /api/v1/usage-records(repeatable withexternalRef),GET /api/v1/usage-records
with the filters customerId, brandId, metric, billed, subjectType, subjectRef, from and to.
FAQ & troubleshooting
**A line is still Open.** It is only charged on the next billing run of its customer; its time is what counts.
A report came twice but appears only once. Intended, if both carry the same external reference.
The quantity is wrong. Do not change it — balance it with a negative line.
"customerId, metric and quantity are required." One of the three required fields is missing in a report sent through the API.