Fanvue API Documentation

This page maps the objects the Fanvue API exposes, who owns them, how money moves between them, and the identifiers that join one surface to another. Read it once; every other page assumes it.

Roles

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

Content objects

Object	Belongs to	The rule that matters
Chat / Message	Creator ↔ fan pair	Messages carry `media_uuids`; sync with Efficient Chat Sync rather than polling
Post	Creator	PPV posts gate on purchase; likes, comments, tips hang off the post `uuid`
Media	Creator	The `uuid` is permanent; variant URLs are signed and expire. Store IDs, resolve URLs at display time (Working with Media)
Vault folder	Creator	Addressed by exact display name, URL-encoded, not by id
Checkout link / product	Creator	A shareable `fvcl_` URL selling a product one-off or recurring (Accept Payments)
Pricing plan / one-time item	App	What creators buy from your app (App Payments)

Money flow

Every sale is an invoice (a payment) from a payer to an earner. Amounts are integers in minor units; each resource carries its own currency.

Sale	Payer → earner	Events	Read back via
Tip, PPV post, paid message, media	Fan → creator	`creator.payment.succeeded` (`source` tells you what)	Earnings endpoints
Profile subscription	Fan → creator	`creator.subscription.*` + payment events	Subscribers endpoints
Checkout link sale	Fan (guest OK) → creator	`checkout_link.*`	Payments ledger, agency checkout payments endpoints
App plan or item	Creator → app developer	`app.*`	App payments + subscription endpoints
Fan experience (one-time or subscription)	Fan → creator, inside a fan-facing app	No public webhook family yet	Experiences token endpoints in the API Reference
Withdrawal	Fanvue → creator	`payout.paid` / `payout.failed`	Payout history

Two rules apply 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, reconcile revenue off the payment event.
Webhooks are notifications, not the ledger. They can be missed or delayed; the REST read endpoints are the source of truth to reconcile against.

Join keys

The identifiers that connect one surface to another:

Key	Joins
Payment `data.id` (invoice number, e.g. `FV-12345`)	Payment webhooks ↔ `{invoiceNumber}` read endpoints ↔ the dashboard ledger
`subscription.id` / `subscription.uuid`	Payment events ↔ subscription events for the same recurring sale
Plan UUID	Builder Pricing tab ↔ deeplinks (`?plan=`) ↔ `plan.uuid` / `item.uuid` on `app.*` events ↔ entitlement endpoints
`client_reference_id` + `metadata`	Your system ↔ every event for a sale, including later refunds and disputes (Attribution)
`purchase_reference` (`appotp_` prefix)	An app one-time purchase across payment, refund, and dispute events
`creatorUuid`	Any agency-endpoint row ↔ the managed creator it belongs to
Media `uuid`	Messages and posts ↔ media endpoints; permanent, unlike the signed variant URLs

See also

Accept Payments, selling with checkout links
App Payments, charging creators for your app
Webhooks Overview, choosing an event family
Errors, recovery actions per error

⌘I