Payload of the deprecated flat subscription.new webhook, fired for a new paid subscription, and its replacement creator.subscription.activated.
subscription.new is the deprecated flat event for a user taking out a paid subscription to a creator. It requires the read:creator scope, and new integrations use creator.subscription.activated instead.
Don’t build new integrations on subscription.new. It keeps firing during the migration window, after which only creator.subscription.activated is delivered. Subscribe to creator.subscription.activated and move existing consumers before the window closes.
subscription.new fires when a user takes out a paid subscription to a creator. A free follow doesn’t fire it; free follows come through the separate New Follower event (follow.new).Amounts are in minor units (for USD, cents).
The payload carries both the subscription detail and the payment information, so you don’t need a separate payment event to get the amount charged.
Field
Description
price
The amount charged for this subscription, in minor units
subscription
The subscriber’s subscription detail. Omitted when the subscription row cannot be resolved at emission time.
subscription.status
active, cancelled, pending_confirmation, or paused
subscription.price
The plan’s list (original) price, in minor units, the amount charged on renewal
subscription.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)
subscription.currentPeriodEnd
ISO 8601 end of the current period, or null if the subscription has no expiry set
subscription.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)
trackingLinkId
The tracking link the subscriber arrived through. Omitted when the subscriber has no tracking link attribution
trackingLinkUrl
The same value as trackingLinkId. Omitted together with it
trackingLinkMetadata
The per-user metadata captured on that tracking link for this creator, as a string map. Omitted when none was captured
clientReferenceId
The attribution reference captured on the subscription purchase. Omitted when the subscription was not attributed. See Checkout attribution
metadata
The custom metadata captured on the subscription purchase. Omitted when none was set
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 (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). It is a snapshot at event time and may change as the payment matures. Included alongside transactionOrderId.
timestamp
ISO 8601 time the event occurred
price vs subscription.price.price is what the fan paid, and 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.The subscription object carries the same fields as the subscription field on Get creator subscribers, with one exception: intervalMonths, the plan’s billing cycle length, is on the endpoint only. You get the same subscription state whether you poll that endpoint or consume this event, but take the cycle length from the endpoint; see Billing cycle length. Neither carries the amount charged. For that, use the top-level price on this event.
