Invoicing concept

At the end of the billing period, PortaBilling can produce an invoice for your customers. An invoice reflects all the transactions (calls, payments, refunds, subscription charges, and so on) which occurred during this period, and serves as the primary record of services provided to a specific customer, as well as his current status.

A billing period defines how often invoices/statements will be generated and when exactly they are to be produced. PortaBilling supports the following billing periods:

• Daily – covers a 24-hour period. If a customer’s account is activated at 12:00 on March 11th, his first invoice covers the period until March 12th; the second period covers the period from the beginning of March 12th until March 13th, etc.
• Weekly – covers a 7-day period (Monday through Sunday). For example, if a customer’s account is created on Wednesday, his first statement covers the period from Wednesday to Sunday; the second statement covers the period from Monday to Sunday, etc.
• Semimonthly – Covers a period from the 1st to the 15th or from the 16th to the last day of the month.
• Monthly – covers the period from the 1st of the month to the last day of that month.
• Monthly (anniversary) – covers the period from the Nth day of the month to the day before the Nth day of the following month. N is the day of the month when the customer was created; therefore, if a customer was created on March 19th, their invoices will always cover the period from the 19th of the current month to the 18th of the following month.To avoid complications for customers who were created on the 29th, 30th or 31st day of the month, their first billing period will cover the time until the 28th day of the following month, and thereafter will always cover the period from the 28th until the 28th. For instance, if a customer was created on March 30th, his first invoice will cover the period from that day until April 28th, while his next invoice will cover the period from April 28th until May 28th.
• 30 days – every billing period is exactly 30 days, so if a customer was created on March 20th, his first invoice will cover the period from March 20th to April 18th, the second invoice will cover the period from April 19th to May 18th, and so on. This invoicing method allows you to make subscription fees more straightforward compared to regular monthly billing, where the same monthly fee is applied to longer (e.g., March) as well as shorter periods (e.g., February or April).

Every billing period is adjusted to the respective customer’s (or vendor’s) billing time zone. So, in the case of a customer with the Los Angeles time zone and a weekly billing cycle, the billing period will start at midnight on Monday Los Angeles time, while for a customer with a weekly billing cycle and the Singaporewas time zone it will start at midnight on Monday Singapore time. Thus, while both invoices will cover 7 days (168 hours), they will actually refer to different intervals of time, with a 15-hour difference.

Or in other words: when will invoices actually appear in the system?

By default, invoices/statements are generated on the day after the last day of the billing period, e.g., invoices for customers with a weekly billing cycle are generated on Monday, while invoices for customers with a monthly billing cycle are generated on the first day of the month. A transaction is included in a certain billing period if it was initiated during that period; this is because calls are considered as taking place within a certain period according to their bill time (which is equal to their connect time). For example, if a call starts at 23:55 (11:55 p.m.) on March 31st and finishes at 00:43 (12:43 a.m.) on April 1st, then this call belongs to the March billing period.

For this reason, a billing period cannot be closed the next day at midnight sharp; there might be calls in progress which started just a few minutes ago, and which should still be included on the current invoice. PortaBilling waits a sufficient amount of time before closing a billing period, to ensure that all calls have been completed. By default, this interval is six hours, but it can be changed via the Configuration server.

Also note that since statements are generated in the billing time zone of the customer/vendor, the billing period is closed in that time zone. Thus if your system time zone is Singapore, you cannot expect to see invoices for your US customers on Monday morning, since it is still Sunday evening then in the US. Finally, in order to provide optimal system response time for your online users, PortaBilling only performs resource-intensive calculations (such as creating statistics/invoices) during the period specified in your configuration as “off-peak”. So, in the example above, if your “statistic calculation” hours are defined as 2:00 a.m. to 7:00 a.m., you will receive invoices for US customers on Tuesday morning.

You can design multiple invoice templates, so that each template has its own layout, language, logos/pictures, and the like. Every customer will be assigned a specific invoice template, according to which PortaBilling will create a .pdf file that can be emailed to the customer and/or downloaded from the PortaBilling web interface (by both the administrator and the customer himself). It is also possible to disable the “Generate invoice” option for a customer. In this case, PortaBilling would only produce CDR summaries, but not generate .pdf invoice files.

