> ## Documentation Index > Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt > Use this file to discover all available pages before exploring further. # GET /api/external/payouts — Payout history (paginated) > The account's payout history, newest first — the same rows as the creator's Payouts page, in integer cents. - Source: https://www.dropfans.io/developers/reference/list-payouts - Section: API reference - OpenAPI: https://www.dropfans.io/developers/openapi.json The 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 `Authorization: Bearer dpfn_...` — an API key generated in the dashboard (Vault → API Connect). By default the key acts for the one account it belongs to. Missing or invalid keys return 401 `{"error":"Unauthorized","code":"unauthorized"}`. Optional `X-Dropfans-Account: ` — with a verified agency's own key, act for a creator or AI persona the agency manages (ids from GET /api/external/agency/creators); the agency needs `canViewStats` on that account. The response echoes the account acted on in the same header. ## Query parameters | Field | Type | Required | Description | |---|---|---|---| | `since` | string | | Only rows created (requests: made) at or after this time. | | `until` | string | | Only rows created at or before this time. | | `status` | string | | Comma-separated subset of requested, approved, pending, processing, paid, failed, cancelled, rejected. Default: everything except failed / cancelled payout attempts. | | `kind` | string | | Comma-separated subset of payout, manual, request. Default: all three. | | `includeReversed` | boolean | | Also return reversed wallet loads and their negative reversal rows. | | `limit` | integer | | Page size. | | `cursor` | string | | `nextCursor` from the previous page. | ## Responses ### 200 A page of rows. Money in cents. | Field | Type | Required | Description | |---|---|---|---| | `payouts` | Payout[] | yes | Newest first. | | `nextCursor` | string \\| null | | Pass as `cursor` for the next page; null on the last page. | ```json { "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 Per-key fixed windows by tier (Personal 60/min · 5,000/day; approved apps 300/min · 50,000/day; Dropfans-operated integrations exempt). Read the live values from X-RateLimit-Tier, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and their -Day variants; a 429 carries Retry-After and `{"error":"Rate limit exceeded","code":"rate_limited"}`. See [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md). ## Code samples ### curl ```bash curl "https://www.dropfans.io/api/external/payouts?since=2026-01-01T00%3A00%3A00Z&status=paid" \ -H "Authorization: Bearer $DROPFANS_API_KEY" ``` ### Node ```javascript 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()); ``` ### Python ```python 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()) ``` ## OpenAPI ```json { "method": "GET", "path": "/api/external/payouts", "operationId": "listPayouts", "tags": [ "payouts" ], "summary": "Payout history (paginated)", "description": "The account's payout history, newest first — the same rows as the creator's Payouts page, in integer cents.\n\nIt 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**.\n\nLike 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).\n\nKeep the filters the same while you follow `nextCursor`.", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Only rows created (requests: made) at or after this time.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "until", "in": "query", "required": false, "description": "Only rows created at or before this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated subset of requested, approved, pending, processing, paid, failed, cancelled, rejected. Default: everything except failed / cancelled payout attempts.", "schema": { "type": "string" }, "example": "paid" }, { "name": "kind", "in": "query", "required": false, "description": "Comma-separated subset of payout, manual, request. Default: all three.", "schema": { "type": "string" } }, { "name": "includeReversed", "in": "query", "required": false, "description": "Also return reversed wallet loads and their negative reversal rows.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page.", "schema": { "type": "string" } }, { "name": "X-Dropfans-Account", "in": "header", "required": false, "description": "Agencies only. With a verified agency’s own key, the id of a creator or AI persona the agency manages (from GET /api/external/agency/creators): the request then acts as that account, exactly as if it were sent with that account’s own key. Account ids only — usernames are refused (400 invalid_account_header). Checked on every request: the management must be ACCEPTED, nobody may be suspended, banned or deleted (else 403 account_not_managed), and the agency needs the endpoint’s permission on that account (else 403 permission_denied). Omit it to act as the key’s own account.", "schema": { "type": "string", "pattern": "^c[a-z0-9]{20,32}$" }, "example": "cmh4v2q8k0003xy9z7w6v5u4t" } ], "responses": { "200": { "description": "A page of rows. Money in cents.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } }, "X-Dropfans-Account": { "description": "The id of the account this request acted on — the key’s own account, or the managed account named in the X-Dropfans-Account request header. Assert it when acting for several accounts.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the row. Unique across the three kinds — use it with GET /api/external/payouts/{id}.", "example": "clxpo0001payout" }, "kind": { "type": "string", "description": "`payout`: sent by Dropfans (Paxum, MassPay wallet load, or settled by an admin). `manual`: paid outside the platform and recorded by an admin. `request`: a payout request the account made that has not been fulfilled into a payout yet.", "enum": [ "payout", "manual", "request" ] }, "status": { "type": "string", "description": "Requests: `requested` → `approved` → (`processing` for Paxum, from the moment they are made) → `paid`, or `rejected` / `cancelled`. Payouts: `pending` (in a batch, not sent yet) → `processing` (sent) → `paid` or `failed`; `cancelled` when an attempt was dropped. Manual payouts are always `paid`.", "enum": [ "requested", "approved", "pending", "processing", "paid", "failed", "cancelled", "rejected" ] }, "amountCents": { "type": "integer", "description": "Integer **cents**. What is paid out (negative only on a reversal row).", "example": 34210 }, "currency": { "type": "string", "description": "Always \"USD\".", "enum": [ "USD" ] }, "side": { "type": "string", "description": "Which balance it draws from: `creator` (own sales), `agency` (income from managed creators / AI personas), `affiliate` (referral commission), `share` (partner shares of other accounts’ sales), or `combined` (several sides in one transfer — see `sides`).", "example": "creator" }, "sides": { "type": "object", "properties": { "creatorCents": { "type": "integer", "description": "Creator side, cents.", "example": 34210 }, "agencyCents": { "type": "integer", "description": "Agency side, cents.", "example": 0 }, "affiliateCents": { "type": "integer", "description": "Referral commission, cents.", "example": 0 }, "shareCents": { "type": "integer", "description": "Partner shares, cents.", "example": 0 } }, "required": [ "creatorCents", "agencyCents", "affiliateCents", "shareCents" ], "description": "The amount split by side, integer cents. Adds up to `amountCents`." }, "method": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "description": "Provider method type.", "enum": [ "PAXUM_P2P", "MASSPAY", "BANK_SWIFT" ] }, "label": { "type": "string", "description": "Display label — the creator’s nickname, or e.g. \"Paxum · j***@example.com\", \"Payout wallet · SWE\", \"Bank transfer · ••••1234\". Never a full e-mail, IBAN or token.", "example": "Paxum · j***@example.com" } }, "required": [ "type", "label" ], "description": "The destination frozen when the payout or request was made, masked. Null for manual payouts." }, "note": { "type": [ "string", "null" ], "description": "Requests: the note sent with the request. Manual payouts: the note the admin recorded for the payee. Otherwise null." }, "failureMessage": { "type": [ "string", "null" ], "description": "Why a `failed` payout failed, as reported by the provider. Null unless `status` is `failed`." }, "invoiceNumber": { "type": [ "integer", "null" ], "description": "Payout invoice number once the invoice exists. The invoice itself is in the dashboard.", "example": 1042 }, "requestId": { "type": [ "string", "null" ], "description": "kind `payout` / `manual`: the request this payout fulfilled, if any." }, "payoutId": { "type": [ "string", "null" ], "description": "kind `request`: the payout or manual payout that fulfilled it, if any." }, "createdAt": { "type": "string", "description": "When the payout was created or the request made. The list is ordered by this.", "format": "date-time" }, "initiatedAt": { "type": [ "string", "null" ], "description": "When the payout was sent to the provider.", "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "description": "When it was paid. Null unless `status` is `paid` (requests carry it on the fulfilling payout instead).", "format": "date-time" }, "failedAt": { "type": [ "string", "null" ], "description": "When it failed. Null unless `status` is `failed`.", "format": "date-time" }, "reversedAt": { "type": [ "string", "null" ], "description": "Set on a paid wallet load that was sent back (spendback): the money is available again. Its negative twin has `reversalOfId`. Both are hidden from GET /payouts unless includeReversed=true.", "format": "date-time" }, "reversalOfId": { "type": [ "string", "null" ], "description": "Set on the negative row that reverses the payout with this id." } }, "required": [ "id", "kind", "status", "amountCents", "currency", "side", "sides", "createdAt" ] }, "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "payouts" ] }, "example": { "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 } } } }, "400": { "description": "Unparseable `since` (`invalid_until` for `until`). Also: Unknown status (`invalid_kind` for an unknown kind). Also: `limit` out of range. Also: The cursor was not one we returned. Also: `X-Dropfans-Account` is not an account id.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "since must be an ISO date", "code": "invalid_since" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "`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). Also: With `X-Dropfans-Account`: the agency lacks `canViewStats` on that account.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "This key cannot act for that account.", "code": "account_not_managed" } } } }, "429": { "description": "Rate limit exceeded for the current minute or day window. Wait Retry-After seconds and retry.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (sent with 429s).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Rate limit exceeded", "code": "rate_limited" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "curl", "source": "curl \"https://www.dropfans.io/api/external/payouts?since=2026-01-01T00%3A00%3A00Z&status=paid\" \\\n -H \"Authorization: Bearer $DROPFANS_API_KEY\"" }, { "lang": "JavaScript", "label": "Node", "source": "const res = await fetch(`https://www.dropfans.io/api/external/payouts?since=2026-01-01T00%3A00%3A00Z&status=paid`, {\n headers: {\n Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,\n },\n});\nconsole.log(await res.json());" }, { "lang": "Python", "source": "import os\nimport requests\n\nres = requests.get(\n \"https://www.dropfans.io/api/external/payouts\",\n headers={\"Authorization\": f\"Bearer {os.environ['DROPFANS_API_KEY']}\"},\n params={\"since\": \"2026-01-01T00:00:00Z\", \"status\": \"paid\"},\n)\nprint(res.json())" } ], "x-dropfans-docs": "https://www.dropfans.io/developers/reference/list-payouts", "x-dropfans-agency-permission": "canViewStats" } ``` --- Previous: [Payout balance, eligibility and status](https://www.dropfans.io/developers/reference/get-payout-summary.md) · Next: [One payout or payout request](https://www.dropfans.io/developers/reference/get-payout.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)