API reference
Payout history (paginated)
The account's payout history, newest first — the same rows as the creator's Payouts page, in integer cents.
View as MarkdownUpdated Oct 30, 2026
GET
/api/external/payoutsNewThe account's payout history, newest first — the same rows as the creator's Payouts page, in integer cents.
It lists payouts sent by Dropfans (kind: "payout"), payouts recorded by an admin ("manual") and payout requests not fulfilled yet ("request"). Once a request is paid it is replaced by the payout that fulfilled it (requestId links them). Money in integer cents.
Like the dashboard, payout attempts that never moved money (failed / cancelled) are left out unless you ask for them with status, and a wallet load that was sent back is hidden together with its negative twin unless includeReversed=true (the pair nets to zero).
Keep the filters the same while you follow nextCursor.
Authentication
Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.
An agency's own key can call this for a creator it manages by adding X-Dropfans-Account: <account id> (needs canViewStats). See Agencies.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
since | string | Optional | Only rows created (requests: made) at or after this time. Format: date-time |
until | string | Optional | Only rows created at or before this time. Format: date-time |
status | string | Optional | Comma-separated subset of requested, approved, pending, processing, paid, failed, cancelled, rejected. Default: everything except failed / cancelled payout attempts. |
kind | string | Optional | Comma-separated subset of payout, manual, request. Default: all three. |
includeReversed | boolean | Optional | Also return reversed wallet loads and their negative reversal rows. Default: false |
limit | integer | Optional | Page size. Default: 50Min: 1 Max: 100 |
cursor | string | Optional | nextCursor from the previous page. |
Responses
200A page of rows. Money in cents.
| Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
payouts | Payout[] | Newest first.Show child attributes
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursor | string | null | Pass as cursor for the next page; null on the last page. |
Example response
{
"payouts": [
{
"id": "clxpr0001request",
"kind": "request",
"status": "requested",
"amountCents": 34210,
"currency": "USD",
"side": "creator",
"sides": {
"creatorCents": 34210,
"agencyCents": 0,
"affiliateCents": 0,
"shareCents": 0
},
"method": {
"type": "MASSPAY",
"label": "Payout wallet · SWE"
},
"note": "October",
"failureMessage": null,
"invoiceNumber": null,
"requestId": null,
"payoutId": null,
"createdAt": "2026-10-30T09:12:00.000Z",
"initiatedAt": null,
"paidAt": null,
"failedAt": null,
"reversedAt": null,
"reversalOfId": null
},
{
"id": "clxpo0001payout",
"kind": "payout",
"status": "paid",
"amountCents": 52000,
"currency": "USD",
"side": "combined",
"sides": {
"creatorCents": 40000,
"agencyCents": 12000,
"affiliateCents": 0,
"shareCents": 0
},
"method": {
"type": "PAXUM_P2P",
"label": "Paxum · j***@example.com"
},
"note": null,
"failureMessage": null,
"invoiceNumber": 1042,
"requestId": "clxpr0000request",
"payoutId": null,
"createdAt": "2026-10-15T08:00:00.000Z",
"initiatedAt": "2026-10-15T08:00:05.000Z",
"paidAt": "2026-10-15T08:03:41.000Z",
"failedAt": null,
"reversedAt": null,
"reversalOfId": null
}
],
"nextCursor": null
}Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error":"since must be an ISO date","code":"invalid_since"} | Unparseable `since` (`invalid_until` for `until`). |
| 400 | {"error":"status must be a comma-separated subset of requested,approved,pending,processing,paid,failed,cancelled,rejected","code":"invalid_status"} | Unknown status (`invalid_kind` for an unknown kind). |
| 400 | {"error":"limit must be an integer from 1 to 100","code":"invalid_limit"} | `limit` out of range. |
| 400 | {"error":"Invalid cursor","code":"invalid_cursor"} | The cursor was not one we returned. |
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 400 | {"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"} | `X-Dropfans-Account` is not an account id. |
| 403 | {"error":"This key cannot act for that account.","code":"account_not_managed"} | `X-Dropfans-Account` names an account this key cannot act for: not an agency’s own key, no ACCEPTED management, or the agency or account is suspended, banned or deleted (an unknown id gets the same answer). |
| 403 | {"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canViewStats"} | With `X-Dropfans-Account`: the agency lacks `canViewStats` on that account. |
Rate limiting
Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.
Code samples
curl "https://www.dropfans.io/api/external/payouts?since=2026-01-01T00%3A00%3A00Z&status=paid" \
-H "Authorization: Bearer $DROPFANS_API_KEY"const res = await fetch(`https://www.dropfans.io/api/external/payouts?since=2026-01-01T00%3A00%3A00Z&status=paid`, {
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
},
});
console.log(await res.json());import os
import requests
res = requests.get(
"https://www.dropfans.io/api/external/payouts",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
params={"since": "2026-01-01T00:00:00Z", "status": "paid"},
)
print(res.json())Questions? [email protected]