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
{
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.
Parameters
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.
Parameters
Either offeringId or onetimeOfferingId must be provided.
The offering ID to purchase.
The onetime offering ID to purchase.
ISO4217 currency code.
Must match the currency of user’s tab, otherwise the purchase will fail.
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: {
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.
Parameters
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"
});
