Usage & Metering

For metered billing:

1. Create a meter.
2. Attach that meter to a recurring price with billable_metric_id.
3. Create the subscription through an order.
4. Send usage events to POST /api/usage/ingest.

Always send external_id with each event. It is the idempotency key used to avoid double-counting retries.

API pages used

• Usage Records API
• Catalog API
• Subscriptions API

Implementation notes

• Use external_customer_id when the emitting service does not know the GetPaidHQ customer id.
• Use subscription_id when you need direct subscription attribution.
• Omit subscription_id only when the customer's earliest active metered subscription should receive unattributed usage.
• Use async ingestion only when NATS JetStream is deployed.

For the system behavior, see Usage & Metering.