Allow Voucher Flag

Use control.allow_voucher when a charge item must be settled in cash, not from a voucher grant. The flag is the funding source side of the control block. The runtime reads it after rating, while it is choosing which wallet should fund the debit.

The value must be the string "true" or "false". Use "false" to force cash-only funding; the absence of the key is equivalent to "true" (voucher allowed).

{
  "name": "setup-fee",
  "metric": "setup_fee",
  "type": "number",
  "unit": "event",
  "quantity_expr": "dec('1')",
  "currency": "USD",
  "unit_price_expr": "dec('49')",
  "amount_expr": "dec_mul(dec(item['quantity']), dec(item['unit_price']))",
  "control": { "allow_voucher": "false" }
}

When to use it

A cash-only item makes sense when the price should not be subsidized by a marketing voucher or a sign-up credit. Common cases include:

• One-time setup or onboarding fees. These usually cannot be paid with a sign-up voucher grant.
• Hardware, shipping, or tax-line items. The supplier cost cannot be netted against a marketing voucher.
• Refund reversals or clawbacks. They should restore cash balance, not increase the voucher pool.
• Compliance or regulated line items. Some regulators require the source of funds to be identifiable.

If you want the price to come out of a specific grant, prefer a dedicated metric and a usage-control rule that targets that metric. allow_voucher only governs “cash vs voucher”, not which specific voucher grant.

How allow_voucher differs from analytics_only

allow_voucher and analytics_only are independent keys on the same control block. They answer different questions:

• allow_voucher="false" still produces a debit; it just forces the funding source to cash. The item is queryable, rated, and debited.
• analytics_only="true" skips the entire money path. No debit, no funding source, no reconciliation.

When both keys are present, analytics_only wins because the runtime exits the money path before the funding question is asked. See the Charge-Item Control overview for the resolution order.

Default behavior

When control is omitted, or when the key is absent, voucher is allowed. This matches the historical behavior of the rating pipeline: a rated item is debited against the billing account’s available voucher grants first, and only the uncovered portion is paid with cash. Set allow_voucher="false" to opt out of voucher funding for a specific item.

The default applies even when other control keys are present. An item with control.analytics_only="true" and no allow_voucher is still analytics-only; the absent allow_voucher is just irrelevant.

Failure mode

A cash-only item that the account cannot pay in full still fails the same way as a voucher-funded item would: the runtime records the failure and emits the configured failure signal. allow_voucher does not retry, escalate, or block the rating pipeline. It only changes which wallet is consulted first.

If you need a soft-fail that falls back to voucher when cash is empty, do not use allow_voucher. Write two charge items: one with allow_voucher="false" and one without, and let the rating pipeline pick the one the account can fund.

Related pages

• Charge-Item Control — overview of the control block and how keys interact.
• Analytics-Only — the “should this item be debited at all” side of the same block.
• Create Rules — how to define charge_item_extractors and attach pricing.