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

# New Subscriber Webhook

> Webhook event fired when a creator gains a new subscriber.

<Warning>
  `subscription.new` is deprecated. Use
  [`creator.subscription.activated`](/docs/creator/subscriptions) instead. This event
  continues to fire during the migration window; new integrations should use the
  `creator.*` event.
</Warning>

## When this fires

Triggered when a user takes out a **paid** subscription to a creator.

<Note>
  This is the paid subscription event. A free follow does not fire this event;
  free follows come through the separate [New Follower](/docs/webhooks/new-follower)
  event (`follow.new`).
</Note>

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

## Payload

This single event carries **both** the subscription detail and the payment information, so you do not need a separate payment event to obtain the amount charged.

* `price`: The amount actually charged for this subscription, in minor units
* `subscription`: The subscriber's subscription detail. Omitted when the subscription row cannot be resolved at emission time. Fields:
  * `status`: `active`, `cancelled`, `pending_confirmation`, or `paused`
  * `price`: The plan's list (original) price, in minor units — the amount charged on renewal
  * `currentPeriodStart`: ISO 8601 start of the current period, anchored on the latest paid charge. Falls back to the subscription's creation time when nothing has been charged yet (for example, a fan still inside a free trial)
  * `currentPeriodEnd`: ISO 8601 end of the current period, or `null` if the subscription has no expiry set
  * `autoRenewalEnabled`: Whether the subscription is in an auto-renewing state. This reflects the renewal setting only — not whether a future charge would succeed
* `recipientUuid`: UUID of the creator who was subscribed to
* `sender`: The user who subscribed (uuid, handle, displayName, avatarUrl)
* `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 (for example, a free trial with no billable transaction).
* `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

<Note>
  **`price` vs `subscription.price`.** `price` is what the fan actually paid;
  `subscription.price` is the plan's list price and the amount they would be
  charged on renewal. They differ when a discount applies. For a paid plan with
  a 100%-off promotion the fan pays nothing, so `price` is `0` while
  `subscription.price` stays the plan price. There is no coupon field on the
  payload, so compare the two amounts to detect a discount.
</Note>

<Note>
  The `subscription` object carries the same fields as the `subscription` field
  on [Get creator subscribers](/docs/api-reference/get-creator-subscribers), so you
  get the same subscription state whether you poll that endpoint or consume this
  event. Note that neither carries the amount actually charged — for that, use
  the top-level `price` on this event.
</Note>

## Example payload

```json theme={null}
{
  "price": 1299,
  "subscription": {
    "status": "active",
    "price": 1299,
    "currentPeriodStart": "2025-11-06T10:32:50.529Z",
    "currentPeriodEnd": "2025-12-06T10:32:50.529Z",
    "autoRenewalEnabled": true
  },
  "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:50.529Z"
}
```