Usage ingestion

Real-time ingestion, from events to usage

Q: What is usage ingestion?

Usage ingestion is the path a usage event takes from your product to a billable number. Lago receives the event, deduplicates it, enriches it with its billable metric, subscription and plan, and aggregates it into the usage that invoices and wallet balances read.

Q: How many events per second can Lago ingest?

It depends on the connector and deployment. Lago's performance guide reports about 10,000 events/sec for REST batch and 1–3 million for Kafka/Redpanda with ClickHouse Cloud in its tested configurations. Amazon Kinesis and S3 have different limits and jobs. Validate your own peak load and event-to-billable lag.

Q: What happens if the same event is sent twice?

Lago deduplicates retries, but the key depends on the event store. On ClickHouse, a changed timestamp can make a retry a new billable event. Send an explicit timestamp and resend the original event payload unchanged, then reconcile usage before invoicing.

Q: What does enrichment add to an event?

Lago matches each event to its billable metric, subscription and plan, then adds the value billing needs. Lookups are served from memory, so there is no database round trip per event. Events for pay-in-advance charges are routed separately so they can be invoiced right away.

Q: How fast does a wallet's ongoing balance update after an event?

Typically in under a second. The ongoing balance is the wallet balance minus current usage, taxes included. Lago waits until usage includes the new event before refreshing, so a balance is never computed on partial data.

Follow one event through Lago's pipeline: the events API, Kafka, deduplication, enrichment, usage aggregation and the wallet balance it moves.

Ingest usage from any source

HTTP
Batch HTTP
Kafka
AWS Kinesis
AWS S3
AWS SQS
Google Cloud
Azure
Redis
MongoDB
CockroachDB
SQL
CSV Files
Websocket
Custom

One usage event, seven steps.From the API to the wallet balance.

Follow a single event through Lago's ingestion pipeline. The model moves to the step you are reading.

01 / 07
API intake
Send usage through the REST API, Kafka or Redpanda, Amazon Kinesis, or Amazon S3 for backfills. Lago's performance guide reports about 10,000 events/sec for REST batch and 1–3 million for Kafka/Redpanda with ClickHouse Cloud in its tested setups.
REST, one or many
Send single events or batches of up to 100. A batch is checked event by event, then accepted or rejected as a whole.
Validation per event
Each event needs a transaction ID and a metric code. Errors come back per event, so you know exactly what to fix.
Straight to the stream
Accepted events are published to Kafka right away. The API never waits on billing logic.
1–3Mevents/sec
Kafka/Redpanda + ClickHouse Cloud load test
100K+events/sec
On Amazon Kinesis
15+sources
HTTP, streaming and cloud storage
02 / 07
Event stream
Every event lands on a Kafka or Redpanda topic. Two readers consume it independently: one stores the raw events in ClickHouse, the other prepares them for billing.
Raw events kept
ClickHouse keeps every event as it was received. It is the audit trail, compressed 10 to 20 times versus raw JSON.
Independent readers
Each reader tracks its own position in the stream. A slow reader never holds the other back.
Managed or yours
Lago Cloud runs Kafka and ClickHouse for you. Self-hosted, you run both and control scaling and retention.
100%retained
Every raw event, a full audit trail
10–20xsmaller
Than raw JSON, once compressed
99.9%uptime
Historical, with Enterprise SLAs
03 / 07
Deduplication
Retries happen. Lago identifies each event by its transaction ID, subscription, metric and timestamp, so an event sent twice is counted once.
Safe retries
Events are keyed on transaction ID and timestamp. Retry the same payload on a 429 or a 5xx and it still bills once.
New timestamp, new event
If only the timestamp differs, Lago treats it as a separate event.
Clean reads
Duplicates collapse in storage, and every usage read sees the deduplicated result.
1xbilled
However many times the same event is retried
100%idempotent
Keyed on transaction ID and timestamp
0dedup code
To write on your side
04 / 07
Enrichment
A Go service matches each event to its billable metric, subscription and plan, then stamps in the value billing needs. A second pass expands it per charge filter for dimensional pricing.
In-memory lookups
Metrics and subscriptions are cached in memory and kept in sync with the database. No round trip per event.
Three tables
Raw events for the audit trail, enriched events for billing aggregation, and expanded events for dimensional billing.
Nothing dropped
Events that fail on a temporary error go to a dead-letter queue and are retried for up to 12 hours.
0round trips
Lookups are served from memory
0dropped
Failed events wait in a dead-letter queue
12h auto-retry
Before anyone has to look
05 / 07
Aggregation
Enriched events roll up into usage per charge as they arrive. Lago benchmarks an event becoming billable in under 2 seconds at p99, with aggregation staying fast over billions of events.
Pre-aggregated usage
Count, sum, max and latest are stored already rolled up, so reading current usage stays fast at any volume.
Any time zone
Usage lines up with each customer's local day, wherever they are.
Raw when needed
Unique counts, weighted sums and custom aggregations are computed from the raw events instead.
< 2s p99
From event to billable
< 100ms p99
Billing aggregation
1B+events
Aggregated at that speed
06 / 07
Checkpoint
Before a wallet updates, Lago waits for usage to include the event that triggered it. No balance is computed on partial data.
At-least-once delivery
Progress is committed only after events are processed. Replays are deduplicated, so nothing is lost or counted twice.
Wait for usage
The wallet refresh checks every 100 ms until usage includes the triggering event. It usually takes a few checks.
Safety net
If usage lags by more than 5 seconds, a periodic job refreshes the wallet instead.
< 1s refresh
Typical wallet refresh
10checks/sec
Until usage catches up
0partial reads
Balances only use complete usage
07 / 07
Wallet balance
The ongoing balance is the wallet balance minus current usage. It typically moves in under a second after the event lands.
Ongoing balance
Prepaid credits minus usage not yet invoiced, taxes included. Usage draws from wallets in priority order.
Automatic top-ups
When the balance crosses a threshold, Lago tops the wallet up. Top-ups are rate-limited, and back off after a declined payment.
Depletion webhook
The first time the balance reaches zero, Lago sends a webhook and evaluates wallet alerts.
< 1s update
Typical ongoing balance update
0manual top-ups
Threshold rules refill the wallet
100%of usage
Taxes included, drawn down live

