BillaBear

BillaBear is an open-source, self-hostable billing and subscription management platform designed for SaaS businesses that need full control over their billing infrastructure. It solves the complexity of managing recurring payments, tax compliance, and customer billing workflows without relying on proprietary SaaS billing tools. Built on PHP and Symfony, powered by Stripe, it provides a REST API for seamless integration into existing systems while supporting multi-currency, multi-language, and multi-brand setups.

The system is architected around extensible components: Twig templates for documents and emails, a Symfony Workflow-based engine for async operations like refunds or subscription onboarding, and integrations with tax services like VAT Sense and accounting tools like Xero and EasyBill. It can be deployed on any server with PHP, PostgreSQL, and Redis, and offers both the open-source self-hosted version and a managed cloud version with more frequent updates.

BillaBear ships with an extensive feature set covering the full subscription lifecycle: plan management, dunning, credit notes, vouchers, quotes, mass subscription changes, revenue reports, churn analytics, and hosted checkout via Stripe.JS. Its tax system handles country and state tax rules, EU reverse charge, one-stop-shop (OSS), and configurable thresholds — making it one of the most complete self-hosted billing platforms available.

The project is actively developed and maintained by Humbly Arrogant Software Limited, with a regular release cadence and growing integrations covering email providers, help desks, CRMs, marketing tools, and PDF generation services.

What You Get

• Tax System - Configurable country and state tax rules with EU reverse charge, one-stop-shop (OSS), and threshold-based triggers; integrates with VAT Sense for automated EU tax rule synchronization.
• Workflow Engine - Symfony Workflow-powered async, retryable pipelines for critical billing operations like subscription creation, refunds, and onboarding tasks — eliminating manual developer intervention on failures.
• Invoice & Document Generation - PDF invoices, quotes, and receipts generated via Twig templates or DocRaptor, allowing non-technical teams to customize branding, content, and legal text.
• Flexible Pricing Models - Supports fixed pricing, tiered volume, stair (graduated) pricing, package-based billing, seat-based pricing, and usage-based billing with monthly consumption tracking.
• Email Template Management - Choose between EMSP templates (SendGrid, Mailgun, PostMark, EmailOctopus) or Twig templates for full control over transactional email content and branding.
• Hosted Checkout & Paylinks - Generate Stripe.JS tokens to embed secure branded checkout pages or one-time paylinks directly in your application or website.
• Dunning & Credit Notes - Automated retry logic for failed payments with configurable schedules, plus support for issuing credit notes and vouchers to customers.
• Mass Subscription Changes - Bulk upgrade or downgrade subscriptions across customer segments with a built-in mass change workflow and status tracking.
• Reporting & Analytics - Built-in subscription, lifetime value, and churn reports; daily analytics entities auto-aggregated at the database level using TimescaleDB.
• Multi-Brand & Multi-Currency Support - Operate multiple brands from a single installation with per-brand settings, and bill customers in any currency with automatic exchange rate handling.

Common Use Cases

• EU SaaS tax compliance - A European SaaS company uses BillaBear to automatically apply VAT rules per customer country, handle OSS reporting thresholds, and sync tax rule updates from VAT Sense without manual maintenance.
• Usage-based billing for developer platforms - An API platform bills customers based on monthly call volume using BillaBear’s package and tiered pricing models, automatically generating invoices from tracked usage data.
• Enterprise invoice customization - An enterprise software vendor uses Twig templates to brand invoices with client logos, custom payment terms, and legal disclaimers without engineering involvement.
• Replacing a SaaS billing tool to cut costs - A bootstrapped SaaS founder self-hosts BillaBear to eliminate Chargebee or Recurly subscription fees while maintaining full billing feature parity for their customer base.
• Multi-brand subscription management - A holding company manages billing for three product brands from a single BillaBear installation, with separate invoice branding, email templates, and pricing plans per brand.

Under The Hood

