BillaBear is a self-hostable subscription and billing system built around Stripe

Stripe handles the card, BillaBear handles everything else

BillaBear is a standalone Subscription Management and Billing System that integrates with Stripe, and it provides a REST API allowing you to integrate it easily.

The division of labour is what defines the product. Card processing, and the payment provider's own dashboard, stay with Stripe. Everything on the subscription side, the plan catalogue, the customer records, the invoices, the tax rules and the dunning, belongs to BillaBear. That means the interesting work in a billing system is all here, and the part that is genuinely hard to do well, namely talking to a payment processor securely and correctly, is not.

The customer-facing side uses the same split. BillaBear allows you to use Stripe.JS by providing you a token that is registered with Stripe to be used with the customer, which allows all the normal flexibility that Stripe.JS allows for. So the checkout page is Stripe's, and BillaBear hands out the token.

The feature list is long and reads like a checklist of what a billing team ends up needing: a tax system with thresholds, multiple tax types, country tax rules and state tax rules, a workflow system, plan management, subscription management, an invoice system, hosted checkout, paylinks, quotes, a mass subscription change system, reports covering subscription, lifetime value and churn, subscription add-ons, webhooks, dunning, vouchers and credit notes.

The repository is PHP, the last push was on 2026-09-13, and the releases are dated rather than semver: 2025.01.03 from 2025-02-02, 2025.01.02 from 2025-01-31 and 2025.01.01 from 2025-01-27.

Workflows exist so a failed side effect can be retried

The workflow system is the feature that tells you what kind of engineering this project is.

The description is specific. Workflows allow you to integrate important tasks that have to be done during a process that, if it fails, you want to be able to retry later and resume with the rest of the process. This avoids manual developer intervention which can be time-consuming and frustrating.

Two examples are given. You might want a microservice to be called on a subscription creation to allow for the creation of resources. And when you are issuing refunds and for some reason the connection or API request fails, you can retry the refund later without requiring manual intervention.

Both examples are the same problem in different clothing. A billing system does two kinds of thing: it mutates its own state, and it calls out to other systems. The first is transactional and can be rolled back. The second cannot, and if it fails halfway through you have a subscription that exists with no resources provisioned, or a refund that never reached the processor. A workflow system is the answer, because the step is recorded as pending work and can be retried rather than lost.

This is the difference between a billing system and a set of scripts, and it is the part that a self-hosted deployment needs most, because the operator is the one who gets paged when an integration breaks at three in the morning.

The system also exposes webhooks, which is the outbound direction of the same problem: your application needs to know when a subscription changes, and BillaBear needs to deliver that notification reliably.

Tax is the part that has to match a legal requirement

The tax system is described as powerful, and the reason is that it has to match the legal requirements for your specific product type, which is a different kind of constraint from a feature wishlist.

You can set up tax rules for countries and states. EU tax laws such as reverse charge and one-stop-shop are supported. And there is an integration with VAT Sense so you can automate the syncing of tax rules for the EU and countries other than US and Canada.

The thresholds are the part that shows the system was built by someone who has done this. The system is aware of thresholds which are configurable per country and state, which allows you to set up the system to charge tax only when you reach a certain threshold, and you can configure it to receive notifications when a threshold is reached.

That is a detail that only matters if you sell digital goods across the EU, where VAT registration thresholds determine whether you have to charge at all. A system that hardcodes a single rate is wrong for that case, and a system with per-country, per-state rules and thresholds is a system that can be configured to be right.

The integrations list reinforces the same point. Beyond Stripe there is VAT Sense for tax rules, DocRaptor for PDF generation, Xero and EasyBill for accounting, SendGrid, Mailgun and PostMark for email, Slack for notifications, Mailchimp and EmailOctopus for marketing, and FreshDesk and Zendesk for help desk. This is a system designed to sit inside an existing business stack rather than replace it.

Pricing models are the feature teams ask for in month two

The pricing section lists the models, and the list is a good proxy for who uses this software.

A fixed price for a plan. Sell packages, for example 200,000 euros of revenue, which can also be sold in usage so they are billed based on their previous month's usage. Tier volume pricing where the price per unit decreases as the volume increases. Stair pricing, called tier graduated, where the price per unit decreases as the volume increases but only after a certain volume. Tiered volume with a fixed fee and a per unit fee. And seats pricing where you charge per seat.

