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 agentic-ai-demo@example.local 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 REST API and OpenAPI schema are open source, allowing you to generate typed clients or tools. The Lago MCP server, under an MIT license, gives an MCP-compatible agent tools to read and write invoices, usage, customers, payments, credit notes, and coupons. There is also an Agent SDK for Python that wraps supported LLM clients and sends token or model-cost events without blocking the LLM call. The JavaScript and TypeScript SDK instruments OpenAI, Anthropic, Mistral, Gemini, and AWS Bedrock clients with under 5 ms p99 wrapper overhead, according to the README. This is a meaningful shift from traditional billing systems, which usually expose only a REST API and a UI. 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 start with the open source engine, but the README mentions Premium deployment, customization, security, and support options. This suggests that the open source core is the base, and additional enterprise features may be commercial. The documentation is not explicit about what exactly Premium adds, so you would need to check the pricing page.

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. The README does not discuss this, so 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. Also, the README mentions the Lago UI and REST API, but the actual performance under high event volume is not documented in the provided material. You should load-test it with your own event rates.

Alternatives and How They Differ

The main alternative in the open source space is Stripe Billing, but Stripe 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.52.1, v1.52.0, and v1.51.0 pushed in August and July 2026. The release cadence appears to be roughly monthly, which means you should plan for regular upgrades. The README does not describe a migration path between versions, so you should check the changelog 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. The MCP server and agent SDKs are MIT licensed, which is more permissive, but the core engine remains AGPL. That split is worth noting when you plan your deployment.

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, MCP server, and agent SDKs. 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.

Official sources

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