Architecture BillaBear is a well-structured Symfony monolith built on domain-driven design principles, with explicit layering across controllers, DTOs, data mappers, entities, repositories, and domain services. The MicroKernelTrait-based kernel is thin, and a custom DI compiler pass (WorkflowPass) wires the workflow engine at boot time. Data mappers strictly decouple external API payloads and internal Doctrine entities, preventing leakage between layers. The Symfony Messenger component handles async workflows with retry semantics, and Symfony Scheduler manages periodic billing tasks. The Vue 3 frontend communicates with the PHP backend via a REST API and is treated as a fully separate application layer, keeping the server-side domain clean.

Tech Stack The backend runs on PHP 8.3+ with Symfony 7.2, Doctrine ORM, Symfony Messenger for async, and Symfony Workflow for billing state machines. PostgreSQL with TimescaleDB powers time-series billing data and daily aggregation, while Redis handles caching and sessions. Elasticsearch provides search functionality. The frontend uses Vue 3 with Composition API, Pinia for state management, Vue Router, Tailwind CSS, Flowbite-Vue, HeadlessUI, ApexCharts for analytics visualizations, and Vue Flow for workflow diagram rendering. Asset pipeline is handled by Webpack Encore and Vite. The full stack runs in Docker with nginx and php-fpm.

Code Quality The codebase shows strong type discipline using PHP 8.3 typed properties, readonly constructors, union types, and immutable DTOs throughout. Testing is comprehensive: PHPUnit for unit and integration tests across 110+ PHP test files, Behat with 245+ feature files for behavior-driven acceptance testing, and Vitest for frontend component tests. Business-terminology-driven naming conventions make the domain model readable without comments. The CI pipeline and php-cs-fixer enforce consistent code style. One gap is the limited use of custom exception hierarchies — most error paths use generic exceptions, reducing error specificity.

What Makes It Unique BillaBear’s built-in Symfony Workflow integration for billing state machines is a genuine differentiator: rather than ad-hoc event handling, every critical billing operation runs through a defined, retryable state graph with Slack-based failure notifications. The TimescaleDB-backed daily analytics aggregation means revenue metrics are precomputed at the database level without external analytics tools. Its tax engine is unusually complete for an open-source billing system, with per-country and per-state tax rule configuration, EU OSS compliance, and automated VAT Sense syncing. The Fair Core License model — free for internal use but restricting commercial resale of the software itself — sets a clear ethical boundary that distinguishes it from both pure open-source and fully proprietary billing platforms.

Self-Hosting

BillaBear is released under the Fair Core License (FCL-1.0-ALv2), an emerging open-source-adjacent license designed to protect the sustainability of independent software businesses. In plain terms: you can freely use, modify, and deploy BillaBear for your own internal business purposes — including running it commercially to manage subscriptions for your SaaS products. What you cannot do is build a product or service that competes directly with BillaBear itself or resell access to the BillaBear platform. After two years, versions automatically relicense to Apache 2.0, making them fully permissive. For most self-hosters, the FCL imposes no practical restriction.

Running BillaBear yourself requires a reasonably capable server setup: PHP 8.3+, PostgreSQL with the TimescaleDB extension, Redis, Elasticsearch, nginx, and optionally a mail relay server. Docker Compose configurations are provided, making initial deployment straightforward, but you are responsible for database backups, TimescaleDB maintenance, Redis persistence, Elasticsearch index management, and keeping the PHP application and its dependencies updated. The workflow engine and scheduler run as background processes that must be kept alive. This is a full-stack application with meaningful operational surface area — not a simple single-binary deployment.

The managed cloud version at billabear.com receives updates on a continuous basis, while the self-hosted GitHub release follows a roughly six-month major release cycle. Self-hosters therefore lag behind on features and security patches unless they track the main branch. There are no published SLAs, enterprise support contracts, or high-availability deployment guides in the open-source version. If your business requires guaranteed uptime, 24/7 support, or automated managed upgrades, the hosted cloud tier provides those — at the cost of losing the control that self-hosting offers.