Earnings & balance

Two read-only endpoints cover the money picture: GET /earnings mirrors the dashboard’s revenue view, GET /balance shows where the payout money sits.

Earnings#

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"

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();

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#

{ "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 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). A dashboard that polls once a minute per creator stays comfortably inside every rate tier.

Next: Money & units or Webhooks & polling.