Skip to main content
POST
Create a settlement rule

Authorizations

Authorization
string
header
required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Headers

Idempotency-Key
string
required

A unique identifier for the rule, scoped to the agent. A retry with the same key and body returns the rule the first request created; the same key with a different body is rejected.

Maximum string length: 255
Example:

"<uuid>"

Body

application/json

A settlement rule as an agent proposes it, for the agent's customer.

name
string
required

What the rule is called. It is the description of each payment the rule sends.

Required string length: 1 - 255
Example:

"Glossier deal"

currency
string
required

Code of the payments the rule splits, which is the currency of the Embedded Wallet its selectors name.

Example:

"USDB"

match
object[]
required

A payment matches when any selector matches it. Every selector sets creditedAccountId to the customer's Embedded Wallet.

Required array length: 1 - 20 elements
splits
object[]
required

The shares, in the order they are paid. At most 20.

Minimum array length: 1
priority
integer<int32>

Rules are tried in ascending priority. Unique among the customer's rules that are not DELETED, the platform's included. Omit it to try the rule after the customer's others.

Required range: 0 <= x <= 2147483647
Example:

1

holdSeconds
integer
default:0

How long after a payment completes the rule waits to pay it, for payments on rails other than ACH.

Required range: 0 <= x <= 86400
Example:

0

achHoldSeconds
integer
default:86400

How long after an ACH payment completes the rule waits to pay it.

Required range: 0 <= x <= 86400
Example:

86400

limits
object

Caps on what the rule pays, in the smallest unit of its currency. An execution that would go over a cap is skipped with LIMIT_EXCEEDED, and the customer keeps the payment.

Response

The rule this Idempotency-Key already created

id
string
required

System-generated unique settlement rule identifier

Example:

"SettlementRule:019542f5-b3e7-1d02-0000-000000000001"

customerId
string
required
Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

name
string
required
Example:

"Glossier deal"

status
enum<string>
required

Status of a settlement rule.

Available options:
PENDING_APPROVAL,
ACTIVE,
PAUSED,
DELETED
priority
integer<int32>
required
Example:

1

currency
string
required
Example:

"USD"

match
object[]
required
splits
object[]
required
holdSeconds
integer
required
Example:

0

achHoldSeconds
integer
required
Example:

86400

limits
object
required

Caps on what the rule pays, in the smallest unit of its currency. An execution that would go over a cap is skipped with LIMIT_EXCEEDED, and the customer keeps the payment.

createdAt
string<date-time>
required
Example:

"2026-11-06T18:00:00Z"

updatedAt
string<date-time>
required
Example:

"2026-11-06T18:00:00Z"

agentId
string

The agent that created the rule through the agent API. Absent for a rule created with an API token.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

agentActionId
string

The CREATE_SETTLEMENT_RULE agent action awaiting the customer's approval of the rule. Present while the rule is PENDING_APPROVAL.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

pendingChangeActionId
string

The UPDATE_SETTLEMENT_RULE agent action holding a change to the rule's match, shares or limits until the customer approves it. Present while the change waits; the rule keeps its current terms until then.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000098"