Usage Records API

Ingest usage events for metered billing and read current-period usage for a subscription.

Metering has three separate parts:

Object	Purpose	Endpoint
Meter	Defines what is measured and how events aggregate	`POST /api/meters`
Usage event	One measurement for a customer	`POST /api/usage/ingest`
Metered price	Connects a meter to a subscription price	`POST /api/prices`

Events are stored in the usage database. Billing reads those events when the subscription cycle closes.

1. Define a meter

curl https://api.getpaidhq.com/api/meters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "api_calls",
    "name": "API calls",
    "aggregation": "count"
  }'

For numeric aggregation, set field_name to the metadata key that contains the number.

{
  "code": "ai_tokens",
  "name": "AI tokens",
  "aggregation": "sum",
  "field_name": "tokens"
}

Supported aggregation values are count, sum, max, latest, and unique_count.

2. Attach the meter to a price

A price is metered when it has billable_metric_id.

{
  "variant_id": "var_123",
  "category": "subscription",
  "currency": "USD",
  "billing_interval": "month",
  "billing_interval_qty": 1,
  "billable_metric_id": "met_123",
  "scheme": "volume",
  "unit_price": 0,
  "tiers": [
    { "from_value": "0", "to_value": "0", "per_unit_amount": "0.0003", "flat_amount": 0 }
  ]
}

3. Create the subscription through an order

Checkout with a metered recurring price creates a subscription. That subscription drives recurring billing and usage aggregation.

4. Ingest usage

POST https://api.getpaidhq.com/api/usage/ingest

The endpoint accepts a batch of 1 to 500 events.

curl https://api.getpaidhq.com/api/usage/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "cus_123",
        "metric_code": "ai_tokens",
        "subscription_id": "sub_123",
        "external_id": "req_123",
        "timestamp": "2026-06-17T10:30:00Z",
        "metadata": { "tokens": "1500" }
      }
    ]
  }'

Event fields

metric_code string required - The meter code.
customer_id string - Existing GetPaidHQ customer id.
external_customer_id string - Your customer id. Use this instead of customer_id when you do not have the GetPaidHQ id in the emitting service.
subscription_id string - Optional attribution to a subscription.
external_id string - Idempotency key. Send one for every event.
timestamp string - RFC 3339 timestamp. Omit to use server time.
metadata object - String key/value pairs used by the meter.

Use exactly one of customer_id or external_customer_id.

Response

{
  "results": [
    { "index": 0, "id": "mev_123", "status": "recorded" }
  ]
}

Status values:

Status	Meaning
`recorded`	Stored synchronously
`duplicate`	`external_id` was already seen
`accepted`	Queued for async ingestion
`rejected`	This event failed validation; see `error`

Batch results are aligned by index with the request's events array.

5. Read current-period usage

GET https://api.getpaidhq.com/api/subscriptions/{id}/usage

{
  "subscription_id": "sub_123",
  "current_period_start": "2026-06-01T00:00:00Z",
  "current_period_end": "2026-07-01T00:00:00Z",
  "meters": [
    {
      "metric_code": "ai_tokens",
      "aggregation": "sum",
      "quantity": "1500"
    }
  ]
}

Billing

At cycle close, GetPaidHQ aggregates events for each metered price, creates usage invoice lines, and charges the subscription's stored payment method.

Usage Records API

On this page