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 organised in a table, that can be ordered asceding or descending when a column header is clicked. At the right 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 filters.
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:
- Active: returns all invoices that have status “Open”.
- Last month returns all invoices from the previous month
- Ready to Approve: returns all Open invoices that are ready to be approved.
- Pending my approval: returns all invoices that are pending the user approval.
- Approved returns all invoices that were approved.
- Error returns all invoices that failed at some point in the billing or invoicing process and are now in an error state.
A custom search can be done by using the filters on the right side of the page ( Figure Invoices 4). Most options will help the user by giving suggestions. The user can search for the following options:
- Number: find an invoice with a specific number.
- Reference: find an invoice with a specific reference.
- Customer: find all invoices for a specific customer.
- Cluster: find all invoices for a particular customer cluster and the descendants of that cluster.
- Type: find all invoices of a specific type (Period, AdHoc, Credit).
- Status: find all invoices that match a specific status (Pending, Open, Approved, Approving, Pending my approval, Closed, Error).
- Period From: find all invoices whose period started on or after the date specified.
- Period To: find all invoices whose period ended on or before the date specified.
- Amount From: find all invoices whose amount is equal or higher than the value specified.
- Amount To: find all invoices whose amount is less or equal to the value specified.
- Approved From: find all invoices whose approval date was on or after the date specified.
- Approved To: find all invoices whose approval date was on or before the date specified.
- Sent by e-mail: find all invoices that were or not sent by email.
- Only emty invoices: find all invoices that have no purchases assigned.
These filters can be combined in searches for invoices.
Figure Invoices 4: Filter 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. The Customer Code and Customer Name that the invoice is related to can be seen, respectivaly, on the second and third colum. The status of the invoice can be seen on the fourth column. The type of the invoice can be seen in the fifth column. If an invoice is not of the type Period, but AdHoc, a reference will exist in the sixth column of the table. The Period column shows the timeframe that the invoice refers to, and the Cost and Amount are the totals of the invoice.
When selecting the checkbox on the left side of an invoice row, some actions can be applied to the invoice (Figure Invoices 5).
Figure Invoices 5: Buttons invoices table
The buttons will do the following:
- Request Approval: request approval for the invoice.
- Approve: approve the invoice.
- Reject: reject the approval of the invoice.
- Close: close the invoice.
- E-mail: trigger the messaging process.
- Transform: execute a transformation on the invoice.
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.
Invoice Viewer
The invoice viewer can be accessed by clicking on the row of the invoice to be checked. 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 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 Transformations shows tab shows a list of transformations that exist for the invoice. On the same tab is also possible to execute new transforations. The Details will show a collapsible and expandable tree view of the invoice line items. This section can also be used for troubleshooting faulty invoices, and also used to trigger Recalculations of the invoice, or to trigger a Download of the XML file of the invoice. Lastly, the History tab shows all the history of actions performed on the invoice.
Figure Invoices 6: Example view invoice viewer
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 on the bottom of the invoice Figure Invoices 7.
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 7: Switch to live preview button
On the right side of the screen, a Summary section can be seen, with information about the invoice status, its period, amount and cost, and also a link to all the purchases assigned to the invoice. The Activity section shows the latest activity on the invoice.
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.