Fanvue API Documentation

Two events report whether a fan’s paid fan-experience subscription currently grants access. They are the grant and revoke pair an app uses to open and close whatever the experience gates, a Discord or Telegram group for example.

Event (`type`)	Name in Developer Area	Fires when
`creator.experience_subscription.deactivated`	Experience Subscription Ended	The subscription stops granting access, for any reason
`creator.experience_subscription.activated`	Experience Subscription Started	The subscription starts granting access: a first purchase, or a failed renewal recovered by a later retry

Both require the read:experience scope, not the read:creator scope the rest of the creator.* domain uses. Both are delivered in the Standard-Webhooks envelope; the fields below describe the data object.

A fan-experience subscription is not a profile subscription. They are separate resources and a fan can hold both against the same creator at the same time, plus one per experience. creator.experience_subscription.deactivated says a fan lost access to one experience. It says nothing about their profile subscription, and revoking profile-gated content on it removes access the fan still pays for. Profile subscriptions ride creator.subscription.* with data.object: "subscription"; these events carry data.object: "experience_subscription". Discriminate on type or on data.object, never on the word “subscription”.

Access ended, not billing changed

A cancellation is not an access-ended signal. A fan turning auto-renew off keeps access until the period they paid for runs out. creator.experience_subscription.deactivated fires at that point, not at the moment they cancel.Key every revocation on access_ends_at and on the event arriving. Never key it on cancel_at_period_end being true, and never key it on expires_at alone, a refund, chargeback, ban or unpublish ends access mid-period and leaves expires_at in the future.Fan experiences have no intent-to-cancel event. creator.subscription.cancel_at_period_end_changed covers auto-renew changes for profile subscriptions only and has no fan-experience equivalent.

Delivery

These two topics do not use the creator.* delivery model. Other creator.* events fan out to every app holding the required scope for that creator. These reach only:

the app that owns the experience, resolved from the subscription’s own app.uuid, unconditionally, and
the creator’s connector destinations subscribed to the topic.

An experience subscription belongs to one app, so a creator-wide fan-out would tell app A which fans stopped paying app B. If your app does not own the experience, you do not receive the event, however many scopes you hold for that creator.

Experience subscription resource

Field	Type	Description
`object`	string	Always `"experience_subscription"`
`id`	string	The subscription’s own uuid. Stable across renewals, and reused if the fan lapses and resubscribes to the same experience
`status`	string	`expired` on `deactivated`, `active` on `activated`
`end_reason`	string	`deactivated` only. Why access ended, see End reasons. Always present on this event
`access_ends_at`	string	`deactivated` only. ISO 8601 moment access was revoked. This is the field to act on, it is not always `expires_at`
`activation_reason`	string	`activated` only. `subscribed` or `renewal_recovered`, see Activation reasons
`cancel_at_period_end`	boolean	Whether auto-renew was already off. On `deactivated`, `true` means the fan had cancelled and this event is the end of the period they had paid for
`cancelled_at`	string \| null	ISO 8601 time auto-renew was turned off. `null` when the fan never cancelled
`expires_at`	string \| null	ISO 8601 paid-through date of the last period the fan bought. Carried alongside `access_ends_at` so you can tell a mid-period revocation from a period-end one
`price`	integer \| null	The price the fan subscribed at, in minor units. Frozen at subscribe time, so it is not the amount of any particular charge
`created_at`	string \| null	ISO 8601 time the subscription was first created. Never advances on renewal
`experience`	object	`{ uuid }` of the experience
`app`	object	`{ uuid }` of the app that owns the experience
`fan`	object	`{ uuid }` of the fan. Carries no handle, display name or email, these are grant and revoke signals for a fan the receiving app already knows by uuid
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Always `{}` on these events

access_ends_at and expires_at agree only on a period-end cancellation. Every other end_reason revokes mid-period, leaving expires_at the later of the two. Compare them to tell the two cases apart: access_ends_at < expires_at means the fan lost time they had paid for.

End reasons

end_reason is a required discriminator on creator.experience_subscription.deactivated.

