Preview a settlement rule

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    amount: 1000000,
    settlementRuleId: 'SettlementRule:019542f5-b3e7-1d02-0000-000000000001'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/settlement-rules/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"amount\": 1000000,\n  \"settlementRuleId\": \"SettlementRule:019542f5-b3e7-1d02-0000-000000000001\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/settlement-rules/preview")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Settlement Rules

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 --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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    amount: 1000000,
    settlementRuleId: 'SettlementRule:019542f5-b3e7-1d02-0000-000000000001'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/settlement-rules/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"amount\": 1000000,\n  \"settlementRuleId\": \"SettlementRule:019542f5-b3e7-1d02-0000-000000000001\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/settlement-rules/preview")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

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

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 that created the rule can no longer send payments. The rule is paused.

Available options:

RULE_PAUSED,

INCOMING_PAYMENT_RETURNED,

AMOUNT_BELOW_RULE,

LIMIT_EXCEEDED,

CANCELLED,

CREATOR_REVOKED

Using the API

API documentation

Preview a settlement rule

Authorizations

Body

Response