Usage-Based Billing

Usage-Based Billing lets you charge customers based on how much of your product they consume — API calls, GB transferred, seats active, characters rendered, anything measurable. You define **Meters** to track usage, ingest **Meter Events** from your infrastructure, attach **Usage Prices** (PER_UNIT, PER_PACKAGE, TIERED_GRADUATED, or TIERED_VOLUME) to Products, and HL Hunt handles aggregation, invoicing, and billing automatically on each subscription cycle. Optional **Usage Alerts** notify you or your customers when thresholds are crossed, and **Credit Grants** let you prepay or trial usage.

POST
/v1/billing/meters

Create a Meter

Create a meter to track a specific usage metric. `event_name` is the identifier you'll send when ingesting events. `default_aggregation.formula` can be `sum`, `count`, `last`, or `max`. `customer_mapping.event_payload_key` (default `customer_id`) tells HL Hunt which field in the event payload identifies the customer.

curl -X POST https://api.hlhunt.org/v1/billing/meters \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "API Calls",
    "event_name": "api_call",
    "default_aggregation": { "formula": "count" },
    "customer_mapping": { "event_payload_key": "customer_id", "type": "by_id" },
    "value_settings": { "event_payload_key": "value" }
  }'
GET
/v1/billing/meters

List Meters

List all meters for your account. Supports `limit`, `starting_after`, `ending_before`, and `status` (`active`, `inactive`).

curl https://api.hlhunt.org/v1/billing/meters \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/billing/meter-events

Ingest a Meter Event

Record a unit of usage for a customer. Send `event_name` matching the meter, a `customer_id` identifying the buyer, a numeric `value`, and an optional `identifier` for idempotency (dedupes within 24h). Events outside the window [-35 days, +5 minutes] are rejected. The ingestion endpoint supports up to **1,000 events/sec per API key**.

curl -X POST https://api.hlhunt.org/v1/billing/meter-events \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_call",
    "identifier": "req_abc123",
    "timestamp": "2026-04-21T12:00:00Z",
    "payload": { "customer_id": "cus_xxx", "value": 1 }
  }'
POST
/v1/billing/meter-event-adjustments

Adjust Meter Events (void)

Void a previously-ingested event by its `identifier`. Emits a compensating negative-value record at the current time — the original row is never mutated. Only supported on meters with aggregation `sum` or `count`.

curl -X POST https://api.hlhunt.org/v1/billing/meter-event-adjustments \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_call",
    "type": "cancel",
    "cancel": { "identifier": "req_abc123" }
  }'
GET
/v1/billing/meters/:id/event-summaries

Query aggregated usage

Return aggregated usage for a meter over a time range, bucketed by `day`, `hour`, or `minute`. Use this to power customer-facing usage dashboards or reconcile billed quantities.

curl "https://api.hlhunt.org/v1/billing/meters/mtr_xxx/event-summaries?start_time=2026-04-01T00:00:00Z&end_time=2026-04-30T23:59:59Z&value_grouping_window=day" \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/billing/alerts

Create a Usage Alert

Create a threshold alert on a meter. Fires a `usage_alert.triggered` webhook and/or email when the aggregated usage crosses `threshold` within `window_seconds`. Supports `filter` by customer.

curl -X POST https://api.hlhunt.org/v1/billing/alerts \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "meter_id": "mtr_xxx",
    "title": "10k calls/day",
    "threshold": 10000,
    "window_seconds": 86400
  }'
POST
/v1/billing/credit-grants

Create a Credit Grant

Issue prepaid or promotional credit to a customer. Credits are consumed automatically on usage invoices before the card is charged. Supports expiration, grant priority, and scoping to specific meters.

curl -X POST https://api.hlhunt.org/v1/billing/credit-grants \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xxx",
    "amount": { "monetary": { "value": 10000, "currency": "USD" } },
    "category": "promotional",
    "name": "Welcome credit",
    "expires_at": 1767225600
  }'
POST
/v1/billing/credit-grants/:id/void

Void a Credit Grant

Void the unused portion of a credit grant. Fully-applied (depleted) grants cannot be voided.

curl -X POST https://api.hlhunt.org/v1/billing/credit-grants/cgr_xxx/void \
  -H "Authorization: Bearer sk_live_your_api_key"