Link Search Menu Expand Document
CloudBilling Docs

Transformations Overview

The main output of CloudBilling is an Invoice for each Customer, for each 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. It’s most basic form of representation is an XML that lists all of these results and their properties.

However, this information often needs to be represented in different formats, for different purposes. For instance, you might want to create an overview of a customer’s invoice, where only the high-level values are displayed, and detailed specifics left out. Or you might want to create a detailed specification, where only the specifics are displayed, and nothing else. Finally, you might want to create a single export for your general ledger system, containing ledger entries for every customer on some specified level of detail.

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 instead.

API Interaction CB API V1.1+

As of V1.1 of the CloudBilling API, Invoice Transformation Results can be retrieved via API. This allows for better integration with self-service portals and easier retrieval of large volumes of invoice transformation results. To retrieve an actual file (PDF, HTML, TXT, etc) a few steps are involved. There are two basic scenarios:

  1. Retrieve transformation results for a set of customers: GetInvoiceTransformationResultsForCustomers
  2. Retrieve transformation results for a set of invoices: GetInvoiceTransformationResultsForInvoices

That is, one ore more customers can be specified by code (optionally together with some additional criteria) and the system will return all matching invoice transformation results. Or, one or more invoices can be specified by id (optionally together with some additional criteria) and the system will return all the matching invoice transformation results. The InvoiceIds are internal CloudBilling ids and they can be retrieved with the GetInvoiceHeaders method, which allows searching for invoices based on a large set of possible criteria.

Both calls will return a list of InvoiceTransformationResults matching the specified criteria. The InvoiceTransformationResult objects contain additional information regarding the result (period, when it was created, the status, etc.). These can be used, for instance, to display a link for each invoice to start the actual retrieval. Which is performed by calling the final method: GetInvoiceTransformationResultFile with an InvoiceTransformationResult id as a parameter. This returns the contents of the actual file along with some metadata. From this result the file can be created and processed further as required.

Learn more…

Copyright Ⓒ 2023 CloudBilling (Inter8-NL B.V.)