Please consult the PortaBilling Templates Guide for more information about creating and managing invoice templates.

PortaBilling offers three invoicing options configurable at the customer or customer class level:

• .pdf file generation at the end of a billing period. This is the default option. Once a billing period ends, PortaBilling processes the customer’s xDRs, applies charges (e.g., subscriptions, fees, etc.), creates an invoice and generates a .pdf file. XDR processing for the next customer only starts once the .pdf file for the previous customer has been generated. Therefore, it takes longer to process xDRs for all customers, though the .pdf files are quickly available.
• Postponed .pdf file generation. This is a useful option for service providers who automatically charge customers’ credit cards. With this option enabled, PortaBilling creates an invoice and charges a customer’s credit card immediately. PortaBilling begins to generate the .pdf files only once the calculations related to the previous billing period (e.g., xDR processing, statistics) for all customers have been completed. Postponed generation accelerates the payment procedure, evenly distributes the load on the system, allowing service providers to quickly receive revenue.
• .pdf file generation on demand. PortaBilling makes all calculations for the customer, creates their invoices and saves them to a database. These invoices are then accessible via API. However, the .pdf file will not be generated unless explicitly requested. By generating .pdf file invoices on demand you can save hard disk space and decrease the workload on the system by up to 50%, depending on the data amount. Note that at any time an administrator can initiate .pdf file invoice generation on the customer’s page.

PDF file generation management enables service providers to schedule invoice generation according to their business models. This results in decreasing the workload on the system, saving hard disk space, and quicker statistics calculation.

Every invoice contains global invoice data, which is stored as part of the invoice record in the database:

• Invoice number – unique identifier of an invoice.
• From date – start date of the billing period.
• To date – end date of the billing period.
• Invoice date – date when the invoice was generated.
• Due date – date by which payment should be received.
• Payment terms – description of payment terms (e.g., “due on receipt”).
• Invoice total – sum of all charges in this period minus credits/refunds.
• Invoice amount due – amount the customer is supposed to pay you (see below for a detailed explanation of invoice balances).
• Invoice status – the following statues are possible:
  • Open means that the invoice has been generated, but has not yet been delivered to or viewed by the customer, so it can potentially be modified.
  • Closed means that the invoice has already been sent to the customer by email or downloaded by him from the web interface.
• Invoice payment status – the following statues are possible :
  • Unpaid – the normal status after invoice generation; the customer is expected to pay the amount due (calculated as the sum of the previous invoice’s amount due and this invoice’s total).
  • Overdue – no payment was received for this invoice and the due date has already passed. If applicable for this customer class, the collection process (notifications, suspension and termination) will be launched.
  • Paid – invoice paid in full.
  • Partially paid – a payment was received, but it does not cover the full invoice amount (invoice total).
  • Do not pay – the invoice total is zero (e.g., the customer did not use the service) or negative (e.g., the customer was given credit in an amount higher than the actual service usage) and there is no unpaid balance from the previous invoices. No payment is applicable to this invoice; it is produced only for the customer’s reference.
  • No payment required – this invoice’s amount due is lower than the collection threshold, so the customer is not required to pay it right now (but still has to pay it eventually). The collection process will not be launched if no payment is received.
  • Previous balance remaining – although this invoice has a zero (or negative) invoice total, when combined with the amount due from earlier invoices there is still an outstanding balance. So the customer is still required to make a payment (to be applied to the earlier invoices), after which this invoice’s status will become “Do not pay”.

Invoices also contain certain data extracted from other PortaBilling objects, which are included in the invoice’s .pdf version:

• Information about the customer (invoice recipient).
• Information about the invoice issuer (your company or a reseller, if the invoice was issued on behalf of a reseller).
• Information about calls and other transactions included in the invoice.

PortaBilling provides two methods for computing the invoice balance (amount due):

