CloudBilling generates an Invoice for each Customer. An invoice in the CloudBilling context is a collection of InvoiceItems. That is, each time a Price Rule is applied to a source item (either a Purchase, or the result of a previous Price Rule) a result is generated, if the result is specified as ‘should be output to invoice’ then an InvoiceItem is created. The subset of InvoiceItems pertaining to a specific Customer within the billing period of the invoice, forms the basis of the invoice. This set of InvoiceItems is extended with information regarding the Customer (name, address, metadata, etc.) and invoice (billing period start/end, calculation date, status, etc.).
By default, Cloudbilling generates the invoice in an XML format. It is also possible to view the invoice directly through the UI, this view shows the all results that ‘should be output to invoice’. The XML invoice is a collection of one or more InvoiceItems. It is possible to transform the XML invoice to a different format, this process is call a Transformation.
Each invoice has a period, the invoice period is configured and stored in the Customer to which the invoice belongs. Once the invoice period has been configured and stored it cannot be changed by a Cloudbilling user. Each invoice contains the customer id, customer code, customer name, customer address, metadata and the billing period.
Due to the real time processing nature of CloudBilling, invoices are continuously updated. This is reflected in the status of the invoice. The following statuses exist:
|Pending||The invoice is pending calculation. This means that there were changes (such as, a new Purchase imported, a price rule changed, etc) which caused the invoice to no longer be a reflection of the current situation.|
|Calculating||The system is calculating. Each Purchase is being processed and results for the Price Rules are being generated.|
|Calculated OK||Calculation was successful. We now have a set of rule results that can be viewed in the interface. This also means we have a calculated total for the invoice.|
|Calculated Error||An error occurred during calculation (for example, invalid syntax on a Price Rule condition or expression).|
|Invoicing||During the invoicing step, the invoice XML is being generated.|
|Invoice OK||The XML invoice is completed and can be downloaded (either via the UI or via the API).|
|Invoiced Error||An error occurred while creating the invoice XML.|
|Approval Queued||The invoice has been marked for approval by a user. This means that the invoice will shortly (according to processing schedules) be moved to the “Approved’’ state, with all the accompanying actions (see below).|
|Approved||The invoice is approved. This means the invoice is closed and an invoice number is generated. This also means that the invoice can no longer be changed and no new usage can be added to it. An invoice has to be manually approved. When a invoice has been approved it can not be “un-approved”, this is to ensure invoice number continuity.|
|Exported||This status is to indicate that the invoice has been exported to an external system. It currently has no specific side-effects or influence on the invoice themselves.|
|Rejected||The entire invoice has been rejected and needs to be recalculated. All previously calculated results associated with the invoice will be deleted. Invoices are rejected when a new Price Rule has been added or an existing Price Rule has been modified. It is also possible to manually rejected one or more invoices via the UI.|
|Closed||The closed status of an invoice is similar to the Approved status. The main difference is that there will be no Invoice number generated for the invoice. An invoice has to be manually closed. When a invoice has been closed it can no longer be “re-opened”.|
Each invoice has an Invoice Total, and a Cost Total.
The Invoice Total reflects the total calculated value at that moment. If Purchases are being sent to CloudBilling on an ongoing basis, the system processes these Purchase imports continuously and calculates the invoice amounts continuously. This means that the calculated amounts can be dynamic during the specific billing period. This provides insight at any moment in time in the revenues generated.
The same principle holds for cost. When costs have been added to the pricing plan, the Cost Total reflects the total cost associated with the invoice.