> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout approvals

> Read pending approval requests and approve, reject, or cancel them.

Approval authority is separate from payout submission. Grant `approvals:read` to read the queue and `approvals:write` to decide requests. Existing keys do not gain these permissions automatically; `payouts:write` alone is insufficient. Write does not imply read.

> [!WARNING]
>
> Approving a request can execute a payout. Grant `approvals:write` only to integrations authorized to make that decision.

## Read requests

| Method and path | Result |
| - | - |
| `GET /sdk/v1/payout-approvals` | Paginated queue/history |
| `GET /sdk/v1/payout-approvals/:id` | One agency-owned approval |
| `GET /sdk/v1/payout-approvals/pending-count` | `{ success: true, count }` |
| `GET /sdk/v1/payout-approvals/selection-preview` | `{ success: true, selection }` for a filtered pending selection |

All require `approvals:read`. List parameters include `page`, `pageSize` (maximum 100), `status` (comma-separated), `excludeStatuses`, `ids` (approval UUIDs), `search`, `sourceType`, `fromDate`, `toDate`, `campaignId`, `submittedBy=me`, `sortBy`, and `sortOrder`. `me` refers to the SDK application that submitted the request. Statuses are `PENDING`, `APPROVING`, `APPROVED`, `REJECTED`, and `CANCELLED`.

## Decide one request

| Method and path | Body |
| - | - |
| `POST /sdk/v1/payout-approvals/:id/approve` | `{}` |
| `POST /sdk/v1/payout-approvals/:id/reject` | `{ "rejectionNote": "Please correct the amount" }` |
| `POST /sdk/v1/payout-approvals/:id/cancel` | `{}` |

All require `approvals:write`. IDs are approval UUIDs. Decisions atomically claim a pending request; an already decided request returns `409`. Cross-agency IDs return `404`. Cancellation is limited to the application that originally submitted the request. Use rejection when the integration is deciding someone else's pending request.

## Bulk decisions

`POST /sdk/v1/payout-approvals/bulk-approve`, `/bulk-reject`, and `/bulk-cancel` accept:

```json theme={null}
{ "approvalIds": ["00000000-0000-4000-8000-000000000001"] }
```

Bulk rejection also accepts `rejectionNote`. Inspect each row of the result: a successful HTTP response can contain individual failures. Bulk cancellation preserves the original-submitter restriction.

For bulk approval, use a stable `x-idempotency-key` when retrying. To approve a filtered selection, first call `selection-preview`, then send the returned IDs with `selectionFingerprint` and `selectionFilters`; stale selections are rejected by the existing approval workflow. Read the queue after any uncertain outcome before submitting a fresh decision.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.