Create a settlement rule

A standing instruction on a customer’s incoming payments. When a payment into one of the customer’s internal accounts completes and matches the rule, Grid splits it by the rule’s shares and pays each share from the account the payment credited, through a payout run. Each share sends the usual OUTGOING_PAYMENT.* webhooks.

Matching: a payment matches when it is in the rule’s currency and any selector in match matches it. A customer’s rules are tried in ascending priority, which is unique among its rules that are not DELETED. The first ACTIVE rule that matches wins, so a payment pays out under at most one rule.

Shares: a PERCENT share is the payment times basisPoints over 10,000, rounded down. A FIXED share is amount. A REMAINDER share is what every other share leaves, wherever its row is; there is at most one. Without one, the customer keeps the rest. Shares are paid, and listed, in row order. The percentages add up to at most 10,000, and to less than 10,000 with a REMAINDER share. When a payment is smaller than its fixed and percentage shares together, nothing is paid.

Destinations: the payout run row destinations. An ACTIVE external account of the platform or of one of its customers. A contact, held for a claim as on a payout run. An internal account of the platform (GRID_CUSTOMER), paid as a transfer between internal accounts under the rules of a quote between them.

Limits: a customer has at most 50 rules that are not DELETED, and a rule has at most 20 shares.

Requires an API token with the UMA_TRANSACT permission. The rule’s shares are paid as that token. Once the token is deleted, expires or loses the permission, the rule pays nothing more and is paused.

POST /settlement-rules

Create a settlement rule

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/settlement-rules \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Glossier deal",
  "currency": "USD",
  "match": [
    {
      "creditedAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "ruleBasedAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001",
      "counterpartyName": {
        "prefix": "GLOSSIER",
        "contains": "glossier inc"
      },
      "receivedAtWalletAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "rail": "ACH"
    }
  ],
  "splits": [
    {
      "share": {
        "basisPoints": 4000,
        "amount": 50000
      },
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      }
    }
  ],
  "priority": 1,
  "holdSeconds": 0,
  "achHoldSeconds": 86400,
  "limits": {
    "maxAmountPerExecution": 1000000,
    "maxAmountPerDay": 5000000
  }
}
'

200

{
  "id": "SettlementRule:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Glossier deal",
  "status": "PENDING_APPROVAL",
  "priority": 1,
  "currency": "USD",
  "match": [
    {
      "creditedAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "ruleBasedAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001",
      "counterpartyName": {
        "prefix": "GLOSSIER",
        "contains": "glossier inc"
      },
      "receivedAtWalletAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "rail": "ACH"
    }
  ],
  "splits": [
    {
      "share": {
        "type": "PERCENT",
        "basisPoints": 4000,
        "amount": 50000
      },
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "position": 0
    }
  ],
  "holdSeconds": 0,
  "achHoldSeconds": 86400,
  "limits": {
    "maxAmountPerExecution": 1000000,
    "maxAmountPerDay": 5000000
  },
  "createdAt": "2026-11-06T18:00:00Z",
  "updatedAt": "2026-11-06T18:00:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "pendingChangeActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000098"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Headers

Idempotency-Key · string · required

Unique identifier for this rule. A retry with the same key and body returns the stored rule; the same key with a different body is rejected.

Maximum string length: 255

Example:

"glossier-split"

Body

application/json

customerId · string · required

The customer whose incoming payments the rule splits.

Example:

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

name · string · required

What the platform calls the rule. It is the description of each payment the rule sends.

Required string length: 1 - 255

Example:

"Glossier deal"

currency · string · required

ISO 4217 code of the payments the rule splits. A payment in another currency never matches.

Example:

"USD"

match · object[] · required

A payment matches when any selector matches it. [{}] matches every payment in the rule's currency.

Required array length: 1 - 20 elements

Show child attributes

splits · object[] · required

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

Minimum array length: 1

Show child attributes

priority · integer<int32>

Rules are tried in ascending priority. Unique among the customer's rules that are not DELETED. Omit it to try the rule after the customer's others, at one more than their highest priority, or 1 when the customer has none.

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. An ACH payment can be returned after it completes; a return that arrives while the execution is held skips 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.

Show child attributes

Response

200

application/json

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.

Status	Description
PENDING_APPROVAL	Proposed by an agent beyond its policy, waiting for the customer's approval. It fires on nothing.
ACTIVE	Fires on the payments it matches.
PAUSED	Fires on nothing. A payment it would have matched is tried against the customer's next rule.
DELETED	Deleted. It fires on nothing and cannot be changed.

Available options: PENDING_APPROVAL, ACTIVE, PAUSED, DELETED

priority · integer<int32> · required

Example:

1

currency · string · required

Example:

"USD"

match · object[] · required

Show child attributes

splits · object[] · required

Show child attributes

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.

Show child attributes

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"