Update a settlement rule

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/settlement-rules/{settlementRuleId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Glossier deal",
  "priority": 2,
  "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"
      }
    }
  ],
  "holdSeconds": 0,
  "achHoldSeconds": 0,
  "limits": {
    "maxAmountPerExecution": 1000000,
    "maxAmountPerDay": 5000000
  }
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Glossier deal',
    priority: 2,
    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'
        }
      }
    ],
    holdSeconds: 0,
    achHoldSeconds: 0,
    limits: {maxAmountPerExecution: 1000000, maxAmountPerDay: 5000000}
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/settlement-rules/{settlementRuleId}', 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  \"name\": \"Glossier deal\",\n  \"priority\": 2,\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  \"holdSeconds\": 0,\n  \"achHoldSeconds\": 0,\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/{settlementRuleId}")
  .patch(body)
  .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"
}

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

PATCH

settlement-rules

{settlementRuleId}

Update a settlement rule

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/settlement-rules/{settlementRuleId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Glossier deal",
  "priority": 2,
  "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"
      }
    }
  ],
  "holdSeconds": 0,
  "achHoldSeconds": 0,
  "limits": {
    "maxAmountPerExecution": 1000000,
    "maxAmountPerDay": 5000000
  }
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Glossier deal',
    priority: 2,
    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'
        }
      }
    ],
    holdSeconds: 0,
    achHoldSeconds: 0,
    limits: {maxAmountPerExecution: 1000000, maxAmountPerDay: 5000000}
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/settlement-rules/{settlementRuleId}', 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  \"name\": \"Glossier deal\",\n  \"priority\": 2,\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  \"holdSeconds\": 0,\n  \"achHoldSeconds\": 0,\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/{settlementRuleId}")
  .patch(body)
  .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"
}

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

Path Parameters

settlementRuleId

string

required

System-generated unique settlement rule identifier

Body

application/json

The fields to change. A field left out is unchanged.

name

string

Required string length: 1 - 255

Example:

"Glossier deal"

status

enum<string>

ACTIVE or PAUSED.

Available options:

PENDING_APPROVAL,

ACTIVE,

PAUSED,

DELETED

priority

integer<int32>

Required range: 0 <= x <= 2147483647

Example:

2

match

object[]

Required array length: 1 - 20 elements

Show child attributes

splits

object[]

Every share, replacing the current ones. At most 20.

Minimum array length: 1

Show child attributes

holdSeconds

integer

Required range: 0 <= x <= 86400

Example:

0

achHoldSeconds

integer

Required range: 0 <= x <= 86400

Example:

0

limits

object | null

Both limits, replacing the current ones. A limit left out is removed; null removes both.

Show child attributes

Response

The updated rule

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

Update a settlement rule

Authorizations

Path Parameters

Body

Response