Cancel a held execution

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel")
  .post(null)
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

{
  "id": "SettlementRuleExecution:019542f5-b3e7-1d02-0000-000000000003",
  "settlementRuleId": "SettlementRule:019542f5-b3e7-1d02-0000-000000000001",
  "status": "HELD",
  "incomingTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "creditedAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "incomingAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "incomingCompletedAt": "2026-11-06T18:00:00Z",
  "firesAt": "2026-11-06T18:00:00Z",
  "createdAt": "2026-11-06T18:00:00Z",
  "updatedAt": "2026-11-06T18:00:02Z",
  "skipReason": "RULE_PAUSED",
  "splitAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000005",
  "firstPaymentSentSeconds": 1.8,
  "lastPaymentSentSeconds": 2.6
}

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

POST

agents

settlement-rules

{settlementRuleId}

executions

{executionId}

cancel

Cancel a held execution

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel")
  .post(null)
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

{
  "id": "SettlementRuleExecution:019542f5-b3e7-1d02-0000-000000000003",
  "settlementRuleId": "SettlementRule:019542f5-b3e7-1d02-0000-000000000001",
  "status": "HELD",
  "incomingTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "creditedAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "incomingAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "incomingCompletedAt": "2026-11-06T18:00:00Z",
  "firesAt": "2026-11-06T18:00:00Z",
  "createdAt": "2026-11-06T18:00:00Z",
  "updatedAt": "2026-11-06T18:00:02Z",
  "skipReason": "RULE_PAUSED",
  "splitAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000005",
  "firstPaymentSentSeconds": 1.8,
  "lastPaymentSentSeconds": 2.6
}

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

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Path Parameters

settlementRuleId

string

required

System-generated unique settlement rule identifier

executionId

string

required

System-generated unique settlement rule execution identifier

Response

The cancelled execution

string

required

System-generated unique execution identifier

Example:

"SettlementRuleExecution:019542f5-b3e7-1d02-0000-000000000003"

settlementRuleId

string

required

Example:

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

status

enum<string>

required

What a rule's firing on one payment became.

Status	Description
`HELD`	Waiting out the rule's hold until `firesAt`. It can be cancelled.
`EXECUTING`	Its payout run is paying the shares.
`EXECUTED`	Its payout run finished `COMPLETED` or `PARTIALLY_FAILED`.
`FAILED`	Its payout run finished `FAILED`, or was cancelled. The customer keeps what the run did not pay.
`SKIPPED`	Nothing was paid. See `skipReason`.

Available options:

HELD,

EXECUTING,

EXECUTED,

FAILED,

SKIPPED

incomingTransactionId

string

required

The incoming transaction the rule fired on.

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000004"

creditedAccountId

string

required

The customer's internal account the payment credited, which pays the shares.

Example:

"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

incomingAmount

object

required

The incoming payment, as a CurrencyAmount (amount in the smallest unit, and currency) in the rule's currency.

Show child attributes

incomingCompletedAt

string<date-time>

required

When the incoming payment completed.

Example:

"2026-11-06T18:00:00Z"

firesAt

string<date-time>

required

When a held execution pays out.

Example:

"2026-11-06T18:00:00Z"

createdAt

string<date-time>

required

Example:

"2026-11-06T18:00:00Z"

updatedAt

string<date-time>

required

Example:

"2026-11-06T18:00:02Z"

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

splitAmount

object

What the shares add up to, as a CurrencyAmount (amount in the smallest unit, and currency) in the rule's currency. Set once the execution has fired.

Show child attributes

payoutRunId

string

The payout run that pays the shares. Set once the execution has fired.

Example:

"PayoutRun:019542f5-b3e7-1d02-0000-000000000005"

firstPaymentSentSeconds

number<double>

Seconds from the incoming payment's completion to the first share's payment being sent. Set once the payout run has finished.

Example:

1.8

lastPaymentSentSeconds

number<double>

Seconds from the incoming payment's completion to the last share's payment being sent. Set once the payout run has finished.

Example:

2.6

Using the API

API documentation

Cancel a held execution

Authorizations

Path Parameters

Response