Create a price rule
A price rule works out the price of a usage event. cost_plus prices the cost of the usage from the cost catalog plus a markup or a target margin. table looks the price up by dimension values, and formula evaluates an expression. Any of them can have a floor and a cap. A plan rate uses a rule through price_rule. In live mode an agent’s write is refused with 403 and proposal_required: put the same object in a config proposal. People change live configuration in the dashboard.
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Headers
Send true to see what the write would do without doing it. The response is the normal body with dry_run: true, changes (path, before, after), warnings and errors added, and nothing is stored. Validation runs as it would for a real write. The request is kept in request logs, tagged Dry run. When the same change is then made for real, its audit event has dry_run_preceded: true.
Request
Lowercase ISO 4217 code. Must match the currency of the rate cards the rule reads and of the plans that use it: Runledger doesn’t convert between currencies, so a rule that mixes them is a validation error.
cost_plus: the cost of the usage plus a markup or a target margin. table: a price looked up by dimension values. formula: an expression.
The label on invoices. On a change, null clears it.
What cost_plus and formula rules take the cost from. catalog: the cost models and the event’s quantity and properties, the same at check() and track(). run_cost: the costs trace() recorded under the event’s run_id, for pass-through pricing after the work. check() can’t know that cost yet, so it prices from estimated_usage or, without it, from the observed average.
cost_plus and formula rules on the catalog basis.
cost_plus. The price is the cost times one plus this, as a decimal string: "0.4" is cost plus 40%. Send this or target_margin_percent.
cost_plus. The price is the cost over one minus this, so the margin is this share of the price, as a decimal from 0 to 1. "0.3" is a 30% margin.
table rules.
formula rules. An expression over cost, quantity and numeric event properties written properties.<name>, with +, -, *, /, brackets, min(), max() and ceil(). It returns minor units of currency.
The lowest price for one event, in minor units. The price is raised to it. On a change, null clears it.
The highest price for one event, in minor units. The price is lowered to it. On a change, null clears it.
Prepaid plans. Minor units of currency that one credit is worth, used to turn the price into credits. Defaults to the plan’s top-up price per credit.
What the rule does when a new rate card changes the cost it prices from, whether you added it or Runledger published a new catalog price. hold: it keeps pricing from the versions in force when you last saved it, so the margin moves and a person decides whether to change the price from a later date. follow: the price follows the new card from its effective_from.
Response
cost_plus: the cost of the usage plus a markup or a target margin. table: a price looked up by dimension values. formula: an expression.
What the rule does when a new rate card changes the cost it prices from, whether you added it or Runledger published a new catalog price. hold: it keeps pricing from the versions in force when you last saved it, so the margin moves and a person decides whether to change the price from a later date. follow: the price follows the new card from its effective_from.
What cost_plus and formula rules take the cost from. catalog: the cost models and the event’s quantity and properties, the same at check() and track(). run_cost: the costs trace() recorded under the event’s run_id, for pass-through pricing after the work. check() can’t know that cost yet, so it prices from estimated_usage or, without it, from the observed average.
The rate card versions this version prices from. Under hold, they stay until the rule is saved again.
Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.