App Subscriptions

If you’re building a Fanvue app with App Store pricing, you can use the app subscription endpoints to read:

• the pricing lifecycle for a developer-owned app
• the authenticated user’s current subscription entitlement for that app

These are read-only endpoints designed for app dashboards, builder surfaces, and server-side feature gating.

Available endpoints

• GET /apps/{appUuid}/subscription-status
• GET /apps/{appUuid}/subscription/me

Which endpoint should I use?

Use GET /apps/{appUuid}/subscription-status when you need to understand the lifecycle of an app’s pricing plans as the app owner or developer.

Use GET /apps/{appUuid}/subscription/me when your app needs to know whether the currently authenticated user has an active, pending, cancelled, or absent subscription for that app.

Get app pricing lifecycle

GET /apps/{appUuid}/subscription-status returns a lifecycle summary for the app and includes each pricing plan’s status.

Response fields

• availability: whether pricing lifecycle data is fully available
• overallStatus: one of notConfigured, pendingSetup, active, withdrawn, mixed, or unavailable
• pricingPlans[]: each plan’s uuid, name, billingType, interval, price, currencyCode, and status

Example request

$
curl -X GET "https://api.fanvue.com/apps/00000000-0000-4000-8000-000000000001/subscription-status" \
>
  -H "Authorization: Bearer ACCESS_TOKEN" \
>
  -H "X-Fanvue-API-Version: 2025-06-26"

Example response

1
{
2
  "appUuid": "00000000-0000-4000-8000-000000000001",
3
  "appName": "Example App",
4
  "availability": "complete",
5
  "overallStatus": "pendingSetup",
6
  "pricingPlans": [
7
    {
8
      "uuid": "00000000-0000-4000-8000-000000000002",
9
      "name": "Monthly",
10
      "billingType": "recurring",
11
      "interval": "monthly",
12
      "price": 999,
13
      "currencyCode": "USD",
14
      "status": "pending_setup"
15
    }
16
  ]
17
}

Error behavior

• 403: the authenticated user does not have access to this app
• 404: the app could not be found for the authenticated user
• 503: the environment is not configured to serve developer app subscription data

Get current user subscription for an app

GET /apps/{appUuid}/subscription/me returns the authenticated user’s entitlement for the app, plus a managedCreators array describing per-creator entitlements for any creators the user is assigned to manage (relevant only for agency team members).

Response fields

Top-level fields describe the authenticated OAuth user’s own subscription state:

• userUuid: the OAuth user’s UUID. This may be a creator or an agency team member — do not assume it is always a creator.
• hasActiveSubscription: whether the current subscription is active
• status: one of active, pending, cancelled, or none
• planUuid / planName: the matched pricing plan, if one exists
• currentPeriodEnd: the current billing period end, if available
• cancelAtPeriodEnd: whether the subscription is set to end after the current period
• managedCreators: per-creator subscription records for creators this user is explicitly assigned to manage (agency team members only). Always present in the response — [] for non-agency users.

Each entry in managedCreators mirrors the top-level shape, scoped to a single managed creator: userUuid (the creator’s UUID), hasActiveSubscription, status, planUuid, planName, currentPeriodEnd, cancelAtPeriodEnd.

Example request

$
curl -X GET "https://api.fanvue.com/apps/00000000-0000-4000-8000-000000000001/subscription/me" \
>
  -H "Authorization: Bearer ACCESS_TOKEN" \
>
  -H "X-Fanvue-API-Version: 2025-06-26"

Example response — non-agency creator with an active subscription

1
{
2
  "appUuid": "00000000-0000-4000-8000-000000000001",
3
  "userUuid": "00000000-0000-4000-8000-000000000003",
4
  "hasActiveSubscription": true,
5
  "status": "active",
6
  "planUuid": "00000000-0000-4000-8000-000000000002",
7
  "planName": "Pro Monthly",
8
  "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
9
  "cancelAtPeriodEnd": false,
10
  "managedCreators": []
11
}

Example response — agency team member with two managed creators

