Lotus: a self-hosted pricing and billing engine for usage-based models

The pricing problem Lotus is built around

Most billing systems assume a small set of shapes: a monthly seat price, an annual seat price, maybe a flat overage fee. Lotus targets the cases that fall outside that set. The README describes it as a pricing and billing engine that lets SaaS companies "deploy, monitor, and experiment with custom subscriptions and complex models like usage-based pricing." The stated goal is to sit on top of an existing quote-to-cash stack rather than replace it, pulling data from multiple systems so a team can work out which pricing scheme fits its product.

The intended user is a company that has a working payments and CRM setup but keeps hitting the limits of its billing tool whenever pricing changes. The README frames the cost directly: as pricing models evolve, maintaining and scaling a pricing and billing stack can take significant engineering hours. Lotus is the attempt to move that work into a self-hosted service with an API. It is not aimed at a solo developer selling a single flat-rate plan, and the installation path makes that clear.

What actually runs when you start Lotus

The tech stack listed in the README is the most concrete description of the architecture available: React with TypeScript for the front end, Postgres with the TimescaleDB extension, Redpanda, Redis, Python with Django, Celery for background jobs, and Go microservices. That combination implies a specific data flow. Metering events arrive through an API, land in Postgres or TimescaleDB for time-series storage, and are queued for asynchronous processing. Celery workers handle the background jobs, which in a billing system means aggregation, invoice generation and proration calculations. Redis serves as the broker or cache layer, and Redpanda is the Kafka-compatible event bus. The Go services sit alongside the Django application rather than inside it, which is a deliberate split: Go for throughput-sensitive paths, Python for the business logic and admin surface.

The practical consequence is that Lotus is a distributed system, not a Django app you can run with a single process. Anyone evaluating it should read the compose setup as the real specification of its operational footprint, because the README does not document the service boundaries between the Go microservices and the Django core. That gap matters when something breaks at 2am and you need to know which container owns the failure.

Installing the self-hosted version

The README states that the self-hosted version is currently the only version. There is no hosted tier to fall back on. The documented path is Docker-based. Install Docker Desktop and start it, then clone and enter the repository:

git clone https://github.com/uselotus/lotus.git && cd lotus

Then run the self-hosting script:

./scripts/self-host.sh

The README notes that if the script lacks execute permission you should run chmod 755 ./scripts/self-host.sh first. After that, the homepage is reachable at localhost, and you sign in with the ADMIN_USERNAME and ADMIN_PASSWORD you defined. The documented defaults are username change_me and password change_me.

Configuration lives in env/.env.prod. The README says you can change the environment variables there to suit your needs and links to a self-hosting guide in the docs. The repository topics include self-hosted, so this is the primary distribution model rather than a demo convenience. The homepage field is empty, which means the documentation site and the repository are the only two entry points the listing gives you.

Plan management, proration and the experimentation claim

The feature list is where the project's ambitions are clearest. Usage-based pricing with flexible prorations is the headline, with the README claiming a variety of models supported out of the box and a fully extensible framework for building others. Plan management covers subscriptions, plans, versioning and deployments, which is the unglamorous part of billing that usually ends up as a pile of migration scripts. Lotus positions that as a first-class concern.

The experimentation tools are the most interesting claim and the least documented. The README mentions backtests, A/B tests and forecasts. What it does not provide is a worked example of any of them, a description of how a backtest is configured, or a definition of what a forecast is computed against. Treat those three words as a roadmap item rather than a feature you can evaluate from the README alone. The integrations section makes a similar promise of avoiding lock-in, but names no specific provider. If your adoption decision depends on a particular payment processor or data warehouse being supported, that is something you have to confirm in the docs, not in this repository description.

Where Lotus is the wrong choice

The release history is the first thing to weigh. The most recent release listed is 0.10.2 from March 2023, with 0.10.1 and 0.10.0 immediately before it. The repository shows a later push date, so commits continue, but the version line has been sitting in 0.10.x. A pre-1.0 billing engine means schema and API changes between versions are a realistic possibility, and the README offers no upgrade or migration guidance. If you need a stable interface with a support contract behind it, this is the wrong tool.

The second constraint is operational. Running Postgres with TimescaleDB, Redis, Redpanda, Celery workers and Go microservices is a real infrastructure commitment. A team that wants to write pricing logic and nothing else will spend more time on deployment than on pricing. The third is the default credentials. The README documents change_me as the default username and password, which is fine for a local instance and unacceptable for anything reachable from a network. There is no mention of SSO, audit logging or role-based access control in the supplied material, so if those are requirements, verify them before you plan around Lotus.

How Lotus differs from Stripe Billing and Lago

Stripe Billing is the obvious comparison. The difference is where the pricing logic lives. With Stripe Billing you define products, prices and meters inside Stripe's system, and Stripe holds the subscription state, computes invoices and collects payment. Lotus inverts that: the pricing engine runs on your infrastructure, the plan definitions live in your Postgres database, and the README describes it as a control panel on top of your existing quote-to-cash stack. You keep the payment processor you already have and put Lotus in front of it. That buys flexibility in pricing shape and keeps customer and usage data inside your perimeter. It costs you the operational burden that Stripe absorbs, and it means you own the correctness of every proration calculation.

Lago is the closer comparison, since it is also open source, self-hosted and usage-based. The architectural difference visible here is the stack: Lotus pairs Django with Celery and Go microservices and uses Redpanda as an event bus, which is a heavier service topology than a single application plus a queue. That choice is defensible for high-volume metering and harder to justify for a small team. If your event volume is modest, the extra moving parts are cost without benefit.

Licence, maintenance and what to verify before adopting

Lotus is distributed under the MIT License, with the LICENSE file in the repository root. MIT is permissive: it allows commercial use, modification and redistribution, and it does not require you to publish your changes. It also provides no warranty, which for a component that computes invoices is worth stating plainly. Nothing in the licence obliges the maintainers to fix a billing bug you hit. This is a description of the licence terms, not legal advice; if you are embedding Lotus in a product with unusual compliance constraints, have counsel read the file.

Maintenance cost is the variable you control least. Because the project is self-hosted only, upgrades are your responsibility, and the README does not describe a migration path between versions. Budget for reading release notes before every bump and for testing proration output against known-good invoices after one. The maintainers point contributors at a development guide in the docs, and there is a Slack community linked from the README, which is where upgrade questions would realistically get answered.

Before you commit, do three concrete things. Open env/.env.prod and confirm which variables the compose file actually reads, since the README does not enumerate them. Replace ADMIN_USERNAME and ADMIN_PASSWORD before the instance is reachable from anywhere but localhost. And check whether the 0.10.x line covers the pricing models you need, because the extensibility claim and the experimentation claim are both stated without examples in the material available here.

Editorial conclusion

Adopt Lotus if you already run Postgres and Redis, your pricing has outgrown flat plans, and you are willing to own a multi-service deployment. Do not adopt it if you want a managed billing vendor or cannot staff a Python and Go stack. Before committing, inspect env/.env.prod and confirm which variables the compose file actually consumes, change ADMIN_USERNAME and ADMIN_PASSWORD away from change_me, and check the release history against the features you need.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. uselotus/lotus on GitHub