Fanvue API Documentation

creator.payment.succeeded fires when an on-platform payment to the creator settles: a paid post, a locked (PPV) message, a media purchase, a tip or a profile-subscription charge. It replaces the legacy purchase.new and tip.new events and carries the full money breakdown in one payload. The two reward events report affiliate and referral commission and use their own resource.

Event (`type`)	Resource	Fires when
`creator.payment.succeeded`	payment	An on-platform payment to the creator succeeds
`creator.reward.created`	reward	An affiliate or referral commission is earned by the creator
`creator.reward.reversed`	reward	A previously earned commission is clawed back

All three require the read:creator scope. Each event arrives in the envelope, and the tables below describe data. Subscription money arrives on creator.payment.succeeded too. A profile subscription’s initial charge and every renewal fire it with source: "subscription" and billing_reason subscription_initial or subscription_renewal, alongside the access-state event on creator.subscription.*. Join the two with subscription.id. Checkout-link sales are a separate surface and fire checkout_link.payment.succeeded instead. creator.payment.pending and creator.payment.failed are reserved names. No Fanvue code path emits them and they can’t be subscribed to, so don’t build against them. Get earnings data is the API view of the same charges.

Payment resource

Field	Type	Description
`object`	string	Always `"payment"`
`id`	string	Fanvue invoice number for the charge
`status`	string	Always `"succeeded"` for this event
`source`	string	What was bought: `post`, `message`, `media`, `tip`, or `subscription`
`billing_reason`	string	`one_time`, `subscription_initial`, or `subscription_renewal`
`gross`	integer	Gross amount in minor units
`net`	integer \| null	Creator net after fees, in minor units
`fees`	object	`{ fanvue_fee, transaction_fee }`, each integer minor units or `null`
`currency`	string \| null	ISO 4217 currency code
`paid_in_full`	boolean	Always `true`, this event only fires for a settled charge
`client_reference_id`	string \| null	Reserved; always `null` on this event. See Attribution
`transaction_id`	string \| null	Reserved; always `null` on this event. See Test deliveries
`post_uuid`	string \| null	The post the charge came from: a paid post, or a tip sent on a post. `null` otherwise
`message_uuid`	string \| null	The chat message the charge came from, for a paid-message unlock. `null` otherwise, including for tips
`message_type`	string \| null	Chat message type for `source: "message"`, e.g. `SINGLE_RECIPIENT`, `BROADCAST`, an `AUTOMATED_*` value. `null` for every other source
`tip_context`	string \| null	For `source: "tip"` only: `post` when the tip was sent on a post, otherwise `message`. `null` for every other source
`created_at`	string \| null	ISO 8601 settlement time, the same value as `paid_at`
`paid_at`	string \| null	ISO 8601 time the payment settled
`subscription`	object \| null	`{ id }` correlating a `source: "subscription"` charge to its `creator.subscription.*` event. `null` for one-time charges
`purchaser`	object	The buyer, see Purchaser
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Reserved; always `{}` on this event
`tracking`	object \| null	Tracking-link attribution for the buyer, see Tracking. `null` when the buyer has none

Amounts are integers in USD cents; Units and currency explains gross, net and the fees.

Attribution

Unlike the checkout-link surface, creator.payment.succeeded does not carry your passthrough attribution. client_reference_id is always null, metadata is always {}, and transaction_id is always null; the keys are present for shape parity only. Attribution that was captured at signup survives on the subscription events, which do echo real values.

Purchaser

Field	Type	Description
`uuid`	string	The buyer’s user UUID
`email`	null	Always `null`. Present for shape parity only; never populated
`handle`	string	The buyer’s public handle. Omitted when the identity lookup fails
`display_name`	string	The buyer’s display name. Omitted when the identity lookup fails

handle and display_name are omitted from the payload rather than sent as null, so treat an absent key as “not resolved”.

Test deliveries

Test deliveries sent from the Developer Area differ from production in two fields. A test payload sets purchaser.email to test@example.com and transaction_id to the payment id, while a production payload sends null for both. Don’t build on either value.

Tracking

tracking is null when the buyer carries neither a tracking parameter nor an impression on one of this creator’s links. When present:

Field	Type	Description
`link_url`	string \| null	The buyer’s stored tracking-link parameter. Platform-wide last-touch, not scoped to this creator
`metadata`	object	Latest tracking-link impression metadata for this creator

link_url is last-touch across the whole platform while metadata is creator-scoped, so the two can disagree. A fan who arrived through creator A’s link and later buys from creator B reports A’s link here.

Example: `creator.payment.succeeded` (paid message)

{
  "id": "f1a2b3c4-1111-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.payment.succeeded",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "payment",
    "id": "FV-12345",
    "status": "succeeded",
    "source": "message",
    "billing_reason": "one_time",
    "gross": 1999,
    "net": 1799,
    "fees": { "fanvue_fee": 200, "transaction_fee": 0 },
    "currency": "USD",
    "paid_in_full": true,
    "client_reference_id": null,
    "transaction_id": null,
    "post_uuid": null,
    "message_uuid": "2f7c5e8a-6d36-4e3a-98d9-9f1b3b0a1a10",
    "message_type": "SINGLE_RECIPIENT",
    "tip_context": null,
    "created_at": "2026-06-09T08:39:33.139Z",
    "paid_at": "2026-06-09T08:39:33.139Z",
    "subscription": null,
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {},
    "tracking": {
      "link_url": "https://fanvue.com/creator-handle?fvc=summer-campaign",
      "metadata": { "campaign": "summer", "source": "x" }
    }
  }
}

