Cancel a payout run

Skip every row that has not started. A row whose payment has already started still settles, and its transaction is still reported on the run.

POST /payout-runs/{payoutRunId}/cancel

Cancel a payout run

cURL

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

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",
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

payoutRunId · string · required

System-generated unique payout run identifier

Response

200

application/json

The cancelled run

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"

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"