Concepts & conventions

In order to start working with Billingbooth, it's quite useful to learn about the concepts and architecture that we have put together so you can better understand how to tie in with your organisation's needs.



The source of all your revenue are your customers, and within Billingbooth these are the billable units that form the main part of all your configuration. Each customer has a unique reference and is used to identify the customer when making any API calls, and should match a customer reference used within your own CRM or ordering systems.

Customer Hierarchy

All customers have a billed_directly flag that dictates whether invoices raised should be sent directly to them, or to a parent customer. This is particularly useful in situations where you have a channel model whereby distributors and resellers sell your products to their own customers. In this model, quite often, the price at which you sell your products to your distributors and resellers will tend to differ to the price that their own customers get charged. Distributors and Resellers will quite often take care of the billing of their own customers, so any features used by their customers on your services need to be billed directly to the distributor or reseller.

When a customer is billed_directly, a billing address is required in order to generate an invoice for them. If the customer is not billed_directly, then the billing_customer reference needs to be applied, so Billingbooth knows which customer should be invoiced for the charges applied.


Invoice runs are done on a Scheduled-basis. By default, your account will have a "default" Schedule set up, on a monthly basis. Your default schedule should match your organisation's invoicing intervals. For example, if your organisation typically invoices all their customers at the beginning of the month, your default schedule's period should be Monthly, and the period_start should be FirstDay

Multiple Independent Schedules

In certain cases, you may want to have different customers on different invoicing schedules. You may for example, want some of your bigger customers on a Monthly schedule, whereas some of your smaller customers may need to be on a Weekly basis. You can create an unlimited number of schedules on your account, each one with a unique name. You can then assign customers to specific schedules by explicitly setting their schedule property.


In a channel model, where different customers get charged different amounts based on organisational agreements on pricing, you can create multiple tariffs and assign customers to a specific tariff by explicitly setting their tariff property.


In Billingbooth, a product is a pre-defined charge that acts as a shortcut for applying charges to customers. A product can be either a physical product, or a physical or virtual service, which has a set cost.

The cost of the product can be a single one-off amount, or it can be a recurring amount that gets applied on a frequency interval, for example Weekly or Monthly.

Typically you would define your commonly used products and services that your organisation sells as a product in Billingbooth to remove the overheads of having to define the cost of a specific recurring or single charge.

In the case of recurring charges, changing the cost of a product will automatically apply to all customers that are already set up with this product as a recurring charge on their invoices.


The fundamental basic unit within Billingbooth, a charge defines a set amount that a customer receives during an invoicing period. Charges can be single or recurring, and can either be specified manually using the type, frequency and amount properties, or if you want to apply a product charge onto your customers, you would use the product property.


To see some of the above in action, please read our getting started page for more detailed information on how it all fits together.