Example: `creator.payment.succeeded` (subscription renewal)

The renewal charge for a profile subscription. subscription.id is the subscription’s initial-payment invoice number, the same token creator.subscription.renewed carries as its id.

{
  "id": "f1a2b3c4-1112-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.payment.succeeded",
  "timestamp": "2026-07-09T08:39:33.139Z",
  "data": {
    "object": "payment",
    "id": "FV-12999",
    "status": "succeeded",
    "source": "subscription",
    "billing_reason": "subscription_renewal",
    "gross": 999,
    "net": 899,
    "fees": { "fanvue_fee": 100, "transaction_fee": 0 },
    "currency": "USD",
    "paid_in_full": true,
    "client_reference_id": null,
    "transaction_id": null,
    "post_uuid": null,
    "message_uuid": null,
    "message_type": null,
    "tip_context": null,
    "created_at": "2026-07-09T08:39:33.139Z",
    "paid_at": "2026-07-09T08:39:33.139Z",
    "subscription": { "id": "FV-12345" },
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {},
    "tracking": null
  }
}

Example: `creator.payment.succeeded` (tip on a post)

A tip sent on a post carries post_uuid and tip_context: "post". A tip sent anywhere else reports tip_context: "message" with post_uuid: null. Fanvue doesn’t record which surface a fan tipped from, so message means “not on a post” and is not evidence of a chat origin.

{
  "id": "f1a2b3c4-1113-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.payment.succeeded",
  "timestamp": "2026-06-09T09:02:11.000Z",
  "data": {
    "object": "payment",
    "id": "FV-12500",
    "status": "succeeded",
    "source": "tip",
    "billing_reason": "one_time",
    "gross": 500,
    "net": 450,
    "fees": { "fanvue_fee": 50, "transaction_fee": 0 },
    "currency": "USD",
    "paid_in_full": true,
    "client_reference_id": null,
    "transaction_id": null,
    "post_uuid": "217d5dc9-cae0-4c09-b643-2e3aa498587a",
    "message_uuid": null,
    "message_type": null,
    "tip_context": "post",
    "created_at": "2026-06-09T09:02:11.000Z",
    "paid_at": "2026-06-09T09:02:11.000Z",
    "subscription": null,
    "purchaser": { "uuid": "fan-uuid", "email": null, "handle": "janed", "display_name": "Jane D" },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {},
    "tracking": null
  }
}

message_uuid is not a way to tell a chat tip from a post tip. Every paid tip writes a TIP chat message into the thread. That write happens after this event’s invoice snapshot is taken, so message_uuid is absent here even though GET /insights/earnings reports it for the same transaction. Use tip_context and post_uuid.

Reward resource

creator.reward.created and creator.reward.reversed share this resource. Rewards are account-level affiliate and referral earnings, not a sale to the creator’s own fans, so there is no purchaser.

creator.reward.created fires when a commission invoice is generated for the earner, a referral commission for a referrer, or an affiliate commission for an affiliate-link owner.
creator.reward.reversed fires when that commission is clawed back because the underlying sale was refunded or charged back. It carries the same id.

Field	Type	Description
`object`	string	Always `"reward"`
`id`	string	Commission invoice number. Identical on the `created` and `reversed` pair
`amount`	integer	Commission amount in minor units
`currency`	string \| null	ISO 4217 currency code
`source_payment_id`	string \| null	Invoice number of the originating sale the commission was calculated from
`referred_creator`	object \| null	`{ uuid }` of the creator whose sale generated the commission; `null` when not a referral
`creator`	object	`{ uuid }` of the reward recipient, the creator this event is delivered to
`created_at`	string \| null	ISO 8601 time the commission invoice was created
`metadata`	object	Reserved; always `{}` on this event

Example: `creator.reward.created`

{
  "id": "f1a2b3c4-1114-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.reward.created",
  "timestamp": "2026-06-09T08:45:00.000Z",
  "data": {
    "object": "reward",
    "id": "FVR-4455",
    "amount": 500,
    "currency": "USD",
    "source_payment_id": "FV-12345",
    "referred_creator": { "uuid": "referred-creator-uuid" },
    "creator": { "uuid": "creator-uuid" },
    "created_at": "2026-06-09T08:45:00.000Z",
    "metadata": {}
  }
}

creator.reward.reversed uses the identical shape with "type": "creator.reward.reversed" and the same id as the original creator.reward.created.

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Creator payment events

Payment resource

Attribution

Purchaser

Test deliveries

Tracking

Example: `creator.payment.succeeded` (paid message)

Example: `creator.payment.succeeded` (subscription renewal)

Example: `creator.payment.succeeded` (tip on a post)

Reward resource

Example: `creator.reward.created`

​Payment resource

​Attribution

​Purchaser

​Test deliveries

​Tracking

​Example: creator.payment.succeeded (paid message)

​Example: creator.payment.succeeded (subscription renewal)

​Example: creator.payment.succeeded (tip on a post)

​Reward resource

​Example: creator.reward.created

Payment resource

Attribution

Purchaser

Test deliveries

Tracking

Example: `creator.payment.succeeded` (paid message)

Example: `creator.payment.succeeded` (subscription renewal)

Example: `creator.payment.succeeded` (tip on a post)

Reward resource

Example: `creator.reward.created`