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:
- 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
- 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.
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).
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.