Lago

Last reviewed Aug 26, 2026 · 824 words

You will be running roughly six containers before Lago issues its first invoice: an API, a web frontend, a background worker, a clock process for scheduled jobs, PostgreSQL and Redis, with a PDF renderer alongside and ClickHouse optional for high event volumes. That is the correct shape for what Lago is: a metering and billing engine for software companies that charge per seat, per API call or per gigabyte. It is the wrong shape for sending 12 invoices a month to consulting clients, and the catalogue is right to rate it Hard and to say 2 GB is the floor.

Metering means events, and events mean discipline

Lago's model has four nouns. A billable metric is a thing you count, defined by a code and an aggregation: count, sum, max, unique count, latest, or weighted sum. A plan attaches charges to metrics with a price model (per unit, graduated, volume, package, percentage). A customer gets a subscription to a plan. Your application then sends events, and Lago turns them into invoices at the end of each period.

The events are the part people underestimate. Every metered action in your product has to produce an HTTP call like this one:

curl -X POST https://billing.example.com/api/v1/events \
  -H "Authorization: Bearer $LAGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":{"transaction_id":"req-8f3a21","external_subscription_id":"sub-acme-prod","code":"api_calls","properties":{"count":1}}}'

The transaction_id is the idempotency key, so retries do not double-bill. That is the discipline: your code must generate stable IDs, buffer events when Lago is unreachable, and never fire-and-forget on a metered path. If your billing is a flat monthly fee, none of this machinery earns its keep.

The stack you sign up to operate

The project publishes a docker-compose.yml that stands the whole thing up. Before the first docker compose up you generate an RSA key with openssl genrsa 2048 | base64 -w 0 for LAGO_RSA_PRIVATE_KEY, and you set LAGO_API_URL and LAGO_FRONT_URL to the public addresses you will actually use, because the frontend, the webhooks and the emailed invoice links all embed them. By default the frontend listens on port 80 and the API on 3000; put both behind Caddy on two hostnames rather than exposing them raw.

Sizing: the catalogue's 2 GB minimum is what the containers idle at. Give it 4 GB if you expect any event volume, because Redis holds the job queue and Postgres holds every event you have ever sent unless you enable the ClickHouse path. Back up Postgres nightly with pg_dump; that database is your revenue history and there is no rebuild-from-source for it.

It bills, you still collect

Lago generates the invoice; money moves through a payment provider it integrates with, and the built-in ones are Stripe, GoCardless and Adyen. You link a customer to a provider customer ID, and Lago creates the charge when the invoice finalises. Failed payments come back as webhooks (invoice.payment_failure and friends) that your app must handle. Credit notes, coupons, add-ons and prepaid wallets are all in the open-source edition; a few enterprise features sit behind a premium licence, and the settings page tells you which when you hit one.

Invoices render as PDFs through the bundled renderer container, and the templates are customisable enough for a logo and legal footer, not for a designer's opinions.

It is not accounting software, and it does not pretend to be

Lago knows what you charged and whether it was paid. It does not know your expenses, your bank balance, your VAT return or your chart of accounts. For that you export to a ledger: Akaunting for a small business, or a proper ERP. If what you need is "send professional invoices and chase them", InvoiceShelf does it in one container on 256 MB and you will be done by lunch. The older open-source contender for the same job is Kill Bill, a Java platform with more years and a steeper build; Lago's API is the friendlier of the two. The rest of the finance category is mostly ledgers and budgets, which tells you how unusual Lago's niche is.

What I'd do

If I ran a SaaS with usage pricing and a real engineering team, I would self-host Lago on a 4 GB VM, wire events through a small queue in my own app so a Lago outage never blocks a request, back up Postgres nightly, and pin the image tags. I would budget two weeks for integration, mostly on the event side, and not regret it: the alternative is renting the same logic from Stripe Billing at a percentage of revenue. If I ran anything simpler, a fixed-price product, a consultancy, a side project with 30 customers, I would not touch it. The catalogue's phrase is exact: overkill for simple invoicing.