API reference

Get transactions for a creator (cursor-paginated)

Every drop sale, tip and subscription payment of the key's account, newest first, with net, gross, platform fee and VAT per transaction. No cap — follow `nextCursor` until it is null.

View as MarkdownUpdated Oct 28, 2026

GET/api/external/v1/earnings/transactionsalso served at /api/external/earnings/transactionsNew

Every drop sale, tip and subscription payment of the key's account, newest first, with net, gross, platform fee and VAT per transaction. No cap — follow nextCursor until it is null.

Same sources and filters as GET /api/external/v1/earnings: refunds and chargebacks are left out, so the netAmountCents of a window's pages add up to its stats.totalEarningsCents (pass the same window as since / until instants). Pass includeReversed=true to also get refunded and charged-back transactions, with their status.

Keep since, until, type and includeReversed the same while you follow a cursor.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

For a creator you manage or onboarded

GET /api/external/v1/creators/{creatorId}/earnings/transactions — an agency's own key for a creator or AI persona it manages (needs canViewStats), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.

Query parameters

Name	Type	Required	Description
`since`	string	Optional	Only transactions paid at or after this time. Format: date-time
`until`	string	Optional	Only transactions paid at or before this time. Format: date-time
`type`	string	Optional	Comma-separated subset of drop,tip,subscription. Default: all three.
`includeReversed`	boolean	Optional	Also return refunded and charged-back transactions. Default: `false`
`limit`	integer	Optional	Page size. Default: `100` Min: 1 Max: 200
`cursor`	string	Optional	`nextCursor` from the previous page.

Responses

200A page of transactions. All money in cents.

Name Type Description

transactions

LedgerTransaction[]

Newest first.

Show child attributes

`id`	string	The order / tip / renewal id. Unique per transaction — dedupe on it.
`type`	string	Revenue source. One of: `drop`, `tip`, `subscription`
`productId`	string \| null	The sold drop — drops only, null on tips and subscriptions.
`productName`	string	Drop name, or the literal "Tip" / "Subscription".
`externalRef`	string \| null	Your per-fan reference from the checkout or tip link, when there was one.
`linkId`	string \| null	The link id (POST /api/external/v1/links) the sale came through; null for template links and subscriptions.
`amountCents`	integer	NET seller earnings in cents — the same number /earnings calls amountCents.
`netAmountCents`	integer	Same as amountCents: what the creator keeps (after the platform fee and VAT; before any agency split).
`grossAmountCents`	integer	Seller gross in cents (buyer-paid minus VAT, before the fee).
`platformFeeCents`	integer	Platform fee in cents.
`taxCents`	integer	VAT in cents.
`totalChargedCents`	integer	What the buyer paid in cents (VAT included).
`currency`	string	Always USD. One of: `USD`
`buyerEmail`	string \| null	Buyer email when known. Format: email
`buyerName`	string \| null	Buyer display name — tips and subscriptions only.
`paidAt`	string	When it was paid (UTC). Format: date-time
`status`	string	Always "paid" unless includeReversed=true. One of: `paid`, `refunded`, `charged_back`

nextCursor string | null Pass as cursor for the next page; null on the last page.

Example response

{
  "transactions": [
    {
      "id": "clx0rd3r000001sale",
      "type": "drop",
      "productId": "clxdr0p000001prod",
      "productName": "Beach set — 6 photos",
      "externalRef": "tg_48213377",
      "amountCents": 2000,
      "netAmountCents": 2000,
      "grossAmountCents": 2500,
      "platformFeeCents": 500,
      "taxCents": 250,
      "totalChargedCents": 2750,
      "currency": "USD",
      "buyerEmail": "buyer@example.com",
      "buyerName": null,
      "paidAt": "2026-10-18T21:03:00.000Z",
      "status": "paid"
    }
  ],
  "nextCursor": "MjAyNi0xMC0xOFQyMTowMzowMC4wMDBafGNseDByZDNyMDAwMDAxc2FsZQ"
}

Errors

Status	Body	When
400	`{"error":"since must be an ISO date"}`	Unparseable `since` (or `until`).
400	`{"error":"type must be a comma-separated subset of drop,tip,subscription"}`	Unknown type.
400	`{"error":"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.
400	`{"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"}`	Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone 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"}`	For a managed creator: the agency lacks `canViewStats` on that account.
403	`{"error":"This app does not have the earnings API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"earnings"}`	Your app has the Earnings & balance [API category](/developers/concepts/api-categories) switched off.

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/v1/earnings/transactions?since=2026-10-01T00%3A00%3A00Z&until=2026-10-31T23%3A59%3A59.999Z&type=drop%2Ctip" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const res = await fetch(`https://www.dropfans.io/api/external/v1/earnings/transactions?since=2026-10-01T00%3A00%3A00Z&until=2026-10-31T23%3A59%3A59.999Z&type=drop%2Ctip`, {
  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/v1/earnings/transactions",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    params={"since": "2026-10-01T00:00:00Z", "until": "2026-10-31T23:59:59.999Z", "type": "drop,tip"},
)
print(res.json())

← Previous

Get the earnings summary for a creator

Get paid tips for a creator (cursor-paginated)

Questions? support@dropfans.io