Get earnings data

curl --request GET \
  --url https://api.example.com/insights/earnings \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>'

import requests

url = "https://api.example.com/insights/earnings"

headers = {
    "X-Fanvue-API-Version": "<x-fanvue-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Fanvue-API-Version': '<x-fanvue-api-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.example.com/insights/earnings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "date": "2024-01-15T00:00:00.000Z",
      "gross": 5000,
      "net": 4250,
      "currency": "USD",
      "source": "subscription",
      "transactionOrderId": "FV-ORDER-123",
      "transactionOrderStatus": "availableForPayout",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "nickname": "SarahK",
        "displayName": "Sarah Jones",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "gross": 2500,
      "net": 2125,
      "currency": "USD",
      "source": "tip",
      "transactionOrderId": "FV-ORDER-124",
      "transactionOrderStatus": "pendingBalance",
      "tipContext": "message",
      "user": {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "handle": "mike-smith",
        "nickname": null,
        "displayName": "Mike Smithly",
        "isTopSpender": false,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "gross": 2500,
      "net": 2125,
      "currency": "USD",
      "source": "message",
      "transactionOrderId": "FV-ORDER-126",
      "transactionOrderStatus": "availableForPayout",
      "messageUuid": "b7c8d9e0-1234-5678-9abc-def012345678",
      "messageType": "BROADCAST",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "nickname": "SarahK",
        "displayName": "Sarah Jones",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "gross": -2500,
      "net": -2125,
      "currency": "USD",
      "source": "refund",
      "transactionOrderId": "FV-ORDER-125",
      "transactionOrderStatus": "availableForPayout",
      "user": {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "handle": "mike-smith",
        "nickname": null,
        "displayName": "Mike Smithly",
        "isTopSpender": false,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    }
  ],
  "nextCursor": "eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "nextVersion": "<string>"
}

{
  "error": "<string>"
}

Earnings & payouts

Get earnings data

Returns cursor-paginated invoice data for the authenticated 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.

Pass transactionOrderIds (comma-separated, max 100) to fetch only specific transactions by ID — useful for re-fetching known transactions to pick up status changes. It combines with the other filters and normal pagination still applies.

Polling for real-time updates? Use a webhook instead.

If you are calling this endpoint on a schedule to detect new activity, subscribe to the creator.payment.succeeded, creator.refund.created, creator.dispute.created, creator.dispute.flagged webhook events instead — you’ll get pushed updates in real time without polling. See the webhook documentation.

Webhooks replace polling for detecting these events, but for authoritative financial figures you should still reconcile against this endpoint. The creator.payment.succeeded payload’s data.id is the Fanvue invoice number, which matches the transactionOrderId on the rows returned here — pass it to transactionOrderIds to cross-check specific transactions without a full re-poll.

GET

insights

earnings

Get earnings data

curl --request GET \
  --url https://api.example.com/insights/earnings \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>'

import requests

url = "https://api.example.com/insights/earnings"

headers = {
    "X-Fanvue-API-Version": "<x-fanvue-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Fanvue-API-Version': '<x-fanvue-api-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.example.com/insights/earnings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "date": "2024-01-15T00:00:00.000Z",
      "gross": 5000,
      "net": 4250,
      "currency": "USD",
      "source": "subscription",
      "transactionOrderId": "FV-ORDER-123",
      "transactionOrderStatus": "availableForPayout",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "nickname": "SarahK",
        "displayName": "Sarah Jones",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "gross": 2500,
      "net": 2125,
      "currency": "USD",
      "source": "tip",
      "transactionOrderId": "FV-ORDER-124",
      "transactionOrderStatus": "pendingBalance",
      "tipContext": "message",
      "user": {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "handle": "mike-smith",
        "nickname": null,
        "displayName": "Mike Smithly",
        "isTopSpender": false,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "gross": 2500,
      "net": 2125,
      "currency": "USD",
      "source": "message",
      "transactionOrderId": "FV-ORDER-126",
      "transactionOrderStatus": "availableForPayout",
      "messageUuid": "b7c8d9e0-1234-5678-9abc-def012345678",
      "messageType": "BROADCAST",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "nickname": "SarahK",
        "displayName": "Sarah Jones",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "gross": -2500,
      "net": -2125,
      "currency": "USD",
      "source": "refund",
      "transactionOrderId": "FV-ORDER-125",
      "transactionOrderStatus": "availableForPayout",
      "user": {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "handle": "mike-smith",
        "nickname": null,
        "displayName": "Mike Smithly",
        "isTopSpender": false,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    }
  ],
  "nextCursor": "eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "nextVersion": "<string>"
}

{
  "error": "<string>"
}

Required scope

read:insights — Access analytics, metrics, and insights data for performance tracking.

Authorizations

Authorization

string

header

required

OAuth 2.0 access token, presented as a JWT bearer token in the Authorization header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call.

Headers

X-Fanvue-API-Version

string

default:2025-06-26

required

API version to use for the request

Example:

"2025-06-26"

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

enum<string>[]

Comma-separated list of earning sources

Earning source. Reversals are surfaced here too: refund and chargeback rows carry negative gross/net, matching /insights/spending.

Available options:

all,

affiliate,

appStore,

checkoutLink,

fanExperience,

mediaLink,

message,

post,

referral,

renewal,

subscription,

tip,

giveaway,

refund,

chargeback

transactionOrderIds

string[]

Comma-separated transaction order IDs to fetch (max 100). Use to re-fetch specific transactions by ID and pick up status changes. Combines with the other filters; normal pagination still applies. Comma-separated transaction order IDs (max 100)

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.

Required range: 1 <= x <= 50

Response

Earnings data with cursor pagination

data

object[]

required

Show child attributes

nextCursor

string | null

required

Cursor for next page, null if no more data

Get subscribers Get aggregated earnings summary

⌘I

Overview

Popular endpoints

Account

Account Health

Chats

Notifications

Posts

Creator Tools

Insights & Earnings

Apps

Onboarding

Experiences

Webhooks

Agency

Get earnings data

Authorizations

Headers

Query Parameters

Response