Hold a price change for a price rule
Records that a person chose to hold this catalog price change for one price rule: the rule keeps pricing from the rate card versions it is pinned to, so customer prices stay where they are and your margin moves with the new cost. Nothing else is written. The decision is the audit event catalog.price_change_held, with the catalog price as its resource, so read the decisions on a change with GET /v1/audit_events?resource={catalog_price}. The rule must price from a cost model of yours that follows the price’s catalog model (otherwise 400 with parameter_invalid on price_rule) and be on hold: a rule on follow already reprices from the new card’s date, so it is refused with 409 and invalid_state. To follow instead, change the rule’s on_cost_change; to reprice, change the rule.
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.
Path parameters
The catalog price version ID (catp_...).
Request
The price rule (ID or key) that holds its prices through this change.
Response
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.
dashboard: a person in the dashboard. api: a key. mcp: an agent through the MCP server.
What was done, as object.verb. Includes catalog.price_change_held (a person held a catalog price change, so customer prices stay where they are; resource.id is the price change, catp_...) and auto_top_up.created, auto_top_up.updated and auto_top_up.turned_off. New actions may be added.
true when the same change was dry-run or validated first. The dry run is in request logs, tagged Dry run.
The request behind it, in request logs. Absent when no request is: a change the system makes by itself, such as a dispute decided by default when its window passes.
Present when the change was made by approving a config proposal. actor on the event is who made the request, such as the agent that proposed it, and approved_by is the signed-in person who approved it and when.