Billerang v1 API

What Billerang is

Billerang is a quote-to-cash billing platform: it holds the account hierarchy and catalog, turns usage and orders into invoices, and tracks what customers owe. It is built on the Opencell v17 engine (Java EE / Jakarta EE), and /api/v1/ (BillerangV1Application, package org.billerang.api) is the canonical, purpose-built REST API for it. Every other surface (/api/rest/v2/*, /api/rest/*, the Generic API, TM Forum, Custom API) is legacy and is being migrated to v1 over time; the migration table at the bottom of this page tracks that.

The account hierarchy

Billerang organizes every customer relationship into five levels. Each level owns a distinct concern, and every level below Seller extends the same AccountEntity base class in the domain model.

Seller
  └── Customer
        └── Customer Account (CA)
              └── Billing Account (BA)
                    └── User Account (UA)
                          └── Subscription ── Access (usage endpoints)

Level	Owns	Verified from
Seller	The legal entity issuing invoices; its own invoice numbering sequence per invoice type	Seller extends AccountEntity, field invoiceTypeSequence (List<InvoiceTypeSellerSequence>)
Customer	The commercial relationship (who the customer is); groups one or more Customer Accounts	Customer extends AccountEntity
Customer Account (CA)	Payment: the list of payment methods, and which one is preferred	CustomerAccount extends AccountEntity, field paymentMethods (List<PaymentMethod>), method getPreferredPaymentMethod()
Billing Account (BA)	Invoicing: which billing cycle applies, the next invoice date, and (optionally) its own payment method override	BillingAccount extends AccountEntity, fields billingCycle, nextInvoiceDate; named query BillingAccount.getPreferredPaymentMethod joins up to CustomerAccount.paymentMethods when the BA has none of its own
User Account (UA)	Service usage: the subscriptions that actually consume the catalog, and the prepaid wallet	UserAccount extends AccountEntity, fields subscriptions (List<Subscription>), wallet (WalletInstance)

A Subscription belongs to a User Account and links to the catalog (OfferTemplate). To receive usage data, a subscription registers one or more Access records (Access.accessUserId, e.g. a phone number, SIM ID, meter ID, or API key) that CDRs are matched against.

Today, creating and reading this hierarchy (Seller aside, which has a v1 resource) is legacy-API territory; see the migration table below.

The catalog model

The catalog is what a customer subscribes to. It is built bottom-up from charges, and top-down from offers:

OfferTemplate (the commercial offer, e.g. "Enterprise Plan")
  └── Products (ProductVersion: DRAFT → PUBLISHED, Attributes for configuration)
        └── Charges (one-shot / recurring / usage)
              └── Pricing Versions (flat / matrix / formula), one mutable DRAFT + published history
  └── Discount Plans (offer-level or order-level discounts)
  └── Articles (map each charge/product to an invoice sub-category, accounting code, and tax class)

• Charges come in three kinds: one-shot (fires once, at subscription or termination), recurring (fires on a billing calendar, with proration), and usage (fires when an EDR arrives). Source: ChargeTemplate discriminator charge_type (O/R/U; a fourth kind, P for product charges, backs CPQ product instances).
• Pricing Versions are how a charge is priced. All pricing goes through PricePlanMatrix → a PricePlanMatrixVersion in PUBLISHED status. A version is either flat (isMatrix=false, single price or priceEL) or a matrix (isMatrix=true, one or more dimensions matched by PricePlanMatrixColumn, priced per matching PricePlanMatrixLine); a formula is a flat version whose price is computed from an EL expression instead of a literal number. The v1 charge pricing endpoints (/api/v1/charges/{code}/pricing/draft and /pricing/publish) work against one mutable draft at a time, never a raw version number.
• Discount Plans apply at the offer or order level and reduce a rated amount before it becomes an invoice line.
• Articles (AccountingArticle) are the bridge from rating to accounting: every rated transaction is mapped through an article to an invoiceSubCategory (where it prints on the invoice), an accountingCode (general ledger mapping), and a taxClass.

See the catalog to first invoice quickstart for this entire chain run live, and the pricing models and discounts quickstart for flat, matrix, and formula pricing plus a discount plan, also run live.

The revenue pipeline

An order is how a subscription comes into existence; usage and the billing calendar are what keep charging it. The full path from a commercial transaction to money owed:

Order (typed lines: CREATE / AMEND / TERMINATE / APPLY_ONE_SHOT)
  → Subscription (created or changed; typed product actions: CREATE / ACTIVATE / SUSPEND / TERMINATE / MODIFY)
      → Mediation: CDR (raw usage event) → EDR (subscription-linked, ready to rate)
          → Rating: EDR → WalletOperation (OPEN) → RatedTransaction (billable, OPEN)
              → Billing Run (aggregates RatedTransactions into InvoiceLines)
                  → Invoice
                      → Account Operations (accounts receivable: what is owed, matched, or overdue)

• Order. An order's lines (OrderOffer) are typed by orderLineType (CREATE, AMEND, TERMINATE, APPLY_ONE_SHOT); each product line inside a line is typed by productActionType (CREATE, ACTIVATE, SUSPEND, TERMINATE, MODIFY). Validating an order for a CREATE line creates the subscription and activates its services in the same call.
• Mediation. A CDR is the raw, unparsed usage event; converting it to an EDR links it to a subscription (via its Access record) and makes it rating-ready. EDRs are always persisted; CDRs are persisted only if configured to be.
• Rating. A WalletOperation is the rated result of one charge event (amount = quantity x unit price, from the matched pricing version). It starts OPEN. A separate job converts OPEN wallet operations into RatedTransaction rows — only rated transactions are billable; a billing run does not look at wallet operations directly.
• Billing Run. Aggregates open rated transactions per billing cycle into InvoiceLine rows (grouped by billing account, offer, article, tax, and seller, plus optional keys like subscription or user account), then generates the Invoice.
• Account Operations. Once an invoice is validated, it becomes an account operation (a debt entry) for accounts-receivable tracking: matching against payments, aging, and dunning.

See the catalog to first invoice quickstart for an order through to a validated invoice, and the usage mediation quickstart for a CDR through to a rated transaction, both run live end to end.

API surface tour

The v1 resources are grouped into 8 functional areas.

Customer Account Management — the account hierarchy entities that have a v1 resource today (business accounts and their models), plus the reference data attached to a customer: customer brands, customer categories, and titles. The full hierarchy is created and reparented through the root /businessAccounts resource; single-tier edits (Customer, Customer Account, Billing Account, User Account) go through their own level endpoints; see the Business Accounts API page.

Catalog Management — the full catalog: offer templates, products (with product lines, attributes, and commercial rules), offer categories, bundle templates, brands, channels, tags, media, and the charge types (one-shot, recurring, usage) with their pricing, counters, discount plans, and articles. This is the largest group and the one with the most maturity; see the catalog to first invoice quickstart and pricing models and discounts quickstart.

Orders Management — placing and managing orders, order types, subscriptions, and termination reasons. An order's CREATE lines both create and activate subscriptions in one call; see the catalog to first invoice quickstart for this run live. Every order can also be rendered to a PDF document and emailed to the customer; see the Orders API page.

Usages — the mediation and rating pipeline: CDRs, EDRs, and rated transactions. See the usage mediation quickstart for the full CDR-to-rated- transaction path, including both the JSON and CSV wire dialects for CDR ingestion.

Billing Management — everything that turns rated transactions into invoices: billing runs and their schedules, billing cycles, invoice types, sequences, categories and sub-categories, the invoices themselves, billing templates, and tax categories/classes. Billing templates also back order documents, via a documentKind of ORDER instead of the default INVOICE; see the Orders API page.

Account Receivables — post-invoice accounting: account operations and their templates, accounting codes, bank transports, and payment webhooks.

Platform — cross-cutting platform capabilities: the Query API for generic reads, the schema Workbench, Formulas, job instances and timers, script instances, workflows, notifications, custom field definitions, custom objects and endpoints, code generators, modules, files, users, roles, auth, and system endpoints. See the Query API page for reads across any entity, used throughout every quickstart to look up codes before using them in a mutation.

Global Configuration — tenant-wide setup: providers, settings, sellers, trading countries/currencies/languages, calendars, and units of measure.

Conventions

Base URLs, JSON-only content negotiation, resource path conventions (create, create-or-update, partial update, typed-action envelopes, action sub-resources, versions, bulk, async, list parameters), idempotency, traceability (auditable), null-vs-empty update semantics, pagination, date-time formats, and the error model are all covered in detail on the API principles page. Read that page before building against any endpoint below.

Migration status

Surface	Status
/api/v1/* (org.billerang.api)	Canonical. Build all new work here.
/api/rest/v2/* + /api/rest/* (org.meveo.api)	Legacy. Migrating to v1 incrementally, including the account hierarchy above Seller.
/api/rest/v2/generic/all/{entity} (Generic API)	Legacy, read-only. Frontend reads still depend on it.
TM Forum + Custom API	Legacy/auxiliary. Migrate or wrap behind v1 where it makes sense.

The full endpoint-by-endpoint reference (every v1 resource, request/response schemas, and try-it-out) is at /apiReference, an embedded Scalar viewer over the generated openapi-v1.yaml spec.