Nested pricing rules

Pricing rules can be nested, so a rule only applies to events that already matched the rule above it. Nesting keeps large pricing plans readable, and it changes which price the system picks.

Why nest rules

A flat list of pricing rules repeats every shared condition on every row. Once a plan prices on three or four meter properties, that list grows into hundreds of rows that are slow to scan and risky to edit, because a change to one shared condition has to be repeated everywhere it appears.

Nesting states the shared condition once and hangs the variations underneath it. The same pricing, expressed both ways:

Both produce the same prices. The nested version states region = EU once, so retiring that region is one edit instead of three.

How the best match is picked

The system reads the rules from top to bottom and looks for the best match for each event. In the default (volume) matching mode:

• When a rule matches and has a price, the system follows that path.
• If a sub-rule on that path also matches, it is a better match, so its price is the one applied.
• If no sub-rule matches, the parent is the best match and its price is applied.

The best match replaces the prices above it. Levels are not charged next to each other and their prices never add up. A percentage applies to the meter property the price targets, not to the amount the parent rule would have produced, so percentages do not compound down the tree.

Using the nested rules above, and a default price of 3.9% for the product item:

The first event is priced at 0.2%, not at 2.9% (the parent) and not at 3.1% (the two levels added together). Both levels target the same meter property, so both percentages are calculated over the amount ingested with the event.

The negative case is already covered

Because the parent is the best match whenever no sub-rule matches, you do not configure the opposite of a sub-rule. The parent price is what an event falls back to.

These two configurations behave identically:

Spelling out the negative case doubles the number of rules to maintain and gives the second row a price that has to be kept in step with the parent by hand.

When charges should add up

Nesting picks one price. It cannot express a surcharge, where a narrower condition adds to the broader one rather than replacing it.

To charge 2.9% on EU transactions and a further 0.2% when the payment method is a credit card, model the surcharge as its own product item:

1. Keep the original product item priced on the broad condition: region = EU at 2.9%.
2. Add a second product item, for example EU credit card surcharge, with a filter at product item level: region = EU AND payment_method = credit_card.
3. Price that second product item in the plan at 0.2%, with no pricing rule of its own.

An EU credit card event then matches both pricings: 2.9% on the original item and 0.2% on the surcharge item. An EU bank transfer event matches only the first.

Structure in the API

Nesting is expressed on the pricing item config. Each level carries its own conditions.meter_properties and its own price under details, and conditions.configs holds the levels underneath it.

1
{
2
  "conditions": {
3
    "name": "EU",
4
    "meter_properties": [
5
      { "reference": "region", "comparator": "EQUALS", "value": "EU" }
6
    ],
7
    "configs": [
8
      {
9
        "conditions": {
10
          "name": "EU bank transfer",
11
          "meter_properties": [
12
            { "reference": "payment_method", "comparator": "EQUALS", "value": "bank_transfer" }
13
          ]
14
        },
15
        "details": {
16
          "bands": [{ "percentage": "0.2" }]
17
        }
18
      }
19
    ]
20
  },
21
  "details": {
22
    "bands": [{ "percentage": "2.9" }]
23
  }
24
}

A level without configs is a leaf, which is the shape of an ordinary pricing rule. The comparators available at each level are the ones listed under pricing rules.

Working with levels in Desk

• Set a level’s own condition before nesting under it. A level needs at least one meter property condition; Add nested condition only appears once it has one.
• Add nested condition creates a child level. Set the child’s condition and price, then repeat on the child to nest further.
• Give a level a price with Add pricing. A level can hold both a price and nested children at once; without a price, it relies entirely on its children matching, and falls through to the product item’s default price if none of them do either.
• Duplicate a level from its menu to start a sibling from an existing condition and price, then adjust the copy.
• Delete a level from its menu. This removes everything nested underneath it, not just that one row.

Edge cases

• Give a parent its own price. The system follows a path when the rule it matched has a price. A parent used only for grouping leaves events that match it, but none of its sub-rules, without a price at that level.
• Overlapping sub-rules are resolved in order. If two sub-rules of the same parent can match one event, the first matching sub-rule in the configured order applies. Order the narrower condition first.
• Depth is not the same as breadth. Two conditions that must both hold for one event belong on the same level, where they are combined with AND. Nesting expresses “and then, more specifically”, not a second independent match.