---
title: "Lago"
description: "Use Lago for MainSDK usage metering - open-source usage billing, self-hosted or cloud, main.yaml, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/lago"
updated: "2026-10-28"
---

# Lago

> Use Lago for MainSDK usage metering - open-source usage billing, self-hosted or cloud, main.yaml, testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/lago · Updated: 2026-10-28

Lago is an open-source usage billing tool you can host yourself or use as a hosted service. The `lago` driver behind [`meter`](https://mainsdk.dev/docs/interfaces/meter) sends each `meter.record()` to Lago, where you price and invoice it. Pick Lago when you want usage billing you can self-host, or when you don't bill through Stripe.

> **Note:** `meter` has no spec yet. The calls and options on this page are provisional, taken from the catalog and the product requirements, and may change when the spec lands.

## Interfaces it serves

### Usage metering (`meter`)

- Status: Building for 0.3 · ships as a beta API
- Driver: `lago` (Lago). later, as an export target behind pay
- Docs: https://mainsdk.dev/docs/interfaces/meter.md

```yaml
meter:
  driver: lago
```

Swap to another provider: `db`, `redis`, `local`, `stripe-meters`.

## Before you start

1. Run Lago yourself or create a hosted Lago account.
2. Define the billable metrics and plans you charge on.
3. Create an API key for your app.

## Configure

```yaml title="main.yaml"
meter:
  driver: lago
```

How the driver takes its API key (as a `secret:` reference) and the Lago address, and how metrics map to Lago billable metrics, are [TBD].

## Use it

```ts title="lib/usage.ts"
import { meter } from "mainsdk";

await meter.record({ customer: org.id, metric: "api_calls", value: 1 });
```

## Local development and testing

`meter` ships in phase 2, and its in-memory fake for `createTestApp()` from `@mainsdk/testing` arrives with its spec. Until then, a self-hosted Lago on your machine works for trying the flow.

## What MainSDK adds on top

`meter` has no guarantees in the catalog yet; they arrive with its spec. Keys go in as `secret:` references. See [Usage metering](https://mainsdk.dev/docs/interfaces/meter).

## Limits and notes

- Planned for phase 2; `meter` has no spec.
- If you self-host Lago, usage data stays where you run it. Pick a host in your MainSDK data region (US, EU or India).
- Not decided yet: whether a retried `meter.record()` counts once.

## Swap to or from it

```yaml title="main.yaml"
meter:
  driver: lago   # was stripe-meters
```

> **Warning:** Billing customers and past usage live in the provider, so moving between Lago and Stripe meters is a stateful migration, not a one-line switch.

## FAQ

**Does Lago charge the card?** Lago prices and invoices usage; collecting the payment is done by a payment provider you connect to it.

**Can I use Lago with Stripe for payments?** `meter` and `pay` are separate interfaces, so you can record usage in Lago and take payments through `pay`.

## Next

- [Usage metering](https://mainsdk.dev/docs/interfaces/meter) and [Payments](https://mainsdk.dev/docs/interfaces/pay)
- [Stripe](https://mainsdk.dev/docs/integrations/stripe)