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

# Earnings & balance

> Mirror the creator’s dashboard numbers and payout buckets inside your own product.

- Source: https://www.dropfans.io/developers/guides/earnings-and-balance
- Section: Guides
- OpenAPI: https://www.dropfans.io/developers/openapi.json

Two read-only endpoints cover the money picture: [GET /earnings](https://www.dropfans.io/developers/reference/get-earnings.md) mirrors the dashboard’s revenue view, [GET /balance](https://www.dropfans.io/developers/reference/get-balance.md) shows where the payout money sits.

## Earnings

```bash tab="curl"
curl "https://www.dropfans.io/api/external/earnings?startDate=2026-08-01&endDate=2026-08-19&tz=Europe/Stockholm" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"
```

```javascript tab="Node"
const params = new URLSearchParams({
  startDate: '2026-08-01',
  endDate: '2026-08-19',
  tz: 'Europe/Stockholm',
});
const res = await fetch('https://www.dropfans.io/api/external/earnings?' + params, {
  headers: { Authorization: 'Bearer ' + process.env.DROPFANS_API_KEY },
});
const { stats, chart, transactions } = await res.json();
```

```python tab="Python"
import os, requests

res = requests.get(
    "https://www.dropfans.io/api/external/earnings",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    params={"startDate": "2026-08-01", "endDate": "2026-08-19", "tz": "Europe/Stockholm"},
)
data = res.json()
```

- `startDate` and `endDate` are **required**, `YYYY-MM-DD`. `tz` is an IANA timezone; days bucket in that zone (invalid values silently fall back to UTC). Pass the creator’s zone and your "today" matches their dashboard.
- **Bucketing**: spans up to 31 days chart by `day`, up to 90 by `week` (weeks start Monday), longer by `month`. The response tells you which via `chart.groupBy`.
- **Net vs gross**: `stats.totalEarningsCents` is net (what the creator keeps), `stats.grossEarningsCents` is what buyers paid; `typeTotals` splits both by `drop` / `tip` / `subscription`. Chart `values` are gross. All cents. Refunds and chargebacks are excluded throughout.
- **Transactions** are always the 50 most recent in the range — there is no pagination. Need older ones? Narrow the date range.

## Balance

```json
{ "currency": "USD", "pending": 412.5, "available": 180, "processing": 0, "paidOut": 12750.25 }
```

USD **dollars** (unlike earnings’ cents). The buckets: `pending` — earned but still inside the payout hold; `available` — released and payable; `processing` — inside a payout run right now; `paidOut` — lifetime total paid. Agency-managed accounts can go negative — render signed. See [Money & units](https://www.dropfans.io/developers/concepts/money-and-units.md) for the payout model.

## Caching advice

Earnings queries aggregate a lot of rows — do not call them per page view. Cache per creator for 60 seconds or more, single-flight concurrent requests for the same range, and refresh on demand when you know something changed (a sale you saw via [check-status](https://www.dropfans.io/developers/reference/check-drop-status.md)). A dashboard that polls once a minute per creator stays comfortably inside every [rate tier](https://www.dropfans.io/developers/concepts/rate-limits.md).

Next: [Money & units](https://www.dropfans.io/developers/concepts/money-and-units.md) or [Webhooks & polling](https://www.dropfans.io/developers/webhooks/overview.md).

---

Previous: [Post to the For You feed](https://www.dropfans.io/developers/guides/post-to-feed.md) · Next: [Webhooks (coming soon) & polling today](https://www.dropfans.io/developers/webhooks/overview.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)