Skip to navigation
API ReferenceProviders and paymentsRouting rules

Create a routing rule

Routing rules choose a provider for new checkout sessions and new customers when the customer has no override of their own. They are ordered and the first match wins. Editing rules doesn't move customers who already saved a payment method.

Authentication

AuthorizationBearer

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

Runledger-Dry-RunbooleanOptional

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

This endpoint expects an object.
providerstringRequired
A connected provider's name.
whenobjectOptional
Every condition you send must match. A rule with none matches everything.
positionintegerOptional>=1
Where the rule goes in the order. Defaults to last.

Response

The new rule.
idstring
object"routing_rule"
positioninteger
1 is checked first. The first matching rule wins.
whenobject
Every condition you send must match. A rule with none matches everything.
providerstring
livemodeboolean
created_atdatetime
actorobjectOptional

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.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error