Architecture
Last reviewed: 16 November 2026 · Audience: developers integrating with or contributing to BillHive.
System overview
| Component | Responsibility |
|---|---|
| API facade | The only public API. Authenticates JWTs and API keys, checks permission scopes, validates requests, runs the pricing (rating) engine, and orchestrates the services |
| Subscription service | Catalogue, customers, orders, subscriptions, usage events, offers |
| Billing service | Invoices, credit and debit memos, transactions, wallet memos |
| Payment service | Gateways, mandates, payment requests, refunds |
| Reporting service | Analytics boards and metrics |
| User & tenant service | Tenants, team members, roles, API keys |
| Workflow engine | Long-running processes as BPMN workflows: create subscription, trial activation, renewals, plan and frequency changes, pause/resume, cancellation, expiry, dunning, mandate waits, daily wallet job, exchange-rate sync |
| Notification service | Turns business events into emails (templates), in-app notifications and webhook deliveries |
Each tenant (merchant) is isolated by tenant ID on every request and record.
Why workflows
Subscription actions run over days or months: a trial ends in 14 days, a renewal invoice goes out 5 days early, dunning retries for 3 weeks. These steps are modelled as workflows with timers. That is why:
- the API returns as soon as the order is placed, and the subscription appears a moment later;
- scheduled actions (End of Term, Specific Date) can be removed before they run;
- steps are retry-safe: a retried step doesn’t create a second subscription, invoice or payment request for the same order.
Business data model
Key ideas:
- A rate plan price is one currency and billing frequency of a plan; it is what orders reference.
- Every change to a subscription is an order, so orders are the history of a subscription.
- A subscription has terms; renewals add terms. The term holds the price used to renew.
- Money moves through invoices, memos and transactions; a prepaid wallet is built on credit memos.
Money and rounding
- The rating engine keeps amounts to 6 decimals.
- Each invoice line and its GST are rounded to paise; the invoice total is the sum of the rounded lines.