Fanvue API Documentation

The insights and earnings endpoints report money in a few different ways, and the differences are not guessable from the field names. This page is the reference for three things integrators keep having to ask about: what each payment source actually covers, which figures are gross and which are net of refunds and chargebacks, and how a reversal is recorded.

Payment sources

Every earning row on GET /insights/earnings carries a source, and the fan spend breakdown on GET /insights/fans/{userUuid} is keyed by the same names.

`source`	What it is	Fan pays the creator?	Recurring charges land on
`subscription`	The payment that starts a profile subscription	Yes	`renewal`
`renewal`	Every recurring charge after a first payment, whatever started it	Yes	`renewal`
`message`	A fan unlocking a paid (PPV) chat message	Yes	Not recurring
`post`	A fan unlocking a paid post	Yes	Not recurring
`tip`	A tip, sent on a post or in a chat	Yes	Not recurring
`mediaLink`	A fan buying a media link	Yes	Not recurring
`checkoutLink`	A fan’s first payment on a checkout link, one-time or subscription	Yes	`renewal`
`fanExperience`	A fan buying a creator’s paid experience: a one-off unlock, or the first charge of a recurring experience	Yes	`renewal`
`appStore`	The creator buying a third-party app, one-off or subscription	No, this is the creator paying an app developer	`appStore`
`referral`	A Fanvue referral reward	No fan involved, `user` is `null`	Not recurring
`affiliate`	An affiliate reward	No fan involved, `user` is `null`	Not recurring
`giveaway`	Promotional credit Fanvue posts to the creator	No fan involved, `user` is `null`	Not recurring
`refund`	A refund of an earlier payment, with negative `gross`/`net`	Reverses a fan payment	Mirrors the original
`chargeback`	A chargeback on an earlier payment, with negative `gross`/`net`	Reverses a fan payment	Mirrors the original

The `renewal` catch-all

renewal is not “subscription renewal”. It is every recurring charge after the first payment, no matter which product started the subscription: profile subscriptions, checkout-link subscriptions and recurring fan experiences all bill as renewal from their second charge onwards. appStore is the single exception. An app subscription’s recurring charges stay under appStore. The consequence catches integrators out. A fan subscribes to a recurring fan experience priced at 500 cents per month:

Charge	`source`
Month 1, the fan subscribes	`fanExperience`
Month 2, automatic renewal	`renewal`
Month 3, automatic renewal	`renewal`

So fanExperience only ever holds first payments and one-off unlocks, and the same is true of subscription and checkoutLink. If you want a product’s full recurring revenue you cannot read it off one source: renewal is where the ongoing money is, and it does not say which product produced it.

A renewal row does not tell you which product renewed. To attribute renewals to a product, follow the fan’s subscription rather than the earning source.

Fan experiences and the App Store are different transactions

Both involve a third-party app, and the same app can produce both, but the parties are different:

fanExperience is the creator selling to a fan. An experience is a fan-facing mini-app the creator publishes, backed by a third-party app. This is fan-to-creator spend and it belongs in fan spend metrics.
appStore is the app developer selling to the creator. The buyer is the creator who installs the app. A fan cannot even see the App Store, so an appStore invoice is not fan spend on a creator.

Only paid experiences produce a payment. A free experience produces no invoice of any kind, so it never appears on any earnings or spend figure.

Fan experiences are not fully live yet. They are behind a staged rollout, so most creators will have no fanExperience rows at all today.

Gross, net, and reversals

Two different distinctions share the words gross and net, and the endpoint decides which one is meant:

The fee axis. On the earnings endpoints and the agency insights endpoints, gross is what the fan paid and net is the creator’s cut after platform fees. Both describe the same transaction.
The reversal axis. Whether a refunded or charged-back purchase is still counted. This is per field, and it is not consistent across the insights surface.

The table below is the reversal axis, field by field.

Endpoint and field	Reversal treatment
`GET /insights/earnings` rows	Reversals are their own `refund`/`chargeback` rows carrying negative amounts. Original payment rows are never rewritten.
`GET /insights/earnings/summary`	Reversals are left out of every figure rather than subtracted, on both `gross` and `net`.
`GET /insights/spending`	Reversal rows only, this endpoint returns nothing else.
`GET /insights/top-spenders` `gross`/`net`	Gross of reversals. Only positive invoices are counted, so a refunded purchase stays in at its full amount.
`GET /insights/fans/{userUuid}` `spending.total`	Net of reversals. Each refund or chargeback is subtracted, so the figure can be lower than the sum of the sources, and can even be negative.
`GET /insights/fans/{userUuid}` `spending.sources.*`	Gross of reversals. A reversed purchase is still counted in full, and reversals are not returned as a source of their own.
`GET /insights/fans/{userUuid}` `spending.maxSinglePayment`	Excludes reversed purchases. A payment later refunded or charged back is not eligible to be the highest. This has been the behaviour since July 2025.
`GET /insights/fans/{userUuid}` `spending.lastPurchaseAt`	Fan-initiated payments only, so an automatic renewal never moves it. Reversed purchases are not skipped: the fan did buy at that moment.
`GET /agencies/insights/*` `gross`/`net`	Both are already net of refunds and chargebacks. Here `gross` and `net` are the fee axis only.

