Create a payout run

Pay many recipients from one internal account in one request. Grid validates every row before it stores the run and answers with the run and the rows it rejected. The accepted rows are then paid in the background, each through its own quote, so each emits the usual OUTGOING_PAYMENT.* webhooks. A PAYOUT_RUN.* webhook reports the run when no row is left to pay.

Funding: the source must be an open INTERNAL_FIAT or INTERNAL_CRYPTO account of the platform or of one of its customers.

Validation: a rejected row is returned with its failureCode and failureReason and stored as FAILED. The run pays the accepted rows unless allOrNothing is set, in which case any rejection fails the run and skips every row. Every rule is enforced again when a row is paid, so a row can still fail then, for example on insufficient funds.

Rows to a contact: a row addressed to a phone number or email is accepted and held as PENDING_CLAIM. Grid does not pay it.

Rows to a Grid customer: a GRID_CUSTOMER row pays an internal account on the platform, under the rules of a quote between internal accounts.

Requires an API token with the UMA_TRANSACT permission.

POST /payout-runs

Create a payout run

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/payout-runs \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "rows": [
    {
      "clientRowId": "contractor-0042",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "description": "October invoice"
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "allOrNothing": false
}
'

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",
  "rejectedRows": [
    {
      "id": "PayoutRunRow:019542f5-b3e7-1d02-0000-000000000002",
      "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
      "clientRowId": "contractor-0042",
      "rowIndex": 41,
      "state": "PENDING",
      "lockedCurrencySide": "SENDING",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "createdAt": "2026-11-04T22:00:00Z",
      "updatedAt": "2026-11-05T02:14:00Z",
      "description": "October invoice",
      "purposeOfPayment": "GIFT",
      "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
      "claimablePayoutId": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000007",
      "failureCode": "INSUFFICIENT_FUNDS",
      "failureReason": "Insufficient balance on the source account."
    }
  ],
  "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>

Headers

Idempotency-Key · string · required

Unique identifier for this run. A retry with the same key and body returns the stored run; the same key with a different body is rejected.

Maximum string length: 255

Example:

"payroll-2026-11-04"

Body

application/json

source · object · required

Show child attributes

rows · object[] · required

Required array length: 1 - 1000 elements

Show child attributes

scheduledAt · string<date-time>

When to start paying the rows. Omit it, or give a time in the past, to start as soon as the run is created.

Example:

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

allOrNothing · boolean · default: false

When true, a single rejected row fails the run and no row is paid.

Response

200

application/json

The run this Idempotency-Key already created

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"

rejectedRows · object[] · required

The rows Grid rejected at validation, in submission order. Empty when every row was accepted.

Show child attributes

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"