> ## 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
messageUuid:
type: string
format: uuid
description: >-
Message UUID when source is message (e.g. paid chat
or broadcast message)
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
tipped on a post, `message` otherwise (tip sent in
chat or from the creator profile). Matches the
`context` field on the tip.new webhook. Chat tips
and profile tips are not distinguishable and both
return `message`.
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
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.
````