Add / Edit a Price Rule

Search for Rules

The Price Rule Details screen is split into sections, which make up the properties of every rule. Before creating or updating a rule, it is a good idea to become familiar with the major concepts of Price Rules, and specifically, the different Types.

To navigate this article, either scroll through to read all the information or click on a section name below to jump directly to that section.

General
Scope
Rounding
Pro Rata
Expressions
Advanced

In addition to the standard sections, some rule types have additional properties. These additional properties will appear on the right-hand side of the screen when the relevant rule type is selected.

Additional settings are available for:

Adjust Rules
Sum
Group Price
Ladder
Bundle

All fields are editable. Once you have filled in all the relevant details, press the button at the bottom of the screen.

Note: adding or updating rules means that open Invoices might be affected. All these affected invoices will be marked for recalculation.

General

Rule Name - a unique name to identify the rule by.
Type - CloudBilling supports many different types of calculation, represented through Types. The first step when creating a rule is to choose the Type most appropriate to your needs. Doing so will change the layout of the add/edit screen, by showing the various fields relevant to your choice, and hiding those that are irrelevant.
Rule Order (optional, defaults to 0) - The sequence in which Price Rules are run is primarily determined by the order of the Product and Customer clusters. However, should there be more than one rule sharing the same combination of clusters, the Order property is then used as a “tie-breaker” (lowest number going first).
- Note: If 2 rules are found in this situation, and they have the same Order specified, these two rules will run in parallel. It is important to understand that this will result in the same source items (for instance, purchases) being calculated in 2 different ways, resulting in 2 sets of output results too. While this is generally not desirable, it is of particular importance when concepts such as “Component Pricing” are required. As an example, using this technique you would be able to create 2 separate price charges for the same purchase simultaneously, to represent 2 “parts” of the overall price.
Value - This is the explicit unit price that will be applied to each item and ultimately is what drives the price your customers will pay. Note that because this is a “unit price” the value will be multiplied by the Quantity.
Cost - This works the same as the Value property but is used to define the Cost price to your business.
Billing Output Tags - Billing output tags allows additional output tags to be specified for a specific rule. Each of these output tags will be included on the results generated by the rule. The output tag can be used in multiple ways. The most common use of billing output tags is to identify specific results that you want to display on the PDF invoice. The tags can be imported to other systems as well, like a general ledger classification for an accounting system.

Tags can be added simply by typing in the field, once a tag is complete press either tab or enter to confirm. Tags can be edited by clicking them, or by pressing backspace when at the end of a completed tag. Tags can be removed by clicking on the x next to them, or by simply removing the text when editing. Tags can be copied and pasted from and to the field as well.

Scope

Product Cluster - The product grouping to which this rule applies. This rule will apply to source items linked to this cluster and to items linked to any clusters that is a descendant of this cluster. Furthermore, the results generated by this rule will be linked to this cluster.
Customer Cluster - The customer grouping to which this rule applies.

As your business’s pricing model changes, so the Rules within CloudBilling need to change too. Many of these changes will be date-sensitive (such as new pricing plans becoming available, discounts applicable to a particular month, or new tax laws coming into effect). To cater for this, CloudBilling supports the notion of Rule Validity. Very simply, you are able to specify when a rule is valid from, and to. Leaving these fields blank (which is the default) means that the rule is always available.

If you do wish to specify validity, you are able to choose a specific date and time for the “From” and/or the “To”.

Rounding

Value and Cost rounding can be specified here. The two work identically, and each consist of the following properties and principles:

Rounding Type
- None (default) - no extra rounding is applied.
- Nearest - standard rounding, to the nearest number. Thus, 2.4 would round to 2, while 2.5 would round to 3.
- Down - away from positive infinity. E.g. 4.76 rounded down to the next integer would be 4.00.
- Up - away from negative infinity. E.g. 2.31 rounded up to the next integer would be 3.00.
- Bankers - similar to “Nearest”, except round to the nearest even number. Thus, 2.5 rounds to 2, while 3.5 rounds to 4.
To (optional) (“to nearest…”) - this is a numeric representation of what level of precision you require from your rounding. Some examples:
- 0.01 - values will be rounded to the nearest cent. Often used for invoice Grand Totals, for VAT, and particularly important for any calculations that may be governed by rounding standards dictated by relevant Fiscal Authorities.
- 0.00001 - values are rounded to 5 decimal places
- 1.0 - values are rounded to the nearest whole unit.
- 0.05 - values are rounded to the nearest 5 cents. (E.g. $2.54 would become $2.55)