Why the sources do not add up to the total

On GET /insights/fans/{userUuid}, spending.total is net of reversals while spending.sources are gross of them. The two therefore disagree, and the gap is exactly the reversals, which are dropped from sources entirely rather than shown as their own entry. If you need the two to reconcile, fetch the fan’s reversals from GET /insights/spending with fanUuid set and subtract them yourself.

Fanvue is adding reversal-free companions to spending.total, to each per-source figure and its average, and a last-valid-purchase field alongside spending.lastPurchaseAt. The existing fields keep their current meaning, so nothing shifts under an integration that already reads them. Separately, Fanvue is removing appStore from the fan spend metrics as a correction, because it records a creator’s purchase from an app developer rather than a fan’s spend. That one does move numbers, and the changelog will call it out when it ships.

How a reversal is recorded

A refund or a chargeback is written as its own invoice, never as an edit to the payment it reverses. Three consequences worth knowing:

The original stays settled. It keeps its own row on GET /insights/earnings with its original amount. Nothing about it changes when it is reversed.
A reversal is always the full amount. Fanvue has no partial refunds, so a reversed purchase is reversed for exactly what the fan paid.
The pairing is explicit. On GET /insights/earnings, refund and chargeback rows carry reversedTransactionOrderId, which is the transactionOrderId of the payment they reverse. That is the supported way to match the two.

{
  "data": [
    {
      "date": "2026-08-14T09:12:00Z",
      "gross": -1999,
      "net": -1799,
      "currency": "USD",
      "source": "refund",
      "transactionOrderId": "FVC-20260814-91",
      "transactionOrderStatus": "availableForPayout",
      "reversedTransactionOrderId": "FVE-20260801-44"
    },
    {
      "date": "2026-08-01T16:40:00Z",
      "gross": 1999,
      "net": 1799,
      "currency": "USD",
      "source": "message",
      "transactionOrderId": "FVE-20260801-44",
      "transactionOrderStatus": "availableForPayout"
    }
  ],
  "nextCursor": null
}

Both rows also carry the fan’s user object, trimmed here for brevity. Note that the original message row is untouched: it still reports the full 1999 it was paid.

Freshness

Endpoint	Freshness
`GET /insights/fans/{userUuid}`, `GET /insights/fans`, `POST /insights/fans/batch`	Computed from live invoice data on every request, with no caching. Two reads seconds apart can legitimately return different numbers.
`GET /insights/earnings/summary`	Cached for up to 10 minutes per creator and per parameter set, so a figure can lag a payment that has already settled.
`GET /agencies/insights/*`	Whole UTC days come from the daily warehouse export; the current day, and any partial day at either edge of the range, are read live from invoices. The `overview` endpoint’s `retention` and `averageFanLifetime` are the exception: they are warehouse snapshots with no live branch, and are not affected by `startDate`/`endDate` at all.

Agency insights

Three agency-level insights endpoints sit alongside the chatter leaderboard, under Agency Insights in the API Reference. All of them are agency-wide: they aggregate across every creator the agency manages, and accept a creatorUuids filter (max 50) to narrow to a subset.

Endpoint	Returns	Scopes	Pagination
`GET /agencies/insights/overview`	Headline metrics: total earnings, newly acquired fans, average revenue per paying fan, the 30-day retention snapshot and average fan lifetime	`read:agency`, `read:creator`	None, single object
`GET /agencies/insights/demographics`	Paying fans grouped by billing country, ordered by fan count descending	`read:agency`, `read:creator`	Cursor, pass `nextCursor`
`GET /agencies/insights/top-fans`	The five highest-spending fans across the agency’s creators	`read:agency`, `read:creator`, `read:fan`	None, at most five rows

Every row returns both figures, gross and net, so you never have to pick one at request time. On top-fans, earningsView chooses which of the two the ranking is done by, and both are returned regardless. Amounts are USD cents. This gross-and-net-on-every-row shape is the convention the fan insights endpoints are moving to as well.

Agency endpoints require agency admin access on top of the scopes above. A creatorUuids value that does not belong to the agency fails the whole request with 403 rather than being ignored.

Get Started

Core Concepts

Tutorials

Insights metrics: payment sources, gross vs net, reversals

Payment sources

The `renewal` catch-all

Fan experiences and the App Store are different transactions

Gross, net, and reversals

Why the sources do not add up to the total

How a reversal is recorded

Freshness

Agency insights

​Payment sources

​The renewal catch-all

​Fan experiences and the App Store are different transactions

​Gross, net, and reversals

​Why the sources do not add up to the total

​How a reversal is recorded

​Freshness

​Agency insights

Payment sources

The `renewal` catch-all

Fan experiences and the App Store are different transactions

Gross, net, and reversals

Why the sources do not add up to the total

How a reversal is recorded

Freshness

Agency insights