Add / Edit a Price Rule


 

Related Items

The Add / Edit a Price Rule screen is composed of many smaller parts, which make up the critical 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 Operator Types.


Operator Types

CloudBilling supports many different types of calculation, represented through Operator Types. The first step when creating a rule is to choose the Operator 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 Operator choice, and hiding those that are irrelevant.


The various sections are listed in the table below. As different sections are visible for different Rule Operators, the table also shows, per Operator, a  for sections that are visible, and a for those that are not.

To navigate this article, the following options are available:

  • To go straight to the detail for any particular section, you can click on the section name or on any of the corresponding green ticks
  • To only show the detail of the sections relevant to a particular Operator type, click on that type in the table below.
  • Each section can be collapsed/expanded (to show or hide the detail of those fields) by clicking on that section's header.
Section Price Adjust Percentage Adjust Fixed Sum Group Price Ladder Min Price Max Price Bundle
Classification
Value & Cost
Rounding
Charge & ProRata
Conditions
Overrides
Validity
Source Product Metadata
Metadata Copy
Result Is Final
Invoice Output
Separate Line Item
Grouping
Billing Output Tags
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.

Top


Classification

Price |  Adjust Percentage |  Adjust Fixed |  Sum  |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle

  • Order (optional, defaults to 0) - The sequence in which Price Rules are run is primarily determined buy 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.
  • Rule Name  - a unique name to identify the rule by.
  • Show in Price Plan? - indicates whether this rule should be included in the Price Plan Highlights of the Customer Cockpit.
  • Product Cluster  - Autocompleter. The product grouping to which this rule applies. This rule will work off source items from this and any descendant clusters, and output results as part of this cluster.
  • Customer Cluster  - Autocompleter. The customer grouping to which this rule applies.

Top


Value & Cost

