# Lago

> Open-source metering and usage-based billing.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: lago, postgres, redis
- Tags: lago, billing, metering, subscriptions
- Source: https://docker.recipes/ecommerce/lago

## Overview

Lago is an open-source metering and usage-based billing platform designed to help businesses implement sophisticated pricing models beyond traditional subscription fees. Developed to address the complexity of modern SaaS billing requirements, Lago enables companies to track customer usage across multiple dimensions and automatically generate accurate invoices based on consumption patterns, subscription tiers, or hybrid models combining both approaches.

This Docker configuration combines Lago's API and frontend components with PostgreSQL for reliable billing data storage and Redis for high-performance session management and background job processing. PostgreSQL's ACID compliance ensures billing accuracy and data integrity - critical requirements when handling financial transactions and customer invoicing. Redis accelerates the platform by caching frequently accessed pricing rules, managing user sessions, and queuing billing calculations that need to process large volumes of usage events.

This stack targets SaaS companies, API providers, and usage-based service businesses that need to move beyond simple monthly subscriptions. Development teams building platforms with pay-per-use models, tiered pricing, or complex billing rules will find Lago particularly valuable for replacing expensive third-party billing solutions with a self-hosted alternative that offers complete control over pricing logic and customer data.

## Features

- Real-time usage metering with billable metrics tracking API calls, storage consumption, and custom events
- Advanced pricing models including graduated tiers, package deals, percentage-based fees, and volume discounts
- PostgreSQL-backed invoice generation with automated tax calculations and multi-currency support
- Redis-powered background processing for high-volume usage aggregation and billing calculations
- Webhook system for real-time notifications on invoice creation, payment events, and subscription changes
- Customer portal integration allowing end-users to view usage analytics and billing history
- Subscription lifecycle management with proration, upgrades, downgrades, and custom billing cycles
- Multi-tenant architecture supporting usage isolation and billing segmentation across customer organizations

## Use cases

- API-first companies billing customers based on request volume, bandwidth usage, or compute resources consumed
- Cloud storage providers implementing tiered pricing with different rates for storage, bandwidth, and API operations
- SaaS platforms combining monthly subscriptions with overage charges for premium features or usage limits
- Development teams building internal billing systems for multi-product companies with complex pricing structures
- Telecommunications and IoT service providers tracking device usage, data consumption, and service utilization
- Marketplace platforms charging transaction fees, listing fees, and usage-based commission structures
- Enterprise software vendors implementing seat-based licensing with additional usage-based feature charges

## Prerequisites

- Minimum 2GB RAM recommended for PostgreSQL billing data processing and Redis caching operations
- Available ports 3000 (Lago API), 8080 (web interface), 5432 (PostgreSQL), and 6379 (Redis)
- Understanding of billing concepts like metering, pricing plans, and invoice generation workflows
- Environment variables configured for database credentials and Lago's secret key authentication
- Knowledge of webhook integrations for connecting billing events to payment processors or accounting systems
- Familiarity with usage-based billing models and how to define billable metrics for your specific use case

## docker-compose.yml

```yaml
services:
  lago-api:
    image: getlago/api:latest
    container_name: lago-api
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      REDIS_URL: redis://redis:6379
      SECRET_KEY_BASE: ${SECRET_KEY}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
      - redis
    networks:
      - lago

  lago-front:
    image: getlago/front:latest
    container_name: lago-front
    environment:
      API_URL: http://lago-api:3000
    ports:
      - "8080:80"
    depends_on:
      - lago-api
    networks:
      - lago

  postgres:
    image: postgres:16-alpine
    container_name: lago-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - lago

  redis:
    image: redis:alpine
    container_name: lago-redis
    networks:
      - lago

volumes:
  postgres_data:

networks:
  lago:
    driver: bridge
```

## .env

```bash
DB_NAME=lago
DB_USER=lago
DB_PASSWORD=changeme
SECRET_KEY=your-secret-key
```

## Usage notes

- Docs: https://docs.getlago.com/
- UI at http://localhost:8080, API at http://localhost:3000
- Create billable metrics for metering (API calls, storage, etc)
- Define pricing plans: flat fees, graduated, package, percentage
- Supports usage-based, subscription, and hybrid billing models
- Webhook events for invoice, payment, subscription lifecycle

## Troubleshooting

- Lago API failing to connect to PostgreSQL: Verify DATABASE_URL format and ensure PostgreSQL container is fully started before lago-api
- Usage events not processing correctly: Check Redis connectivity and ensure REDIS_URL matches the redis service network configuration
- Frontend showing 'API connection failed': Confirm lago-front can reach lago-api container and API_URL environment variable is correctly set
- Database migration errors on startup: Ensure PostgreSQL has sufficient disk space and proper permissions for the postgres_data volume
- Webhook delivery failures: Verify your external webhook endpoints are accessible from the Docker network and return proper HTTP status codes
- High memory usage during billing calculations: Monitor Redis memory consumption and consider increasing container limits during peak billing cycles

