Flexprice: usage-based billing you can self-host, built on Kafka and ClickHouse

The billing work Flexprice is trying to take off your plate

The README frames billing as a developer problem, and it is direct about why. Metering high-volume usage events, applying prepaid credits, enforcing feature limits and producing invoices that survive proration and time-zone edge cases is a lot of custom code. The project's own summary of the alternative is blunt: a pricing model that does not fit a traditional billing tool leaves you either bending the product or writing workarounds. Flexprice targets that gap. It is aimed at AI-native and SaaS teams whose pricing is usage-based, credit-based or a hybrid of the two, and at the engineers who would otherwise maintain the metering pipeline themselves. The repository topics list billing, clickhouse, events, kafka, postgresql, pricing and temporal, which is a fair description of the operational surface you are taking on.

How the pieces fit: Postgres, Kafka and ClickHouse

The docker-compose.yml is the clearest statement of the architecture. Postgres 17 holds the transactional state, and the migration SQL under ./migrations/postgres is mounted into the container's docker-entrypoint-initdb.d, so the schema is applied on first boot. Kafka runs as a single-node KRaft broker on confluentinc/cp-kafka:7.7.1 with KAFKA_AUTO_CREATE_TOPICS_ENABLE set to "false", which means topics have to exist before anything can be written to them. ClickHouse, in clickhouse/clickhouse-server:24.9-alpine, is the analytics side, exposed on 8123 for HTTP and 9000 for the native protocol. The application code in go.mod backs this up: the ClickHouse Go driver, Shopify/sarama and watermill-kafka for the event path, ent for the Postgres models, and Temporal for workflow orchestration. The data flow the README describes is that your application or your warehouse sends usage events in, Flexprice meters and prices them in real time, and the result is synced out to payment, CRM, CPQ and accounting systems. The outbound connectors are visible in the dependency list too, with SDKs for Stripe, Chargebee, Paddle, Razorpay and AWS Marketplace metering. That is a real event pipeline, not a wrapper around a payment API, and it is the part that determines your operational cost.

Running Flexprice locally with docker compose

The Makefile exposes the shortest path to a working stack. The up target builds and starts the compose services in the background, and down stops them. On a first run the Postgres container executes the migrations mounted from ./migrations/postgres, so expect the healthcheck to take a moment before it reports ready.

make up

If you would rather drive compose directly, the same thing is available without the Makefile. The compose file pins Postgres to 127.0.0.1:5432, Kafka to 127.0.0.1:29092 and ClickHouse to 127.0.0.1:8123, so nothing is exposed beyond the loopback interface by default.

docker compose up -d --build

Once the containers are healthy you can run the API server from source rather than in a container. This is the command the Makefile uses for its run-server target, and it starts the Gin-based HTTP server defined under cmd/server.

make run-server

The repository also ships cmd/e2eprobe, described in the Makefile as an end-to-end probe, which is the closest thing to a smoke test for the running stack. The README points at https://docs.flexprice.io for the API surface and at official SDKs published as github.com/flexprice/go-sdk/v2, pypi.org/project/flexprice and @flexprice/sdk on npm. Those are the three client entry points named in the README badges; the exact call sequence for sending a first event is documented in the docs site, not in the README.

The operational bill that comes with the architecture

Self-hosting Flexprice means running Kafka, ClickHouse and Postgres, plus Temporal for the workflow side. The compose file is a development setup, not a production topology: one Kafka broker, replication factors of 1, and a ClickHouse container with a default user. Anyone moving this to production owns broker durability, ClickHouse storage sizing and Temporal's own database, which the repository acknowledges with a separate init-temporal-db.sh script. The second constraint is more subtle. Because KAFKA_AUTO_CREATE_TOPICS_ENABLE is "false", a misconfigured producer fails rather than silently creating a topic, which is the right default but is also a first-run stumbling block. The third is the licence. The repository is AGPL-3.0, and the README's framing of "no vendor lock-in" is about data and code access, not about licence obligations. If you embed this in a product you distribute, the AGPL's network clause is something your legal side needs to read in LICENSE, not something this article can settle. Finally, the README does not document rollback or downgrade procedures for schema migrations, so treat the migration path as forward-only until you find otherwise.

Where Flexprice is the wrong choice

If you sell a single flat monthly subscription with no usage component, the metering pipeline is dead weight. You would be operating Kafka and ClickHouse to compute an invoice that a plain subscription record already describes. The same applies if your team has no appetite for running stateful infrastructure at all: the README offers both cloud and self-hosted, and the cloud option is the honest answer for a small team that wants billing to be someone else's pager. There is also a fit question around event volume. The design assumes you are streaming usage events continuously. If your billable units are seats or one-time purchases, the event path adds latency and failure modes without adding accuracy. And if your requirement is a payment processor rather than a billing engine, Flexprice is explicitly positioned to sit alongside Stripe or Chargebee rather than replace them, so adopting it does not remove those dependencies.

How it differs from Lago and from Stripe Billing

The comparison people search for is Lago versus Flexprice, and the meaningful difference is in the storage and event layer rather than the feature checklist. Flexprice puts ClickHouse behind the metering path and Kafka in front of it, which is a design aimed at high-volume event aggregation and real-time reporting; the trade-off is three stateful systems to operate. Stripe Billing takes the opposite approach entirely: it is a closed hosted service, and the README's criticism of that model is the percentage fee on revenue and the loss of control over pricing logic. Choosing Stripe Billing means you do not run Kafka, and it also means your pricing rules live in someone else's system. Flexprice's answer to that is composability, keeping your existing payment gateway and syncing invoices into it. The honest summary is that Flexprice trades operational burden for control, and that trade only pays off if you actually need the usage metering.

Release cadence and what upgrading costs

The project is not archived, and the last push was on 2026-09-22. Releases are frequent and versioned: v2.1.31 on 2026-09-18, v2.1.30 on 2026-09-09 and v2.1.29 on 2026-09-01, roughly weekly. That cadence is good for fixes and a cost for operators, because each release can carry schema changes. The Dockerfile shows how migrations are applied: dbmate runs the reviewed .sql files in migrations/versioned/ and records them in a schema_migrations table, and it is built as a separate binary rather than imported as a Go dependency so that its unused drivers stay out of go.mod. That is a deliberate design choice worth knowing about, because it means the migration tool is pinned by DBMATE_VERSION (v2.35.0 in the Dockerfile) and updated independently of the application. The Dockerfile also pins the builder to golang:1.25.13-alpine and warns that the image sets GOTOOLCHAIN=local, so the builder Go version must be at least the go directive in go.mod (1.25.12) or the module download fails. If you self-host, budget for reading migration files before each upgrade rather than pulling the latest tag automatically.

Editorial conclusion

Adopt Flexprice if your product already emits usage events and you want to own the metering and pricing logic instead of paying a percentage of revenue to a closed platform. Do not adopt it if you want a hosted billing service with no infrastructure to run, or if a plain seat-based subscription is all you sell. Before committing, run docker compose up and confirm the Postgres, Kafka and ClickHouse containers all pass their healthchecks on your machine, then read the licence text in LICENSE and decide whether AGPL-3.0 fits how you distribute your product.

Frequently asked questions

Official sources

1. flexprice/flexprice on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases