> ## 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.

# Payouts

> Incrementally sync payouts with complete records, removals, and durable cursors.

## GET /sdk/v1/payouts/sync

Sync agency payout settlement state, including provider status changes, withdrawal retries and completed restricted-country refunds. Replace by the stable `id`, not by `payoutId`, which can initially be null.

Requires `X-Application-Id`, `X-Api-Key`, and `payouts:read`.
Follow the [shared syncing workflow](https://api-docs.usegrade.com/syncing/overview.md) for pagination, cursor
storage, retries and removals. Only `cursor` and `limit` are accepted.

```bash theme={null}
curl --get "$BASE_URL/sdk/v1/payouts/sync" \
  -H "X-Application-Id: $APP_ID" \
  -H "X-Api-Key: $API_KEY" \
  --data-urlencode "limit=100"
```

On subsequent requests, add `--data-urlencode "cursor=$SAVED_CURSOR"`.

## Record format

Each item in `data` is a complete replacement with these fields:

```json theme={null}
{
  "id": "123",
  "transactionId": "TX_123",
  "payoutId": "PAYOUT_123",
  "campaignId": "CAMPAIGN_123",
  "creatorEmail": "jordan@example.com",
  "amount": "-120.50",
  "currency": "USD",
  "transactionStatus": "COMPLETED",
  "status": "completed",
  "datePaid": "2026-10-26T10:00:00.000Z",
  "recipientAmount": "118.00",
  "recipientCurrency": "USD",
  "fulfillmentMode": "CREATOR_WALLET_WITHDRAWALS",
  "creatorWithdrawalId": "WITHDRAWAL_123",
  "creatorWithdrawalState": "SUCCEEDED",
  "creatorWithdrawalProvider": "provider",
  "withdrawalCompletedAt": "2026-10-26T10:00:00.000Z",
  "refund": null
}
```

`id` is an opaque stable sync identity for the payout transfer. Use `payoutId`
for existing payout operations when present; do not pass the sync `id` to them.
Campaign-linked and direct/role payouts are included. A completed payout remains
in the feed, so later corrections can still update it.

`status` uses the same settlement rules as the [payout list](https://api-docs.usegrade.com/payouts.md).
`transactionStatus` is the underlying ledger status; it can be completed while
the recipient's external withdrawal is still pending. The latest associated
withdrawal is returned, including a retry after a failure.

`amount` is the signed sender ledger amount in `currency`. `recipientAmount` is
the stored recipient display amount in `recipientCurrency`; either recipient
field can be null. Monetary values are **decimal strings**. Neither field is a
live currency conversion or an inferred final bank receipt. Payout previews,
fee breakdowns and expected-landing estimates remain on existing endpoints.

A completed restricted-country cancellation sets `status: "refunded"` and returns
`refund: { reasonCode: "restricted_country", amountUsd, completedAt }`.
The object describes that specific refund; other cancellation/reversal states
are represented by the settlement and transaction status fields. Internal
provider evidence and errors are excluded.

Moves, deletion of required records, and transfers leaving the public payout
view produce removals. New payout links and changes to existing links, ledger
status, fulfillment mode, withdrawal associations, provider or refund state
produce replacements.


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