Create Routing Rule
Create a routing rule.
The rule is created as a draft at the end of the evaluation order. Position
it with POST /routing-rules/reorder, then activate it with
PATCH /routing-rules/{rule_id} — a draft rule is never evaluated.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
At least one condition. Use the account default route for catch-all behaviour.
Single route to use. Give this OR route_distribution when outcome is ‘route_to’ — never both, and neither when ‘stop’.
Split matching traffic across two or more routes. Shares must add up to 100. Use route_id instead for a single route — a one-way split is rejected so each rule has exactly one representation.
Response
Evaluation order, 1 = first
How a rule combines its conditions.
The spec offers exactly these two and no nesting. Compound logic that neither expresses is written as several rules pointing at the same route — see the spec’s “subscription tenure” example. That keeps the stored shape flat and the builder UI honest about what it can express.
What happens when a rule matches.
PRIMARY_ONLY is route-less, like STOP: it names no route. But where STOP blocks the attempt entirely (fraud auto-fail, no processor reached), PRIMARY_ONLY lets the attempt run and charges only the PRIMARY processor the caller would have tried first — no fallback to others. It exists for the default dunning rule (“on a dunning retry, do not fall back across processors”). The short “primary_only” token fits the String(20) outcome column, so no migration. The merchant-facing label is “Stop Processor Fallback”.
A rule’s lifecycle.
DRAFT rules are never evaluated — they exist so an operator can build and position a rule before it touches live traffic. The spec’s Flow 2 is explicit that activation is one-way: a rule cannot go back to draft. Only an ACTIVE rule’s logic is frozen, because it is routing live payments; the supported way to change it is deactivate -> edit -> reactivate, and activation re-runs the route checks on the edited rule.
Route ID, when outcome is ‘route_to’ and one route takes all
Weighted route split, when outcome is ‘route_to’ and traffic is shared