Fanvue API Documentation

Before you design tables for a Fanvue integration, get the shape of the platform straight. Learn who the actors are, which objects each one owns, how money moves between them and which identifiers join an API response to a webhook event. The tables below are a map to keep open while you model your data; each row links to the guide or reference that covers the object in depth.

Roles

Role	What it is	Identified by
Creator	The account that publishes content and earns. Owns chats, posts, media and links. An OAuth-connected app acts on a creator’s behalf.	`uuid`
Fan	A follower or subscriber who pays. Appears as `purchaser` or `buyer` on money objects and as `user` in chats.	`uuid`
Agency	Manages several creators. Agency endpoints span every managed creator and each row carries `creatorUuid`.	`uuid`, plus `creatorUuids` filters
App	Your integration: an OAuth client plus an optional App Store listing. Creators buy app plans and items. Fans pay through an app’s fan experiences.	`appUuid`, Client ID

Content objects

Object	Belongs to	The rule that matters
Chat / Message	Creator and fan pair	Messages carry `media_uuids`. Sync with Efficient chat sync rather than polling.
Post	Creator	Pay-per-view posts gate on purchase. Likes, comments and tips hang off the post `uuid`.
Media	Creator	The `uuid` is permanent. Variant URLs are signed and expire, so store ids and resolve URLs at display time (Work with media).
Vault folder	Creator	Addressed by exact display name, URL-encoded, not by id.
Smart list / custom list	Creator	Smart lists are built-in cohorts such as subscribers. Custom lists are hand-curated. Both are read with cursor pagination on `/v1`.
Dynamic list	Creator	A saved filter over relationship, spend, engagement and memory dimensions. Membership is computed on read. `/v1` only. Available to creators who have dynamic lists enabled (Dynamic lists).
Checkout link / product	Creator	A shareable `fvcl_` URL selling a product one-off or recurring (Create a checkout link).
Pricing plan / one-time item	App	What creators buy from your app (App billing).
Fan experience	Creator, published from an app	A fan surface the creator publishes with an access mode and priced actions. Fans pay the creator inside it (Fan experiences).

Money flow

Every sale is an invoice from a payer to an earner. Amounts are integers in minor units, USD cents on earnings endpoints, and each resource carries its own currency. The event catalogue lists every event by family.

Sale	Payer to earner	Events	Read back via
Tip, pay-per-view post, paid message, media	Fan to creator	`creator.payment.succeeded`, where `source` names the product	Earnings endpoints (conventions)
Profile subscription	Fan to creator	`creator.subscription.*` plus payment events	Subscribers endpoints
Checkout link sale	Fan, guest allowed, to creator	`checkout_link.*`	Payments ledger and the creator checkout-link payments endpoints
App plan or item	Creator to app developer	`app.*`	App payments and subscription endpoints
Fan experience access or priced action	Fan to creator, inside a fan surface	`creator.experience_subscription.activated` and `.deactivated` for access. `app.experience.action.*` for priced actions. `purchase.new` carries `experienceUuid`.	`GET /experiences`, `GET /experiences/{experienceUuid}/actions` and `GET /experiences/{experienceUuid}/action-purchases`. Earnings rows carry `experienceUuid`.
Withdrawal	Fanvue to creator	`payout.paid` and `payout.failed`	Payout history

Two rules hold across every family:

Money and access are separate events. A subscription’s first charge emits a payment event and an activation event. Fulfil access off the subscription event and reconcile revenue off the payment event.
Webhooks are notifications, not the ledger. A delivery can be delayed or missed. The REST read endpoints are the source of truth to reconcile against.

Join keys

These identifiers connect one surface to another. Store them, and you can match any webhook to the record your API calls return.

Key	Joins
Payment `data.id` (invoice number, for example `FV-12345`)	Payment webhooks, the `{invoiceNumber}` read endpoints and the Developer Area ledger
`subscription.id` / `subscription.uuid`	Payment events and subscription events for the same recurring sale
Plan UUID	The Pricing tab, deeplinks (`?plan=`), `plan.uuid` and `item.uuid` on `app.*` events, and the entitlement endpoints
`client_reference_id` plus `metadata`	Your system and every event for a checkout sale, including later refunds and disputes (Attribution)
`purchase_reference` with the `appotp_` or `appupg_` prefix	An app one-time purchase or plan upgrade across its payment, refund and dispute events
`purchase_reference` with the `expact_` prefix	An experience action purchase across `app.experience.action.*` events and `GET /experiences/{experienceUuid}/action-purchases/{purchaseReference}`
`experienceUuid`	Earnings rows, `creator.experience_subscription.*` events and the experience your app published
`creatorUuid`	Any agency-endpoint row and the managed creator it belongs to
Media `uuid`	Messages and posts and the media endpoints. Permanent, unlike the signed variant URLs

Start here

Authentication

API concepts

Guides

Fanvue object model

Roles

Content objects

Money flow

Join keys

​Roles

​Content objects

​Money flow

​Join keys

Roles

Content objects

Money flow

Join keys