`end_reason`	Meaning
`cancelled`	The fan turned auto-renew off and the period they had paid for has now ended
`payment_failed`	The renewal charge was declined. A dunning retry may still restore access, see Activation reasons
`payment_method_invalid`	No usable stored payment method to renew with: none on file, or Pix, which cannot recur
`refunded`	The charge was refunded, so the access it bought was revoked with it
`chargeback`	The charge was charged back, so the access it bought was revoked with it
`experience_unavailable`	The experience stopped being sold as a recurring paid experience: unpublished, no longer sold under the paid access mode, re-priced as one-off, or its app was uninstalled
`creator_earnings_disabled`	The creator’s earnings were disabled, so Fanvue stopped billing for them
`account_closed`	The fan’s or the creator’s account was deleted or banned
`system_error`	A failure on Fanvue’s side left the fan charged but not entitled, so the charge was reversed

The payload carries no retry state. A payment_failed event tells you the charge that was due has been declined and access is gone as of access_ends_at, nothing more, any retry state would already be stale by the time you process it. Revoke on it and wait for creator.experience_subscription.activated.

Activation reasons

activation_reason is a required discriminator on creator.experience_subscription.activated.

`activation_reason`	Meaning
`subscribed`	The fan bought the subscription, access starts for the first time
`renewal_recovered`	A renewal charge that had previously failed was recovered by a dunning retry, restoring access

Handling renewal_recovered is required if you revoke on deactivated. A declined renewal revokes access and fires deactivated with end_reason: "payment_failed" before the dunning retries run. A retry that settles pays for the period and restores access. An app that revoked and never re-grants leaves a fan who has paid locked out permanently.

Example: `creator.experience_subscription.deactivated`

A cancellation reaching the end of its paid period, the one case where access_ends_at and expires_at agree.

{
  "id": "9b3c1d20-4d5e-4f60-8a71-1c2d3e4f5a60",
  "type": "creator.experience_subscription.deactivated",
  "timestamp": "2026-07-09T08:39:33.310Z",
  "data": {
    "object": "experience_subscription",
    "id": "7f2a91c4-58d3-4b0e-9c11-6a4e8b2d0f37",
    "status": "expired",
    "end_reason": "cancelled",
    "access_ends_at": "2026-07-09T08:39:33.139Z",
    "cancel_at_period_end": true,
    "cancelled_at": "2026-06-21T14:02:10.000Z",
    "expires_at": "2026-07-09T08:39:33.139Z",
    "price": 999,
    "created_at": "2026-05-09T08:39:33.139Z",
    "experience": { "uuid": "3d8f0b52-77a1-4c9e-b6d4-2e5a1f9c8b03" },
    "app": { "uuid": "c41e7a68-9b25-4d13-8f7a-0b6c2d94e5f1" },
    "fan": { "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3" },
    "creator": { "uuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12" },
    "metadata": {}
  }
}

A mid-period revocation carries the same shape with access_ends_at before expires_at:

{
  "id": "9b3c1d20-4d5e-4f60-8a71-1c2d3e4f5a61",
  "type": "creator.experience_subscription.deactivated",
  "timestamp": "2026-06-24T11:07:02.480Z",
  "data": {
    "object": "experience_subscription",
    "id": "7f2a91c4-58d3-4b0e-9c11-6a4e8b2d0f37",
    "status": "expired",
    "end_reason": "chargeback",
    "access_ends_at": "2026-06-24T11:07:02.311Z",
    "cancel_at_period_end": false,
    "cancelled_at": null,
    "expires_at": "2026-07-09T08:39:33.139Z",
    "price": 999,
    "created_at": "2026-05-09T08:39:33.139Z",
    "experience": { "uuid": "3d8f0b52-77a1-4c9e-b6d4-2e5a1f9c8b03" },
    "app": { "uuid": "c41e7a68-9b25-4d13-8f7a-0b6c2d94e5f1" },
    "fan": { "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3" },
    "creator": { "uuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12" },
    "metadata": {}
  }
}

Example: `creator.experience_subscription.activated`

The recovery case, the reason an app that revokes has to handle this topic.

