Usage & Metering
How metered usage moves from events to subscription billing.
Usage billing has three pieces: a meter, a metered price, and usage events.
Core objects
- Meter: what to measure and how to aggregate it.
- Usage event: one measurement for a customer.
- Metered price: a recurring price linked to a meter.
- Subscription: the recurring agreement that owns the metered line.
Flow
- Create a meter.
- Create a recurring price with
billable_metric_id. - Complete an order with that price.
- Send usage events.
- Read current-period usage when needed.
- At cycle close, billing computes usage lines from the meter events.
Attribution
Send either:
customer_idfor the GetPaidHQ customer id, orexternal_customer_idfor your own customer id.
external_id is the event deduplication id. It is not the customer id.
If an event has no subscription_id, GetPaidHQ attributes it to the customer's
earliest active metered subscription for that meter.
Ingestion modes
| Mode | Behavior |
|---|---|
sync | Validate and write usage events inline. Default. |
jetstream | Publish validated events to NATS JetStream and drain them in batches. |
Set USAGE_INGEST_MODE to choose the write path.
Event storage
| Store | Use when |
|---|---|
| Postgres | Default and simplest deployment. |
| Separate Postgres usage DB | You want separate retention or scaling for usage events. |
| ClickHouse | You need an analytical usage-event store. |
Set USAGE_EVENT_STORE and USAGE_DATABASE_URL as needed.
For request and response fields, see Usage Records API.