Skip to main content

Data Model

This page maps the core entities of the Billerang platform and how they relate: the account hierarchy that owns money, the catalog that defines what can be sold, and the rating and billing chain that turns usage into invoices.

For definitions of individual terms, see the Glossary.

Entity relationship diagram​

The diagram deliberately leaves out custom fields, discount plans, and tax mapping to keep the core chain readable. They attach to the entities above without changing this shape: a discount plan attaches to an offer, product, or subscription; a tax class attaches to an article; custom fields attach to almost anything.

Accounts​

The account hierarchy is four levels deep, each level narrowing the scope of what it controls.

  • Seller is the legal, invoicing entity. It owns invoice sequences and the set of trading currencies it can bill in.
  • Customer is the commercial party under a seller. It carries CRM-level data (brand, category, contacts).
  • Customer Account is the financial layer under a customer. It fixes the currency, payment method, and credit terms shared by everything below it.
  • Billing Account is the invoicing unit. It picks a billing cycle, which decides when and how the account gets invoiced, and it is the parent of every subscription that gets billed together.

A billing account can hold many subscriptions, and split billing lets a single subscription's rated transactions land on more than one billing account when needed.

Catalog​

The catalog side defines what can be sold before anything is subscribed.

  • Offer Template is the sellable product as seen by a customer. It bundles one or more service templates or products.
  • Service Template / Product groups the charges that make up a feature or SKU.
  • Charge Template is the pricing unit: recurring, one-shot, or usage. Every charge template resolves its unit price from a Price Plan Matrix, which can key off date, quantity, currency, or custom attributes.
  • Article sits next to the charge template and controls how the charge is presented and posted: its tax class, its invoice sub-category, and the Accounting Code it lands on in the ledger.

When a customer subscribes, the offer template is instantiated into a Subscription, which copies the services, products, and charges relevant at that point in time. Changes to the catalog after that point do not retroactively change an existing subscription.

Rating and billing​

This is the runtime chain that turns activity into money.

  1. Usage arrives as a CDR (raw) or is submitted directly as an EDR (normalized), or a recurring/one-shot charge simply comes due on its own schedule.
  2. Rating applies the charge's price plan matrix to produce a Rated Transaction (RT), updating the subscription's Wallet with a Wallet Operation along the way.
  3. A Bill Run, scoped by billing cycle, aggregates eligible rated transactions into Invoice Lines using the article's aggregation rule, and produces an Invoice.
  4. The invoice is rendered from a billing template (HTML/PDF) and, where required, as a structured e-invoice. See eInvoicing Overview.

Records that fail validation during mediation or rating are held in Quarantine rather than dropped, so they can be corrected and resubmitted without losing the original event.

Where to read this from the API​

  • GET /api/v1/query/{entity} is the read path for every entity above: sellers, customers, customerAccounts, billingAccounts, subscriptions, offerTemplates, chargeTemplates, invoices, and so on.
  • Entity-specific mutation endpoints live under /api/v1/ (for example /api/v1/sellers, /api/v1/orders, /api/v1/subscriptions). See the API Reference for the full surface.