Purchase Overview
Purchases in CloudBilling reflect any kind of product or service that you need to charge your customers for. Depending on your business and industry, this could be anything from a contract fee, subscription, or recurring purchase, usage of one of your products or services, a once-off admin or setup fee, or even the purchase of a physical product. Purchases can be added via the UI manually or fed to CloudBilling via the API. In order to be able to price a purchase and place it on the correct invoice you need to include a few key pieces of information. Each purchase that is added or sent must have the following information:
- Product Label, matches an Alias of a Product Cluster. It is used to determine “what” was bought or used.
- Customer Code, links the purchase to a Customer.
- Quantity, “how much” was bought or used.
- Purchase Date, “when” it was bought or used (we need this to know which invoice it belongs on. If relevant, a Purchase EndDate, this is used in conjunction with the Purchase date to determine how long the purchase or usage is/was valid for.
- Reference, must be unique, it is used to ensure your data remains consistent and traceable.
In most cases, Purchases are fed to the CloudBilling Public API, directly from your systems.
Sometimes, it is important to be able to include extra information that is specific to your situation, that needs to be used during calculations (in PriceRule Expressions and Conditions), or needs to be included on the invoice. To cater for this, CloudBilling allows for the addition of extra information to a purchase, in the form of metadata. This metadata can be anything, as long as it can be represented as a String, a Number, or a Date.
Some common industry specific examples of where Metadata is useful include:
- Telco
- When a purchase represents a CDR, it is often important to include the the From and To MSISDNs as string metadata
- This allows you to apply bundles per MSISDN, and to include the MSISDN info on a specification or itemised invoice
- IAAS
- When a purchase represents storage space for a specific VM, you can add the VM name to the purchase.
- This allows you to generate specifications that shows you the usage per VM.
Unmapped Purchases
An unmapped purchase is one that has not been associated to a Customer or ProductCluster. The mapping of purchases occurs automatically during the automated Import process. This process maps a purchase to a customer (by matching the CustomerCode of the purchase to that of the customer), and to a ProductCluster (by matching the ProductLabel of the purchase to an alias of a ProductCluster).
Not Invoiced Purchases
A not invoiced purchase is a purchase that has not yet been placed on a invoice. This can be an unmapped purchase, but it does not have to be.
Apart from when a purchase is also Unmapped, there are two possible situations that can lead to this:
- When a purchase has a PurchaseDate that lies in the future it will have the status not-invoiced, until an invoice is opened with a period that encompasses the PurchaseDate.
- When a purchase is linked to a product cluster or customer cluster that has no valid price rules associated with it. This means the purchase will never be priced, and therefore, never placed on an invoice.
Purchase Routing
Purchases can be routed to a different customer. The main use of this functionality is to register usage against one customer, while another customer should pay for the usage. This allows you to track the technical registration (who used the product/service) in your backend, while tracking the commerical registration (who should pay for the product/service) in the billing system.
Routing works through a set of rules. Each rule consists of 3 parts:
- Source Customer Cluster
- Source Product Cluster
- Target Customer
The rule then states that purchases for all customers underneath Source Customer Cluster for products underneath Source Product Cluster are forwarded to Target Customer.
As an example, consider a customer cluster structure like so:
All Customers -> Netherlands -> Reseller -> Customer
In this example there are customers representing the Reseller and the Customer at the relevant levels. The customer is generating usage, which is being sent to CloudBilling. However, the agreement is that the Reseller pays for this usage.
Let’s assume the product cluster structure looks like:
All Products -> Usage
Now a Purchase Routing rule can be defined for source cluster “Reseller”, product cluster “Usage” and target customer “Reseller”. This would make it so that all customers underneath the reseller (for now only this single one, but in the future more can be added) will have their Usage purchases routed to the Reseller.
Routing of purchases is applied continuously to purchases that are not yet completed (a purchase is considered completed when the invoice it is on is approved). That is to say, if a routing rule is adjusted, the purchases will be re-routed to reflect the new state of the rule. If, in the example, the Customer would be moved to a different parent cluster, the rule would no longer apply and the purchase would go back to the customer. The rules are automatically re-evaulated whenever a relevant aspect in the system changes. This includes customer clusters, product clusters, the customer itself, or the purchase.
Routing is always based on the original customer of the purchase, not on the outcome of previous routing rules. This makes it so that if a routing rule is adjusted, the new outcome will be according to this rule. This also means that rules cannot be “chained”.
The system enforces that routing rules cannot overlap. That is, there cannot be 2 rules that would cover the same purchase. Since there would be no way to determine which rule should be applied.