Fanvue API Documentation

creator.subscription.* events track the lifecycle of a fan’s profile subscription to a creator, separately from the money, which arrives on creator.payment.succeeded.

Event (`type`)	Fires when
`creator.subscription.activated`	A subscription becomes active (new subscriber or a lapsed one re-subscribes)
`creator.subscription.renewed`	An uninterrupted subscription renews for another billing period
`creator.subscription.deactivated`	A subscription ends and the fan loses access
`creator.subscription.cancel_at_period_end_changed`	Auto-renew is turned off or back on; access continues until `expires_at`

All four require the read:creator scope. Each event arrives in the envelope, and the tables below describe data. A typical churn sequence is cancel_at_period_end_changed (auto-renew off, access continues) followed by deactivated when the paid period runs out. A failed renewal can deactivate a subscription with no prior cancel_at_period_end_changed. The four events replace these legacy events:

Legacy event	Replacement
`subscription.new`	`creator.subscription.activated`
`subscription.renewed`	`creator.subscription.renewed`
`subscription.cancelled`	`creator.subscription.cancel_at_period_end_changed`
`subscription.expired`	`creator.subscription.deactivated`

activated vs renewed

Both report a subscription that is active and set to renew. They differ in what happened.

creator.subscription.renewed means the fan’s access never lapsed and the subscription rolled straight into a new billing period. Read expires_at and current_period_start off this event. The money for the same cycle arrives on creator.payment.succeeded with billing_reason: "subscription_renewal".
creator.subscription.activated means access is being granted where there was none. That covers a new subscriber, a lapsed fan re-subscribing, or a renewal that only succeeded after the subscription had already been deactivated.

Take renewed if you cache expires_at. Without it a cached period goes stale every cycle, because the payment event carries the money but no new dates.

Subscription resource

Field	Type	Description
`object`	string	Always `"subscription"`
`id`	string \| null	Correlation token, the subscription’s initial-payment invoice number. Carried on `activated` and `renewed`; `null` on `deactivated` and `cancel_at_period_end_changed`
`status`	string	`active` on `activated`, `renewed` and `cancel_at_period_end_changed`; `expired` on `deactivated`
`cancel_at_period_end`	boolean	Whether auto-renew is currently off
`auto_renew`	boolean	The inverse of `cancel_at_period_end`, so you don’t have to negate it
`price`	integer \| null	The price the fan signed up at, in minor units (USD cents). Carried unconditionally; the signup price, not the amount charged
`expires_at`	string \| null	ISO 8601 end of the current billing cycle. Set whether or not the subscription will renew
`current_period_start`	string \| null	ISO 8601 start of the current billing cycle, the most recent paid charge. Falls back to `created_at` for a fan with no paid charge yet
`renew_date`	string \| null	ISO 8601 next renewal date. `null` unless a charge will actually occur
`renew_price`	integer \| null	The same signup price as `price`. `null` unless a charge will actually occur
`created_at`	string \| null	ISO 8601 time the subscription was first created. Never advances on renewal or resubscribe
`deactivation_reason`	string \| null	On `deactivated`: `payment_failed`, `not_renewed`, `user_deleted`, `user_banned`, or `other`. On a cancellation: `subscriber_requested`, `creator_blocked`, or `moderation`. `null` on `activated`, `renewed`, and a reactivation
`client_reference_id`	string \| null	Your passthrough reference from the original purchase
`purchaser`	object	The subscriber, see Purchaser. `email` is always `null`
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Your passthrough metadata map, echoed from the original purchase
`tracking`	object \| null	Tracking-link attribution for the subscriber, see Tracking

status is never "cancelled". A cancelled-but-still-active subscription reports status: "active" with cancel_at_period_end: true, and the fan keeps access until expires_at. Only deactivated reports expired. Gate access on expires_at and cancel_at_period_end, not on status alone.

price is the signup price, not the amount charged. A discount or free trial makes the charged amount differ. A creator who changes their subscription price bills the new price on renewal, and Fanvue doesn’t rewrite this value. For the amount actually taken, read gross on the correlated creator.payment.succeeded. Use current_period_start, not created_at, for “since when is this fan on their current period”. created_at is the first-ever subscription date and never advances, so it reports a stale period for any returning subscriber. current_period_start falls back to created_at for a fan with no paid charge yet, for example one still inside a free trial. cancel_at_period_end is false on a deactivated subscription that ran out. The field reports the auto-renew flag at the moment of deactivation, not whether the fan had cancelled earlier. To tell voluntary churn from a failed renewal, look for the preceding cancel_at_period_end_changed or read deactivation_reason.

Tracking

tracking travels on every creator.subscription.* event and carries the subscriber’s tracking-link attribution as { link_url, metadata }. The block is null when the subscriber carries neither a tracking parameter nor an impression on one of this creator’s links.

Field	Type	Description
`link_url`	string \| null	The subscriber’s stored tracking-link parameter. Platform-wide last-touch, not scoped to this creator
`metadata`	object	Latest tracking-link impression metadata for this creator

The lookup is best-effort. A failed lookup sends tracking: null rather than dropping the event, so null means “none recorded or not resolved”.

Correlating with the money

Native profile subscriptions have no external UUID, so the identity is the (purchaser, creator) pair. id is a correlation token, the subscription’s initial-payment invoice number, carried on activated and renewed. subscription.id here equals payment.subscription.id on creator.payment.succeeded, so you can join the access event to the money event. The token is null on deactivated and cancel_at_period_end_changed, so key your own records on the (purchaser, creator) pair rather than on id.

Examples

`creator.subscription.activated`