Price |  Adjust Percentage |  Adjust Fixed |  Sum  |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle

  • Value (optional - use value or expression- 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.
  • Value Expression (optional - use value or expression) - Here you are able to specify an expression (in the form of simple C# code) to create more complex methods of obtaining the unit price. This is particularly useful when the unit price depends on some kind of dynamic information contained on the customer, purchase, or in a Custom Table.
  • Cost Value (optional - use value or expression) - this works the same as the Value property, but is used to define the Cost price to your business.
  • Cost Expression (optional - use value or expression) - this works the same as the Value Expression property, but is used to define the Cost price to your business.

Top


Rounding

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


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.
      • Note that CloudBilling always applies standard rounding to at least 7 decimal places.
    • 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 next integer would be 4.00.
    • Up - away from negative infinity. E.g. 2.31 rounded up to next integer would be 3.00.
    • Bankers - also known as Gaussian rounding or Dutch rounding. Similar to "Nearest", except round to the nearest digit that can be divided by 2. Thus, 2.75 rounds to 2.8, while 2.65 rounds to 2.6.
  • Precision (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 of currency, such as Euro, Dollar, Pound, etc.
    • 0.05 - values are rounded to the nearest 5 cents. (E.g. $2.54 would become $2.55)

Top


Charge & ProRata

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


  • 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 "once 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.
    • YearCharge per year of the calculated time span of the item.
  • ProRata - in real world usage, time-spans of usage seldom fit neatly into the charging period you have chosen. The ProRata 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 March to the 16th May.
    • Start rounding
      • 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 rounding
      • 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 foMay 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.

Top


Conditions

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


Conditions offer a powerful way to direct the calculation engine to make dynamic decisions, at the point of calculation, of whether to apply the rule or not. Conditions are simple pieces of C# code that can access metadata on the purchase, customer, or from a Custom Table, and must always return a "true" or "false" result. There are 2 levels of conditions made available to you:

  • Rule Condition (optional) -  this condition is executed at the beginning of the rule-run, and indicates whether the rule should run at all.
  • Item Condition (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.

Top


Overrides

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


Overrides provide a way to "replace" another rule in your greater pricing model. While figuring out how and when to use this is often very complicated, the usage of this feature is very straightforward. Simple specify the name of the rule (using the autocompleter field) - when the invoice calculation process is started, and the set of rules is loaded, the system will exclude any rule that appears in the "Override" box of another rule.

Rule Overrides are, of course, optional.

Top


Validity

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


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 (including timezone) for the "From" and/or the "To".

Note: when calculating a result where there are 2 valid rules in the same period (such as a price change over in the middle of a purchase's time span), the first price rule (the one valid at the date of Purchase) is used.

Top


Source Product Metadata

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle

Top


Metadata Copy

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


This option lets you specify what kind of copying mechanism to use on your rule, for metadata.

  • None (default) - do not take any metadata from source item/s to the result item/s
  • GroupOnly - on aggregating rules (i.e. Sum and GroupPrice), only copy metadata that has been created due to a GroupBy setting on that rule
  • Optimistic - copy all metadata that is common across items. Metadata that does not exist on *all* source items is ignored
  • Custom - copy only metadata according to user-specified keys. As with Optimistic copies, metadata must exist on all source items.

Top


Result Is Final

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


Selecting the  option means that the result of this rule will not be available for further processing (i.e., as the source item for a subsequent rule). This is by default not selected.

Top


Invoice Output

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


Not all rule calculation results need to appear on a customer invoice. However, if this rule's result is important, then this option should be specified. If it is, you are able to then provide a Label Key, which indicates to the system how to build up a sensible descriptive name for this result.

See more about Invoice Labels (coming soon)

Furthermore, you are able to override the position (the sequence) of this result on the invoice, if you wish to (for example) perform a VAT (Adjust Percentage) calculation before the final Total (Sum) calculation, but want it to appear after the Total on the invoice.

By default, results will not be output to an invoice.

Top


Separate Line Item

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


This option only applies to the Adjust Percentage and Adjust Fixed rules. When performing an adjustment to your invoice values, it is often necessary to include all the information about the adjustment (including the original amount, the adjusted amount, the final total, etc) on the invoice, and in separate results/line items.

To this end, the "Separate Line Item" option is available. With this option selected, the amount the value was adjusted by will now appear as a separate line item. Note that the separate item will automatically be marked as a "Final" item, and not take part in any further calculations. (This is to avoid including the adjusted amount twice in the overall calculation)

It is also possible to specify an Invoice Position and Label Key for this item, separately to the "normal" result.

Lastly, it is also possible to specify different Billing Output Tags for the separate line item result. This works in the same way that normal output tags work: to add a new one, click the  button. This will show a new, empty field, where you can fill in the desired tag name.

To remove it, click the  button.

By default, this option is not selected.

Top


Grouping

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


In normal use, the aggregating rules (the Sum and GroupPrice rules) take a set of source items (such as purchases), perform a calculation on them, and produce a single result. The most common example of this would be using a Sum rule to produce a single "Total" invoice line item from multiple "price" line items.

However, it is sometimes important to be able to create more than one output from a set of source items, based on some common property. To support this, CloudBilling offers the Grouping functionality on these rule types. The following settings are available:

  • Group By - various grouping options are allowed, as follows:
    • None (default) - No grouping will take place
    • PurchaseDate - group on the PurchaseDate of source purchases (or "FromDate" of source results). If this option is chosen, you will need to specify the Group UOM and Anchor date to settings
    • SourceProduct - group on the TagName of the source item's product cluster.
    • Meta: Text - group on the text value found corresponding to the key specified in Metadata Key.
    • Meta: Numbergroup on the numeric value found corresponding to the key specified in Metadata Key.
    • Meta: Dategroup on the data value found corresponding to the key specified in Metadata Key. If this option is chosen, you will need to specify the Group UOM and Anchor date to settings
  • Metadata Key - this property needs to be specified if using one of the Meta... grouping options. It refers to the metadata key to group on.
  • Group UOM - If grouping on PurchaseDate or Meta: Date, then you will need to specify to what level of detail you want to group. Options are:
    • None (default) - no alteration. Grouping occurs on exact dates, i.e. dates must be equal (to the millisecond) to be included in the same group.
    • Hour - groups on dates occurring in the same date and hour (ignoring minutes and seconds etc).
    • Day - groups on dates occurring on the same day (ignoring the time).
    • Week - groups on dates occurring in the same calendar week. If selected, you also need to indicate what is regarded as the first day of the week in your region (defaults to Sunday)
    • Month - groups on dates in the same month and year.
    • Year - groups on year only.
  • Week starts on (default: Sunday) - when grouping by Week, you will need to specify what day is regarded as the first day of the week, in your region.
  • Max # Source Items (optional) - for performance reasons, aggregated results are split into "chunks". When this happens, these "intermediate" results are by default then passed back into the same rule again, to be further "refined" or reduced. If this iterative process is enabled (see Rollup Intermediate Results below), you can choose whether to show or hide the intermediate results, as your needs dictate (see Output Intermediate Results below). The default (and maximum) size of each chunk is 1000, but you are able to further limit the number of source items that can be included in each result, if you wish.
  • Output intermediate results (default: no) - As mentioned above, should you wish to see intermediate results of the iterative aggregation process, select this option. This is generally useful for gaining more insight during testing and fine-tuning of your pricing model.
  • Rollup intermediate results (default: no) - As mentioned, selecting this option ensures that you always end up with only one final result (per grouping, of course), even if there are multiple intermediate results.
    • Note: This option is recommended for normal use.

Top


Billing Output Tags

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


Billing output tags allows additional output tags to be specified for a specific rule. Each of these output tags will be included in the XML invoice generated by CloudBilling. 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 displayed on the PDF invoice. The tags can be imported to other systems also, like a general ledger classification for an accounting system.

To add a new tag, click the  button. This will show a new, empty field, where you can fill in the desired tag name.

To remove a tag, click the corresponding  button.

By default there are no Billing Output Tags included.

Top


Ladder

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  Bundle


CloudBilling supports "Ladder" pricing, which allows pricing for a purchase (or group of similar purchases) to be dependent on the quantity of purchases. Ladder pricing can take many forms, so to cater for these, we provide the following options:

  • Step Type - 2 different behaviours are supported here:
    • Segmented (default) - items will each be charged according to a single price, which is determined by the Qty.
    • Staggered - items are priced in groups according to multiple Qty steps (e.g. first 10 are charged one price, next 10 at the next price, and so on)
  • Price Type
    • UnitPrice (default) - each item will be charged the price, individually.
    • GroupPrice - each step is given a group price (i.e. charged a fixed amount for entire step, even if not fully used), and the items that apply to this step are charged this amount as a group.
  • Steps - the "steps" are where the separate price values are specified per quantity range. See below...
  • Deprecated fields:
    • Rounding
    • Rounding Total

Top


Ladder Steps

​To add a new step, click the  button. Doing so will display a new set of fields, as detailed below.

  • From (optional) - the quantity from which this step starts. This value is exclusive, and if left empty will default to 0.
  • To (optional) - this step will apply to quantities up to and including this amount. If left empty, it is assumed to be "open ended"
  • Value (optional - use value or expression) - the price value (decimal) to assign to this step
  • Expression (optional - use value or expression) - as with normal price rules, an expression can be used in stead of a discrete value.
  • Cost Value (optional - use value or expression) - the cost value (decimal) to assign to this step
  • Cost Expression (optional - use value or expression) - as with normal price rules, an expression can be used in stead of a discrete cost value.

​Once you have filled in the details for the new step, click the   button to apply the changes. The new step will now appear in the Ladder Steps list. To remove a step, click the corresponding  button.

Top


Bundle

Price |  Adjust Percentage |  Adjust Fixed |  Sum |  Group Price |  Ladder |  Min Price |  Max Price |  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 bundle/s.

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 autocompleter: start typing the name of a known Bundle Type. Click the  button to include it in the available types. (It will appear to the right - click on the name to remove it again)
    • For an example, see the screenshot above - one Bundle Type has been added, with the name "SMSBundle".
  • Ignore Out Of Bundle (default: no) - If this option is selected, then any usage or any items that fall outside of an existing bundle (i.e. the Bundle exists, but has no remaining capacity), then a separate result will be created with the remaining item qty and appropriate cost and value amounts (based on original rates, but adjusted for quantity differences) 

Click here to learn more about the Bundle concept.

Click here to learn more about managing Bundle Types.

Top