Cancel a payout run

Cancel everything of the run that has not been sent. A PENDING row becomes SKIPPED with failureCode CANCELLED. A contact row whose claimable payout is still AWAITING_CLAIM has its payout cancelled, which ends its claim link and releases its hold, and becomes SKIPPED with failureCode CANCELLED. PROCESSING and COMPLETED rows, and contact rows already claimed, are left to finish. A run still PENDING_APPROVAL becomes CANCELLED, and its PAYOUT_RUN action fails with AGENT_CANCELLED. A run that has finished is refused with 409.

POST /agents/me/payout-runs/{payoutRunId}/cancel

Cancel a payout run

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}/cancel \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "total": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "rowCount": 12,
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

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

payoutRunId · string · required

System-generated unique payout run identifier

Response

200

application/json

The cancelled run

A payout run an agent created. allOrNothing is always false, and scheduledAt is never set.

id · string · required

System-generated unique payout run identifier

Example:

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

status · enum<string> · required

Status of a payout run.

Status	Description
VALIDATING	Grid is validating the rows. No row is paid yet.
PENDING_APPROVAL	An agent's run waiting for the customer to approve its PAYOUT_RUN action. No row is paid yet. Approving it makes the run PROCESSING; rejecting it, or letting it expire, makes it CANCELLED.
SCHEDULED	Accepted, waiting for scheduledAt.
PROCESSING	Rows are being paid.
COMPLETED	Every accepted row completed or is held for a claim, and none failed.
PARTIALLY_FAILED	At least one row completed or is held for a claim, and at least one failed.
FAILED	No row completed or is held for a claim.
CANCELLED	Cancelled. Rows that had not started are SKIPPED.

Available options: VALIDATING, PENDING_APPROVAL, SCHEDULED, PROCESSING, COMPLETED, PARTIALLY_FAILED, FAILED, CANCELLED

source · object · required

Show child attributes

allOrNothing · boolean · required

Example:

false

rowCounts · object · required

Show child attributes

createdAt · string<date-time> · required

Example:

"2026-11-04T22:00:00Z"

updatedAt · string<date-time> · required

Example:

"2026-11-05T02:14:00Z"

agentId · string · required

The agent that created the run.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

agentActionId · string · required

The run's PAYOUT_RUN agent action, which the customer approves or rejects when the run needs approval.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

total · object · required

The sum of the rows' amounts, in the source account's currency. This is what leaves the wallet if every row is paid.

Show child attributes

rowCount · integer · required

How many rows the run has.

Example:

12

scheduledAt · string<date-time>

When the run starts paying rows, if it was scheduled.

Example:

"2026-11-05T02:00:00Z"

finishedAt · string<date-time>

When the run reached COMPLETED, PARTIALLY_FAILED, FAILED or CANCELLED.

Example:

"2026-11-05T02:14:00Z"