Usage Metering & Compilation

What this does for you

If you bill customers based on how much they use your product — API calls, seats, storage, transactions, or any other metered quantity — Usage Metering lets you connect the place where that usage already lives (your own database or spreadsheet) and have it automatically turned into charges on the right customer's subscription. You don't need to build an integration or manually enter numbers: you tell the system where your usage data is and how to read it, and it pulls fresh usage on a nightly schedule and applies it to the customer's wallet balance for you.

For situations where you don't have a live data source, or you just need to backfill or spot-check some usage, you can also upload a file of usage records directly, and view a chart of what's been recorded for any customer's subscription.

Who can use it

This is managed by your own team, not by your end customers. What a team member can do depends on the permissions assigned to their role:

• Usage sources — viewing requires usageSource.view; creating, editing, and archiving/reactivating require usageSource.create, usageSource.edit, and usageSource.archive.
• Usage compilation — viewing requires usageCompilation.view; creating, editing, and archiving/reactivating require usageCompilation.create, usageCompilation.edit, and usageCompilation.archive.
• Usage collection — viewing the upload log requires usageCollection.view. Uploading a new file goes through the same modal as the general Imports flow and is actually gated by import.create, not a usage-collection-specific permission.

If a button is greyed out or you land on an access-denied screen, your account admin needs to grant you the relevant permission.

Where to find it

Three related screens under Settings → Configure billing:

• Usage sources (/settings/configurebilling/usageSources)
• Usage compilation (/settings/configurebilling/usageCompilation)
• Usage collection (/settings/configurebilling/usageCollection)

How to use it

Step 1 — Connect a Usage Source

1. Go to Usage sources and click + New usage source.
2. Fill in a title/description and pick the type of system your usage data lives in: MySQL, GSheets (Google Sheets), MongoDB, or Get API Link (a webhook you push usage events to yourself).
3. Enter the connection details for that source (host, credentials, database name, or the sheet URL, depending on the type you picked). Picking "Get API Link" shows you a worked example instead — the webhook URL and the JSON payload shape (BUID, CustomerId, count, timestamp) it expects.
4. For MySQL, GSheets, or MongoDB, click Validate to test the connection. Once it succeeds, the source is marked as validated — if you come back later to edit the connection details, you'll see a Re-Validate button instead. Saving is blocked until this passes. An API Link source doesn't need this step.
5. Save. Your new source appears in the Usage sources table, where you can Edit or Archive/Unarchive it from the row actions.

Step 2 — Set up a Usage Compilation

1. Go to Usage compilation and click + New usage compilation.
2. Pick the Usage Source you just connected. For a MySQL/MongoDB/GSheets source, the form then shows you the tables (or sheets) available in it; an API Link source skips this since there's no table to inspect.
3. Pick the specific table/sheet that holds your usage events, then map its columns: which column is the usage quantity, which is the timestamp, and which identifies the billing unit (and subscription, where applicable).
4. Choose a Billing Unit — the metered item (e.g. "API calls") this compilation feeds — and a Calculation type: sum, min, max, avg, or count. This decides how multiple usage rows for the same customer on the same day are combined into one billed amount. There's a Reset button if you want to start the Calculation section over.
5. Save. The compilation now appears in the Usage compilation table, where you can edit it or archive/unarchive it.
6. This screen doesn't attach the compilation to anything by itself — go to the relevant Plan or Product editor's Usage & Wallet section and pick it from the Usage compilations field there (only available when that Plan/Product is Usage based and Recurring). That's what tells the nightly job which subscriptions to rate against it.

Step 3 — Let it run, or upload usage manually

Once a Usage Compilation is attached to a plan/product a customer is subscribed to, usage is pulled from your connected source and applied to that customer's wallet automatically every night — no further action needed.

If you'd rather upload usage by hand, go to Usage collection and click + Add usage. This opens the same upload modal as Imports: drop in a CSV or JSON file, or click Download first to get a sample file showing the expected columns (Company's Customer ID, billing unit's BUID, usage count, and an optional timestamp — it defaults to "now" if left blank). Each upload shows up as a row in the Usage collection table with the date/time of ingestion, total events, source, and operation.

To see what's actually been recorded for a specific customer, open that customer's record and look at the Usage metrics card on their Overview page: pick a date range and a subscription from Select subscription, click Get consumption, and you'll get a chart of their usage for that period.

Tips / things to know

• The nightly usage pull only picks up new records it hasn't seen before, so it's safe to leave it running — it won't double-count the same event twice.
• Usage debits are applied even if it pushes a customer's wallet balance negative; overage isn't blocked at the metering step, it shows up as a negative balance to be handled at billing time.
• A CSV/JSON upload through Usage collection checks for duplicate rows (same customer, billing unit, timestamp, and count) and flags them rather than double-billing — but it's still a separate record-keeping path from the automatic nightly pull, not a substitute for connecting a live source if you need that usage to actually bill.
• Every usage source and usage compilation can be archived instead of deleted, so you can pause a connection without losing its configuration or history.
• Usage aggregation always runs on a fixed nightly schedule; there isn't a way to change how frequently usage gets pulled or rated from the interface.
• There's no way to delete a Usage Collection upload log entry from the product once it's been created.
• If a usage row's customer ID or billing unit ID doesn't match an existing customer or billing unit in your account, that row is skipped rather than causing the whole upload to fail — double-check your source file against the validation results if a bulk upload reports fewer records processed than you expected.