FAfanvue

Exchange a fan experience launch token

Changed on

Exchanges the opaque experience token an app's fan-experience surface received in its iframe URL for the resolved experience, the fan's identity, and the fan's entitlement to the experience.

The token is bound to the app that owns the experience: a token minted for one app cannot be exchanged with another app's credentials (403).

Returns 400 if the token is invalid or expired, 403 with `error: "experience_suspended"` if Fanvue has removed the experience (it comes back when reinstated), 403 with `error: "experience_not_approved"` if Fanvue has not approved the experience (it opens once approved), and 404 if the experience no longer exists.
post/experiences/token/exchange

Request

  • Base URL
    https://api.fanvue.com
  • URL
    https://api.fanvue.com/experiences/token/exchange
  • Auth
    OAuth 2
    Authorization code: https://auth.fanvue.com/oauth2/auth
    Token URL: https://auth.fanvue.com/oauth2/token scopes: read:experience

Headers

X-Fanvue-API-Versionstring required
Example:2025-06-26

API version to use for the request

Request body

tokenstring required

The opaque experience launch token appended to the surface iframe URL.

Example request

{
  "token": "exp_2f1c…"
}

Response

The resolved experience, fan identity, and entitlement

fanUuidstring uuid required
walletBalanceinteger nullable required

The fan's Fanvue wallet balance in minor units (cents, USD), so you can show their spending power as the surface loads. null when the wallet is not available to this fan at all, which is not the same as an empty balance — do not offer a wallet charge then. A snapshot, never an authorisation: charge with POST /experiences/{experienceUuid}/action-purchases and read the fresh balance off that response.

Example response

{
  "walletBalance": 2500
}

Changes

  • 966260af2770Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • info

      added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 to the response body anyOf list for the response status

  • 79b9aba8a759Revision changes
    • info

      added the required property / to the response with the status