Catalog management
The catalog defines what you sell, how it is priced, and what charges apply. It is the source of truth that orders, subscriptions, and rating all read from. Get the catalog right and the rest of the pipeline follows.
The catalog hierarchy
Four entity types stack into a hierarchy. You compose sellable bundles at the top and attach pricing at the bottom.
- Offer template is what a customer subscribes to. It groups one or more products into a bundle with its own validity window.
- Product is a versioned unit inside an offer. Versioning lets you evolve a product's attributes and charges over time without breaking existing subscriptions.
- Charge is what actually rates. A product carries one or more charges, each of a specific kind (below).
- Price plan matrix holds the pricing for a charge: flat, tiered, volume, matrix, or formula-based, with dated versions.
The three charge kinds
Every charge is one of three kinds. The kind decides when and how it rates.
| Kind | Fires | Typical use |
|---|---|---|
| Recurring | Every billing period, on a calendar | Monthly platform fee, seat subscription |
| One-shot | Once, at subscription or termination | Setup fee, activation, early-termination penalty |
| Usage | Per rated event (EDR/CDR) | Metered API calls, storage GB, minutes |
Recurring charges support proration on subscription and termination and can apply in advance or in arrears. Usage charges match incoming events by their filter parameters and a formula expression, which is how one subscription can route different event types to different charges. See Multi-instance matching for the routing rules.
Pricing
Pricing lives in the price plan matrix attached to a charge. Billerang supports the full range of pricing models used by modern billing platforms.
A charge's pricing uses a one-mutable-draft lifecycle: you edit THE draft, then publish it. Publishing auto-closes the previous open-ended version so ranges never overlap. The API detail is in Charges API.
What impacts billing
Not every catalog element changes what a customer pays. Keep the distinction clear when you model a new offer.
| Impacts billing | Informational only |
|---|---|
| Offer template (what is subscribed) | Product line (category) |
| Product and its charges | Customer brand |
| Charge kind and calendar | Offer category |
| Price plan matrix and versions | Tags |
| Counter templates (usage limits) | Media and attachments |
| Tax class and tax mapping | |
| Accounting article (GL mapping) | |
| Discount plan |
Build it with the API
Ready to build one end to end? The catalog to first invoice quickstart walks through an offer, a customer, a subscription, and a bill run with live API calls.