Technical ReferenceArchitecture

Architecture

Last reviewed: 16 November 2026 · Audience: developers integrating with or contributing to BillHive.

System overview

ComponentResponsibility
API facadeThe only public API. Authenticates JWTs and API keys, checks permission scopes, validates requests, runs the pricing (rating) engine, and orchestrates the services
Subscription serviceCatalogue, customers, orders, subscriptions, usage events, offers
Billing serviceInvoices, credit and debit memos, transactions, wallet memos
Payment serviceGateways, mandates, payment requests, refunds
Reporting serviceAnalytics boards and metrics
User & tenant serviceTenants, team members, roles, API keys
Workflow engineLong-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 serviceTurns 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.