Tiering conditions

Tiering conditions filter which usage events add to a product item’s tiering metric, a running total that a top-tiered pricing item config uses to pick a price band.

How it works

• The tiering metric is a separate SUM usage metric on the product item. Bands are picked based on it, not on the metric you’re billing.
• Tiering conditions filter that metric’s events.
• Only matched events count toward the running total.
• The total decides the band.
• The band decides the price for the item’s billed usage.

Example

Tiering metric: transaction value, filtered to card_region = EU. Bands:

Three transactions come in:

The total is now $11,000, past the $10,000 bound, so band 2 applies: every request is now billed at $0.03.

When tiering conditions are available

• The product item needs a tiering metric. It must be a SUM-type usage metric, set separately from the item’s regular metric. Without one, tiering conditions have nothing to filter and are inert.
• The pricing item config’s pricing type needs to be TOP_TIERED. It’s the only pricing type that reads a tiering metric to pick a band. Setting tiering_conditions on any other type has no effect, even through the API.

Structure in the API

The tiering metric is set on the product item, separately from its main metric:

1
{
2
  "usage_based": {
3
    "meter_value_calculation_id": "mvc_requests",
4
    "tiering_meter_value_calculation_id": "mvc_eu_transaction_value"
5
  }
6
}

Tiering conditions live on the pricing item config, as an expression tree over meter properties. Those properties have to belong to the meter behind mvc_eu_transaction_value (the tiering metric set above), since that’s the meter whose events get matched — here, card_region is a property on that same meter:

1
{
2
  "details": {
3
    "pricing_type": "TOP_TIERED",
4
    "bands": [
5
      {
6
        "tier_top_bound": { "amount": { "quantity": "10000", "currency": "USD" } },
7
        "amount": { "quantity": "0.05", "currency": "USD" }
8
      },
9
      {
10
        "amount": { "quantity": "0.03", "currency": "USD" }
11
      }
12
    ]
13
  },
14
  "tiering_conditions": {
15
    "name": "EU only",
16
    "expression": {
17
      "operator": "AND",
18
      "operands": [
19
        {
20
          "meter_property": {
21
            "reference": "card_region",
22
            "comparator": "EQUALS",
23
            "value": "EU"
24
          }
25
        }
26
      ]
27
    }
28
  }
29
}

Working with it in Desk

• On the product item, in the usage-based section, set a Tiering metric separately from the item’s regular metric. Only SUM-type usage metrics are selectable; Desk prompts you to create one if none exist.
• On the pricing item config, once the linked product item has a tiering metric and the pricing type is top-tiered, an Add tiering conditions action appears, scoped to the tiering metric’s own meter properties.
• Removing the tiering metric from the product item, or switching the pricing type away from top-tiered, hides the tiering conditions editor and clears any tiering conditions already set on that config.

Edge cases

• No tiering metric, tiering conditions set anyway. They’re inert. Desk won’t let you add them without a tiering metric on the product item, but a config that reaches this state through the API simply has its tiering conditions ignored.
• Pricing type isn’t TOP_TIERED. Same result: the API accepts tiering_conditions on any pricing item config, but only TOP_TIERED reads it.
• The tiering metric resets differently than the billed metric. The running total follows the tiering metric’s own reset period, not the billed metric’s. Check both are configured on the same period if they’re meant to move together.