Invoices
Table of contents
The main output of CloudBilling is an invoice for each customer, per period. This invoice is, at the core, a set of results of all the pricing rules that were applied to purchases for that specific customer in that specific period. Its most basic form of representation is an XML that lists all these results and their properties. The invoices can be found on the invoices page.
An invoice in the CloudBilling context is a collection of Invoice Items, or Pricing rule results. Each invoice has a period which is configured in the customer. Additional information from the customer can be retrieved to show as text on the invoice; think about the customer name, address and metadata fields. Each invoice has a revenue total and a cost total, which reflect the current value of the invoice. Due to the real-time processing nature of CloudBilling, invoices are continuously updated. This can be seen by the invoice statuses. The following statuses exist:
- Pending: The invoice is pending calculation. There were changes that caused the invoice to no longer reflect the current situation.
- Open: The invoice is calculated and up to date.
- Approving: The invoice is in the approval process and is currently locked, preventing it from changing. This allows the user to check whether the information on the invoice is correct and ensure that the finalized invoice will look the exact same.
- Approved: The invoice is approved and ready to be sent out; the invoice will not recalculate anymore. An invoice number is generated. This is considered a finished status and cannot be undone.
- Closed: The invoice is closed and will not be sent out; the invoice will not recalculate anymore. No invoice number is generated. This is considered a finished status and cannot be undone.
- Error: An error occurred during calculation, the invoice may be recalculated, or support should be contacted if a recalculation does not resolve the error.
The invoices are generated once the customer is first saved. New invoices that should be generated are checked once every few minutes, so the invoices might not immediately generate. The new invoices will generate starting in the month configured in the “Bill From” date on the customer. Once usage comes into CloudBilling as purchases, given that the products and pricing rules are also in place, the corresponding invoices will be updated with the purchase starting on the month in the “Bill From” date that is set on the customer. The fact that multiple invoices are generated, ensures that the full current month can be billed and that earlier months can also be billed, if necessary. The invoices pages can be found by clicking on “Invoices” in the menu bar (Figure Invoices 1). By hovering over this option, the Invoice management page and the Transformation Results page can also be found.
Figure Invoices 1: Invoices menu bar
On the invoices page, an overview can be found of all the invoices (Figure Invoices 2). The first page will show the most recent invoices. At the left top of the page, the [Add] button can be used to make an Ad Hoc invoice. Below that are some quick search options, and the option to search with Advanced options. The page then generates the invoices overview table, with 25 invoices per page and the option to travel between pages under this table.
Figure Invoices 2: Invoices screen
Clicking on the [Add] button will bring the user to the Add Invoice page. Over there, the invoice settings can be configured. All settings as shown in Figure Invoices 3 except “Period To” have to be configured. Period To will be automatically filled out as the same date as Period From settings if left empty. An invoice should have a unique reference, which can be used in purchases to route them to this specific Ad Hoc invoice. The Invoice Date will show on the invoice as the date the invoice should be sent out, while the Period From and To dates are used as a period for the invoice. The Customer that is filled out should be corresponding with the customer the invoice is for.
Figure Invoices 3: Add Invoice screen
Back on the invoices page, the pre-defined search buttons empower the user to have some quick search options (Figure Invoices 2). The default option is set to “All”, which means that all invoices are shown without filter. The remaining options for quick searches are listed below:
- Live: returns all invoices that have status “Open”.
- Ready to Approve: returns all Open invoices that have a Billing period in the past.
- Complete: returns all invoices that are Approved or Closed.
- Problem Invoices: returns all invoices that failed at some point in the billing or invoicing process and are now in an error state.
Advanced search options will instead open the full set of search options, which can be modified and searched on ( Figure Invoices 4). Most options will help the user by giving suggestions. The user can search for the following options:
- Customer Code: find all invoices for a specific customer.
- Customer Cluster: find all invoices for a particular customer cluster and, optionally, the descendants of that cluster.
- Invoice Reference: find a specific ad hoc invoice.
- Invoice Number: find one or more approved invoices, based on an invoice number or part of the invoice number.
- Invoice Statuses: find invoices in a specific status by selecting one or more invoice statuses.
- Invoice Types: find only periodical or ad hoc invoices.
- Is Empty: find all invoices that are empty or are not empty and thus have a value.
- Total between: find invoices that have a minimum or maximum total amount, or an amount that falls within a range.
- Billing period: find invoices based on their invoice period.
These options can be combined in searches for invoices.
Figure Invoices 4: Advanced search options invoices
This paragraph will go into detail on the information shown in the table. An invoice will get an Invoice Number only when it gets moved from the “Open” status to the “Approved” status. If an invoice is not for the period, but ad hoc, a reference will exist in the second column of the table. The type of the invoice can be seen in the third column. The next three columns provide information about the customer; the customer name, code and cluster can be found here. The customer name is clickable and will open the corresponding customer page. The cluster will, similarly, open the customer cluster page and show the tree-structure in the left sidebar. After this, information about the invoice can be seen in the table. The From and To date are the period dates of the invoice. After that the last total and last cost total of the invoice can be seen, which are the values on the invoice. Then the Status of the invoice and the Last calculated date and time are shown.
The right side of the table consists of multiple buttons that provide operations that are available for every invoice. The button functions are shown in Figure Invoices 5. For each invoice, the following options are available from left to right in the table:
- View all purchases related to the invoice.
- View the invoice in the Invoice Viewer.
- Approve, Close or Recalculate the invoice. or
- Download the invoice as an XML.
- Apply a transformation to the invoice.
- View all transformation results related to the invoice.
- Select multiple invoices.
- The button in the header will select ALL invoices in the current filter.
- Multi-selecting allows for application of operations on groups of invoices.
Approving and Closing invoices is irreversible. Once an invoice is Approved or Closed, there is no way to undo it. This is enforced to ensure invoice number continuity.
The recalculate button, a circle with a diagonal stripe or an exclamation mark, will change depending on whether the invoice has is “Ready to approve”. When the invoice period has ended, the exclamation mark will appear, meaning that the invoice now can not only be recalculated, but also approved or closed. Invoices can only be approved or closed when the “To” date of the invoice is in the past.
Figure Invoices 5: Buttons invoices table
Invoice Viewer
The invoice viewer can be accessed with the text balloon button in the “View” column. The invoice viewer will contain a standard header, several tabs that show the options, and a view of the template that is currently in the environment ( Figure Invoices 6).
The header of the invoice viewer contains information regarding the selected invoice. The customer name and customer code can be found here, as well as an invoice period, the last calculation date, the current invoice status, and cost and total values.
The Invoice Viewer will open an example of what the invoice looks like with the current set-up, with the Default view opened first. It can be that there are multiple templates that can be accessed through the invoice viewer. In that case there will simply be more clickable tabs in the invoice viewer. The details tab shows a raw list of all invoice line items that are associated with the invoice. Pricing rule results will show a collapsible and expandable tree view of the invoice line items. Pricing rule results can also be used for troubleshooting faulty invoices.
If an up-to-date PDF transformation result exists for this invoice this will be shown by default. In that case the user can switch between the PDF and live preview of the invoice in the top right. When the PDF is shown, there is also the option to download the PDF. This additional button is currently not shown and will only exist when a transformation exists.
What the invoice looks like is entirely dependent on the template that is uploaded in the environment and can, therefore, be adjusted to the wishes of the user. The templates are often not made or kept up to date by the user, but rather by the CloudBilling consultant, since the code the template exists of is CloudBilling-specific.
Figure Invoices 6: Example view invoice viewer
Invoice management
The invoice management page can be used as an alternative to the Advanced search page. The page allows the user to immediately search for a specific customer and select a period (Figure Invoices 7). Additionally, there are three buttons: “Problems”, “Ready For Approval”, and “Approved”. Which can also be used to make an invoice selection.
The main goal of the page is to simplify the approval flow. Because of this, there are also four buttons at the top of the table which allow to perform four of the standard operations on a selection of invoices. By selecting multiple invoices with the checkmark buttons, the user can Approve, Close, Recalculate, and Export to General Ledger a large selection of invoices at once.
Figure Invoices 7: Invoice Management screen
Furthermore, there is an option to go through an “Approve 1 by 1” flow. Clicking this button will open a view for each of the invoices that can be used to ensure that he invoices do not contain any errors and look as expected. An example of the screen that shows when clicking this button can be found in Figure Invoices 8. The page shows a box with all the invoices that can be approved for that month and includes the progress. There are multiple buttons to the right of that box with a header showing the customer name, period, invoice status and total. When an invoice is ready to approve, there will also be an Approve, Close, and Recalculate button. To the right of that, a comment can be placed on an invoice. A scrollable overview of the invoice is shown below the general information.
Figure Invoices 8: Approve 1 by 1 flow screen
Transformation results
The information that is on an invoice, often needs to be represented in different formats, for different purposes. The standard transformation of an invoice can be viewed in the Invoice Viewer on the invoices page. This transformation is dynamically created, which means it is not a PDF yet. The PDF version of an invoice comes into existence once a PDF Transformation is applied to the invoice. Additionally, it could be that an export is needed in a CSV format for an overview of the totals and costs per category, or a general ledger export for an external general ledger system. These transformations will be saved in CloudBilling on the Transformation Results page (Figure Invoices 9). The transformation results page shows all the transformations that have been made for any invoices.
Figure Invoices 9: Transformation results screen
The aim of the transformation system is to enable the generation of these different representations of the same underlying invoice data. To this end we use transformation templates, which make use of the Razor view engine, to transform the invoice information to any text-based format. Additionally, provided the text format is HTML, the platform allows for a PDF transformation to be performed generating a PDF as a result.
The table on the transformation page shows the similar information as the Invoices page. There is some information about the customer, invoice period, the used transformation and template, the channel, status of the transformation, created date and a last processed date when the invoice is Completed. The invoice can then be saved, deleted, recalculated and multi-select transformation results with the buttons, respectively from left to right.
Invoice Approval
The default invoice approval process consists of the following steps:
- Requesting approval for an invoice or a selection of invoices. Executing this step will lock the invoice(s).
- The invoice is ready for approval. In the default process, every CloudBilling user that belongs to a user group with invoice approval permission is able to approve the invoice.
- The invoice is approved and an invoice number is assigned.
If the invoice is rejected, the invoice will be reopened. This will automatically update the invoice to reflect any changes to it. If a process with multiple reviewers is set up in the Invoice Approval Processes , approving the invoice will send it to the next reviewer. Rejecting it will send it back to the prior reviewer. If the last required reviewer approves the invoice it will be approved definitively. If the first reviewer rejects, the invoice will be reopened.