Balances and alerts, computed live from usage

Current usage, always current

In Lago's documented Kafka/ClickHouse benchmark, accepted events became billable in under 2 seconds at p99. Test the lag for your own ingestion path.

Live wallet balances

The ongoing balance is prepaid credits minus current usage, taxes included. It moves within a second of each event.

Alerts as usage lands

Usage and wallet alerts are checked against live usage, and send a webhook as soon as spend, units or a balance cross a threshold.

Read a live balance in one call

Fetch a wallet's ongoing balance or a customer's current usage from the API. Both already include the events that just landed.

Get a customer's current usage

Create usage alerts

Create credits consumption alerts

2 "wallet": {

3 "external_customer_id": "acme",

4 "status": "active",

5 "credits_balance": "500.0",

6 "credits_ongoing_usage_balance": "128.4",

7 "credits_ongoing_balance": "371.6",

8 "ongoing_balance_cents": 37160

9 }

10}

Read a wallet from the Lago API:

curl -s "$LAGO_API_URL/api/v1/wallets/$WALLET_ID" -H "Authorization: Bearer $LAGO_API_KEY"

The wallet holds 500 credits. 128.40 of current usage is already drawn, so the ongoing balance is 371.60.

{
  "wallet": {
    "external_customer_id": "acme",
    "status": "active",
    "credits_balance": "500.0",
    "credits_ongoing_usage_balance": "128.4",
    "credits_ongoing_balance": "371.6",
    "ongoing_balance_cents": 37160
  }
}

The fastest path from event to invoice

How usage-based billing platforms compare on ingestion, aggregation and alerting.

	Lago	Orb	Metronome	Stripe Billing	Chargebee	Recurly
Ingestion
Peak ingestionRaw events, sustained	1–3M events/s	~10k events/s by API, more with pre-aggregated rollups	Up to 110k events/s, 5k by default	10k events/s on v2 streams, 200k on request	Up to 200k requests/s, advisory	Not published
Streaming sources	Kafka, Kinesis, S3 and 9 more	S3, GCS, Segment	Segment, bulk files (preview)	Event streams, S3	S3, CSV	API only
Aggregation
Event to billable usage	< 2 s p99	Under 10 s	Under 10 s	Asynchronous, S3 within 5 min	Near real time, no figure	At invoice time
Aggregation queryReading current usage	< 100 ms p99 over 1B+ events	Not published	Not published	Not published	Not published	Not published
Balances and alerts
Credit balance update	< 1 s, typical	Under 10 s	Under 10 s	At invoice time	Live, no figure	Not published
Alert latency	< 1 s on balances, ≤ 1 min on usage	~3 min or more on usage	~3 min or more on usage, within 5 min documented	Not published	Within seconds (private beta)	Not documented
Deduplication window	No expiry	Grace period, 12 h by default	34 days	At least 24 h	Not published	1 h

Figures as of October 2026. Lago's 1–3M events/sec result is for Kafka/Redpanda with ClickHouse Cloud in its documented load tests; REST batch is about 10,000 events/sec in its tested setup. Validate your own payload and deployment. Defaults can often be raised by plan or on request. “Not published” means no figure is stated.

Usage ingestion FAQ

What is usage ingestion?

Usage ingestion is the path a usage event takes from your product to a billable number. Lago receives the event, deduplicates it, enriches it with its billable metric, subscription and plan, and aggregates it into the usage that invoices and wallet balances read.

How many events per second can Lago ingest?

It depends on the connector and deployment. Lago's performance guide reports about 10,000 events/sec for REST batch and 1–3 million for Kafka/Redpanda with ClickHouse Cloud in its tested configurations. Amazon Kinesis and S3 have different limits and jobs. Validate your own peak load and event-to-billable lag.

What happens if the same event is sent twice?

Lago deduplicates retries, but the key depends on the event store. On ClickHouse, a changed timestamp can make a retry a new billable event. Send an explicit timestamp and resend the original event payload unchanged, then reconcile usage before invoicing.

What does enrichment add to an event?

Lago matches each event to its billable metric, subscription and plan, then adds the value billing needs. Lookups are served from memory, so there is no database round trip per event. Events for pay-in-advance charges are routed separately so they can be invoiced right away.

How fast does a wallet's ongoing balance update after an event?

Typically in under a second. The ongoing balance is the wallet balance minus current usage, taxes included. Lago waits until usage includes the new event before refreshing, so a balance is never computed on partial data.

Real-time ingestion, from events to usage

Ingest usage from any source

One usage event, seven steps.From the API to the wallet balance.

API intake

Event stream

Deduplication

Enrichment

Aggregation

Checkpoint

Wallet balance