Pro Rata

Charge Per - in essence, this property describes how to “divide” up a purchase (that has some sort of “time span” to it, defined by its Purchase date and End date). The calculation engine uses this information to calculate the “measured quantity” of a purchase. Some examples are included below.
- None (default). When this rule applies to “one-off” purchases without a “time span” concept, or when you want to charge for usage regardless of the length of time.
- Second - Charge per second of the calculated time span of the item.
- Minute- Charge per minute of the calculated time span of the item.
- Hour- Charge per hour of the calculated time span of the item.
- Day- Charge per day of the calculated time span of the item.
- Month- Charge per calendar month of the calculated time span of the item.
- Year - Charge per year of the calculated time span of the item.
- Billing Period - Charge the item by the length of the time span relative to the length of the billing period.
Pro Rata - in real-world usage, time-spans of usage seldom fit neatly into the charging period you have chosen. The Pro Rata options allow you to specify how to handle partial usage. To this end, you are able to specify the type of rounding to use, both for the start of the usage, and the end of the usage. To explain in more detail, we will use the example of charging for a Monthly subscription, where the subscription runs from the 10th of March to the 16th of May.
- Start
  - None (default) - no rounding is used. The customer will be charged roughly 2/3rds of March.
  - Nearest - the customer has had the subscription for the majority of March, and is therefore charged the full month
  - Down - subscription start date is rounded down, which means to the beginning of March. Customer is therefore charged for the full month.
  - Up - subscription start date is rounded up, which means the very end of March. Customer is therefore not charged for March at all.
- End
  - None (default) - no rounding is used. The customer will be charged roughly half of May.
  - Nearest - the customer has had the subscription for the majority of May (only just!) and is therefore charged for the full month.
  - Down - subscription end date is rounded down, which means to the beginning of May. Customer is therefore not charged for May at all.
  - Up - subscription end date is rounded up, which means the very end of May. Customer is therefore charged for the full month of May.
- Note: In all examples above, the customer would still be charged for the full month of April.

Expressions

In the expressions section, we have grouped both conditions and expressions. Since they are both in the form of an expression. The outcome of the conditions determines whether or not the rule will run, while the value and cost expressions determine the value and cost used when evaluating the rule.

Both conditions and expressions are simple pieces of C# code that can access metadata on the purchase, customer, or from a Custom Table. Conditions must return a boolean. Expressions must return a decimal.

There are two types of condition available:

Rule Condition Expression (optional) - this condition is executed at the beginning of the rule-run and indicates whether the rule should run at all.
Item Condition Expression (optional) - this condition is executed on each instance of the rule running on a source item and indicates whether the rule should run for the current source item or not. This condition, therefore, has access to using the source item metadata as well.

Advanced

The advanced section contains miscellaneous infrequently changed settings.

Show in price plan - Whether to highlight the rule in the Customer Cockpit
Result is final - If enabled, calculation will stop for items after this rule.
Simple Summing - (Only present for Sum) Allows an aggregating rule to perform pro rata calculation, instead of using the pro rata coming in from previous rules.
Override Rule - Can be set to a specific rule. If set, the overridden rule will not be executed for an item if this rule is executed for that item.
Output to Invoice - Whether or not to output the results generated by the rule.
Save Source ProductCluster as Key - If specified, the product cluster of the incoming item will be stored as text metadata on the result under the specified key.
Copy Meta Data - How to copy metadata from the input items to the output item(s),
- None - Don’t copy any metadata to the result.
- Group Only - Only copy metadata that this rule groups on (see Sum and Group Price).
- Optimistic - Try to copy as much metadata as possible. The only metadata that will not be copied are keys for which the input has conflicts. For example, one item has a value of 1 for a certain key and another item has a value of 2 for the same key.
- Custom - Allows you to specify which keys should be copied to the result.

Adjust Rules

The Adjust Percentage and Adjust Fixed rules both have two outcomes:

The new (adjusted) result
The adjustment itself

For example, applying 21% VAT to a result of value 100 will lead to a new result of 121 and an adjustment result of 21. By default, only the new result will be generated. If you want to have the adjustment result as well, you can check the “Separate Line Item” box. This will also allow you to specify Billing Output Tags for the adjustment result.

Sum

A sum rule has the following additional properties:

