Get user data (paywall.getUser)

Call the function paywall.getUser() to get information about the user, including country match, subscription status, and balance (if tokenization is enabled). If the user is not authenticated, a 401 error will be returned with the body { error: 'Unauthorized', countryMatch: boolean, tier: number, country: string }. Upon successful authentication, you will receive the following object:

💡

If user has active subscription or lifetime payment then paid is true

Subscription statuses

STATUS	DESCRIPTION
`active`	The subscription is in good standing and the most recent payment is successful. It’s safe to provision your product for your customer.
`incomplete`	A successful payment needs to be made within 23 hours to activate the subscription. Or the payment requires action, like customer authentication.
`incomplete_expired`	The initial payment on the subscription failed and no successful payment was made within 23 hours of creating the subscription. These subscriptions don’t bill customers. This status exists so you can track customers that failed to activate their subscriptions.
`past_due`	Payment on the latest finalized invoice either failed or wasn’t attempted. The subscription continues to create invoices. If the invoice is still unpaid after all Smart Retries have been attempted, you can configure the subscription to move to `canceled`, `unpaid`, or leave it as `past_due`. To move the subscription to `active`, pay the most recent invoice before its due date.
`canceled`	The subscription has been canceled. This is a terminal state that can’t be updated.
`unpaid`	The latest invoice hasn’t been paid but the subscription remains in place. The latest invoice remains open and invoices continue to be generated but payments aren’t attempted. You should revoke access to your product when the subscription is `unpaid` since payments were already attempted and retried when it was `past_due`. To move the subscription to `active`, pay the most recent invoice before its due date.

/** * Represents a user's profile information */ interface User { /** Unique user identifier */ id: string; /** User's email address */ email: string; /** User's full name */ name: string; /** URL to user's avatar image */ avatar: string; /** ISO timestamp when user was created */ created_at: string; } /** * Represents a balance type and count */ interface Balance { /** Type of tokens (e.g., 'standard', 'standard-2', 'advanced') */ type: string; /** Amount of balance remaining */ count: number; } /** * Represents a purchase/subscription information */ interface Purchase { /** Current status of the purchase/subscription */ status: 'active' | 'paid' | 'pending' | 'unpaid' | 'canceled' | 'incomplete_expired' | 'past_due' | 'incomplete' | 'unpaid'; /** ISO timestamp when current billing period started */ current_period_start: string; /** ISO timestamp when current billing period ends */ current_period_end: string; /** Whether subscription will cancel at period end */ cancel_at_period_end: boolean; /** ISO timestamp when subscription was canceled, if applicable */ canceled_at?: string; /** ISO timestamp when subscription was created */ created: string; /** ISO timestamp when subscription ended, if applicable */ ended_at?: string; } /** * Response structure for getUser method */ interface GetUserResponse { /** User profile information */ user: User; /** Array of user's balance information */ balances: Balance[]; /** Whether user's country matches allowed countries */ countryMatch: boolean; /** User's country tier level */ tier: number; /** User's country code */ country: string; /** Array of user's purchases/subscriptions */ purchases: Purchase[]; /** Whether user has active paid subscription or lifetime payment */ paid: boolean; } interface Paywall { /** * Retrieves current user information including profile, balances, and purchase history. * * @throws {Error} If the request fails or paywall is not initialized * * @example * try { * const userInfo = await paywall.getUser(); * * if (userInfo.paid) { * console.log('User has active subscription or lifetime payment'); * } * * // Check user's standard token balances * const credits = userInfo.balances.find(b => b.type === 'standard'); * if (credits) { * console.log(`User has ${credits.count} standard tokens`); * } * } catch (error) { * console.error('Failed to fetch user info:', error); * } */ getUser(): Promise<GetUserResponse>; }

WELCOME

PAYWALL

PAYWALL API

PAYMENT PROCESSOR

API PROVIDER

TUTORIALS

ANALYTICS

SERVER API

Get user data (paywall.getUser)

Subscription statuses