Cancel a held execution

Stop a HELD execution of a rule the authenticated agent created before it fires. It becomes SKIPPED with CANCELLED, nothing is paid, and the customer keeps the payment.

Requires the MANAGE_SETTLEMENT_RULES permission.

POST /agents/me/settlement-rules/{settlementRuleId}/executions/{executionId}/cancel

Cancel a held execution

cURL

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

200

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

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

200

application/json

The cancelled execution

id · 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