• Simple – in this case, the invoice’s amount due is equal to the invoice total, and is calculated as the sum of all charges during the given period (no previous payments are taken into consideration). This is an optimal method for integration with an external bookkeeping system, where you keep track of your incoming payments via accounting software, and not PortaBilling.
• Balance-aware – the invoice total is calculated as the sum of all charges during the given period (both call and non-call related), minus the sum of all credits/refunds. The invoice’s amount due is calculated as: previous_balance + invoice_total - payments. This allows you to “carry over” a balance in the case of partial payments. For example, suppose a customer’s March invoice was for $40. If he makes a payment of $30 on April 10th, makes calls for $25 during April, and is also issued a $3 refund, then his April invoice will have an invoice total of $25 - $3 = $22, while the invoice’s amount due will be $40 + $22 - $30 = $32.

By default, PortaBilling uses the balance-aware invoice generation method.

To simplify payment collection and improve cash-flow, PortaBilling can charge a customer’s credit card before closing an invoice. So if, as in the example above, the invoice’s amount due was initially $32, the customer’s credit card will be charged $32, with payment entered to the April billing period. As a result, the customer’s invoice will be created with a zero amount due.

This type of auto-payment can be activated on a per-customer basis (using the Payment method panel).

Every time a payment is recorded in the system (this could be a periodic payment, an online payment by a customer, or a payment entered manually by the administrator), in addition to modifying a customer’s balance it will also be applied to one of his unpaid invoices. If the amount so applied equals the invoice’s amount due, the invoice becomes “paid”, while if the payment is less than the amount due, the invoice becomes “partially paid”. Payments are applied to an invoice cumulatively; thus if an invoice is for $30, and the customer makes three payments of $10, $13, and $17, following this last payment the invoice will be “paid”. If a customer has several unpaid invoices, the payment will be applied to the oldest one.

If a payment exceeds the total amount of all unpaid invoices, the remaining sum will be assigned to the special customer property “unallocated payments”, and applied to future invoices. For instance, suppose a customer receives his weekly invoice, with an amount due of $8.99. Since he plans to leave for a three-week vacation, he sends in a payment of $36. This entire amount is applied to the customer’s balance, so that $8.99 will cover the existing invoice, while $27.01 will remain in “unallocated payments”. When his next several invoices are created, they will show an amount due of zero and the status “paid in full”.

You can see the customer’s current “unallocated payment” status on the Balance & Credits tab in the customer info.

You can change the rounding method for invoice amounts in the customer class. You can select one of the following rounding methods:

• Away from zero – this rounding method is selected by default. It works similar to rounding up but differs when rounding negative values. Positive and negative values round symmetrically. For example, if the rounding precision is set to two decimals, then:
  • 1.214, 1.215 and 1.216 all round up to 1.22.
  • - 1.214, - 1.215 and - 1.216 all round to - 1.22.
• Half away from zero – this rounding method works similar to arithmetic rounding but differs when rounding negative values. Positive and negative values round symmetrically. For example, if the rounding precision is set to two decimals, then:
  • 1.214 rounds to 1.21, 1.215 and 1.216 all round to 1.22.
  • - 1.214 rounds to - 1.21, - 1.215 and - 1.216 all round to - 1.22.
• Special rounding (malaysian) – formerly known as custom rounding. This type of rounding depends on the last decimal at precision point. For example, if the rounding precision is set to two decimals, then:
  • If the last decimal at precision point is [0...2], it is set to zero. For example, 1.204, 1.215 and 1.226 all round to 1.20.
  • If the last decimal at precision point is [3...7], it is set to 5. For example, 1.234, 1.255 and 1.276 all round to 1.25.
  • If the last decimal at precision point is [8...9], it is set to 0 and the previous decimal increases by 1. For example, 1.284, 1.296 all round to 1.30.

Also, you can choose the number of decimals to round the invoice amounts in the Rounding precision option in the customer class.

The difference between the sum of all the charges and the rounded off invoice amount is written as a separate xDR with the proper (plus or minus) sign.