In hosted PBX environments, clients need to be billed monthly. The PBX can automatically generate invoices at the beginning of a month, based on the usage of the previous month.

The usage data can be sent out either by email or by a billing provider (currently Freshbooks, see freshbooks.com). The emails are intended for internal purposes and are not supposed to go to the clients. They contain the CDR that were used to calculate the minute-based part of the bill. The billing provider-invoices are generated as "draft" invoices and need to be manually approved before they are sent out to clients.

For new tenant, months are counted pro rata and depending on how many days that month has. If the tenant has existed during the whole month, the PBX bills for the whole months. Even though the number of days per months differs, the PBX bills full months the same amount.

In order to use the monthly billing, the tenant needs to have the billing information that is needed to generate an invoice, the PBX has to be set up for the monthly billing either for all tenants or for a specific tenant and if minute-based billing is used, the involved trunks need to have rate tables set up (see Trunk Rates).

Tenant Billing Settings

There are several settings that relate to the billing for that tenant.

Billing parameter: This is a general purpose billing parameter. It can be used to set up static parameters that can be referenced in the billing (see below). A typical example is a number of extensions that has been negotiated with the client, no matter of how many extensions were actually used by the client. Billing email address: This is the email address that will be used by the billing provider. The PBX does not use that address to send out emails. The PBX checks if the billing provider has an account with that email address. If it exists, it uses that account; otherwise it will attempt to create an account with that email address. Customer number: This number can be used in the invoice number generation. If not provided, the PBX will attempt to use the client number provided by the billing provider. First name, last name, company or organization name: These fields contain the first name and the last name for the account and the name of the organization under which the account is stored. These fields are only used if the client does not exist on the billing provider (they are mandatory for successful account creation). Discount: Invoices can have discounts. When this field contains a number between 0 and 100, the PBX copies the value into the invoice. This number is not copied into the email.

Monthly Billing Parameters

There are several billing parameters that independent from the billing provider. Those settings can be set for all tenants, or they can be set for a specific tenant. The PBX first tries to load the settings for the specific tenant; if it does not exists, it used the setting for all tenants. If there was no parameter set available, it will not bill the tenant.

Tenant: This field controls if the parameter set applies to a specific tenant or to all tenants. Currency: All values in the parameter set must use the same currency, which is set with this field. List of email recipients for the bill: When the PBX generates bills, it sends out an email to the list provided in this field (separated by semicolons, for example abc@domain1.com;def@domain2.com). These emails are intended for internal proofing purposes and are not supposed to be sent to the client.

In the invoice itself, there are line items that contain a line item text, a description and a unit price. The unit price is a floating point number in the selected currency that shows the price for one unit in the line. The item text is typically a short text like "Extensions", the description is a longer text that explains in more detail the line. The item and description text can contain variables in the form {variable} which are replaced by the PBX when the invoice is generated. The following variables are available:

• {month} The month for which the invoice is being generated.
• {year} The year for which the invoice is being generated.
• {currency} The currency (e.g. USD or EUR) depending on what has been selected.
• {name} The address of the tenant (e.g. "client1.hosted.pbx").
• {description} The name for the tenant (e.g. "Bens Bakery").
• {firstname}, {lastname} The first and last name for the customer as set in the tenant billing settings.
• {organization} The organization name for the customer as set in the tenant billing settings.
• {email} The email address for the customer as set in the tenants billing settings.
• {number} The customer number as set in the tenants billing settings.
• {discount} The customer discount as set in the tenants billing settings.
• {parameter1/2/3} The value of the general purpose billing parameters as set in the tenants billing settings.

There are several possible line items that the PBX can put into the invoice:

• Fixed cost: If there are costs that are not depending on the actual usage, they can be put into this line. The number of used units it always 1, even if the domain was created in the middle of the month.
• Extension: The PBX keeps track on how many extensions were used during the month (based on daily samples). The number of extensions is averaged over the measured days. If the domain was created in the month, the number of extensions is calculated as if the number was zero before the creation.
• Extension (mailbox, redirect, classroom): This is similar to the regular extensions, but for the extensions that have administrative usage restrictions. If these lines are used, the extensions are "regular" extensions and the restricted extensions are counted separately.
• Agent group, conference room: Similar to the measuring of the extensions, the PBX also keeps track on how many ACD and conference are used, so that they can be billed as separate items.
• Tenant parameter: This line parameter references the domain parameter which was described above.
• Cost for calls: When trunks generate cost information, they are listed under the line item which is set here. The description for the call costs are taken from the rate table.

Save the parameters. A parameter set can be deleted using the delete button. In order to test the settings and in order to avoid waiting until the end of the month, the test button can be used. It generates the bill for the selected domain.

(Empty tenants)

For tenants that have just been created, the metered values will be zero. In order to get any output, there needs to be for example a fixed cost item.

Freshbooks Parameters

In order to use Freshbooks, you need to have an account at freshbooks.com. Before the PBX can generate invoices, there needs to be a trust relationship between the PBX and Freshbooks. The PBX currently only supports the simple authentication (no OAuth).

Here are the steps to integrate the PBX with Freshbooks:

First you need to visit the URL https://portal.vodia.com/en/freshbooks and press Generate Token on that page.

You are then redirected to the Freshbooks Website for allowing third party access by Freshbooks. Confirm, to grant the access.

Now, the token shall be generated for you back on Vodia's webpage as shown below.

Then you can apply the token to the "Authentication Token" field, on the Admin > Domains> Monthly Billing>Freshbookspage as shown below.

(Account holders)

Freshbooks might have allowed the old account holders to use the JSON API option for integrating from here.

Then you can copy the token into the web interface of the PBX:

API Version: Dropdown menu gives a choice between Freshbooks Classic which is if you have an Old account on Freshbooks and Freshbooks JSON API if you have a new Freshbooks account. Freshbooks classic is being discontinued. API URL: The API URL as shown in freshbooks (typically https://abc.freshbooks.com/api/2.1/xml-in). Authentication Token: This is the "password" for your account (typically something like c23c3be134a5be445e6965bac8c665ae). Invoice number format: The invoice format that you would like to use. There are several formats available that will hopefully fit your needs.

Emails

In order to support manual invoicing, the system can generate emails that contain the relevant information. The email address in this tab is not the tenants email address; this email address will be used to send all generated invoices to the same address for manual review.

Testing

In order to test if the billing works for a specific tenant, you need to navidate to the tenant list page and edit the tenant. Next to the location where you can select the plan for the tenant, there is a test button that will trigger the test for the tenant. This works for sending out emails as well as for generating invoices on Freshbooks.