Define your metered unit clearly before writing any billing code: what constitutes one billable unit (API call, task completed, tokens processed, minutes of work), and what granularity you will report it at.
Instrument the agent to emit usage events to a billing event store as work is performed; each event must include: customer ID, unit count, unit type, timestamp, and a unique event ID for deduplication.
At the end of each billing period (or in real time if using a streaming billing model), aggregate usage events per customer and report them to your billing platform (Stripe Billing's usage records API, or equivalent); use idempotency on usage record submission to prevent double-reporting.
Send customers an itemized usage summary before charging — automated usage-based billing without transparency leads to disputes; provide a usage dashboard or at minimum a pre-charge email.
For customers approaching their budget cap, send a proactive alert and optionally pause the agent until the customer acknowledges; never silently exceed a stated cap.
Issue invoices with line items that map back to the usage event aggregates; store the invoice ID and period in your audit log alongside the usage events.
Known gotchas
Usage events can be lost if the agent crashes mid-task — write the usage event before or during the work, not only on completion; use a saga pattern or at-least-once delivery and deduplicate on the billing side.
Customers will dispute usage charges they don't recognize; maintain a human-readable usage log they can access self-service, or expect high support volume from automated billing.
Stripe's usage record API aggregates usage within a subscription period and does not support retroactive correction for closed periods — if you discover a reporting error after the invoice is finalized, you must handle the correction as a credit note, not a data fix.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp