Skip to navigation

Update Processor Route

View as Markdown

Update a processor route.

Can update name, description, status, position, and the configuration (the processors or routes it lists, its conditions and match mode). A configuration change creates a new route version.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

route_idstringRequired
account_idstringRequired

Request

This endpoint expects an object.
namestring or nullOptional<=255 characters
Route name
descriptionstring or nullOptional
Route description
processorslist of objects or nullOptional

Ordered list of processors. Sending a non-empty list clears routes.

routeslist of objects or nullOptional

Ordered list of route steps. Sending a non-empty list clears processors.

conditionslist of objects or nullOptional

When this route applies. Empty (the default) means always. A route with conditions is what the dashboard calls a routing rule: give it a position to evaluate it in your account’s rule order, or point another route, a checkout session or a payment link at it.

match_modeenum or nullOptional
Whether ALL conditions must match or ANY one of them
Allowed values:
statusenum or nullOptional

Route lifecycle status. An inactive route is skipped by the charge path: a checkout session, a route step or a cascade tier that names it falls back to the next candidate, and it cannot be set as the account default or referenced by an active route. Activating a route re-checks that every route it points at is active. A route cannot be returned to draft. Changing only the status does not create a new route version.

Allowed values:
positioninteger or nullOptional>=1

The route’s place in your account’s evaluation order (1 = evaluated first), or null when it is not evaluated on its own — only reachable by reference from another route, a session, a pin, or as the account default. On create and update, the route is inserted at that position and the others shift down; a value past the end appends. Use POST /processor-routes/reorder to set the whole order at once. Send null to remove the route from the order.

expected_versioninteger or nullOptional

Optional optimistic-concurrency check. When set, the update is refused with 409 unless it matches the route’s current version — the same field this response returns. Lets a client that fetched the route before editing detect a concurrent edit instead of silently overwriting it. Omit to update unconditionally, as before.

typeenum or nullOptional

Not updatable. A route’s type is fixed at creation; sending one is refused with 422 rather than ignored, so a client asking to turn a split into a stop learns the edit did not happen. Create a new route.

Response

Successful Response
idstring
Unique route identifier
namestring
Route name
processorslist of objects

Ordered list of processors (empty when the route lists routes, or is a stop route)

routeslist of objects

Ordered list of route steps (empty when the route lists processors, or is a stop route)

conditionslist of objects

When this route applies. Empty (the default) means always. A route with conditions is what the dashboard calls a routing rule: give it a position to evaluate it in your account’s rule order, or point another route, a checkout session or a payment link at it.

match_modeenum
Whether ALL conditions must match or ANY one of them
Allowed values:
versioninteger
Current route version. Increments on each configuration edit.
statusenum
Route lifecycle status
Allowed values:
typeenum

How the route uses its steps. Defaults to standard_cascade. standard_cascade: try in order, any failure advances. last_successful_first: the processor that last approved the card is tried first; the list is the fallback order (processors only). last_successful_only: charge the processor that last approved the card and stop — no fallback. Takes no steps at all (dynamic per card). failover: exactly two processors; the backup fires only on error or timeout, never on a decline (processors only). weighted: split by percentage; weights must sum to 100. stop: no steps at all — a matching stop route halts the payment before any processor is tried.

created_atdatetime
When the route was created
updated_atdatetime
When the route was last updated
descriptionstring or nullOptional
Route description
positioninteger or nullOptional

The route’s place in your account’s evaluation order (1 = evaluated first), or null when it is not evaluated on its own — only reachable by reference from another route, a session, a pin, or as the account default. On create and update, the route is inserted at that position and the others shift down; a value past the end appends. Use POST /processor-routes/reorder to set the whole order at once.

Errors

422
Unprocessable Entity Error