Custom invoice references

By default the Billingbooth One platform utilise a sequentially-increasing numerical system for issuing invoice references, e.g. an invoice number. For each invoice created, the invoice number is increased by one, and no invoice can be issued with a lower invoice number than the highest one on the account.

Using custom invoice references, an account can utilise a different naming scheme that includes data in context with the invoice, customer or organisation. This article describes how this is achieved and gives some examples and what could be produced.

Configuration

To enable custom invoice configuration, you must first head over to Settings -> General, then under the Invoice Reference heading you can enable the custom generation of references.

In the Generation Code box, you can write code that will be used during the invoice generation to issue custom references.

Javascript

Generation of custom invoice references is achieved by scripting it in Javascript. Some basic development knowledge is required (the converter uses Javascript with ECMA 5.1 compliance), if you are unsure then please contact us.

Generation example

Below is a simple example on taking the customer's reference, and the current invoice's issue date month and year, and putting them together to make a custom invoice reference:

// get the invoice billing period
var date = invoice.billingPeriod;

// months are zero indexed in Javascript, so we add +1
var month = (date.getMonth()+1).toString();

// if month is single digit, pad it with a leading zero
if (month.length === 1)
    month = '0' + month

// get year to two places
var year = date.getFullYear().toString().substr(-2);

// set reference
reference(customer.reference + '-' + month + year);

In the above example, we have taken the invoice billing period then broken it down into month (1-12) and year (two-digit format), then using the reference() method, we have set the custom invoice reference to be customer reference followed by a hyphen, then followed by the month and year of the billing period date. If the customer reference was JOEBLOGGS01 and the billing period was January 2023 then this would lead to an invoice reference that looks like:

JOEBLOGGS01-0123

There are a range of methods as well as objects that can be used to retrieve context properties of associated invoices, customers and organisations at the time of invoice generation. These are documented below.

Methods

Property	Description
reference(string)	Set the invoice reference. Any references longer than 50 characters will be truncated

invoice object

The invoice object can be referenced within the code to access properties relating to the invoice being generated.

Property	Description
number	The automatically created numerical invoice number
issueDate	The invoice issue date
dueDate	The invoice due date
billingPeriod	The invoice billing period as defined during the billing run that created it

customer object

The customer object contains properties relating to the customer that the invoice belongs to.

Property	Description
id	Unique customer identifier
name	Customer name
reference	Customer reference
address1	First line of their address
address2	Second line of their address
address3	Third line of their address
address4	Fourth line of their address
town	Town or City
county	County or territory
postcode	Postcode or Zip code
country	Country

organisation object

The organisation object contains properties relating to the customer's organisation that the invoice belongs to.

Property	Description
id	Unique organisation identifier
name	Organisation name

metadata object

The metadata object gives you access to the customer's metadata store, and can be used as a mechanism for accessing configuration data for that customer. This is most common when the customer has been created via the API rather than the portal and custom information from third-parties has been stored.

Method	Description
get(string)	Returns the value the metadata entry with the key specified in the method variable, e.g. metadata.get('test'). If no entry is found, null is returned.