Supertab.api provides a streamlined interface for making authenticated requests to the Customer API. This client handles the underlying HTTP communication, authentication, and error management, allowing developers to interact directly with Customer API endpoints.

While some endpoints don’t require authentication, users must be authenticated via Supertab.auth first to call endpoints with mandatory authentication. Once authenticated, the API client automatically includes the necessary authorization headers with each request.

This interface is particularly useful for custom integrations that require direct control over API interactions beyond what the pre-built experiences provide.

​
Methods

Each method returns a promise which resolves with the response from the Customer API endpoint with object keys transformed from snake_case to camelCase.

See Errors for a list of common exceptions.

​
retrieveCustomer

Retrieves the current customer.

Auth: optional

When called without an existing session, the response will return limits in a currency based on the user’s geographical location. Call this method again after auth to get limits in the user’s tab currency.

You must re-fetch this information after a new auth session is started.

​
Returns

Customer object. See Retrieve current customer. Supertab.js returns the response object keys in camelCase.

​
Type

retrieveCustomer return type
{
    authenticated: boolean;
    tab: {
        currency: {
            symbol: string;
            code: string;
            name: string;
            baseUnit: number;
        };
        testMode: boolean;
        total: {
            currency: {
                symbol: string;
                code: string;
                name: string;
                baseUnit: number;
            };
            amount: number;
        };
        limit: {
            currency: {
                symbol: string;
                code: string;
                name: string;
                baseUnit: number;
            };
            amount: number;
        };
        purchases: {
            status: "completed" | "pending" | "abandoned";
            id: string;
            offeringId: string;
            purchasedAt: string;
            completedAt: string | (string | null)[] | null;
            description: string;
            price: {
                currency: {
                    symbol: string;
                    code: string;
                    name: string;
                    baseUnit: number;
                };
                amount: number;
            };
            entitlementStatus: null[] | {
                contentKey: string;
                hasEntitlement: boolean;
                expires: string | (string | null)[] | null;
                recursAt: string | (string | null)[] | null;
            } | {
                contentKey: string;
                hasEntitlement: boolean;
                expires: string | (string | null)[] | null;
                recursAt: string | (string | null)[] | null;
            }[] | null;
            metadata?: unknown;
        }[];
    };
}

​
Example

await supertabClient.retrieveCustomer();

​
retrieveSite

Retrieves the site object associated with the client ID used to initialize Supertab.js.

Auth: optional

If called without auth, the response will return prices in a currency based on the user’s geographical location. Call this method again after auth to get prices in the user’s tab currency.

You must re-fetch this information after a new auth session is started in order to show correct pricing.

​
Returns

Site object. See Retrieve site. Supertab.js returns the response object keys in camelCase.

​
Type

retrieveSite return type
{
    name: string;
    offerings: {
        id: string;
        description: string;
        price: {
            currency: {
                symbol: string;
                code: string;
                name: string;
                baseUnit: number;
            };
            amount: number;
        };
        entitlementDetails: {
            contentKey: string;
            duration: string;
            isRecurring: boolean;
        } | null[] | {
            contentKey: string;
            duration: string;
            isRecurring: boolean;
        }[] | null;
        isPayNow: boolean;
    }[];
    testMode: boolean;
    url: string;
    logoUrl: string | (string | null)[] | null;
    contentKeys: string[];
    experiences: {
        type: "basic_paygate" | "basic_supertab_button" | "rich_paygate" | "rich_supertab_button";
        name: string;
        id: string;
        offerings: string[];
        configuration: {
            onClose: string | (string | null)[] | null;
            upsells: {
                mainOffering: string;
                upsellOffering: string;
                discount: number;
            }[];
            uiConfig?: unknown;
        };
    }[];
}

​
Example

await supertabClient.retrieveSite();

​
checkEntitlement

This method checks the entitlement details for a given content key.

Auth: required

​
Parameters

​
contentKey
string
required

The content key of the entitlement to check.

​
Returns

An object with the entitlement details. See Retrieve entitlement status. Supertab.js returns the response object keys in camelCase.

​
Type

checkEntitlement return type
{
    contentKey: string;
    hasEntitlement: boolean;
    expires: string | (string | null)[] | null;
    recursAt: string | (string | null)[] | null;
}

​
Examples

Check entitlement for a specific content key
await supertabClient.checkEntitlement({
    contentKey: "content-key"
});
Check entitlement for all site content keys
// Retrieve site to get content keys
const { contentKeys } = await supertabClient.retrieveSite();

// Check entitlement
const entitlement = await Promise.all(
    contentKeys.map(async (contentKey) => {
        return await supertabClient.checkEntitlement(contentKey);
    })
);

​
purchase

Purchases an offering or a one-time offering.

Auth: required

​
Parameters

Either offeringId or onetimeOfferingId must be provided.
​
offeringId
string

The offering ID to purchase.

​
onetimeOfferingId
string

The onetime offering ID to purchase.

​
currencyCode
string
required

ISO4217 currency code.

Must match the currency of user’s tab, otherwise the purchase will fail.

​
metadata
object

Free-form metadata to associate with the purchase.

​
Returns

Purchase object. See Purchase an offering endpoint in Customer API docs for detailed list of returned properties. Supertab.js returns the response object keys in camelCase.

​
Type

purchase return type
{
    purchase: {
        status: "completed" | "pending" | "abandoned";
        id: string;
        offeringId: string;
        purchasedAt: string;
        completedAt: string | (string | null)[] | null;
        description: string;
        price: {
            currency: {
                symbol: string;
                code: string;
                name: string;
                baseUnit: number;
            };
            amount: number;
        };
        entitlementStatus: null[] | {
            contentKey: string;
            hasEntitlement: boolean;
            expires: string | (string | null)[] | null;
            recursAt: string | (string | null)[] | null;
        } | {
            contentKey: string;
            hasEntitlement: boolean;
            expires: string | (string | null)[] | null;
            recursAt: string | (string | null)[] | null;
        }[] | null;
        metadata?: unknown;
    };
    actionRequired: boolean;
    actionRequiredDetails: {
        next: string;
        reason: string;
    } | null;
    rejectionReason?: string;
    purchaseOutcome?: string;
}

​
Example

await supertabClient.purchase({
    offeringId: "offering-id",
    currencyCode: "USD"
});

​
retrievePurchase

This method retrieves a purchase object for a given purchase ID.

Auth: required

​
Parameters

​
purchaseId
string
required

The purchase ID to retrieve.

​
Returns

Purchase object. See Retrieve a purchase. Supertab.js returns the response object keys in camelCase.

​
Type

retrievePurchase return type
{
    status: "completed" | "pending" | "abandoned";
    id: string;
    offeringId: string;
    purchasedAt: string;
    completedAt: string | (string | null)[] | null;
    description: string;
    price: {
        currency: {
            symbol: string;
            code: string;
            name: string;
            baseUnit: number;
        };
        amount: number;
    };
    entitlementStatus: null[] | {
        contentKey: string;
        hasEntitlement: boolean;
        expires: string | (string | null)[] | null;
        recursAt: string | (string | null)[] | null;
    } | {
        contentKey: string;
        hasEntitlement: boolean;
        expires: string | (string | null)[] | null;
        recursAt: string | (string | null)[] | null;
    }[] | null;
    metadata?: unknown;
}

​
Example

await supertabClient.retrievePurchase({
    purchaseId: "purchase-id"
});