---
title: "Get earnings data for a creator"
method: GET
path: "/creators/{creatorUserUuid}/insights/earnings"
---

# Get earnings data for a creator

`GET /creators/{creatorUserUuid}/insights/earnings`

Returns cursor-paginated invoice data for the specified creator over a specified time period. Each transaction includes information about the fan who made the payment. Reversals are included as `refund`/`chargeback` rows with negative gross (matching /insights/spending); filter them with `source`.

## Path parameters

- `creatorUserUuid` string, uuid, required

## Query parameters

- `startDate` string, date-time — Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).
- `endDate` string, date-time — End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.
- `source` EarningSource[] — Comma-separated list of earning sources
- `transactionOrderIds` string[] — Comma-separated transaction order IDs (max 100)
- `experienceUuid` string, uuid — Return only earnings attributed to this fan experience. Matches every charge the experience produced, including one-off access purchases, the first subscription charge and each renewal, plus the refunds and chargebacks that reverse any of them, so a filtered total nets out correctly. Combines with the other filters; normal pagination still applies. Use this rather than filtering on `source`: a renewal reports `source: "renewal"`, so `source=fanExperience` under-reports recurring experience revenue from the second charge onwards.
- `cursor` string — Cursor for pagination - If given, pass `nextCursor` to get the next page.
- `size` number — Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.

## Headers

- `X-Fanvue-API-Version` string, required

## Response `200`

Creator earnings data with cursor pagination