1
{
2
  "appUuid": "00000000-0000-4000-8000-000000000001",
3
  "userUuid": "00000000-0000-4000-8000-000000000010",
4
  "hasActiveSubscription": false,
5
  "status": "none",
6
  "planUuid": null,
7
  "planName": null,
8
  "currentPeriodEnd": null,
9
  "cancelAtPeriodEnd": false,
10
  "managedCreators": [
11
    {
12
      "userUuid": "00000000-0000-4000-8000-000000000011",
13
      "hasActiveSubscription": true,
14
      "status": "active",
15
      "planUuid": "00000000-0000-4000-8000-000000000002",
16
      "planName": "Pro Monthly",
17
      "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
18
      "cancelAtPeriodEnd": false
19
    },
20
    {
21
      "userUuid": "00000000-0000-4000-8000-000000000012",
22
      "hasActiveSubscription": false,
23
      "status": "none",
24
      "planUuid": null,
25
      "planName": null,
26
      "currentPeriodEnd": null,
27
      "cancelAtPeriodEnd": false
28
    }
29
  ]
30
}

Agency team members

Agency team members (Fanvue users that belong to one or more agencies and manage a set of creators) never install third-party apps themselves — only creators do. Two things follow from that:

1. Top-level fields describe the team member’s own subscription, which is always empty (status: "none", hasActiveSubscription: false, planUuid: null, …). Render entitlement off managedCreators, not the top level, when you detect an agency context.
2. No 404 for agency users. Where a non-agency user with no subscription would receive 404, an agency team member receives 200 with the empty top-level shape plus their managedCreators array.

A team member only sees creators they are explicitly assigned to manage via the agency’s team-member-to-creator mapping — chatters see only their assigned subset; admins typically see all of the agency’s creators.

For agency team members, the read:self scope continues to gate this endpoint and now also surfaces basic subscription state for each creator the team member is assigned to manage. No additional scope is required.

Iterating over managedCreators

For agency-aware app surfaces, branch on managedCreators rather than the top-level subscription:

1
type SubscriptionRecord = {
2
  userUuid: string;
3
  hasActiveSubscription: boolean;
4
  status: "active" | "pending" | "cancelled" | "none";
5
  planUuid: string | null;
6
  planName: string | null;
7
  currentPeriodEnd: string | null;
8
  cancelAtPeriodEnd: boolean;
9
};
10
11
type AppSubscriptionMeResponse = SubscriptionRecord & {
12
  appUuid: string;
13
  managedCreators: SubscriptionRecord[];
14
};
15
16
async function renderEntitlements(appUuid: string, accessToken: string) {
17
  const res = await fetch(
18
    `https://api.fanvue.com/apps/${appUuid}/subscription/me`,
19
    {
20
      headers: {
21
        Authorization: `Bearer ${accessToken}`,
22
        "X-Fanvue-API-Version": "2025-06-26",
23
      },
24
    },
25
  );
26
27
  if (res.status === 404) {
28
    return { self: null, managed: [] };
29
  }
30
  if (!res.ok) throw new Error(`subscription/me failed: ${res.status}`);
31
32
  const body = (await res.json()) as AppSubscriptionMeResponse;
33
34
  const self: SubscriptionRecord | null = body.hasActiveSubscription
35
    ? {
36
        userUuid: body.userUuid,
37
        hasActiveSubscription: body.hasActiveSubscription,
38
        status: body.status,
39
        planUuid: body.planUuid,
40
        planName: body.planName,
41
        currentPeriodEnd: body.currentPeriodEnd,
42
        cancelAtPeriodEnd: body.cancelAtPeriodEnd,
43
      }
44
    : null;
45
46
  const managed = body.managedCreators.map((c) => ({
47
    creatorUuid: c.userUuid,
48
    isPaid: c.hasActiveSubscription,
49
    plan: c.planName,
50
    renewsOrEndsAt: c.currentPeriodEnd,
51
  }));
52
53
  return { self, managed };
54
}

Error behavior

• 400: appUuid is not a valid UUID
• 401: bearer token is missing or invalid
• 403: the OAuth token has insufficient scope, or appUuid does not belong to the OAuth client that issued the token
• 404: non-agency user has no subscription record for this app. Agency team members no longer hit this — they receive 200 with an empty self-subscription and a populated managedCreators array
• 410: API version sunset
• 502: the upstream developer/app-integration service returned an error
• 503: the environment is not configured to serve developer app subscription data (typically only in non-production environments)

Typical usage pattern

1. Create and configure your Fanvue app in the Developer area.
2. Authenticate a user with OAuth and request read:self.
3. Use subscription-status in owner-facing or builder experiences to show pricing lifecycle.
4. Use subscription/me in your server-side app logic to gate paid features for the current user. For agency-aware experiences, also iterate managedCreators to render per-creator entitlements.

For local and staged testing guidance, see Testing Your App. For App Store policy and pricing constraints, see App Store Listing Requirements.