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

# Purchase Received Webhook

> Webhook event fired when a purchase is made.

<Warning>
  `purchase.new` is deprecated. Use
  [`creator.payment.succeeded`](/docs/creator/payments) instead (`source` is `post`,
  `message`, or `media`). This event continues to fire during the migration
  window; new integrations should use the `creator.*` event.
</Warning>

## When this fires

Triggered (`purchase.new`) 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

Amounts are in minor units (for USD, cents).

<Note>
  On-platform refunds and disputes are delivered by the
  [`creator.refund.created` / `creator.dispute.*`](/docs/creator/refunds-disputes)
  events; checkout-link payments use
  [`checkout_link.refund.created`](/docs/checkout/refunds-disputes).
</Note>

## Payload

* `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)
* `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`](/docs/api-reference/get-earnings-data). 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). This is a snapshot at event time and may change as the payment matures. Included alongside `transactionOrderId`.
* `timestamp`: ISO 8601 time the event occurred

## Example payloads

### Post purchase

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
}
```

### 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`](/docs/checkout/payments).

```json theme={null}
{
  "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"
}
```