> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://api.fanvue.com/docs/creator/payments).
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.
**Required scope**
* `read:insights` — Access analytics, metrics, and insights data for performance tracking.
## OpenAPI
````yaml /openapi.json get /insights/earnings
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/insights/earnings:
get:
summary: Get earnings data
description: >-
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](https://api.fanvue.com/docs/creator/payments).
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.
operationId: getEarnings
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: date-time
description: >-
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).
required: false
description: >-
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).
name: startDate
in: query
- schema:
type: string
format: date-time
description: >-
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.
required: false
description: >-
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.
name: endDate
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/EarningSource'
description: Comma-separated list of earning sources
required: false
description: 'Comma-separated list of earning sources. Default: all'
name: source
in: query
style: form
explode: false
- schema:
type: array
items:
type: string
description: Comma-separated transaction order IDs (max 100)
required: false
description: >-
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.
name: transactionOrderIds
in: query
style: form
explode: false
- schema:
type: string
description: >-
Cursor for pagination - If given, pass `nextCursor` to get the
next page.
required: false
description: >-
Cursor for pagination - If given, pass `nextCursor` to get the next
page.
name: cursor
in: query
- schema:
type: number
minimum: 1
maximum: 50
description: >-
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: false
description: >-
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.
name: size
in: query
responses:
'200':
description: Earnings data with cursor pagination
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
date:
type: string
description: Payment date as UTC ISO 8601 datetime string
gross:
type: number
description: Amount the fan paid, converted to USD cents
net:
type: number
description: Creator's cut after Fanvue fees, in USD cents
currency:
type:
- string
- 'null'
description: >-
Informational only — the local currency the fan
originally paid in (e.g. 'BRL'). The gross and net
amounts are already converted to USD cents
regardless of this value.
source:
$ref: '#/components/schemas/EarningSource'
transactionOrderId:
type: string
description: Transaction order ID
transactionOrderStatus:
type: string
enum:
- availableForPayout
- pendingBalance
description: Transaction order status
reversedTransactionOrderId:
type: string
description: >-
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:
type: string
format: uuid
description: >-
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:
type: string
enum:
- 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
description: >-
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:
type: string
format: uuid
description: Post UUID when source is post
tipContext:
type: string
enum:
- post
- message
description: >-
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:
type:
- object
- 'null'
properties:
uuid:
type: string
format: uuid
handle:
type: string
displayName:
type: string
nickname:
type:
- string
- 'null'
isTopSpender:
type: boolean
required:
- uuid
- handle
- displayName
- nickname
- isTopSpender
description: >-
Fan's user information (null for transactions
without a fan like referrals, affiliates)
required:
- date
- gross
- net
- currency
- source
- transactionOrderId
- transactionOrderStatus
- user
nextCursor:
type:
- string
- 'null'
description: Cursor for next page, null if no more data
required:
- data
- nextCursor
example:
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
reversedTransactionOrderId: FV-ORDER-124
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
'400':
description: >-
Bad Request - API version not supported OR validation failed (dates,
sources, cursor, pagination)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:insights
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
EarningSource:
type: string
enum:
- all
- affiliate
- appStore
- checkoutLink
- fanExperience
- mediaLink
- message
- post
- referral
- renewal
- subscription
- tip
- giveaway
- refund
- chargeback
description: >-
Earning source. Reversals are surfaced here too: `refund` and
`chargeback` rows carry negative gross/net, matching /insights/spending.
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
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.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````