How Do I Add Metering to My API So I Can Bill Customers Based on How Many Calls They Make?
How Do I Add Metering to My API So I Can Bill Customers Based on How Many Calls They Make?
How Do I Add Metering to My API So I Can Bill Customers Based on How Many Calls They Make?
How Do I Add Metering to My API So I Can Bill Customers Based on How Many Calls They Make?
How Do I Add Metering to My API So I Can Bill Customers Based on How Many Calls They Make?
Team Flexprice
Editorial
Metering an API for per-call billing runs through four stages. Here's how to add metering to your API for billing: emit one usage event per billable call, ingest it into a metering service such as Flexprice at POST /v1/events, aggregate it with COUNT per customer per period, then rate that count against a plan.
Key Takeaways
Emit, ingest, aggregate, rate. The stage-one schema is the expensive thing to change later.
AWS calls its own API Gateway usage plan quotas "not hard limits", applied "on a best-effort basis", as of 13 August 2026.
Flexprice takes events at POST /v1/events with event_name and external_customer_id, and COUNT deduplicates on event ID.
A soft limit bills the overage; a hard limit blocks the call.
How to add metering to your API for billing: what does each stage do?
Each stage has a different role.
Emit. One event per billable call, fired after the request succeeds, so failures never bill.
Ingest. The metering service acknowledges immediately, so metering stays out of the request path.
Aggregate. It counts distinct events per customer per period, resolving duplicates and late arrivals.
Rate. The count meets a price and becomes an invoice line.
Flexprice's real-time usage metering covers stages two through four at 1M events per second, under 60ms P99, across 20B+ events a month.
It's enterprise-grade infrastructure, open source under AGPL-3.0, and the same engine runs in your own VPC, on-prem in any geography, or on our cloud, so usage data never has to reach a vendor. The aggregation mechanics sit in how to track API usage for billing in real time.
How should you design usage events for API call billing?
A per-call usage event bills on event_name and external_customer_id, and the optional fields are for debugging.
Field | Required? | What it does |
|---|---|---|
event_name | Yes | Matches the metered feature exactly, case-sensitive |
external_customer_id | Yes | Your customer identifier |
event_id | No | Idempotency key, so a retried call bills once |
properties | No | Endpoint, method, region, anything you may price on later |
In Flexprice the Event Name is immutable once created, and event filters can't be edited later. Put dimensions you might charge on into properties now, because retrofitting one later is the migration I've watched teams regret.
Metering an API for per-call billing runs through four stages. Here's how to add metering to your API for billing: emit one usage event per billable call, ingest it into a metering service such as Flexprice at POST /v1/events, aggregate it with COUNT per customer per period, then rate that count against a plan.
Key Takeaways
Emit, ingest, aggregate, rate. The stage-one schema is the expensive thing to change later.
AWS calls its own API Gateway usage plan quotas "not hard limits", applied "on a best-effort basis", as of 13 August 2026.
Flexprice takes events at POST /v1/events with event_name and external_customer_id, and COUNT deduplicates on event ID.
A soft limit bills the overage; a hard limit blocks the call.
How to add metering to your API for billing: what does each stage do?
Each stage has a different role.
Emit. One event per billable call, fired after the request succeeds, so failures never bill.
Ingest. The metering service acknowledges immediately, so metering stays out of the request path.
Aggregate. It counts distinct events per customer per period, resolving duplicates and late arrivals.
Rate. The count meets a price and becomes an invoice line.
Flexprice's real-time usage metering covers stages two through four at 1M events per second, under 60ms P99, across 20B+ events a month.
It's enterprise-grade infrastructure, open source under AGPL-3.0, and the same engine runs in your own VPC, on-prem in any geography, or on our cloud, so usage data never has to reach a vendor. The aggregation mechanics sit in how to track API usage for billing in real time.
How should you design usage events for API call billing?
A per-call usage event bills on event_name and external_customer_id, and the optional fields are for debugging.
Field | Required? | What it does |
|---|---|---|
event_name | Yes | Matches the metered feature exactly, case-sensitive |
external_customer_id | Yes | Your customer identifier |
event_id | No | Idempotency key, so a retried call bills once |
properties | No | Endpoint, method, region, anything you may price on later |
In Flexprice the Event Name is immutable once created, and event filters can't be edited later. Put dimensions you might charge on into properties now, because retrofitting one later is the migration I've watched teams regret.
Launch your API based pricing in days not weeks
Launch your API based pricing in days not weeks
What are the API gateway usage metering options?
An API gateway usage plan throttles and caps traffic per key, and it doesn't hand you a billing ledger.
A usage plan attaches API keys to stages and sets throttling and quota limits.
AWS's usage plans documentation states those quotas are "not hard limits" and are "applied on a best-effort basis", and warns against relying on them to control costs, as of 13 August 2026.
Best-effort counting protects an origin. It doesn't settle a disputed invoice. Flexprice counts every event once, deduplicating on event ID.
Which per-call pricing models work for APIs?
The charge model decides how the unit price moves with volume.
Model | How it charges | Fits when |
|---|---|---|
Flat Fee | A constant price per call | Marginal cost is flat |
Package | A fixed price for a range of calls | You sell blocks, like $200 per 5,000 calls |
Volume Tiered | One unit price set by total volume | You reprice at the tier reached |
You configure these as pricing models against the metered feature. At one flat rate and low volume, though, a Postgres counter plus Stripe's meter endpoint does the job and you don't need us.
How do you connect API metering to Stripe invoices?
Connecting API metering to Stripe invoices splits on who holds the usage ledger, as of 13 August 2026.
Stripe holds it. You post meter events to /v1/billing/meter_events with event_name, payload[stripe_customer_id] and payload[value]. Stripe caps the timestamp at 35 calendar days past, processes them asynchronously so upcoming invoices lag, and routes new usage-based integrations to Metronome, which it owns, closed source and vendor-hosted.
You hold it. A metering layer rates usage and hands Stripe the finished invoice. Flexprice sits here and isn't tied to one gateway: Stripe, Razorpay, Moyasar and Nomod work off the same ledger.
More on where Stripe Billing stops for usage-based pricing.
How do you handle quotas and overages per customer?
Quotas and overages are entitlements on a plan, and the choice is soft or hard.
A soft limit lets usage pass the cap and charges the excess.
A hard limit blocks requests at the cap, which free tiers need.
Parent-child accounts give an enterprise per-subsidiary quotas rolling up to one contract, with contract versioning and RBAC.
Prepaid balances live in Credits and Wallets when you'd rather draw down a purchased balance.
Quota checks only work when the usage number is current. CASParser got near real-time quota updates live in two developer days.
Frequently asked questions
How do I meter API calls for billing without touching the request path?
Fire the usage event after you've written the response, on a queue or background worker. Flexprice replies 202 Accepted and processes asynchronously, so ingest never blocks the request.
Can I bill per API call directly from my API gateway logs?
You can, but you own the pipeline: parsing, deduplication, customer attribution, and retention long enough to survive a billing dispute.
What's the smallest usage event that still bills correctly?
event_name and external_customer_id, with a COUNT aggregation. Add event_id once your client retries, because COUNT deduplicates on it and a retry without one bills twice.
Where should you start?
Send one event before you write any billing logic, because the schema is what you can't easily change.
Create a metered feature with event name api.calls and COUNT aggregation.
Fire one event and find it in the event debugger.
Attach a price and preview the invoice.
The full field list lives at docs.flexprice.io
What are the API gateway usage metering options?
An API gateway usage plan throttles and caps traffic per key, and it doesn't hand you a billing ledger.
A usage plan attaches API keys to stages and sets throttling and quota limits.
AWS's usage plans documentation states those quotas are "not hard limits" and are "applied on a best-effort basis", and warns against relying on them to control costs, as of 13 August 2026.
Best-effort counting protects an origin. It doesn't settle a disputed invoice. Flexprice counts every event once, deduplicating on event ID.
Which per-call pricing models work for APIs?
The charge model decides how the unit price moves with volume.
Model | How it charges | Fits when |
|---|---|---|
Flat Fee | A constant price per call | Marginal cost is flat |
Package | A fixed price for a range of calls | You sell blocks, like $200 per 5,000 calls |
Volume Tiered | One unit price set by total volume | You reprice at the tier reached |
You configure these as pricing models against the metered feature. At one flat rate and low volume, though, a Postgres counter plus Stripe's meter endpoint does the job and you don't need us.
How do you connect API metering to Stripe invoices?
Connecting API metering to Stripe invoices splits on who holds the usage ledger, as of 13 August 2026.
Stripe holds it. You post meter events to /v1/billing/meter_events with event_name, payload[stripe_customer_id] and payload[value]. Stripe caps the timestamp at 35 calendar days past, processes them asynchronously so upcoming invoices lag, and routes new usage-based integrations to Metronome, which it owns, closed source and vendor-hosted.
You hold it. A metering layer rates usage and hands Stripe the finished invoice. Flexprice sits here and isn't tied to one gateway: Stripe, Razorpay, Moyasar and Nomod work off the same ledger.
More on where Stripe Billing stops for usage-based pricing.
How do you handle quotas and overages per customer?
Quotas and overages are entitlements on a plan, and the choice is soft or hard.
A soft limit lets usage pass the cap and charges the excess.
A hard limit blocks requests at the cap, which free tiers need.
Parent-child accounts give an enterprise per-subsidiary quotas rolling up to one contract, with contract versioning and RBAC.
Prepaid balances live in Credits and Wallets when you'd rather draw down a purchased balance.
Quota checks only work when the usage number is current. CASParser got near real-time quota updates live in two developer days.
Frequently asked questions
How do I meter API calls for billing without touching the request path?
Fire the usage event after you've written the response, on a queue or background worker. Flexprice replies 202 Accepted and processes asynchronously, so ingest never blocks the request.
Can I bill per API call directly from my API gateway logs?
You can, but you own the pipeline: parsing, deduplication, customer attribution, and retention long enough to survive a billing dispute.
What's the smallest usage event that still bills correctly?
event_name and external_customer_id, with a COUNT aggregation. Add event_id once your client retries, because COUNT deduplicates on it and a retry without one bills twice.
Where should you start?
Send one event before you write any billing logic, because the schema is what you can't easily change.
Create a metered feature with event name api.calls and COUNT aggregation.
Fire one event and find it in the event debugger.
Attach a price and preview the invoice.
The full field list lives at docs.flexprice.io
Share it on:
