Fanvue API Documentation

purchase.new is the deprecated flat event for a user buying a paid item from a creator. It requires the read:creator scope, and new integrations use creator.payment.succeeded instead, where source is post, message or media.

Don’t build new integrations on purchase.new. It keeps firing during the migration window, after which only creator.payment.succeeded is delivered. Subscribe to creator.payment.succeeded and move existing consumers before the window closes.

When this fires

purchase.new fires when a user buys a paid item from a creator. An item is one of:

a paid post, the payload carries postUuid
a locked (PPV) message, the payload carries routeUuid
a checkout-link product, neither postUuid nor routeUuid is present
a fan experience, the payload carries experienceUuid and experienceAppUuid

Amounts are in minor units (for USD, cents). purchase.new has no refund or dispute counterpart. On-platform refunds and disputes are delivered by the creator.refund.created and creator.dispute.* events, and checkout-link payments use checkout_link.refund.created.

Payload

Field	Description
`postUuid`	UUID of the purchased post/content (included if the purchase was for a post)
`routeUuid`	UUID of the purchased message (included if the purchase was for a message)
`price`	Purchase amount in minor units
`recipientUuid`	UUID of the creator who received the purchase
`sender`	The user who purchased (uuid, handle, displayName, avatarUrl)
`experienceUuid`	UUID of the fan experience the purchase was for. Only on fan-experience purchases, and always paired with `experienceAppUuid`. The same UUID your app receives as `experience.uuid` when a launch token is exchanged, so it joins directly to your own experience records.
`experienceAppUuid`	UUID of the app the experience belongs to. Present whenever `experienceUuid` is.
`trackingLinkId`	Tracking link attributed to the purchaser, if one is set (omitted otherwise)
`transactionOrderId`	The Fanvue transaction/order identifier for this payment, matching the `transactionOrderId` on `/insights/earnings`. Lets you reconcile the event against earnings without a second call. Included when the payment has settled; omitted otherwise.
`transactionOrderStatus`	Payout state of the transaction at the time of the event, `availableForPayout` (cleared) or `pendingBalance` (still in the chargeback/fraud retention window). It is a snapshot at event time and may change as the payment matures. Included alongside `transactionOrderId`.
`timestamp`	ISO 8601 time the event occurred

The experience fields are scoped to the app that owns the experience. The rest of the payload fans out to every app holding the required scope for that creator. experienceUuid and experienceAppUuid reach only the owning app and the creator’s own connector destinations. Every other consenting app receives the same purchase without them, so a creator-wide fan-out cannot tell app A which experience of app B a fan just bought.

Example payloads

Post purchase

{
  "postUuid": "217d5dc9-cae0-4c09-b643-2e3aa498587a",
  "price": 2499,
  "recipientUuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12",
  "sender": {
    "avatarUrl": "https://via.placeholder.com/150",
    "displayName": "Test User",
    "handle": "test-user",
    "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3"
  },
  "transactionOrderId": "FV-ORDER-12345",
  "transactionOrderStatus": "availableForPayout",
  "timestamp": "2025-11-06T10:32:51.259Z"
}

Message purchase

{
  "routeUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "price": 1999,
  "recipientUuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12",
  "sender": {
    "avatarUrl": "https://via.placeholder.com/150",
    "displayName": "Test User",
    "handle": "test-user",
    "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3"
  },
  "transactionOrderId": "FV-ORDER-12346",
  "transactionOrderStatus": "pendingBalance",
  "timestamp": "2025-11-06T10:32:51.259Z"
}

Fan experience purchase

A one-off purchase of a paid fan experience. Recurring subscription charges for an experience don’t fire purchase.new; see Creator experience subscription events for the access lifecycle and for how to reconcile recurring revenue. Payments inside experiences describes the money flow on the app side.

{
  "price": 1500,
  "recipientUuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12",
  "experienceUuid": "1ff6b4a0-9d54-4d3a-9f43-8a1cbb5d2f10",
  "experienceAppUuid": "c0a8f2e1-7b3d-4c5a-8e9f-2d1b6a4c8e30",
  "sender": {
    "avatarUrl": "https://via.placeholder.com/150",
    "displayName": "Test User",
    "handle": "test-user",
    "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3"
  },
  "transactionOrderId": "FV-ORDER-12347",
  "transactionOrderStatus": "availableForPayout",
  "timestamp": "2025-11-06T10:32:51.259Z"
}

Checkout-link product purchase

A purchase of an off-platform checkout-link product fires purchase.new with neither postUuid nor routeUuid. For link-level detail (product, billing reason) subscribe to checkout_link.payment.succeeded.

{
  "price": 9999,
  "recipientUuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12",
  "sender": {
    "avatarUrl": "https://via.placeholder.com/150",
    "displayName": "Test User",
    "handle": "test-user",
    "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3"
  },
  "timestamp": "2025-11-06T10:32:51.259Z"
}

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Purchase Received Webhook (deprecated)

When this fires

Payload

Example payloads

Post purchase

Message purchase

Fan experience purchase

Checkout-link product purchase

​When this fires

​Payload

​Example payloads

​Post purchase

​Message purchase

​Fan experience purchase

​Checkout-link product purchase

When this fires

Payload

Example payloads

Post purchase

Message purchase

Fan experience purchase

Checkout-link product purchase