The distinction between tier volume and stair pricing is the one worth pausing on, because the two names are easy to mix up. In tier volume, the price per unit falls as volume rises, across the whole volume. In stair pricing, the per-unit price only drops once you pass a threshold, and below that threshold you pay the higher rate. The first rewards growth smoothly, the second rewards crossing a commitment. Getting that wrong on an invoice is a customer-facing problem, and the fact that both are named separately is a sign the pricing engine models them separately.

The usage model is the other one to note, since it is billed on the previous month's usage. That is a deliberate design choice with consequences: your invoice is a statement about a period that has already closed, which makes it predictable for the customer and awkward for a mid-period change.

Subscription add-ons are the mechanism for the common pattern where the base plan covers the product and extras are sold on top, and the mass subscription change system is for moving many subscriptions at once, such as a price migration.

Twig templates put document wording outside the engineering team

The template section explains a decision that is really about organisational friction.

BillaBear uses Twig templates for the generation of documents such as invoices, quotes and emails. This allows you to customise the look and feel of these documents to match your brands. It also allows for using the email service provider's templates. Both of these allow other departments other than tech to make minor changes, and the README's phrasing is worth quoting: no more minor tickets to change the wording in an invoice or an email.

That is a small feature with an outsized effect on how a billing system gets operated. The invoice wording is a legal document, and legal will want to change it. If the wording lives in code, every change is a deploy. If it lives in a template, it is a file edit by the person who cares.

The email side has the same logic in two forms. You can use the email service provider's own templates, which means the email is rendered by SendGrid, Mailgun or PostMark rather than by BillaBear, or you can use the EMSP templates. Document management covers invoice, PDF and quote, via Twig templates as well, and PDF generation is handled by the DocRaptor integration rather than by a bundled renderer.

That last point is a pattern across the whole integration list. BillaBear owns the billing state and delegates everything it can to a specialist service, which keeps its own codebase smaller and its dependency surface narrower, at the cost of one more service to run and one more vendor relationship to manage.

Self-hosting means PostgreSQL, Redis, Elasticsearch and a mail server

The compose file shows what a self-hosted deployment actually requires, and it is a real infrastructure footprint rather than a single container.

The services are a mail server on bytemark/smtp, Redis on redis:5-alpine with the port published on 6379, Elasticsearch on 8.17.1 with a 2g memory limit and a 1g reservation, a database on timescale/timescaledb-ha:pg17 with the port published on 5432, php-fpm on a billabear ubuntu image for PHP 8.4, and nginx in front of it with the port published on 80.

The database image is the one to notice. It is TimescaleDB, PostgreSQL with time-series extensions, and for a billing system that is the right shape, because subscription events, invoices and usage records are all time-indexed and append-heavy.

Elasticsearch is there for the reporting and search features, and it is the heaviest optional-looking component, with the memory limit explicitly set and security disabled with xpack.security.enabled=false, which is fine for a single-node development instance and not something to copy into production.

The network is a single bridge network called billabear, and each service joins it, so the containers talk to each other by service name rather than by host, with the database URL assembled from the environment variables inside the php-fpm service.

The rest of the repository matches a modern Symfony application. There is a src/ directory, a config/ directory, migrations/, templates/, translations/ for the multiple language support, assets/ and a public/ directory, a bin/ directory, and a features/ directory with behat.yml.dist for the behaviour tests, alongside phpunit.xml.dist for unit tests. The frontend build is a mix of Webpack Encore and Vite, with Tailwind and Vue on the client side, and the scripts expose dev, dev-server, watch, build, test and test:watch.

Editorial conclusion

Adopt BillaBear if you already use Stripe for payment processing and want to own the subscription and invoicing layer yourself, since the REST API and the Stripe integration are the parts that would otherwise be hand-built. Skip it if you are not on Stripe, because the payment relationship is not abstracted, or if you need the newest features immediately, since the open source version gets a feature release every 6 months while the hosted version updates regularly. Verify first that the hosting requirements suit you, because the compose file expects PostgreSQL with TimescaleDB, Redis, Elasticsearch and a mail service, and check the tax configuration for your jurisdiction before you take payments.

Frequently asked questions

Official sources

1. billabear/billabear on GitHub
2. Issues
3. Project website
4. README
5. Releases