Monthly Billing

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 domains, months are counted pro rata and depending on how many days that month has. If the domain exists 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 domain 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 domains or for a specific domain and if minute-based billing is used, the involved trunks need to have rate tables set up (see Trunk Rates).

Domain Billing Settings

There are several settings in the domain that relate to the billing for that domain.

  • 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 domains, or they can be set for a specific domain. The PBX first tries to load the settings for the specific domain; if it does not exists, it used the setting for all domains. If there was no parameter set available, it will not bill the domain.

  • Domain: This field controls if the parameter set applies to a specific domain or to all domains.
  • 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 domain name for the domain (e.g. "client1.hosted.pbx").
  • {description} The name as set in the domain (e.g. "Bens Bakery").
  • {firstname}, {lastname} The first and last name for the customer as set in the domain billing settings.
  •  
  • {organization} The organization name for the customer as set in the domain billing settings.
  • {email} The email address for the customer as set in the domain billing settings.
  • {number} The customer number as set in the domain billing settings.
  • {discount} The customer discount as set in the domain billing settings.
  • {parameter1/2/3} The value of the general purpose billing parameters as set in the domain 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.
  • Domain 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.

In order to save the parameter set, the button needs to be used. 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. Note: For domains 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:

  • Please visit the URL https://vodia.com/en/freshbooks and press here.

  • You are 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 > Freshbooks page as shown below.

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

  • 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 acount.
  • 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 fir the required purpose.