> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# 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:

| Band | Tiering total  | Price per request |
| :--- | :------------- | :---------------- |
| 1    | up to \$10,000 | \$0.05            |
| 2    | above \$10,000 | \$0.03            |

Three transactions come in:

| Event | Region | Value   | Matched? | Running total |
| :---- | :----- | :------ | :------- | :------------ |
| 1     | EU     | \$6,000 | yes      | \$6,000       |
| 2     | US     | \$9,000 | no       | \$6,000       |
| 3     | EU     | \$5,000 | yes      | \$11,000      |

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:

**`Product item with a tiering metric`**

```json Product item with a tiering metric
{
  "usage_based": {
    "meter_value_calculation_id": "mvc_requests",
    "tiering_meter_value_calculation_id": "mvc_eu_transaction_value"
  }
}
```

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:

**`Pricing item config with tiering conditions`**

```json Pricing item config with tiering conditions
{
  "details": {
    "pricing_type": "TOP_TIERED",
    "bands": [
      {
        "tier_top_bound": { "amount": { "quantity": "10000", "currency": "USD" } },
        "amount": { "quantity": "0.05", "currency": "USD" }
      },
      {
        "amount": { "quantity": "0.03", "currency": "USD" }
      }
    ]
  },
  "tiering_conditions": {
    "name": "EU only",
    "expression": {
      "operator": "AND",
      "operands": [
        {
          "meter_property": {
            "reference": "card_region",
            "comparator": "EQUALS",
            "value": "EU"
          }
        }
      ]
    }
  }
}
```

---

## 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.

---