---
name: bill-metered-usage
description: Meter and bill usage-based or consumption pricing with the Fynex Billing API. Use when the user wants usage-based billing, metered billing, pay-as-you-go or consumption pricing, needs to send usage events, define a metric, price API calls or seats, check consumption against an allowance, or find out why metered usage does not match the invoice. Covers metric definition, event ingestion and idempotency, allowances and caps, and corrections.
---

# Bill metered usage with Fynex

Metering is the writable part of the Billing API. Contracts, subscriptions and credit
grants are created in the dashboard; usage is not.

## The shape

1. `POST /billing-api/v1/usage/metrics` — declare the meter.
2. `PUT /billing-api/v1/usage/contracts/{contractId}/metrics/{metricName}/price` — price it.
3. `POST /billing-api/v1/usage/events` — report consumption. Also `:batch` and `/csv`.
4. `GET /billing-api/v1/contracts/{contractId}/usage` — read the meter.

## Rules that bite

- **Quantities are decimal strings** (`"1250.5"`), not numbers. Money is integer minor
  units and ends `Minor`; rates are integer basis points and end `Bps`. Read the suffix.
- **The event id is your idempotency anchor.** Send it, and a replay is recognised rather
  than double-counted. Events are retained indefinitely — nothing prunes them — so a key
  stays recognised for the life of your integration.
- **`GET .../usage` is a live reading, not the bill.** The period is open, late events
  still move it, and allowances, credits, discounts and rounding are applied when the
  period closes. Show it as "usage so far", never as an amount owed, and reconcile against
  the invoice the period produced.
- **Corrections are corrections, not deletions.** Metered history is fixed by a correction
  against the period; events are never removed.
- **Rejected events are not lost.** They land in
  `GET /billing-api/v1/usage/dead-letters`, where they can be redriven or discarded — check
  it rather than assuming a `2xx` on the batch meant every row landed.

## Read next

- [Usage ingestion](/billing-api/v1/docs/usage-ingestion.md) · [Usage](/billing-api/v1/docs/usage.md)
- [Concepts](/billing-api/v1/docs/concepts.md) · [Errors](/billing-api/v1/docs/errors.md)
- [OpenAPI document](/billing-api/v1/openapi.json) · [Agent index](/billing-api/v1/llms.txt)