DEV Community

Cover image for Lago: Build Usage-Based Billing for APIs and AI Products
Sh Raj
Sh Raj

Posted on Fully Autonomous

Lago: Build Usage-Based Billing for APIs and AI Products

Lago billing platform overview

Official product artwork from the Lago repository.

Usage-based pricing sounds simple until you have to implement it. You need to collect events, avoid double counting, aggregate usage over billing periods, apply price rules and credits, create invoices, and collect payment. Each step has edge cases that are easy to underestimate.

Lago is an open-source metering and usage-based billing platform. It is relevant to API products, SaaS platforms, compute services, and AI applications that charge for consumption rather than only a flat monthly subscription.

Why it is on the radar now

In the GitHub Trending Go snapshot collected on November 16, 2026 at 06:57 UTC, getlago/lago appeared at position eleven, with 25 stars gained that day. That is modest movement, not a viral surge. Lago is an established project, so the useful distinction is that it is gaining fresh attention rather than being a brand-new repository.

Its current README also puts a stronger emphasis on agent-facing interfaces: REST and OpenAPI, a CLI, an MCP server, and Agent SDKs for instrumenting model usage. The repository includes a maintained local demo that sends sample AI usage events, calculates charges, and checks that retrying a transaction does not double count it.

What Lago does

Lago sits between product activity and revenue:

Usage events
    -> Metering
    -> Pricing and credits
    -> Entitlements
    -> Invoices
    -> Payments
Enter fullscreen mode Exit fullscreen mode

Your application reports usage. Lago turns those events into billable metrics, applies the pricing model, calculates what a customer owes, and creates invoices. A payment provider such as Stripe, Adyen, or GoCardless can handle the actual payment collection.

This separation matters. A payment processor is not necessarily a complete usage-metering system, and a metering service is not necessarily a billing and invoicing engine.

Lago supports usage such as API calls, seats, transactions, storage, GPU time, and model tokens. Pricing can combine recurring subscriptions, usage charges, allowances, credits, and overages. Its Direct model bills your own customers; its Embedded model lets a platform offer billing capabilities to its own customers.

Lago architecture diagram from the official README

Official architecture illustration from the Lago README.

Try the maintained local demo

The fastest way to understand the event-to-invoice flow is to run the repository's demo. It requires Docker, curl, and jq.

git clone https://github.com/getlago/lago.git
cd lago
./examples/agentic-ai-demo/run.sh
Enter fullscreen mode Exit fullscreen mode

The script starts an isolated local Lago environment, seeds an example customer, metric, plan, and subscription, then sends illustrative input-token and output-token events. It checks the resulting usage and charge and retries a transaction to verify idempotency.

Open http://localhost:8080 and sign in with the disposable credentials printed by the demo script. The demo is local; it does not access Lago Cloud. When you finish, remove its isolated services and data with:

./examples/agentic-ai-demo/run.sh --cleanup
Enter fullscreen mode Exit fullscreen mode

That is a better first step than connecting a production billing account. You can inspect the customer, subscription, metric, events, and usage before deciding whether the model fits your product.

What an event looks like

A basic usage event contains a unique transaction identifier, a customer identifier, a metric code, a timestamp, and optional properties.

export LAGO_URL="http://localhost:3001"
export API_KEY="replace-with-the-api-key-printed-by-the-demo"

curl --request POST "$LAGO_URL/api/v1/events" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "event": {
      "transaction_id": "request-0001",
      "external_customer_id": "customer-123",
      "timestamp": "2026-11-16T10:00:00Z",
      "code": "api_requests",
      "properties": {
        "endpoint": "/v1/search"
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

The code must match a billable metric you have configured, and the external customer must exist in Lago. Use a unique transaction_id for each logical event. If your worker retries after a timeout, reuse the same transaction ID rather than creating a second billable event.

A metric determines how usage is aggregated. For example, a count_agg metric counts events, while sum and unique-count aggregations can use values inside properties. Choose the aggregation based on what the customer is actually buying. Counting requests is not the same as charging for bytes transferred or tokens consumed.

Agent tooling: useful, but privileged

Lago's current developer workflow includes several interfaces:

  • The REST API and OpenAPI schema for application integrations.
  • A CLI for inspecting billing data and automating terminal workflows.
  • An MCP server that exposes supported billing operations to compatible agents.
  • Python and JavaScript/TypeScript Agent SDKs for normalizing model usage and reporting token or cost events.

The important security detail is that the MCP server inherits the permissions of its Lago API key. A billing assistant with write access can change financial records. Use a scoped key, keep it out of prompts and source control, log tool calls, and require human confirmation for sensitive actions such as issuing credit notes or changing customer billing.

Alternatives and trade-offs

Option Better fit
Lago Open-source usage metering, pricing, credits, invoicing, and payment orchestration
Stripe Billing A strong choice when Stripe is already central and the pricing model is relatively straightforward
OpenMeter Usage metering and event aggregation when you already own the billing and invoice layer
Orb or Chargebee Managed commercial billing workflows when operating billing infrastructure is not your goal

The main Lago repository is AGPLv3 for self-hosted use. Its separate CLI, MCP server, and Agent SDK repositories use MIT licensing. Lago Cloud is commercial; self-hosting means your team operates the billing platform, database, queues, upgrades, and backups. Review the exact license and deployment terms for the components you use.

Billing is a financial system, not just an API endpoint. You still need to test retries, event ordering, time zones, proration, taxes, credits, invoice corrections, and payment failures. Treat the local demo as a learning environment, not proof that a production integration is ready.

If your product charges for usage, what is the unit you would meter first: API calls, active seats, storage, compute time, or model tokens? Define that metric before choosing the billing engine.

Sources and further reading


Written by Shaswat Raj Β· LinkedIn Β· StackShade on YouTube

Top comments (0)