DEV Community

Alex Spinov
Alex Spinov

Posted on

Lago Has a Free API: Open-Source Billing and Usage-Based Pricing for SaaS

#saas #billing #tutorial #opensource

What is Lago?

Lago is an open-source billing engine for SaaS companies. It handles usage-based pricing, subscription management, invoicing, and payment processing — the billing infrastructure that companies like Stripe Billing or Chargebee provide, but self-hosted and free.

Quick Start 

git clone https://github.com/getlago/lago
cd lago
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Open http://localhost — full billing dashboard.

The REST API 

export LAGO_URL="https://api.getlago.com/api/v1"
export LAGO_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode

Create a Billable Metric 

curl -X POST "$LAGO_URL/billable_metrics" \
  -H "Authorization: Bearer $LAGO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billable_metric": {
      "name": "API Calls",
      "code": "api_calls",
      "aggregation_type": "count_agg",
      "field_name": null
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Create a Plan 

curl -X POST "$LAGO_URL/plans" \
  -H "Authorization: Bearer $LAGO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": {
      "name": "Pro Plan",
      "code": "pro",
      "interval": "monthly",
      "amount_cents": 4900,
      "amount_currency": "USD",
      "charges": [{
        "billable_metric_code": "api_calls",
        "charge_model": "graduated",
        "properties": {
          "graduated_ranges": [
            {"from_value": 0, "to_value": 1000, "per_unit_amount": "0", "flat_amount": "0"},
            {"from_value": 1001, "to_value": null, "per_unit_amount": "0.01", "flat_amount": "0"}
          ]
        }
      }]
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Create Customer & Assign Plan 

# Create customer
curl -X POST "$LAGO_URL/customers" \
  -H "Authorization: Bearer $LAGO_KEY" \
  -d '{
    "customer": {
      "external_id": "cust_123",
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "currency": "USD"
    }
  }'

# Assign subscription
curl -X POST "$LAGO_URL/subscriptions" \
  -H "Authorization: Bearer $LAGO_KEY" \
  -d '{
    "subscription": {
      "external_customer_id": "cust_123",
      "plan_code": "pro",
      "external_id": "sub_123"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Ingest Usage Events 

curl -X POST "$LAGO_URL/events" \
  -H "Authorization: Bearer $LAGO_KEY" \
  -d '{
    "event": {
      "transaction_id": "txn_001",
      "external_subscription_id": "sub_123",
      "code": "api_calls",
      "timestamp": 1711612800
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Get Invoices 

curl "$LAGO_URL/invoices?external_customer_id=cust_123" \
  -H "Authorization: Bearer $LAGO_KEY"
Enter fullscreen mode Exit fullscreen mode

Node.js SDK 

import { Client } from "lago-javascript-client";

const lago = Client("your-api-key");

// Send usage event
await lago.events.createEvent({
  event: {
    transactionId: "txn_002",
    externalSubscriptionId: "sub_123",
    code: "api_calls",
    timestamp: Math.floor(Date.now() / 1000),
  },
});

// Get customer usage
const usage = await lago.customers.findCustomerCurrentUsage(
  "cust_123",
  { externalSubscriptionId: "sub_123" }
);
console.log(usage.charges_usage);
Enter fullscreen mode Exit fullscreen mode

Pricing Models

Lago supports complex pricing out of the box:

  • Flat rate: $49/month
  • Usage-based: $0.01 per API call
  • Graduated: First 1,000 free, then $0.01 each
  • Package: $10 per 100 units
  • Percentage: 2.5% of transaction volume
  • Volume: Tiered pricing based on total usage

Lago vs Alternatives

Feature Lago Stripe Billing Chargebee
Open source Yes No No
Self-host Yes No No
Usage-based Full Basic Full
Price Free 0.5% rev $599/mo+
Webhooks Yes Yes Yes

Building a SaaS and need billing infrastructure?

📧 spinov001@gmail.com
🔧 My tools on Apify Store

How do you handle SaaS billing? Stripe, Lago, or custom?

Top comments (0)