Advanced invoicing configuration

PortaBilling provides two methods for calculating the invoice amount due:

• Balance-aware (default) – the invoice amount due is calculated as the sum of the outstanding balance
  • for the current billing period
  • from previous billing periods

  This allows you to “carry over” a balance in case of missed or partial payments.

  Example

  Say a customer owes $40 for March. If they make a payment of $30 on April 10th, make calls for $25 during April, and get a $5 credit, then their April invoice will have an invoice total of $25 - $5 = $20, while the amount due will be $40 - $30 + $20 = $30.

  Previous balance	40
  Payments	-30
  Charges for the period	25
  Credit	-5
  Amount due	30

• Simple – the invoice amount due is equal to the invoice period total and is calculated as the sum of all pay-as-you-go charges, subscriptions, credits/refunds, and corresponding taxes applied during the given period. Previous payments and the outstanding balance from the previous billing periods aren’t taken into consideration.
  Example

  Say a customer has $30 of outstanding balance from August. In September, they make calls for $25 and a $10 tax charge is added. The September invoice shows an invoice total of $25 (call charges) + $10 (tax) = $35. The amount due for the September invoice equals the invoice total, which is $35.

  Charges for the period	25
  Taxes	10
  Amount due	30

To change the default balance-aware method to simple, go to the Configuration server web interface and set “No” for the Stats.New_Style_Invoice_Calculation option. As a result, PortaBilling will switch to the simple method for calculating the invoice amount due.

Regular invoices are generated automatically after the billing period is closed in the system.

PortaBilling provides flexibility in configuring the closure of billing periods. You can configure a global delay in the billing period closure, e.g., to ensure that all calls initiated in the last minutes of the billing period are completed and accounted for in the corresponding invoice. Besides that, you can set an additional delay for a specific customer class, e.g., postpone the billing period closure for a few days until the xDRs from external systems are imported.

Let's explore the billing closure configuration in more detail.

By default, PortaBilling does not close the billing period precisely at midnight. To ensure that the sessions that are still in progress are completed, charged, and fully accounted for in the current billing period, there is a global delay (set to 6 hours by default), allowing the ongoing calls or internet sessions to end before closing the billing period.

Say a call starts at 23:55 (11:55 PM) on March 31st and finishes at 00:43 (12:43 AM) on April 1st. The March billing period is closed on April 1st at 6 AM. Therefore, the call ends in the March billing period and the corresponding charge for this call will be reflected on the March invoice.

The global delay is set on the Configuration server web interface within the Default_System_Close_Billing_Period_Delay option. The delay is the amount of time sufficient for the completion of ongoing sessions. By default, it is six hours (21600 seconds). When this period ends, PortaBilling closes the billing period according to the customer’s time zone.

The default value can be adjusted; however, we highly recommend keeping the delay equal to or greater than the maximum call duration (defined by the b2bua.max_credit_time option) to make sure that all sessions that started in the last hours of the current billing period are completed and that charges are correctly calculated for them.

The optimal timeframe for running database queries and generating invoices is during off-peak hours, typically from 2 AM to 6 AM Central European Standard Time (the time frame is set according to the Configuration server's time zone), when the system load is minimal. This scheduling ensures that the heavy load from running database queries to extract and sum up xDRs does not affect server performance. Although invoices are generated using the replica database to prevent any impact on real-time charging, conducting these operations during low-traffic hours helps avoid any potential slowdown in the admin UI and other system operations.

You can set the time frame for invoice calculations through the Calculate_Statistics_At option on the Configuration web interface.

Let's see how the settings for the billing period closure and the invoice calculation timeframe work together and determine when the invoices will be generated.

Say you have customers in Europe and the US with a monthly billing period. You have the default timing configuration:

• The Default_System_Close_Billing_Period_Delay is set to 21600 seconds (6 hours). This configuration means the system waits 6 hours after midnight, as determined by the customer’s time zone, before officially closing it.
• The Calculate_Statistics_At option is set to “hr {2-6}.” This means that the system can begin calculating invoices anytime from 2:00 AM to 6:59 AM, according to the server’s time zone (e.g., Central European Standard Time).

For your customers in Europe, the invoices will be available on the first day of the new month, following early morning processing by the system. Say the March billing period ends at 6 AM on April 1st, matching the customers' time zone. Since the server operates in the same time zone, it will begin generating invoices immediately (since 6 AM falls within the specified time frame) and complete the process by 6:59 AM. As a result, customers will receive their invoices on the morning of April 1st.

For customers in the US, the difference between the server's and the customer's time zones means that their billing period is closed when the timeframe for calculating invoices on April 1st has already passed, so the system will wait for the nearest off-peak period to calculate invoices. Consequently, their invoices will be generated overnight and become available on the second day of each month.

In the customer class settings, you have the option to postpone the billing period closure for a specific number of days. During this period, adjustments can be made to the customer balance (e.g., upon xDR import or manually). PortaBilling includes these adjustments in the still-open billing period and they appear on the customer’s current invoice. Once the period is over, the billing period is automatically closed. Note that the global delay will also be considered.

This option is useful if you have post-paid mobile customers for whom an additional delay is needed to receive the data from your roaming partners and include it in the current billing period.

An admin sets a 3-day delay in the billing period closure on the customer class “Postpaid mobile.” This time is sufficient for receiving the roaming xDRs from an external system so that the corresponding charges will be included in the current billing period. The customers have a monthly billing period.

On September 1st, the billing period is still open. On September 2nd, the roaming xDRs are imported into the system. As a result, a charge of $20 is added to the balance of a customer, John Doe, for a call made while roaming in August. Despite the transaction being added to PortaBilling in September, it is included in the August billing period since the period is not yet closed. The billing period automatically closes at midnight on September 4th, so PortaBilling generates an invoice for John that covers all charges from August 1st to August 31st, including the $20 charge added on September 2nd.

By default, the billing period is closed automatically once it ends, according to the customer’s time zone. Only the global delay that is set on the Configuration server web interface applies in this case.

To close the billing period with an additional delay:

• Open the customer class configuration.
• Go to Finances > General info.
• Select With a specified delay for the Close the billing period option.
• Specify the number of days PortaBilling waits to close the billing period in the Delay option.