{
  "id": "f1a2b3c4-2222-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.subscription.activated",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "subscription",
    "id": "FV-12345",
    "status": "active",
    "cancel_at_period_end": false,
    "auto_renew": true,
    "price": 999,
    "expires_at": "2026-07-09T08:39:33.139Z",
    "current_period_start": "2026-06-09T08:39:33.139Z",
    "renew_date": "2026-07-09T08:39:33.139Z",
    "renew_price": 999,
    "created_at": "2026-06-09T08:39:33.139Z",
    "deactivation_reason": null,
    "client_reference_id": "crm-contact-8821",
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "campaign": "spring-promo" },
    "tracking": {
      "link_url": "https://fanvue.com/creator-handle?fvc=spring-promo",
      "metadata": { "campaign": "spring-promo", "source": "x" }
    }
  }
}

`creator.subscription.renewed`

The same shape, with the billing period rolled forward. created_at is unchanged because it is the first-ever subscription date.

{
  "id": "f1a2b3c4-2223-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.subscription.renewed",
  "timestamp": "2026-07-09T08:39:33.139Z",
  "data": {
    "object": "subscription",
    "id": "FV-12345",
    "status": "active",
    "cancel_at_period_end": false,
    "auto_renew": true,
    "price": 999,
    "expires_at": "2026-08-09T08:39:33.139Z",
    "current_period_start": "2026-07-09T08:39:33.139Z",
    "renew_date": "2026-08-09T08:39:33.139Z",
    "renew_price": 999,
    "created_at": "2026-06-09T08:39:33.139Z",
    "deactivation_reason": null,
    "client_reference_id": "crm-contact-8821",
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "campaign": "spring-promo" },
    "tracking": null
  }
}

`creator.subscription.deactivated`

Access has ended, so renew_date and renew_price are null and id is not carried.

{
  "id": "f1a2b3c4-3333-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.subscription.deactivated",
  "timestamp": "2026-07-09T08:39:33.139Z",
  "data": {
    "object": "subscription",
    "id": null,
    "status": "expired",
    "cancel_at_period_end": false,
    "auto_renew": true,
    "price": 999,
    "expires_at": "2026-07-09T08:39:33.139Z",
    "current_period_start": "2026-06-09T08:39:33.139Z",
    "renew_date": null,
    "renew_price": null,
    "created_at": "2026-06-09T08:39:33.139Z",
    "deactivation_reason": "not_renewed",
    "client_reference_id": "crm-contact-8821",
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "campaign": "spring-promo" },
    "tracking": null
  }
}

`creator.subscription.cancel_at_period_end_changed`

Auto-renew has been turned off. status stays active and the fan keeps access until expires_at, while renew_date and renew_price go null because no charge will occur. Turning auto-renew back on emits the same event with cancel_at_period_end: false, auto_renew: true, and the renewal fields repopulated.

{
  "id": "f1a2b3c4-3334-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.subscription.cancel_at_period_end_changed",
  "timestamp": "2026-06-20T09:00:00.000Z",
  "data": {
    "object": "subscription",
    "id": null,
    "status": "active",
    "cancel_at_period_end": true,
    "auto_renew": false,
    "price": 999,
    "expires_at": "2026-07-09T08:39:33.139Z",
    "current_period_start": "2026-06-09T08:39:33.139Z",
    "renew_date": null,
    "renew_price": null,
    "created_at": "2026-06-09T08:39:33.139Z",
    "deactivation_reason": "subscriber_requested",
    "client_reference_id": "crm-contact-8821",
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "campaign": "spring-promo" },
    "tracking": null
  }
}

Billing cycle length

The creator.subscription.* payloads don’t carry the billing cycle length, so read it off subscription.intervalMonths on GET /subscribers, GET /subscribers/{userUuid}, and GET /creators/{creatorUserUuid}/subscribers. intervalMonths is the cycle length of the fan’s current period, in whole months. The value is 1 for a standard monthly subscription, or 3, 6 or 12 for a fan who signed up on a multi-month bundle.

currentPeriodEnd minus currentPeriodStart is not the cycle, and neither is expires_at minus current_period_start on these events. The two dates come off different clocks. The end is the subscription’s stored expiry, while the start is the timestamp of the latest successful charge. A renewal that fails and only settles on a later retry moves the start without moving the plan. A signup charge that settles after it was quoted shortens the span to less than the months sold. Use intervalMonths, and read the dates only as when this period started and when it runs out.

A bundle buys a longer first period only. Once it renews, the subscription bills monthly at the creator’s current price, and intervalMonths reports 1 from then on. That is the real billing behaviour, not a rounding of the original plan. intervalMonths is null where there is no whole-month cycle to report. That happens for a fan inside a free trial, whose period is a trial length in days rather than a billing cycle, and for a fan with no subscription charge on record.

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Creator subscription events

activated vs renewed

Subscription resource

Tracking

Correlating with the money

Examples

`creator.subscription.activated`

`creator.subscription.renewed`

`creator.subscription.deactivated`

`creator.subscription.cancel_at_period_end_changed`

Billing cycle length

​activated vs renewed

​Subscription resource

​Tracking

​Correlating with the money

​Examples

​creator.subscription.activated

​creator.subscription.renewed

​creator.subscription.deactivated

​creator.subscription.cancel_at_period_end_changed

​Billing cycle length

activated vs renewed

Subscription resource

Tracking

Correlating with the money

Examples

`creator.subscription.activated`

`creator.subscription.renewed`

`creator.subscription.deactivated`

`creator.subscription.cancel_at_period_end_changed`

Billing cycle length