Preview a settlement rule

What a rule, or a draft of one, would pay on a payment of amount, and which of the customer’s recent payments it would have fired on. Nothing is created or paid.

splits lists the rule’s rows in order, each with what it would send, computed exactly as an execution computes it: a percentage rounds down, and the REMAINDER share takes what the others leave. A share of 0 is not sent. ownerKeeps is what stays with the customer. When the fixed and percentage shares add up to more than amount, nothing would be paid, every row’s amount is 0 and skipReason is AMOUNT_BELOW_RULE. Fees are not estimated: each share is sent by its own quote, whose fees come off the share.

recentMatches are the customer’s completed bank and chain deposits from the last 30 days that the rule’s currency and match select, newest first, at most 20, whatever the customer’s other rules would have done with them. Grid looks at the customer’s latest 200 such deposits. Use them to spot a pattern that selects payments it should not.

Give either settlementRuleId or draft.

POST /settlement-rules/preview

Preview a settlement rule

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/settlement-rules/preview \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "amount": 1000000,
  "settlementRuleId": "SettlementRule:019542f5-b3e7-1d02-0000-000000000001"
}
'

200

{
  "currency": "USD",
  "amount": 1000000,
  "splits": [
    {
      "position": 0,
      "share": {
        "type": "PERCENT",
        "basisPoints": 4000,
        "amount": 50000
      },
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "amount": 400000
    }
  ],
  "ownerKeeps": 450000,
  "recentMatches": [
    {
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
      "amount": 1000000,
      "currency": "USD",
      "completedAt": "2026-11-06T18:00:00Z",
      "counterpartyName": "GLOSSIER INC"
    }
  ],
  "skipReason": "RULE_PAUSED"
}

Authorizations

Authorization · string · header · required

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

Body

application/json

customerId · string · required

The customer whose payments the rule splits.

Example:

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

amount · integer<int64> · required

A payment to split, in the smallest unit of the rule's currency.

Required range: 1 <= x <= 9000000000000000

Example:

1000000

settlementRuleId · string

A rule of the customer to preview. Set this or draft.

Example:

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

draft · object

A rule as it would be created. Only the fields that decide what it pays and what it matches are needed; a priority is not.

Show child attributes

Response

200

application/json

The preview

currency · string · required

Example:

"USD"

amount · integer<int64> · required

The payment previewed.

Example:

1000000

splits · object[] · required

Every row of the rule, in row order.

Show child attributes

ownerKeeps · integer<int64> · required

What stays with the customer.

Example:

450000

recentMatches · object[] · required

Show child attributes

skipReason · enum<string>

Why an execution paid nothing.

Reason	Description
RULE_PAUSED	The rule was paused before the execution fired.
INCOMING_PAYMENT_RETURNED	The payment was returned before the execution fired.
AMOUNT_BELOW_RULE	The payment was smaller than the fixed and percentage shares together.
LIMIT_EXCEEDED	Paying it would have gone over one of the rule's limits.
CANCELLED	The execution was cancelled, or the rule deleted, while it was held.
CREATOR_REVOKED	The API token or agent that created the rule can no longer send payments. The rule is paused.
AGENT_PAUSED	The agent that created the rule is paused. The rule stays active, and pays the next payment once the agent is resumed.

Available options: RULE_PAUSED, INCOMING_PAYMENT_RETURNED, AMOUNT_BELOW_RULE, LIMIT_EXCEEDED, CANCELLED, CREATOR_REVOKED, AGENT_PAUSED