Cancel a payout run

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

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

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}/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/payout-runs/{payoutRunId}/cancel")
  .post(null)
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

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

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

Agent Operations

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

payout-runs

{payoutRunId}

cancel

Cancel a payout run

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

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

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}/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/payout-runs/{payoutRunId}/cancel")
  .post(null)
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

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

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

payoutRunId

string

required

System-generated unique payout run identifier

Response

The cancelled run

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

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"

Using the API

API documentation

Cancel a payout run

Authorizations

Path Parameters

Response