Purchases in CloudBilling reflect any kind of product or service that customers need to be charged for. Depending on the user their business and industry, this could be a contract fee, subscription, recurring purchase, suage or a product or service, for example.
As explained in the Introduction, purchases will need customers, products and pricing rules set up in the CloudBilling environment to work as expected. The purchase will come into the environment and connect itself to a specific customer and product cluster. Based on these mappings, the purchase will go through the corresponding pricing rules and end up as a line on the invoice. This chapter will further explain how purchases can come in, the function of product labels, unmapped purchases, billing of purchases, pricing overrides and metadata on purchases.
Purchases in CloudBilling can come into CloudBilling in multiple ways, as explained before, purchases can be uploaded with the Excel Editor, they can come in through an API connection, be pulled through a connector with a partner environment, or manually added. The Purchases page can be found in the menu bar (Figure Purchases 1). When hovering over the purchases bar, the Unmapped Purchases page can also be found. Additionally, the Connectors page and the Excel Editor page can be found in the menu bar as well. If there are no connectors connected to the environment, the header will be called “Excel Editor”. When there are connectors in the environment, the Excel Editor can be found as an extra option by hovering over the Connectors text in the menu bar.
Figure Purchases 1: Purchases and connectors menu bar options
Clicking the Purchases button in the menu bar, will redirect the user to the Purchases page. In the left top of the page under the name “Purchases” there are some filter options provided. This will allow the user to filter on All, New, Unmapped, and Not Invoiced purchases with one click. Additionally, the Advanced options can be chosen, which opens the options as shown in Figure Purchases 2. This will allow the user to also search on more detailed information. The options include invoice ID, invoice reference, imported customer code, mapped customer, imported product label, product cluster, is mapped, is invoiced, purchase reference, purchase date from, purchase date to, imported date from, imported date to, metadata type, metadata key, and metadata value.
Figure Purchases 2: Purchases screen advanced options
These fields all allow to search for information on the purchases. When searching for metadata, all three metadata fields must be filled out and correspond with the metadata field on the purchase. Then the [+ Add] button next to the metadata value field must be clicked before using the [Search] button.
To the right side of the purchases table there are three different buttons, a trash can, a pencil, and a checkmark. The Trash can is used to delete purchases, the pencil to edit purchases, and the checkmark to multi-select purchases. It is important to know that purchases can only be deleted if they are not linked to a finished invoice, the status of the invoice must be “Open” for purchases to be deleted. Purchases can only be edited one-by-one. The checkmark in the blue bar of the table will select all purchases, be careful with using this checkmark to delete purchases.
The checkmark in the blue bar of the table will select ALL pages of purchases in the current selection, be mindful when using it to delete purchases.
As briefly discussed in the first paragraph, purchases can come in (semi-)automatically, or be added by hand. When adding a purchase by hand, the [Add] button in the right top of the Purchases page can be used (Figure Purchases 2). This will redirect the user to the Add Purchase page, as can be seen in Figure Purchases 3. A new, manual, purchase will always have a Reference generated by CloudBilling and the current date and time in the Purchase Date field. The other options will be blank and can be filled out by hand. The mandatory fields for purchases are the Reference, Product Cluster, Customer, Quantity, and Purchase Date.
Figure Purchases 3: Add Purchase screen
The product cluster will correspond with the product that is bought, while the customer corresponds with the customer buying the product. The quantity will determine how many units of the product are being sold. Additionally, a purchase can be set to “recurring”, with the Recurrence option. This will ensure that only one purchase must be made for, for example, a yearly subscription that is paid monthly. The Recurrence options are None, Second, Minute, Hour, Day, Month, and Year. These settings will take into consideration the Purchase Date and End Date. If a purchase End Date is kept empty for a recurring purchase, it will be billed infinitely.
The Purchase Date and End Date are time fields. They will open a little calendar view when clicked, where a date can be selected. These fields are used to determine on which invoice a purchase should appear. A purchase with a date set in September, as can be seen in the screenshot, will connect itself to the September invoice, if this invoice is not already Approved or Closed. If a purchase only has a Purchase Date, which is the start date, the purchase will be put on the invoice that contains that date in full. For non-recurring purchases the purchase might be split over two months if the end date is in the next month.
There are two options under the Billing header, the Ad-Hoc tick box, and the Bill in Advance tick box. When the latter tick box is ticked, the billing period changes against the purchase date. For example, when a purchase has a set purchase date in May, having the tick box on will put the charge of the purchase in June instead. Otherwise, the purchase will just be charged in May. This option is mostly used for licences and subscriptions that should be paid in advance. A purchase can also be connected to an Ad-Hoc invoice. For this, the Ad-Hoc invoice should already be made. This can be done through the invoices page and will be explained in more detail in Chapter 2.5 Invoices. The Invoice Reference must be put into the box that appears when the Ad-Hoc tick box is ticked.
The pricing override section can be found below the Billing section and exists of three boxes, respectively for the Override Unit Price, Override Total Purchase Price, and Override cost. These pricing options can be used when the price that is set up in the pricing rule should not be used. They are also used often by the connectors to steam in the pricing of a product automatically. The overrides can be used to use a different price per unit, for the total purchase or for the cost. The unit price will take into consideration the quantity that is on the purchase to determine the total price, while the total purchase price will not.
Metadata can be found at the bottom of the purchase and has three different possible types, Text, Date, or Number ( Figure Purchases 4). Metadata can be added by clicking the [Add Metadata] button. A new line will appear with a Type, Key, Value, and a [Delete] button with the icon of a trashcan. When metadata is added, it must have all values filled out, otherwise the purchase cannot be saved.
Figure Purchases 4: Metadata fields on purchases
The Keys of the metadata are often determined by the user, they can come from or be used by an external system or be used by the pricing rules to group purchases based on metadata. The Key fields are case sensitive and should not have trailing spaces for them to be effectively used. Text metadata Value fields have a free format of text, numbers, and special characters. A Date metadata Value will also open a calendar view and ensures itself that the format of the date is correct when using this calendar to select the correct date. Number metadata Values only use round and decimal numbers. The decimal place is indicated with a dot (.).
Metadata Keys are case sensitive and should be the exact same format to be effectively grouped with other metadata fields.
As shown in Figure Purchases 1, the Unmapped purchases can be found when hovering over Purchases in the menu bar or using the dashboard purchase module. Clicking this button will redirect the user to the Unmapped Product Labels page (Figure Purchases 5). In the Unmapped overview to the left of the page, the user can also travel to unmapped Customer Codes and unmapped Invoice References. Ideally, there would be no unmapped labels of any kind in the CloudBilling environment.
Figure Purchases 5: Unmapped Product Labels screen
The lines in the tables are clickable, which will redirect the user to the Purchases page with a filter on the Imported Product label (Figure Purchases 6). When the product is unmapped, it means that CloudBilling cannot immediately map the imported product label to a product. Therefore, the Product Cluster of these purchases is empty. It can also be that the Customer Cluster cannot be directly mapped onto an existing customer. Then, the Customer Name will be empty. Usually, the mapping of purchases occurs automatically during the automated import process. This process maps a purchase to a product by matching the product label of the purchase to an SKU of a product, and to a customer by matching the customer code of the purchase to that of a customer. It can also be that the purchase comes in with an invoice reference that does not exist, for example when it should have been connected to an Ad Hoc invoice.
Figure Purchases 6: Unmapped Products on the Purchases page
For purchases without product clusters, there are two ways to ensure that these purchases are mapped. When the purchase comes in for a product that already exists in the environment, the purchase reference can be retrieved from the purchase and added to the corresponding product as a new SKU. When the product does not exist in the environment yet, a new product and corresponding pricing rules should be made that contain the purchase reference as an SKU. In both cases, new purchases that come in with the same purchase reference will now automatically be mapped.
When it comes to unmapped customers on purchases it is often the case that the customer does not exist with the customer code that was sent with the purchase. Therefore, it will often be the case that the customer will have to be made in the environment so that the purchase can be mapped. If the customer code that came in is incorrect, the purchase can also manually be mapped to the correct customer, by clicking on the “edit purchase” pencil and selecting the correct Customer.
Similarly, to map purchases that came in with an incorrect invoice reference, either a new invoice with that reference can be made or the purchase can be mapped through adding in the correct invoice reference in the purchase.