> ## Documentation Index
> Fetch the complete documentation index at: https://supertab-feature-merchant-auth-change-again.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Starting experiences
> Launch an experience using Supertab.js
Supertab.js provides a low-code way to start experiences on your pages.
See [the guide on setting up experiences](/supertab-experiences/experiences)
for more details on how to create and configure experiences.
When you need more control over what happens with experiences you can use Supertab.js to recieve callbacks
for specific events, entitlement statuses, or error conditions.
## Pre-requisites
* You have created an experience in the business portal.
* Supertab.js is installed on your page.
## Initialization
```javascript theme={null}
const supertabClient = new Supertab({clientId: "client.your_client"});
```
## Paywall: `supertab.createPaywall`
Invoke the Paywall on page load or in response to user action.
```javascript theme={null}
const supertabClient = new Supertab({ clientId: "test_client.abc" });
const supertabPaywall = await supertabClient.createPaywall({
experienceId: "experience.abc",
});
supertabPaywall.show()
```
### Parameters
`createPaywall` accepts an object with the following properties:
ID of the paywall experience created in Business Portal.
Key-value pairs of custom information associated with the purchase.
### Return value
A promise which resolves with an object with following properties:
Show the paywall UI.
Returns a promise which resolves with the paywall summary.
If current user has prior entitlement to the content, the paywall will not
show.
Any prior entitlement of the current user. `null` if user has no prior entitlement.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.
Purchase object if launching the flow resulted in a purchase. `null` otherwise.
ID of the purchase.
Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
ID of the purchased offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Date and time of the purchase.
Example: `"2025-04-30T12:00:00Z"`
Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.
Example: `"2025-04-30T12:00:00Z"`
A summary of the purchase, usually including the website name and the type of a given entitlement.
Example: `"The Leek - 24 Hours Time Pass"`
Price object of the purchase.
Amount in currency base units.
Example: `5000`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
Key-value pairs of custom information associated with the purchase.
The customer's access (if any) as a result of this purchase.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Offering object if user has purchased an offering. `null` otherwise.
ID of the offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Description of the offering.
Example: `"24 Hours Time Pass to The Leek"`
Specifies the nature and duration of purchased entitlement.
Where you have chosen to have Supertab manage entitlements for you, customer's purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.
The duration of the entitlement as `{length}{unit}`.
Examples:
```
{
// 1 year
"duration": "1y",
// 2 months
"duration": "2M",
// 3 weeks
"duration": "3w",
// 4 days
"duration": "4d",
// 5 hours
"duration": "5h",
// 6 minutes
"duration": "6m",
// 7 seconds
"duration": "7s"
}
```
Whether the entitlement is sold on a recurring basis (subscription).
The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Price object of the offering.
The users tab
Whether the tab is in test mode.
The currency of the tab.
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The total amount of the tab.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The limit of the tab. When reached, the payment will be required.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Details of all purchases made by the customer through your merchant account. Purchases made with other merchant accounts are shown as a single purchase, which accumulates all totals into one and has a `null` value instead of a purchase ID.
Each purchase in the array has the same structure as the previously described [Purchase object](#param-purchase).
If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
Hide the paywall UI.
Returns a promise which resolves with the paywall summary.
Any prior entitlement of the current user. `null` if user has no prior entitlement.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.
Purchase object if launching the flow resulted in a purchase. `null` otherwise.
ID of the purchase.
Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
ID of the purchased offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Date and time of the purchase.
Example: `"2025-04-30T12:00:00Z"`
Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.
Example: `"2025-04-30T12:00:00Z"`
A summary of the purchase, usually including the website name and the type of a given entitlement.
Example: `"The Leek - 24 Hours Time Pass"`
Price object of the purchase.
Amount in currency base units.
Example: `5000`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
Key-value pairs of custom information associated with the purchase.
The customer's access (if any) as a result of this purchase.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Offering object if user has purchased an offering. `null` otherwise.
ID of the offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Description of the offering.
Example: `"24 Hours Time Pass to The Leek"`
Specifies the nature and duration of purchased entitlement.
Where you have chosen to have Supertab manage entitlements for you, customer's purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.
The duration of the entitlement as `{length}{unit}`.
Examples:
```
{
// 1 year
"duration": "1y",
// 2 months
"duration": "2M",
// 3 weeks
"duration": "3w",
// 4 days
"duration": "4d",
// 5 hours
"duration": "5h",
// 6 minutes
"duration": "6m",
// 7 seconds
"duration": "7s"
}
```
Whether the entitlement is sold on a recurring basis (subscription).
The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Price object of the offering.
The users tab
Whether the tab is in test mode.
The currency of the tab.
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The total amount of the tab.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The limit of the tab. When reached, the payment will be required.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Details of all purchases made by the customer through your merchant account. Purchases made with other merchant accounts are shown as a single purchase, which accumulates all totals into one and has a `null` value instead of a purchase ID.
Each purchase in the array has the same structure as the previously described [Purchase object](#param-purchase).
If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
Starts the login flow. Opens Supertab SSO popup window if user is unknown.
Otherwise will log user in silently if auth data are found but has expired.
Returns a promise which resolves with the paywall summary.
Any prior entitlement of the current user. `null` if user has no prior entitlement.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.
Purchase object if launching the flow resulted in a purchase. `null` otherwise.
ID of the purchase.
Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
ID of the purchased offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Date and time of the purchase.
Example: `"2025-04-30T12:00:00Z"`
Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.
Example: `"2025-04-30T12:00:00Z"`
A summary of the purchase, usually including the website name and the type of a given entitlement.
Example: `"The Leek - 24 Hours Time Pass"`
Price object of the purchase.
Amount in currency base units.
Example: `5000`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
Key-value pairs of custom information associated with the purchase.
The customer's access (if any) as a result of this purchase.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Offering object if user has purchased an offering. `null` otherwise.
ID of the offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Description of the offering.
Example: `"24 Hours Time Pass to The Leek"`
Specifies the nature and duration of purchased entitlement.
Where you have chosen to have Supertab manage entitlements for you, customer's purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.
The duration of the entitlement as `{length}{unit}`.
Examples:
```
{
// 1 year
"duration": "1y",
// 2 months
"duration": "2M",
// 3 weeks
"duration": "3w",
// 4 days
"duration": "4d",
// 5 hours
"duration": "5h",
// 6 minutes
"duration": "6m",
// 7 seconds
"duration": "7s"
}
```
Whether the entitlement is sold on a recurring basis (subscription).
The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Price object of the offering.
The users tab
Whether the tab is in test mode.
The currency of the tab.
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The total amount of the tab.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The limit of the tab. When reached, the payment will be required.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Details of all purchases made by the customer through your merchant account. Purchases made with other merchant accounts are shown as a single purchase, which accumulates all totals into one and has a `null` value instead of a purchase ID.
Each purchase in the array has the same structure as the previously described [Purchase object](#param-purchase).
If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
Initial state of the paywall.
Any prior entitlement of the current user. `null` if user has no prior entitlement.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.
Purchase object if launching the flow resulted in a purchase. `null` otherwise.
ID of the purchase.
Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
ID of the purchased offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Date and time of the purchase.
Example: `"2025-04-30T12:00:00Z"`
Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.
Example: `"2025-04-30T12:00:00Z"`
A summary of the purchase, usually including the website name and the type of a given entitlement.
Example: `"The Leek - 24 Hours Time Pass"`
Price object of the purchase.
Amount in currency base units.
Example: `5000`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
Key-value pairs of custom information associated with the purchase.
The customer's access (if any) as a result of this purchase.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Offering object if user has purchased an offering. `null` otherwise.
ID of the offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Description of the offering.
Example: `"24 Hours Time Pass to The Leek"`
Specifies the nature and duration of purchased entitlement.
Where you have chosen to have Supertab manage entitlements for you, customer's purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.
The duration of the entitlement as `{length}{unit}`.
Examples:
```
{
// 1 year
"duration": "1y",
// 2 months
"duration": "2M",
// 3 weeks
"duration": "3w",
// 4 days
"duration": "4d",
// 5 hours
"duration": "5h",
// 6 minutes
"duration": "6m",
// 7 seconds
"duration": "7s"
}
```
Whether the entitlement is sold on a recurring basis (subscription).
The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Price object of the offering.
The users tab
Whether the tab is in test mode.
The currency of the tab.
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The total amount of the tab.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The limit of the tab. When reached, the payment will be required.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Details of all purchases made by the customer through your merchant account. Purchases made with other merchant accounts are shown as a single purchase, which accumulates all totals into one and has a `null` value instead of a purchase ID.
Each purchase in the array has the same structure as the previously described [Purchase object](#param-purchase).
If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
Destroy paywall instance. This removes all nodes related to paywall from DOM.
## Purchase Button `supertab.createPurchaseButton`
Fill a container element with the Purchase Button
```html theme={null}
```
```javascript theme={null}
const supertabButton = supertabClient.createPurchaseButton({
containerElement: document.getElementById("supertab-button-container"),
experienceId: "experience.abc",
});
```
### Parameters
Container element to render purchase button in. Elements are appended to the
container, so original contents are not replaced.
ID of the purchase button experience created in Business Portal.
Key-value pairs of custom information associated with the purchase.
Callback function called when user leaves the purchase flow either as a result of successful purchase or cancellation.
Returns a promise which resolves with the purchase button summary. See [Purchase button summary](#purchase-button-summary) for more details.
### Return Value
A promise which resolves with an object with following properties:
Destroy Supertab button instance. This removes all nodes related to Supertab
button from DOM.
Initial state of the purchase button. See [Purchase button summary](#purchase-button-summary) for more details.
## Purchase button summary
Both the returned `initialState` object and the object passed as an argument to the `onDone` callback contain the following properties:
Any prior entitlement of the current user. `null` if user has no prior entitlement.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.
Purchase object if launching the flow resulted in a purchase. `null` otherwise.
ID of the purchase.
Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
ID of the purchased offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Date and time of the purchase.
Example: `"2025-04-30T12:00:00Z"`
Date and time of the purchase completion, i.e. when payment was successful if purchase required payment.
Example: `"2025-04-30T12:00:00Z"`
A summary of the purchase, usually including the website name and the type of a given entitlement.
Example: `"The Leek - 24 Hours Time Pass"`
Price object of the purchase.
Amount in currency base units.
Example: `5000`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
Key-value pairs of custom information associated with the purchase.
The customer's access (if any) as a result of this purchase.
The content key of the entitlement.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Whether the customer has entitlement to the content key.
When the customer's access will expire.
Example: `"2025-04-30T12:00:00Z"`
If this access is a result of a subscription, this will be the date and time when the next billing period starts.
Example: `"2025-04-30T12:00:00Z"`
Offering object if user has purchased an offering. `null` otherwise.
ID of the offering.
Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
Description of the offering.
Example: `"24 Hours Time Pass to The Leek"`
Specifies the nature and duration of purchased entitlement.
Where you have chosen to have Supertab manage entitlements for you, customer's purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.
The duration of the entitlement as `{length}{unit}`.
Examples:
```
{
// 1 year
"duration": "1y",
// 2 months
"duration": "2M",
// 3 weeks
"duration": "3w",
// 4 days
"duration": "4d",
// 5 hours
"duration": "5h",
// 6 minutes
"duration": "6m",
// 7 seconds
"duration": "7s"
}
```
Whether the entitlement is sold on a recurring basis (subscription).
The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you.
Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
Price object of the offering.
The users tab
Whether the tab is in test mode.
The currency of the tab.
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The total amount of the tab.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
The limit of the tab. When reached, the payment will be required.
Amount in currency base units.
Example: `50`
Currency code.
Example: `"USD"`
Currency name.
Example: `"United States Dollar"`
Currency symbol.
Example: `"$"`
Base unit of the currency.
Example: `100`
Details of all purchases made by the customer through your merchant account. Purchases made with other merchant accounts are shown as a single purchase, which accumulates all totals into one and has a `null` value instead of a purchase ID.
Each purchase in the array has the same structure as the previously described [Purchase object](#param-purchase).
If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
## Example
```javascript Example theme={null}
const supertabButton = await supertabClient.createPurchaseButton({
containerElement: document.getElementById("supertab-button-container"),
experienceId: "experience.abc",
onDone: ({ priorEntitlement, purchase }) => {
if (priorEntitlement) {
// User has prior entitlement to the content.
return;
}
if (purchase) {
if (purchase.status === "completed") {
// Purchase was completed successfully.
} else {
// Purchase was not completed. User may have
// canceled the payment dialog if purchase
// required payment.
}
} else {
// User has canceled the flow and did not
// attempt to purchase the offering.
}
}
});
```