Group By - Whether to create separate sum results per group of items. The grouping can be made on a few different criteria:
- None - Don’t group, generate a single result
- PurchaseDate - Group on the purchase date. This setting allows you to specify which “unit” of the date should be used: Hour, Day, Week, Month, or Year.
- SourceProduct - Group on the incoming item’s product cluster.
- Metadata - Group on the value of a piece of metadata. Allows you to specify the metadata key to use. If date metadata is selected you have the same options as for purchase date to group on.
Quantity Aggregation - How to aggregate. The name of the rule is sum, but this setting allows you to make it generate either a sum, a minimum, a maximum, or an average.
Max # source items - Allows you to specify that the rule should create smaller groups of at most the specified number of items. The rule will always create some smaller groups and this is normally not a setting you should worry about.
Output intermediate results - Whether or not to output the intermediate results generated by the smaller groups discussed in the previous option.
Rollup intermediate results - Whether to create a final result aggregating all the intermediate results discussed in the previous options.

Group Price

The Group Price rule has mainly the same options as the sum rule.

In addition, it has 2 extra options:

Value Type - Whether the value specified under General should be used as a Total group price, or as a unit price. In the former case, every group will be given the specified value. In the latter case, every group will get a value equal to its quantity multiplied by the specified value.
Cost Value Type - Works the same as the Value Type, but applied to the cost property of the result.

Ladder

The ladder rule has some additional options as well as the definition of the ladder:

Step Type
- Segmented - All items are priced the same, the values used depend on the tier the total quantity falls in.
- Staggered - Items are priced depending on the tier they fall into. For example, the first 10 items are charged at a rate of 1, the next 10 at a rate of 0.8, etc.
Price Type
- Group Price - The value and cost for the step are applied to the entire group. In the screenshot, this would lead to a result of 1, whether there are 2, 3, or 10 items.
- Unit Price - Each item is priced individually. In the screenshot this would lead to 2 items costing 2, 3 costing 3, and 10 costing 10.
Steps - The actual ladder definition, steps consist of
- From (exclusive) - The start of the ladder step
- To (inclusive) - The end of the ladder step
- Value - The value to apply for this step
- Cost - The cost to apply for this step
- Value Expression - The expression to use to determine the value to use for this step. See Expressions.
- Cost Expression - The expression to use to determine the cost to use for this step. See Expressions.

Bundle

To manage usage purchases that may work off purchased customer Bundles, and apply the relevant rates, a special type of price is rule is made available, called the Bundle Rule.

The bundle rule works by connecting purchases from a branch of the Product Cluster tree with certain Bundle Types, identified by a key. Using this information, the system finds any active Customer Bundles that may be relevant, and assigns the usage to those bundles, if possible. During this, the results will be generated indicating the price (based on whether a suitable bundle could be found, and whether (and how much of) the usage could “fit” into the bundles.

The following properties help define this behaviour, according to your needs:

Bundle Metadata Key - certain Customer Bundles may have a GroupName specified (this is optional), which allows more control over which usage goes into which bundles. If usage needs to apply to a Bundle with a certain GroupName, then that information needs to appear in the purchase’s string Metadata. The Bundle Metadata Key property indicates where in the metadata to find this. This property is optional.
Out of Bundle Rate (optional - use value or expression) - when a Customer Bundle is found, but there is no remaining capacity for it, it is possible to specify the “out of bundle” rate to apply to the result’s value (this works as a Unit Price rule).
- Note: in this situation, the result is “split” into an “InBundle” result and a separate “OutBundle” result.
Out of Bundle Rate Expression (optional - use value or expression) - same as above, but making use of an Expression rather than a discrete value.
Out of Bundle Cost (optional - use value or expression) - when a Customer Bundle is found, but there is no remaining capacity for it, it is possible to specify the “out of bundle” rate to apply to the result’s cost value (this works as a Unit Price rule).
Out of Bundle Cost Expression (optional - use value or expression) - same as above, but making use of an Expression rather than a discrete cost value.
Limit to BundleTypes (optional). If necessary, you can limit this rule to only work with certain Bundle Types. If left blank, there is no limitation.
- This field uses an autocomplete: start typing the name of a known Bundle Type. Click the button to include it in the available types.
Ignore Out Of Bundle (default: no) - If this option is selected the system will generate a result with the remaining item qty and appropriate cost and value amounts (based on original rates, but adjusted for quantity differences) for any usage or any items that fall outside of an existing bundle (i.e. the Bundle exists, but has no remaining capacity).

Click here to learn more about the Bundle concept.

Click here to learn more about managing Bundle Types.