BillRun definitions → core-api

Authoritative source for what a BillRun domain means: docs.bill.run Definitions. Supporting pages: Product Catalog, BillAPI.

When this page conflicts with another architecture note, prefer this page. Official docs.bill.run still treats Customer and Account as synonyms; this codebase splits them: an Account is a billing account groups belong to (/accounts) inside a Tenant that represents the client company (Tenant per client), Customer is a real user who can have many Subscriber lines (/customers).

Basic / catalog

docs.bill.run term	Official definition (paraphrased)	core-api today	Wire / storage notes
Product	Anything that can be offered to a market and is usage based	Rates & Tariffs — Rate model, app/services/rates.py, /api/v1/rates	Business term is Product; BillAPI paths and the core-api table/path are rates (BillAPI's Products section itself calls /billapi/rates/*). Nested JSON field rates = tier/volume price map.
Plan	A set of products and services that define tariffs/terms; assigned to a subscriber. Also known as bundle or offer	Plans — /api/v1/plans	A Subscriber references at most one plan via plan_id. include (groups) + rates override maps + commercial flags are on the Plan row; group runtime (balance groups) is not implemented.
Service	Anything offered that is subscriber based (property of subscriber or account). Also known as addon	Out of scope (scope)	No /services API or table.
Customer / Account	Account level that aggregates few/many subscribers	Accounts — /api/v1/accounts	Path and type name stay Account. Current domain term: Account — a billing account of a client company (the company is the Tenant).
Customer	A real user; can have many lines (Subscribers)	/api/v1/customers — Customer model, distinct from Account/Client	One-to-many with Subscribers via customer_subscribers. May also sign in to self-service. Created on first login (when the identifier matches a live line), by an operator, or automatically from live subscriber lines carrying an email (app/services/customer_sync.py); a synced customer has no user until first login.
Subscriber	A line (under a group, with at most one plan)	Subscribers — /api/v1/subscribers	plan_id optional until assigned. Belongs to a Customer (user); its group belongs to an Account of the tenant's client company.
Discounts	Engine that deducts plan/service/invoice price when defined conditions are met	Out of scope (scope)	No /discounts API or table.

Prepaid

docs.bill.run: since 5.16.0 prepaid uses the same configuration as postpaid; the difference is the input processor rejecting out-of-bundle usage.

core-api: Plans carry connection_type (postpaid | prepaid). Balances selection/charge branches on that (app/services/balances.py). Realtime / prepaid deduction and an input-processor reject path are not implemented.

Tools (definitions page)

docs.bill.run term	core-api today
Custom fields	Not applicable as such. Account, Subscriber, Plan and Rate rows carry a free-form metadata JSONB (raw source payload) instead.
Input processor	CDR/line data arrives through Connectors and CSV import.
Cycle	Billing cycles are out of scope (scope).
Export generator	Not implemented.
Events	Events tracks connector sync runs.

Related terms that are easy to confuse

Term	Meaning	Not the same as
Product	Usage-based catalog offer (rates)	Tax admin "Rates" (VAT definitions)
Tax (admin)	VAT/sales-tax rate definitions + mapping rules (out of scope here)	Tax application while rating, and Products
Rate (internal / BillAPI path)	Storage name for Product	Plan recurring price intervals
Tenant	A client company (e.g. "Celtic") and everything it owns	Account (one of its billing accounts)
Account	Billing account of a tenant's client company (/accounts)	Customer (real user at /customers)
Customer	Real user; can have many Subscriber lines	docs.bill.run Customer / Account, which is Account here

Tax (admin) has no core-api domain (scope).

What "match definitions" means for this codebase

1. Semantics — models and APIs implement the definition (e.g. subscriber has one plan; an Account is what groups belong to; a Customer is a real user with many lines; Product is usage-rated).
2. Terminology in OpenAPI and docs — tags/descriptions name the docs.bill.run term and the core-api name when they differ (Product ↔ rates).
3. No silent rename of storage — table rates, path /api/v1/rates, and Python Rate* stay unless a deliberate, versioned API change decides otherwise. BillRun's own BillAPI already uses /rates for Products.
4. Gaps stay explicit — custom fields, plan include-group runtime and product revision windows are not implemented, not papered over by renaming.