Charge-Item Control

ChargeItemExtractor.Control is an optional key-value map that the extractor copies onto every charge item it produces. The runtime reads the map to decide how a charge item behaves after rating: whether the item enters the customer money path at all, which funding source it must use, and so on.

{
  "name": "total-tokens-rollup",
  "metric": "total_tokens",
  "type": "number",
  "unit": "token",
  "quantity_expr": "dec_add(dec_add(dec(items['input_tokens']['quantity']), dec(items['output_tokens']['quantity'])), dec(items['cached_tokens']['quantity']))",
  "amount_expr": "dec_add(dec_add(dec(items['input_tokens']['amount']), dec(items['output_tokens']['amount'])), dec(items['cached_tokens']['amount']))",
  "currency": "USD",
  "control": {
    "analytics_only": "true",
    "allow_voucher": "false"
  }
}

The shape is always map[string]string. The string value is what the runtime compares against, so the keys are quoted in the JSON. A real boolean is rejected by the rule set validator.

Recognized keys

The runtime currently recognizes two keys. Each is documented on its own page; this overview is the entry point.

Key	What it controls	Default	Page
analytics_only	Whether the charge item enters the customer money path.	false — the item is rated and debited normally.	Analytics-Only
allow_voucher	Funding source for a still-debited item. When "false", the debit must be paid with cash and cannot consume voucher grants.	true — voucher is allowed.	Allow Voucher

Unknown keys are stored on the charge item for audit but the runtime does not act on them. They are not an error, so a forward-compatible key written by a newer extractor does not break an older runtime.

How the keys interact

The two keys are independent dimensions, not a stack of overrides. The runtime resolves them in this order:

1. If control.analytics_only is "true", the item skips the entire money path. allow_voucher is then irrelevant because no debit is produced.
2. Otherwise the item is rated normally. If control.allow_voucher is "false", the debit must be paid with cash; if it is "true" or absent, voucher can fund the debit when available.

This means:

• An analytics-only item never reaches the wallet. The funding question does not apply.
• A still-debited item can independently choose cash-only or cash-or-voucher funding. allow_voucher=false does not affect the price; it only changes the funding source.

Where the keys are read

The runtime looks at the control map on the final ChargeItem, not on the extractor. The extractor is just the place where you author the keys. When a charge item is produced by a x-billing.items report, the same control block can be attached directly on the reported item and has the same effect.

For the full runtime order, see How Extraction Runs.

Related pages

• Analytics-Only — keep a charge item queryable but skip realtime wallet debit, fund debit, and reconciliation.
• Allow Voucher — force a still-debited item to be paid with cash instead of a voucher grant.
• Create Rules — author charge item extractors with attached pricing.