Lago: An Open Source Billing Engine That Puts Usage Events Before Invoices

What Lago Actually Solves

Lago addresses the gap between raw product usage and revenue. Many companies track consumption in their own databases, then manually translate that into invoices, credits, and payment requests. Lago replaces that manual pipeline with a programmable system: your application sends usage events, and Lago meters them, applies pricing and entitlements, and generates invoices and payments. The target user is a product team that needs to launch or change pricing frequently without rebuilding billing logic. The README positions it specifically for AI products, mentioning token metering by model, input, output, cache, reasoning, and tool calls, but the same engine handles compute, API calls, seats, and custom events. The core value is that pricing iterations do not require a billing code rewrite.

The Event-to-Revenue Pipeline

The README shows a clear data flow: usage events go into metering, then pricing and credits, then entitlements, then invoices, then payments, then revenue. This is not a single monolithic action. Each stage is a separate concern. Metering accumulates raw events, pricing assigns costs based on plans, entitlements control what a customer can access, and invoicing turns the calculated totals into bills. Lago is headless and API-first, so your application, internal tools, and agents all interact through the same REST API, SDKs, webhooks, and MCP server. The separation between metering and payment processing is a deliberate design choice. The README states that you can connect Stripe, Adyen, GoCardless, or another provider without making the provider's product catalog your source of truth. That independence is the architectural core.

Running the Local AI Billing Demo

The repository includes a maintained demo that prices an AI workload. The command is ./examples/agentic-ai-demo/run.sh. It starts a Lago version matching the checkout, creates a disposable local organization, and prices three illustrative AI requests. Each request sends one input-token event and one output-token event. The example output shows 5,000 input tokens at $0.000002 each, totaling $0.01, and 1,250 output tokens at $0.000008 each, also $0.01, for a total of $0.02. Docker Compose runs an isolated Lago service, and a script seeds and verifies the example through the API. It retrieves current usage, reconciles the result independently, and retries one transaction to confirm idempotency. Everything stays local; the demo does not access Lago Cloud. You log into the UI at http://localhost:8080 with the credentials [email protected] and agentic-ai-demo-local-password. Requirements are Docker, curl, and jq. If ports 8080 or 3001 are occupied, set LAGO_DEMO_UI_PORT and LAGO_DEMO_API_PORT before running. Cleanup is ./examples/agentic-ai-demo/run.sh --cleanup.

Agentic Interfaces: MCP Server and SDKs

Lago markets itself as agentic-first, meaning billing logic is available as structured interfaces rather than being trapped in a dashboard. The README points to the REST API and SDKs, the Lago CLI for inspecting billing and writing scripts, a Lago MCP server (lago-agent-toolkit) that gives an assistant tools for live billing data and supported operations, and a documentation index (llms.txt) and documentation MCP that give an agent current billing and API context. It says these interfaces work independently: application code uses an SDK or the REST API, and no Lago plugin is required. It also advises confirming the target organization and environment, keeping API keys out of prompts and source control, and reviewing financial changes before execution. Whether you need agents to manipulate billing directly is a separate question, but the option exists.

Two Operating Models: Direct and Embedded

Lago supports two deployment modes from the same engine. Lago Direct is for monetizing your own product: you send usage, model pricing, and bill your customers. Lago Embedded lets platforms, marketplaces, and AI builders offer metering and billing to their own customers, with Lago staying behind the scenes under your brand. The README cites Mistral AI as a Direct example and PayPal as an Embedded example. The practical difference is who controls the customer experience. With Embedded, you control which capabilities your users can access and the white-label interface. Both models run on the same engine. The README's header also links to Lago Cloud at getlago.com/pricing.

Limitations and Wrong Use Cases

Lago is not a simple invoicing tool. If your billing needs are flat-rate subscriptions with no usage metering, Lago's event pipeline is overkill. The AGPL-3.0 license is a genuine constraint. If you distribute a modified version of Lago as part of a service, the AGPL obligations may apply to your modifications. You should read the license carefully. Another limitation is that the demo only covers token-based AI pricing. It does not demonstrate complex scenarios like prepaid credits with automatic top-ups, minimum commitments, or overages, even though the README claims support for those. You would need to test those features yourself. The demo depends on Docker, curl, and jq, which may not fit every environment. You should also load-test Lago with your own event rates.

Alternatives and How They Differ

The most common hosted alternative is Stripe Billing, which is not open source and not self-hostable. Stripe's approach is to make its product catalog the source of truth, which is exactly what Lago avoids. Another alternative is Chargebee, which is also closed source and focuses on subscription management rather than granular usage metering. For a more code-centric alternative, you could consider building your own metering layer on top of a time-series database like Prometheus or InfluxDB, then integrating with a payment provider. That gives you full control but requires building the pricing, invoicing, and entitlement logic yourself. Lago's difference is that it provides those primitives out of the box with an API and a UI, so you do not have to write billing logic from scratch. The trade-off is that you adopt Lago's data model and event format, which may not fit every product's existing usage tracking.

Maintenance, Upgrade Cost, and License

The repository is actively maintained, with recent releases v1.56.0 (2026-11-02), v1.55.0 (2026-10-07) and v1.54.0 (2026-10-06). Releases are frequent, so plan for regular upgrades and check the release notes before upgrading. The demo script is tied to the checkout's version, so it is a reliable way to test a specific release. The license is AGPL-3.0, which has implications for any modifications you make. If you run Lago as a service and modify its source, you may need to offer the modified source to users. The README does not provide legal guidance, so consult a lawyer if you are unsure.

Editorial conclusion

Adopt Lago if you sell usage-based products and want a programmable billing layer that keeps metering independent from payment providers, with a REST API, SDKs, and an MCP server. Do not adopt it if you need a simple flat-rate invoicing tool or if you cannot accept the AGPL-3.0 license for your deployment. Before adopting, verify that the AGPL terms fit your distribution model, confirm the payment provider integrations cover your needs, and run the local agentic AI demo to check the event-to-invoice flow matches your expected usage calculations.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes