> ## Documentation Index > Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get subscriber history > Returns the fan's subscription billing history with the creator, newest first: one item per paid subscription, trial or renewal charge, with the period it paid for. Use it to show when a fan subscribed, renewed, lapsed and came back, and what they paid each time. Former subscribers keep their history; a fan who was never billed returns an empty list. Profile subscriptions are always included. Checkout-link subscriptions are included only when the token also holds `read:creator` and, for an agency acting on a creator's behalf, the team member's role has `earnings:read`: the same access the checkout-link subscriptions endpoint requires. Without it the history holds profile subscriptions only. Refunded and charged-back charges stay in the history, flagged with `refunded` and `chargedBack`. This is billing history, not a log of setting changes: whether the subscription currently auto-renews, and its current status, are on the subscriber (`subscription.autoRenewalEnabled`, `subscription.status`). When auto-renew was switched off is not recorded. > [!NOTE] > > **Required scope** > > * `read:fan` — Access fan-related data and information within the platform. ## OpenAPI ````yaml /openapi-v1.json get /v1/subscribers/{userUuid}/history openapi: 3.1.0 info: title: Fanvue API version: '0.1' servers: - url: https://api.fanvue.com security: [] paths: /v1/subscribers/{userUuid}/history: get: summary: Get subscriber history description: >- Returns the fan's subscription billing history with the creator, newest first: one item per paid subscription, trial or renewal charge, with the period it paid for. Use it to show when a fan subscribed, renewed, lapsed and came back, and what they paid each time. Former subscribers keep their history; a fan who was never billed returns an empty list. Profile subscriptions are always included. Checkout-link subscriptions are included only when the token also holds `read:creator` and, for an agency acting on a creator's behalf, the team member's role has `earnings:read`: the same access the checkout-link subscriptions endpoint requires. Without it the history holds profile subscriptions only. Refunded and charged-back charges stay in the history, flagged with `refunded` and `chargedBack`. This is billing history, not a log of setting changes: whether the subscription currently auto-renews, and its current status, are on the subscriber (`subscription.autoRenewalEnabled`, `subscription.status`). When auto-renew was switched off is not recorded. operationId: getSubscriberHistory parameters: - $ref: '#/components/parameters/ApiVersionHeader' - schema: type: string format: uuid description: UUID of the fan whose subscription history to retrieve required: true description: UUID of the fan whose subscription history to retrieve name: userUuid in: path - schema: type: string description: >- Opaque pagination cursor from a previous response's `nextCursor`. It is bound to the creator and fan it was issued for. required: false description: >- Opaque pagination cursor from a previous response's `nextCursor`. It is bound to the creator and fan it was issued for. name: cursor in: query - schema: type: number minimum: 1 maximum: 50 default: 15 description: 'Number of items to return (1-50, default: 15)' required: false description: 'Number of items to return (1-50, default: 15)' name: size in: query responses: '200': description: Cursor-paginated subscription history content: application/json: schema: type: object properties: data: type: array items: type: object properties: source: type: string enum: - profile - checkout_link description: >- Which subscription the charge belongs to: `profile` for the fan's subscription to the creator's profile, `checkout_link` for a subscription bought through one of the creator's checkout links. More kinds may be added, so ignore values you do not recognise. checkoutLinkUuid: type: - string - 'null' format: uuid description: >- For a `checkout_link` charge, the checkout link it was paid through. A fan subscribed to the same price through two links holds one subscription, so its charges can name different links. Null for `profile`. type: type: string enum: - subscribe - trial - renew description: >- `subscribe` for a paid charge that started a subscription (including a resubscribe after a lapse), `trial` for the zero-priced charge that started a free trial, `renew` for an automatic renewal. Trials only exist on profile subscriptions. paidAt: type: string format: date-time description: When the charge was paid (ISO 8601) periodStart: type: string format: date-time description: >- Start of the billing period the charge paid for (ISO 8601). A renewal paid before the previous period ended starts where that period ended; one paid after starts when it was paid. periodEnd: type: - string - 'null' format: date-time description: >- End of the billing period the charge paid for (ISO 8601). For `subscribe` and `trial` this is the expiry quoted at signup, which covers a bundle's longer first period; a renewal always covers 30 days. Null for an old subscription charge with no recorded expiry. amountPaid: type: number description: >- Amount charged for the period, in minor currency units (cents), after any discount and excluding VAT and fees. Same basis as `subscription.amountPaid` on the subscriber. 0 for a free trial or a fully discounted period. intervalMonths: type: - integer - 'null' exclusiveMinimum: 0 description: >- Billing cycle length of the period in whole months: 1 for a standard month, or 3, 6 or 12 for a bundle's first period. Renewals are always 1, as a bundle only lengthens the first period. Null for a free trial, whose length is set in days. followsLapse: type: boolean description: >- Whether the fan's previous period had already ended when this one started, i.e. they went without a subscription in between. True for a resubscribe after a lapse, and for a renewal that only went through after the period had run out. False for the fan's first charge. refunded: type: boolean description: Whether the charge was refunded chargedBack: type: boolean description: Whether the charge was disputed and charged back required: - source - checkoutLinkUuid - type - paidAt - periodStart - periodEnd - amountPaid - intervalMonths - followsLapse - refunded - chargedBack description: Billing periods, newest first by `paidAt` nextCursor: type: - string - 'null' description: >- Cursor for the next page, or null when there are no more results required: - data - nextCursor example: data: - source: checkout_link checkoutLinkUuid: 7c9e6679-7425-40de-944b-e07fc1f90ae7 type: renew paidAt: '2025-05-20T12:15:03.000Z' periodStart: '2025-05-20T12:40:00.000Z' periodEnd: '2025-06-19T12:40:00.000Z' amountPaid: 1500 intervalMonths: 1 followsLapse: false refunded: false chargedBack: false - source: profile checkoutLinkUuid: null type: renew paidAt: '2025-05-09T09:31:12.000Z' periodStart: '2025-05-09T10:00:00.000Z' periodEnd: '2025-06-08T10:00:00.000Z' amountPaid: 999 intervalMonths: 1 followsLapse: false refunded: false chargedBack: false - source: profile checkoutLinkUuid: null type: subscribe paidAt: '2025-02-08T10:00:00.000Z' periodStart: '2025-02-08T10:00:00.000Z' periodEnd: '2025-05-09T10:00:00.000Z' amountPaid: 2499 intervalMonths: 3 followsLapse: true refunded: false chargedBack: false - source: profile checkoutLinkUuid: null type: trial paidAt: '2024-12-01T18:22:40.000Z' periodStart: '2024-12-01T18:22:40.000Z' periodEnd: '2024-12-08T18:22:40.000Z' amountPaid: 0 intervalMonths: null followsLapse: false refunded: false chargedBack: false nextCursor: null '400': description: >- Bad Request - API version not supported OR validation failed OR invalid UUID content: application/json: schema: oneOf: - $ref: '#/components/schemas/UnsupportedVersionError' - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/InvalidUuidError' '401': $ref: '#/components/responses/UnauthorizedResponse' '403': $ref: '#/components/responses/UnauthorizedResponse' '410': $ref: '#/components/responses/SunsetVersionResponse' '429': $ref: '#/components/responses/RateLimitResponse' security: - BearerAuth: - read:fan components: parameters: ApiVersionHeader: name: X-Fanvue-API-Version in: header required: true schema: type: string default: '2025-06-26' example: '2025-06-26' description: API version to use for the request schemas: UnsupportedVersionError: type: object properties: error: type: string message: type: string required: - error - message description: API version not supported ValidationError: type: object properties: errors: type: array items: type: string required: - errors description: Request validation failed InvalidUuidError: type: object properties: message: type: string required: - message description: Invalid UUID format provided responses: UnauthorizedResponse: description: Unauthorized Response content: application/json: schema: type: object properties: error: type: string required: - error SunsetVersionResponse: description: API version no longer supported (sunset) content: application/json: schema: type: object properties: error: type: string message: type: string nextVersion: type: string required: - error - message RateLimitResponse: description: Too many requests - rate limit exceeded headers: Retry-After: description: Number of seconds to wait before retrying the request schema: type: integer X-RateLimit-Limit: description: The maximum number of requests allowed in the current window schema: type: integer X-RateLimit-Remaining: description: The number of requests remaining in the current window schema: type: integer X-RateLimit-Reset: description: The Unix timestamp (seconds) when the rate limit window resets schema: type: integer content: application/json: schema: type: object properties: error: type: string required: - error securitySchemes: BearerAuth: type: oauth2 description: >- OAuth 2.0 access token, presented as a JWT bearer token in the `Authorization` header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call. flows: authorizationCode: authorizationUrl: https://auth.fanvue.com/oauth2/auth tokenUrl: https://auth.fanvue.com/oauth2/token refreshUrl: https://auth.fanvue.com/oauth2/token scopes: read:self: >- Access your own user profile information, including basic account details and settings. read:chat: >- Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history. write:chat: >- Create new chats and send messages. This scope is required for any chat-related actions that modify data. read:experience: >- Exchange a fan's experience token for the resolved experience and the fan's identity, so an embedded fan-facing experience can render the right content. write:experience: >- Request that the creator publish or unpublish a fan-facing experience. The app mints a request token; the creator confirms and Fanvue performs the change. read:fan: Access fan-related data and information within the platform. read:post: Read posts, including post details, comments, likes, and tips. write:post: Create, edit, and manage posts and content on behalf of users. read:media: Access media files, images, videos, and other content assets. write:media: >- Upload, modify, and manage media files and content assets. Also required for vault folder management. read:creator: >- Access creator profiles, content, and creator-specific information. write:creator: Modify creator profiles, settings, and creator-specific data. read:insights: >- Access analytics, metrics, and insights data for performance tracking. read:tracking_links: >- Read tracking links and the users associated with them, including per-user tracking metadata. write:tracking_links: Create and delete tracking links. read:agency: Read agency information, including the agency's team members. write:agency: >- Manage agency team members and invites, including inviting new team members and creators. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.