Create a settlement rule

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

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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}
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/settlement-rules', 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  \"name\": \"Glossier deal\",\n  \"currency\": \"USD\",\n  \"match\": [\n    {\n      \"creditedAccountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n      \"ruleBasedAccountId\": \"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001\",\n      \"counterpartyName\": {\n        \"prefix\": \"GLOSSIER\",\n        \"contains\": \"glossier inc\"\n      },\n      \"receivedAtWalletAddress\": \"spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu\",\n      \"rail\": \"ACH\"\n    }\n  ],\n  \"splits\": [\n    {\n      \"share\": {\n        \"basisPoints\": 4000,\n        \"amount\": 50000\n      },\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      }\n    }\n  ],\n  \"priority\": 1,\n  \"holdSeconds\": 0,\n  \"achHoldSeconds\": 86400,\n  \"limits\": {\n    \"maxAmountPerExecution\": 1000000,\n    \"maxAmountPerDay\": 5000000\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/settlement-rules")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

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

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

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

Settlement Rules

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

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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}
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/settlement-rules', 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  \"name\": \"Glossier deal\",\n  \"currency\": \"USD\",\n  \"match\": [\n    {\n      \"creditedAccountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n      \"ruleBasedAccountId\": \"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001\",\n      \"counterpartyName\": {\n        \"prefix\": \"GLOSSIER\",\n        \"contains\": \"glossier inc\"\n      },\n      \"receivedAtWalletAddress\": \"spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu\",\n      \"rail\": \"ACH\"\n    }\n  ],\n  \"splits\": [\n    {\n      \"share\": {\n        \"basisPoints\": 4000,\n        \"amount\": 50000\n      },\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      }\n    }\n  ],\n  \"priority\": 1,\n  \"holdSeconds\": 0,\n  \"achHoldSeconds\": 86400,\n  \"limits\": {\n    \"maxAmountPerExecution\": 1000000,\n    \"maxAmountPerDay\": 5000000\n  }\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/settlement-rules")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

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

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

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "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>

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

The rule this Idempotency-Key already created

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"

Using the API

API documentation

Create a settlement rule

Authorizations

Headers

Body

Response