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 is the successor to the legacy purchase.new and tip.new events, carrying the full money breakdown in one payload. creator.reward.created and creator.reward.reversed report a different kind of earning, affiliate and referral commission, and use their own resource. See Reward 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. Delivered in the Standard-Webhooks envelope; the fields below describe the data object.

Subscription money arrives here too. A profile subscription’s initial charge and every renewal fire creator.payment.succeeded with source: "subscription" and billing_reason subscription_initial / 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 today, and they cannot be subscribed to, do not build against them.

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
`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

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”.

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

Because link_url is last-touch across the whole platform while metadata is creator-scoped, the two can legitimately 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 does not record which surface a fan tipped from, so message here 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, but 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

Used by creator.reward.created and creator.reward.reversed. These 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.

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

Creator Payments

Payment resource

Attribution

Purchaser

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

​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

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`