Fanvue API Documentation

Read this before you build an earnings or fan spend report on the insights endpoints. The field names alone don’t tell you what each payment source means, which figures are net of refunds and chargebacks, or how a reversal or deduction is recorded. Getting any of them wrong makes a report quietly disagree with the creator’s own earnings. Amounts throughout are integers in USD cents. The tables below cover each money field in turn. For the webhook side of each earning row, see Creator events: payments.

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 (pay-per-view) chat message	Yes	Not recurring
`post`	A fan unlocking a paid post	Yes	Not recurring
`tip`	A tip 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, the creator pays 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` and `total`	Reverses a fan payment	Mirrors the original
`chargeback`	A chargeback on an earlier payment, with negative `gross`, `net` and `total`	Reverses a fan payment	Mirrors the original
`earningsDeduction`	Fanvue taking back the creator’s earnings from a sale without refunding the fan, for example when moderation removes the content sold. `gross` and `total` are 0 and `net` is negative. A later refund or chargeback of the same sale releases the deduction with a second `earningsDeduction` row carrying the matching positive `net`. Both rows carry `reversedTransactionOrderId` naming the sale.	No money moves for the fan	Not recurring

The `renewal` catch-all

renewal is not “subscription renewal”. It is every recurring charge after the first payment, whatever 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. A fan subscribes to a recurring fan experience priced at 500 USD cents per month:

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

fanExperience therefore only ever holds first payments and one-off unlocks, and the same is true of subscription and checkoutLink. You can’t read a product’s full recurring revenue off one source, because renewal holds the ongoing money and doesn’t name the product that renewed. Fan experiences are the exception. Their rows carry experienceUuid on every charge, renewals included; see Attributing fan-experience revenue. For profile and checkout-link subscriptions, 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 differ:

fanExperience is the creator selling to a fan. An experience is a fan surface the creator publishes, backed by a third-party app. The money is fan-to-creator spend and 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 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, so it never appears on any earnings or spend figure. Payments inside experiences covers how experience access and priced actions are charged.

Attributing fan-experience revenue

Two optional fields on every GET /insights/earnings row identify the fan experience a payment came from. They are the supported way to attribute experience revenue, because source on its own cannot.

Field	Type	Description
`experienceUuid`	string (uuid)	UUID of the fan experience the earning came from. Present on every fan-experience charge: a one-off access purchase, the first subscription charge and every renewal after it. The same UUID an app receives as `experience.uuid` when it exchanges a fan’s launch token, so it joins directly to the app’s own experience records.
`experienceAppUuid`	string (uuid)	UUID of the third-party app the experience belongs to. Present whenever `experienceUuid` is. It separates the experiences of different apps on the same creator.

Both fields are absent on any row not tied to a fan experience.

Filter on experienceUuid, not on source. A fan-experience subscription reports source: "fanExperience" on its first charge only; every renewal reports source: "renewal". Code that selects source === "fanExperience" under-reports recurring experience revenue from the second charge onwards, and the shortfall grows with every renewal. Sum the rows where experienceUuid is present instead, and read source as the type of charge rather than the product that produced it.

A purchase and a renewal side by side

The same subscription, two months apart. Both rows carry the same experienceUuid; only the first reports source: "fanExperience". Amounts are USD cents.

{
  "data": [
    {
      "date": "2026-06-09T08:39:33Z",
      "gross": 999,
      "net": 799,
      "total": 1099,
      "currency": "USD",
      "source": "renewal",
      "transactionOrderId": "FVE-20260609-18",
      "transactionOrderStatus": "availableForPayout",
      "experienceUuid": "3d8f0b52-77a1-4c9e-b6d4-2e5a1f9c8b03",
      "experienceAppUuid": "c41e7a68-9b25-4d13-8f7a-0b6c2d94e5f1"
    },
    {
      "date": "2026-05-09T08:39:33Z",
      "gross": 999,
      "net": 799,
      "total": 1099,
      "currency": "USD",
      "source": "fanExperience",
      "transactionOrderId": "FVE-20260509-07",
      "transactionOrderStatus": "availableForPayout",
      "experienceUuid": "3d8f0b52-77a1-4c9e-b6d4-2e5a1f9c8b03",
      "experienceAppUuid": "c41e7a68-9b25-4d13-8f7a-0b6c2d94e5f1"
    }
  ],
  "nextCursor": null
}

Both rows also carry the fan’s user object, trimmed here. A one-off experience unlock looks like the fanExperience row and is never followed by a renewal row. Earnings rows record money that settled, not whether the fan still has access. A declined renewal writes no earning row, so an integration watching earnings alone never learns that the fan lost access. The subscription behind these rows has its own lifecycle events: creator.experience_subscription.activated and .deactivated report when a fan’s paid experience access starts and stops, keyed on the same experience UUID.

Gross, net, total and reversals

Three amounts describe one row, and a separate per-field rule decides whether reversed purchases are still counted. Think of them as two axes.

The fee axis. total is what the fan was charged: gross plus the fan’s tax plus the fan-side transaction fee. gross is the creator’s price the earning is calculated from. net is the creator’s cut after Fanvue fees. On referral, affiliate and giveaway rows no fan paid, so total equals gross. Use total when your figures must match what left the fan’s card.
The reversal axis. Whether a refunded or charged-back purchase is still counted. The rule is per field and is not consistent across the insights surface.

The reversal axis, field by field:

Endpoint and field	Reversal treatment
`GET /insights/earnings` rows	Reversals are their own `refund` and `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. The endpoint returns nothing else.
`GET /insights/top-spenders` `gross` and `net`	Gross of reversals. Only positive invoices count, 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 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.
`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` and `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 gap between them is exactly the reversals, which are dropped from sources rather than shown as their own entry. To reconcile the two, fetch the fan’s reversals from GET /insights/spending with fanUuid set and subtract them yourself.

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 follow:

The original stays settled. It keeps its own row on GET /insights/earnings with its original amount.
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. refund, chargeback and earningsDeduction rows carry reversedTransactionOrderId, the transactionOrderId of the payment they reverse or deduct from.

A reversal reports the source the creator sees in their own earnings. chargeback covers a bank dispute and a refund Fanvue issued to stop one. refund covers every other refund and a payment cancelled before it was collected. Filtering by source follows the same split.

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

Both rows also carry the fan’s user object, trimmed here. The original message row is untouched and 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 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 warehouse snapshots with no live branch and ignore `startDate` and `endDate`.

Agency insights

Three agency-level insights endpoints sit alongside the chatter leaderboard. All of them aggregate across every creator the agency manages and accept a creatorUuids filter of up to 50 UUIDs.

Endpoint	Returns	Scopes	Pagination
`GET /agencies/insights/overview`	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 gross and net. On top-fans, earningsView chooses which of the two ranks the rows, and both are returned regardless. Amounts are USD cents.

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

Start here

Authentication

API concepts

Guides

Insights metrics: payment sources, gross vs net, reversals

Payment sources

The `renewal` catch-all

Fan experiences and the App Store are different transactions

Attributing fan-experience revenue

A purchase and a renewal side by side

Gross, net, total 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

​Attributing fan-experience revenue

​A purchase and a renewal side by side

​Gross, net, total 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

Attributing fan-experience revenue

A purchase and a renewal side by side

Gross, net, total and reversals

Why the sources do not add up to the total

How a reversal is recorded

Freshness

Agency insights