> ## 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.
# Creator Payments
> creator.payment.succeeded for a creator's on-platform sales and subscription charges, and creator.reward.created / reversed for affiliate and referral earnings.
`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](#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](/docs/creator/overview#event-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.*`](/docs/creator/subscriptions). Join the two with
`subscription.id`.
Checkout-link sales are a separate surface and fire
[`checkout_link.payment.succeeded`](/docs/checkout/payments) 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](#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](#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](#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](/docs/creator/subscriptions), 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)
```json theme={null}
{
"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`](/docs/creator/subscriptions) carries as its `id`.
```json theme={null}
{
"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.
```json theme={null}
{
"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`
```json theme={null}
{
"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`.