⚡ ABC Lago

Open Source Usage-Based Billing Platform

A developer-first, open-source alternative to Stripe Billing

Features • Quick Start • Documentation • Contributing

---

🎯 What is ABC Lago?

ABC Lago is a production-ready, open-source metering and usage-based billing platform. It gives you full control over your billing infrastructure without being locked into proprietary solutions.

Perfect for:

• 🚀 SaaS platforms with usage-based pricing
• 💰 Subscription businesses requiring complex billing logic
• 📊 API-first companies needing programmatic billing
• 🔒 Security-conscious teams requiring on-premise deployment

---

✨ Features

🧮 Flexible Billing Models

• Usage-based billing: Track and bill on any metric
• Subscription management: Recurring billing with proration
• Tiered pricing: Graduated, volume, and tiered pricing
• Charges & fees: One-time, recurring, and usage-based
• Coupons & discounts: Percentage or fixed amounts

🔌 Integrations

• Payment gateways: Stripe, GoCardless, Adyen
• CRM tools: HubSpot, Salesforce
• Accounting: QuickBooks, Xero
• Data warehouses: Snowflake, BigQuery, ClickHouse

🏗️ Architecture

• Event-driven: Kafka-based event processing
• Scalable: Horizontal scaling with worker queues
• API-first: GraphQL + REST APIs
• Type-safe: Generated TypeScript clients

🔐 Security & Compliance

• Self-hosted: Keep data on your infrastructure
• GDPR ready: Data privacy controls
• SOC 2 compliant: Audit logs and access controls
• Webhook signing: HMAC and JWT RS256 support

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• 4GB RAM minimum
• Linux/macOS/WSL2

1. Clone the Repository

git clone https://github.com/abc-lago/lago.git
cd lago

2. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit with your configuration
nano .env

3. Generate RSA Keys

export LAGO_RSA_PRIVATE_KEY="`openssl genrsa 2048 | openssl base64 -A`"

4. Start Services

docker compose up -d

5. Access ABC Lago

• API: http://localhost:3000
• Frontend: http://localhost
• Health Check: http://localhost:3000/health

---

📚 Documentation

Resource	Link
📖 Full Documentation	docs.abc-lago.com
🔧 API Reference	api.abc-lago.com/docs
💬 Community	github.com/abc-lago/lago/discussions
🐛 Bug Reports	github.com/abc-lago/lago/issues

---

🏗️ Project Structure

abc-lago/
├── api/                    # Ruby on Rails backend
│   ├── app/                # Application code
│   ├── config/             # Configuration files
│   ├── db/                 # Database migrations
│   └── spec/               # Tests
├── front/                  # Vue.js frontend
│   ├── packages/           # Design system & configs
│   ├── src/                # Source code
│   └── cypress/            # E2E tests
├── events-processor/       # Go event processing service
│   ├── models/             # Data models
│   ├── processors/         # Event processors
│   └── config/             # Configuration
├── connectors/             # AWS SQS & HTTP connectors
├── deploy/                 # Deployment configurations
└── docker/                 # Docker configurations

---

🔧 Development

API Development (Ruby on Rails)

cd api
bundle install
cp .env.example .env
rails db:create db:migrate
rails server

Frontend Development (Vue.js)

cd front
pnpm install
cp .env.template .env
pnpm dev

Events Processor (Go)

cd events-processor
go mod download
go run main.go

---

🧪 Testing

API Tests

cd api
bundle exec rspec

Frontend Tests

cd front
pnpm test
pnpm test:e2e

Events Processor Tests

cd events-processor
go test ./...

---

🐳 Docker Images

Image	Description	Tag
abc-lago/api	Rails API backend	latest, v1.39.0
abc-lago/front	Vue.js frontend	latest, v1.39.0
abc-lago/events-processor	Go event processor	latest, v1.39.0

---

🌐 Features in Detail

Metering & Usage Tracking

• Ingest events via API, SQS, or HTTP
• Real-time event processing with Kafka
• Billable metric aggregation
• Custom event properties

Subscription Management

• Plan creation and versioning
• Subscription lifecycle management
• Proration and billing periods
• Trial periods and discounts

Invoicing

• Automatic invoice generation
• PDF generation with Gotenberg
• Multi-currency support
• Tax calculation (Avalara, TaxJar)

Payment Collection

• Stripe integration
• SEPA Direct Debit (GoCardless)
• Adyen payment methods
• Payment retry logic

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

ABC Lago is based on the open-source Lago project. We thank the original Lago team and contributors for their excellent work.

---

📮 Contact

• Website: abc-lago.com
• Documentation: docs.abc-lago.com
• Email: dev@abc-lago.com

---

Built with ❤️ by the ABC Lago Team

⭐ Star us on GitHub