- object
  - `data` object[], required
    - `date` string, required — Payment date as UTC ISO 8601 datetime string
    - `gross` number, required — Pre-fee earnings for this row, converted to USD cents. Not always money a fan paid: `referral`, `affiliate` and `giveaway` rows are creator rewards. Negative on `refund` and `chargeback` rows, which carry the full amount of the earning they reverse, reward reversals included.
    - `net` number, required — Creator's cut after Fanvue fees, in USD cents. Negative on `refund` and `chargeback` rows.
    - `total` number, required — What the fan was actually charged for this row, in USD cents: `gross` plus the fan's tax and plus the fan-side transaction fee. This is the figure shown as "Fan paid" in the creator's own earnings views, and the one to use when your metrics must match what left the fan's card. On `referral`, `affiliate` and `giveaway` rows no fan paid anything and this equals `gross`. Negative on `refund` and `chargeback` rows, carrying the full amount the fan was originally charged. The three bases differ: `total` is what the fan paid, `gross` is the creator's price the earning is calculated from, and `net` is what the creator keeps after Fanvue fees.
    - `currency` string, nullable, required — Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross, net and total amounts are already converted to USD cents regardless of this value.
    - `source` 'all' | 'affiliate' | 'appStore' | 'checkoutLink' | 'fanExperience' | 'mediaLink' | 'message' | 'post' | 'referral' | 'renewal' | 'subscription' | 'tip' | 'giveaway' | 'refund' | 'chargeback', required — What produced this earning. `renewal` is a catch-all for every recurring charge after the first payment: profile subscriptions, checkout-link subscriptions and fan-experience subscriptions all bill as `renewal` from their second charge onwards. So `subscription`, `checkoutLink` and `fanExperience` only ever hold first payments and one-off purchases. `appStore` is the single exception: an app's recurring charges stay `appStore`. `fanExperience` and `appStore` are different sides of a third-party app: `fanExperience` is the creator selling a paid experience to a fan, `appStore` is the app's developer selling to the creator, so an `appStore` row is not fan-to-creator spend. `referral`, `affiliate` and `giveaway` are creator rewards rather than fan purchases. `user` follows the invoice rather than the source: it is null when the row records no fan, the common case for those three, and a `giveaway` granted to a specific fan returns that fan. Reversals are surfaced here too: `refund` and `chargeback` rows carry negative gross/net, matching /insights/spending.
    - `transactionOrderId` string, required — Transaction order ID
    - `transactionOrderStatus` 'availableForPayout' | 'pendingBalance', required — Transaction order status
    - `reversedTransactionOrderId` string — Only on `refund` and `chargeback` rows: the `transactionOrderId` of the original transaction this row reverses. A reversal never rewrites the original transaction, so use this to link the two.
    - `messageUuid` string, uuid — Message UUID when source is message (e.g. paid chat or broadcast message). Also present on tip rows, where it identifies the chat message Fanvue writes into the thread to record the tip — including for tips sent on a post. On a tip it is therefore not a signal that the tip came from a chat; use `tipContext` and `postUuid` for that.
    - `messageType` 'AUTOMATED_CANCELED' | 'AUTOMATED_NEW_FOLLOWER' | 'AUTOMATED_NEW_PURCHASE' | 'AUTOMATED_NEW_SUBSCRIBER' | 'AUTOMATED_RE_SUBSCRIBED' | 'AUTOMATED_RENEWED' | 'AUTOMATED_FIRST_MESSAGE_REPLY' | 'AUTOMATED_CHAT_MESSAGE_REPLY' | 'BROADCAST' | 'CHAT_TEXT_GENERATION' | 'CHAT_TEXT_REWRITE' | 'CHAT_TEXT_REPLY' | 'GHOST_PROMOTION' | 'MARKETING_KYC' | 'TIP' | 'LOCKED_MESSAGE_UNLOCKED' | 'VOICE_CALL' | 'SINGLE_RECIPIENT' — Underlying chat message type when source is message. Same values as the `type` field on the messages API — e.g. SINGLE_RECIPIENT (1-to-1 DM), BROADCAST / GHOST_PROMOTION (mass message), AUTOMATED_* (automated message). Use it to distinguish direct, mass, and automated message earnings.
    - `postUuid` string, uuid — Post UUID when source is post
    - `experienceUuid` string, uuid — UUID of the fan experience this earning came from, present on every fan-experience charge: one-off access purchases, the first subscription charge, and each subsequent renewal. Same uuid an app receives as `experience.uuid` when a launch token is exchanged, so it joins directly to the app's own experience records. Detect experience revenue by this field's presence rather than by `source`: a renewal reports `source: "renewal"`, so filtering on `source: "fanExperience"` under-reports recurring experience revenue from the second charge onwards.
    - `experienceAppUuid` string, uuid — UUID of the third-party app the `experienceUuid` experience belongs to. Present whenever `experienceUuid` is, and useful to separate experiences of different apps on the same creator.
    - `tipContext` 'post' | 'message' — Context of a tip when source is tip. `post` when the tip was sent on a post — `postUuid` identifies which. `message` for every other tip. Read `message` as 'not on a post' rather than 'in a chat': there is deliberately no `profile` value, because Fanvue does not record which surface a fan tipped from, so a tip sent in a chat thread and a tip sent from a creator profile are indistinguishable and both report `message`. Do not treat `message` as evidence of a chat origin when attributing revenue. Buckets identically to the `context` field on the tip.new webhook.
    - `user` object, nullable, required — Fan's user information (null for transactions without a fan like referrals, affiliates)
      - `uuid` string, uuid, required
      - `handle` string, required
      - `displayName` string, required
      - `nickname` string, nullable, required
      - `isTopSpender` boolean, required
  - `nextCursor` string, nullable, required — Cursor for next page, null if no more data

## Other responses

- `400` — Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) OR invalid UUID
- `401` — Unauthorized Response
- `403` — Unauthorized Response
- `404` — Not Found Response
- `410` — API version no longer supported (sunset)
- `429` — Too many requests - rate limit exceeded

## Changes

- **2026-09-25** `431868e8a264` — 1 info
  - added the required property `data/items/total` to the response with the `200` status
- **2026-09-10** `4d08f36ad6c8` — 1 info
  - added the new optional `query` request parameter `experienceUuid`
- **2026-08-30** `dce5621fe589` — 2 info
  - added the optional property `data/items/experienceAppUuid` to the response with the `200` status
  - added the optional property `data/items/experienceUuid` to the response with the `200` status

[Change history](https://skmtc.dev/fanvue/apis/fanvue-api/changes/creators/:creatorUserUuid/insights/earnings/get.md)

---

[API](https://skmtc.dev/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.dev/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fanvue/apis/fanvue-api/revisions/431868e8a264?raw)