{
  "id": "9b3c1d20-4d5e-4f60-8a71-1c2d3e4f5a62",
  "type": "creator.experience_subscription.activated",
  "timestamp": "2026-07-11T02:15:44.902Z",
  "data": {
    "object": "experience_subscription",
    "id": "7f2a91c4-58d3-4b0e-9c11-6a4e8b2d0f37",
    "status": "active",
    "activation_reason": "renewal_recovered",
    "cancel_at_period_end": false,
    "cancelled_at": null,
    "expires_at": "2026-08-09T08:39:33.139Z",
    "price": 999,
    "created_at": "2026-05-09T08:39:33.139Z",
    "experience": { "uuid": "3d8f0b52-77a1-4c9e-b6d4-2e5a1f9c8b03" },
    "app": { "uuid": "c41e7a68-9b25-4d13-8f7a-0b6c2d94e5f1" },
    "fan": { "uuid": "5939ae62-3eb5-4433-954f-f78c7b4282f3" },
    "creator": { "uuid": "f4b2a184-2b4a-4a04-9b70-3c0e0a1caa12" },
    "metadata": {}
  }
}

Revoking access on subscription end

Gate the resource on one pair of handlers: revoke on deactivated, grant on activated. Verify the signature first, return 2xx immediately, and do the revocation out of band, see Delivery, Retries and Idempotency.

// Fanvue delivers both topics to the same endpoint. Discriminate on `type`.
app.post("/fanvue/webhooks", async (req, res) => {
  const event = verifySignature(req); // see /webhooks/signature-verification
  res.sendStatus(200); // ack first, act after

  const sub = event.data;
  if (sub.object !== "experience_subscription") return;

  // Key on (experience, fan). `id` is reused when a fan lapses and resubscribes,
  // so it identifies the subscription, not one span of access.
  const member = { experienceUuid: sub.experience.uuid, fanUuid: sub.fan.uuid };

  if (event.type === "creator.experience_subscription.deactivated") {
    // access_ends_at, not expires_at: a refund, chargeback, ban or unpublish
    // revokes mid-period and leaves expires_at in the future.
    await removeFromGroup(member, {
      at: sub.access_ends_at,
      reason: sub.end_reason,
      // access_ends_at < expires_at means the fan lost time they had paid for.
      lostPaidTime: sub.expires_at !== null && sub.access_ends_at < sub.expires_at,
    });
    return;
  }

  if (event.type === "creator.experience_subscription.activated") {
    // Required counterpart. `renewal_recovered` follows a payment_failed
    // revocation you have already acted on; without this the fan stays out.
    await addToGroup(member);
  }
});

Two rules this handler encodes:

Revoke on the event, not on a cancellation. cancel_at_period_end: true on a deactivated event is context, it tells you the fan chose to leave rather than failed to pay. It is never itself the trigger.
Always pair revoke with grant. Revoking on deactivated without handling activated permanently locks out any fan whose renewal recovered after a declined charge.

Access can also lapse silently at expires_at. A subscription grants access only while it is not deleted and expires_at is in the future. The hourly expiry sweep defers a row when a renewal is still settling or an upstream lookup fails, so the fan loses access on the clock and no event is sent until a later sweep resolves the row. Treat expires_at as a deadline in its own right: expire your own cached grant at expires_at and let activated extend it, rather than waiting only for deactivated.

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

Creator Experience Subscriptions

Access ended, not billing changed

Delivery

Experience subscription resource

End reasons

Activation reasons

Example: `creator.experience_subscription.deactivated`

Example: `creator.experience_subscription.activated`

Revoking access on subscription end

See also

​Access ended, not billing changed

​Delivery

​Experience subscription resource

​End reasons

​Activation reasons

​Example: creator.experience_subscription.deactivated

​Example: creator.experience_subscription.activated

​Revoking access on subscription end

​See also

Access ended, not billing changed

Delivery

Experience subscription resource

End reasons

Activation reasons

Example: `creator.experience_subscription.deactivated`

Example: `creator.experience_subscription.activated`

Revoking access on subscription end

See also