# Authentication
Source: https://docs.supertab.co/customer-api/authentication
Generate bearer tokens for usage with the Customer API
We strongly recommend you interact with the Customer API using Supertab.js
when building integrations with Supertab.
[Supertab.js](/supertab.js) deals with authentication, purchase confirmation, and payments for you and ensures that
customers have the correct user experience.
All requests to the Customer API require authentication with a bearer token passed in the `Authorization` header unless stated otherwise.
Additionally, all calls to the Customer API must also include the `x-supertab-client-id` header with your client id (see [Clients](#clients) for more information), and a [version](/customer-api/versioning) header.
Supertab uses OAuth2 to issue JWT tokens. After your customer authenticates you will be able to take actions, such as purchasing, on their behalf.
Instead of implementing OAuth2 yourself, you should consider using an [existing library](https://oauth.net/code/), or (recommended) make use of
[Supertab.js](/supertab-js/reference/auth) to authenticate users and obtain tokens.
Example authenticated request to the Customer API:
```bash curl theme={null}
curl --location 'https://tapi.supertab.co/capi/customers/me' \
--header 'Authorization: Bearer ••••••' \
--header 'x-supertab-client-id: ••••••' \
--header 'x-api-version: 2025-04-01'
```
```javascript javascript theme={null}
fetch('https://tapi.supertab.co/capi/customers/me', {
method: 'GET',
headers: {
'Authorization': 'Bearer ******',
'x-supertab-client-id': '******',
'x-api-version': '2025-04-01',
}
})
.then(response => {
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
return response.json();
})
```
***
### Clients
Before making a request to the Customer API you must generate an OAuth client.
This is done for you automatically when you create a [Website](/supertab-experiences/sites).
Each Website will have an associated live and [test](/supertab-experiences/test-mode) client.
You **must** pass an `x-supertab-client-id` header with every request containing your client id.
The client id is used by the Customer API to determine which Website the request is for, and whether the request is in test or live mode.
Make sure to use the client detail generated for your website when working with the Customer API.
The API Keys generated separately in the API Keys section of the Business Portal are for use with the [Merchant API](/merchant-api).
### API Settings
| | |
| ------------------ | -------------------------------------------- |
| Base URL | `https://tapi.supertab.co/capi/` |
| Supported Grants | `Authorization Code + PKCE`, `Refresh Token` |
| Authentication URL | `https://auth.supertab.co/oauth2/auth` |
| Token URL | `https://auth.supertab.co/oauth2/token` |
| Token Type | `bearer` |
### Redirect URIs
In order to successfully authenticate using oAuth2 you must pass a known redirect URI to the Authentication URL.
You can configure your website’s redirect URI from the [Business Portal](https://business.supertab.co) - sites page by editing the Website URL field.
We recommend you use [Supertab.js](/supertab-js) to handle all authentication.
### Scopes
The Customer API is scoped to allow issuing tokens with minimum permissions.
The [api specification](/customer-api/endpoints) details the required scopes for each operation.
You must request a token with the scopes you require when authenticating the customer.
The current available scopes are for the Customer API are:
* `capi:read`: Make purchases and take other actions that modify a customer account.
* `capi:write`: Check for entitlements and take other actions the retrieve a customer's details.
[Supertab.js](/supertab-js/reference/auth) handles acquiring tokens with the correct scopes for you.
# Purchase a one-time offering
Source: https://docs.supertab.co/customer-api/endpoints/purchase-a-one-time-offering
post /purchases/onetime_offerings
Purchases a one-time offering by placing it on the customer's current tab.
If the new purchase(s) causes the tab to become full a payment is required before the purchase(s) will complete.
Required Scopes
`capi:write` - Write access to Customer API resources
# Purchase an offering
Source: https://docs.supertab.co/customer-api/endpoints/purchase-an-offering
post /purchases/offerings
Purchases a pre-defined offering by placing it on the customer's current tab.
Depending on the customer's existing relationship with Supertab they may be required to make purchases
in a specific currency. Check /customers/me for information on what currency the customer makes purchases in.
If the new purchase causes the tab to become full a payment is required before the purchase will complete.
Required Scopes
`capi:write` - Write access to Customer API resources
# Retrieve a one-time offering
Source: https://docs.supertab.co/customer-api/endpoints/retrieve-a-one-time-offering
get /onetime_offerings/{onetime_offering_id}
Retrieves a one-time offering.
Required Scopes
`capi:read` - Read access to Customer API resources
# Retrieve a purchase
Source: https://docs.supertab.co/customer-api/endpoints/retrieve-a-purchase
get /purchases/{purchase_id}
Retrieve a purchase
You may use this endpoint to poll pending purchases when you expect them to complete.
Required Scopes
`capi:read` - Read access to Customer API resources
# Retrieve current customer
Source: https://docs.supertab.co/customer-api/endpoints/retrieve-customer
GET /customers/me
Retrieve the current customer.
If the user is authenticated, retrieve the customer's current tab.
For unauthenticated requests, retrieve a predicted currency and tab limit based on the user's location.
Required Scopes
`capi:read` - Read access to Customer API resources
# Retrieve entitlement status
Source: https://docs.supertab.co/customer-api/endpoints/retrieve-entitlement-status
get /entitlements/{content_key}
Retrieves the entitlement status for the given content key.
Required Scopes
`capi:read` - Read access to Customer API resources
# Retrieve website
Source: https://docs.supertab.co/customer-api/endpoints/retrieve-site
get /site
Retrieves information about the current site, identified by the Client ID.
The response contains information about all the available offerings, configuration for the experiences
(e.g. paygates and buttons), and some other metadata.
Required Scopes
`capi:read` - Read access to Customer API resources
# Check for Entitlements, including Prior Entitlements
Source: https://docs.supertab.co/customer-api/entitlements
Serve content to returning customers
We strongly recommend you interact with the Customer API using Supertab.js
when building integrations with Supertab.
[Supertab.js](/supertab.js) deals with authentication, purchase confirmation, and payments for you and ensures that
customers have the correct user experience.
Begin an oauth flow to obtain a bearer token for your customer.
You must have a token for an authenticated customer before checking entitlement status.
Where you have chosen to have Supertab manage entitlements for you you must
retrieve the current Website in order to determine which
`content_key` applies for entitlement checks.
With the `content_key` and a customer's bearer token you can check
entitlement status.
The response details what entitlement (if any) the customer has for the provided `content_key`,
when that entitlement expires and if the entitlement will recur.
# Making a Purchase
Source: https://docs.supertab.co/customer-api/making-a-purchase
Purchase a pre-defined Offering using the Customer API
We strongly recommend you interact with the Customer API using Supertab.js
when building integrations with Supertab.
[Supertab.js](/supertab.js) deals with authentication, purchase confirmation, and payments for you and ensures that
customers have the correct user experience.
Begin an oauth flow to obtain a bearer token for your customer.
You must have a token for an authenticated customer before attempting to make a purchase.
Before being able to purchase an offering you must first know its ID and which currency your customer uses.
The Website contains information on which offerings are available for sale,
and their prices in your customer's current currency.
If you have already retrieved the current Website before authenticating your customer it is important
you re-fetch this information, as pricing details may have changed.
Purchase the offering in the correct currency to place it on your customer's tab.
The response includes any resulting purchase and details of what action is required (if any) to complete the purchase.
Purchases may be created in a `pending` state when further action is required. This is usually a payment
from the customer.
Supertab does not prevent customers from making purchases with duplicative entitlements,
you should check for prior entitlement before making any purchase and be careful not to send
multiple purchase requests simultaneously
If a purchase has been created in a `pending` state
you may poll for the status of the purchase.
This is useful when you expect the purchase to complete soon (e.g you have already opened a payment popup)
and need to perform some action after successful purchase immediately within the browser.
You can also check purchase status through the Merchant API (when checking from a backend),
by subscribing to a webhook, or by opener messages from checkout.supertab.co
# Customer API
Source: https://docs.supertab.co/customer-api/overview
The Supertab Customer API allows you to interact with the Supertab platform in-browser on your website on behalf of your customers.
With the Supertab Customer API you can create custom on-page experiences for your customers. You can, for example:
* Implement custom gating of content or services using entitlements
* Create custom purchase flows either for pre-configured, or ad-hoc ("One Time") offerings.
There are two ways to interact with the Customer API:
* **Supertab.js (recommended)**: [Supertab.js](/supertab-js) handles authentication for you and also provides a convenient JavaScript API for interacting with the Customer API.
* **Directly**: Using the Customer API directly in your own code. You can choose whether to authenticate using Supertab.JS (recommended) or with your own code.
The Customer API is designed to be used in the browser on your website and on behalf of your customers. It works seamlessly with the [Merchant API](/merchant-api), which is for server-to-server use cases.
# Versioning
Source: https://docs.supertab.co/customer-api/versioning
Make sure you are consuming the correct API version
The Customer API uses header based versioning.
### Version Header
You should pass the `x-api-version` header with every request.
New API versions are released regularly, each version is supported for 18 months.
If the `x-api-version` header is not provided you will by default be served the latest API version and could
experience breaking changes.
The current latest version is `2025-04-01`. This is the first version of the Customer API.
# Authentication
Source: https://docs.supertab.co/merchant-api/authentication
Generate auth tokens for usage with the Merchant API
### Clients
Before making a request to the Merchant API, you must generate your OAuth2 Client ID and Client Secret in the Business Portal.
1. Log in to the [Business Portal](https://business.supertab.co).
2. Click on the **API Keys** tab in the left sidebar.
3. Click on the **Create API Key** button.
4. Enter a name for your API key and click **Save**.
5. Copy the **Client Secret** value from the **Your Secret** modal and store it securely. You will not be able to view this value again.
6. Copy the **Client Secret** value and store it securely. You will not be able to view this value again. Click to close the modal containing the secret.
7. Copy the **Client ID** value from the list of API Keys corresponding to the key you just created. You will need this value to authenticate your requests.
You **must** pass an `x-supertab-client-id` header containing your client id with every request.
### Obtaining a Token
The Merchant API uses OAuth2 Client Credentials Grant to authenticate requests.
To obtain a token, you must send a POST request to the token URL with your client id and secret, using the `client_secret_basic` method.
```bash curl theme={null}
CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"
AUTH_URL="https://auth.supertab.co/oauth2/token"
# Encode the credentials in base64
BASIC_AUTH=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
curl -X POST "$AUTH_URL" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $BASIC_AUTH" \
-d "grant_type=client_credentials" \
-d "scope=mapi:read mapi:write"
```
```javascript javascript theme={null}
const clientId = 'YOUR_CLIENT_ID';
const clientSecret = 'YOUR_CLIENT_SECRET';
const basicAuth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
async function getToken() {
const res = await fetch('https://auth.supertab.co/oauth2/token', {
method: 'POST',
headers: {
'Authorization': `Basic ${basicAuth}`,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'client_credentials',
scope: 'mapi:read mapi:write',
}),
});
const data = await res.json();
console.log(data);
}
getToken();
```
```python python theme={null}
import requests
from requests.auth import HTTPBasicAuth
response = requests.post(
'https://auth.supertab.co/oauth2/token',
data={
'grant_type': 'client_credentials',
'scope': 'mapi:read mapi:write'
},
auth=HTTPBasicAuth('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET'),
headers={'Content-Type': 'application/x-www-form-urlencoded'}
)
print(response.json())
```
```php php theme={null}
post('https://merchant-auth.supertab.co/oauth2/token', [
RequestOptions::HEADERS => [
'Authorization' => 'Basic ' . base64_encode("$clientId:$clientSecret"),
'Content-Type' => 'application/x-www-form-urlencoded',
],
RequestOptions::FORM_PARAMS => [
'grant_type' => 'client_credentials',
'scope' => 'mapi:read mapi:write',
],
]);
$body = $response->getBody();
echo $body;
```
These tokens expire, so you should be prepared to handle token expiration and refresh when necessary.
### API Settings
| | |
| ---------------- | ------------------------------------------------ |
| Base URL | `https://tapi.supertab.co/mapi/` |
| Supported Grants | `Client Credentials` |
| Token URL | `https://merchant-auth.supertab.co/oauth2/token` |
| Token Type | `bearer` |
### Scopes
The Merchant API is scoped to allow issuing tokens with minimum permissions.
The [api specification](/merchant-api/endpoints) details the required scopes for each operation.
You must request a token with the scopes you require when authenticating the customer.
The following scopes are available:
* `mapi:write`: Create onetime offerings
* `mapi:read`: Check the status of purchases
# Create New One-Time Offering
Source: https://docs.supertab.co/merchant-api/endpoints/create-onetime-offering
post /onetime_offerings
Creates a onetime offering.
Required Scopes
`mapi:write` - Write access to Merchant API resources
# Retrieve a One-Time Offering
Source: https://docs.supertab.co/merchant-api/endpoints/retrieve-onetime-offering
get /onetime_offerings/{onetime_offering_id}
Retrieves a one-time offering.
Required Scopes
`mapi:read` - Read access to Merchant API resources
# Merchant API
Source: https://docs.supertab.co/merchant-api/overview
The Supertab Merchant API allows you to interact with the Supertab platform server-to-server.
With the Supertab Merchant API you can create and retrieve One-Time Offerings, which are ad-hoc offerings to that your users can then purchase via the [Customer API](./customer-api).
In addition to the REST API, there is also a webhook interface for receiving notifications about events that occur in the Supertab platform.
The Merchant API is a server-to-server API designed to be used by your backend. It works seamlessly with the [Customer API](./customer-api), which is for browser-based use cases where you are acting on behalf of your customers.
# Versioning
Source: https://docs.supertab.co/merchant-api/versioning
Make sure you are consuming the correct API version
The Merchant API uses header based versioning.
### Version Header
You should pass the `x-api-version` header with every request.
New API versions are released regularly, each version is supported for 18 months.
If the `x-api-version` header is not provided you will by default be served the latest API version and could
experience breaking changes.
The current latest version is `2025-04-01`. This is the first version of the Merchant API.
# Consuming Webhooks
Source: https://docs.supertab.co/merchant-api/webhooks/consuming-webhooks
React to events in your Supertab account with webhooks
### Introduction
Webhooks are a way for Supertab to send real-time notifications to your application when certain events occur in your account. This allows you to react to changes in your account without having to poll the API for updates.
A webhook is an HTTP callback that is triggered by a specific event. When the event occurs, Supertab sends a POST request to the URL you specify with a payload containing information about the event. You can validate that the webhook payload is genuinely from Supertab, and then process it in your application.
Supertab uses a service called Svix to manage our webhook infrastructure.
### Example Use Cases
* **CRM Updates:** When a customer purchases access to the content on your website, a `purchase.completed` webhook event is triggered. You can use this event to update your CRM with the customer's purchase information.
* **Custom Access Management:** You can implement your own custom mechanism for gating content or services within your application using the [One-Time Offering](/merchant-api/endpoints/create-onetime-offering) feature. You can create One-Time Offerings to represent e.g. access or credits by passing custom metadata. When a customer purchases the One-Time Offering, you can use the `onetime_offering.purchasing_completed` webhook event to check the metadata and securely grant them access.
### Consuming Webhook Events
1. **Set Up Your Webhook Endpoint:** Create an endpoint in your application that can handle POST requests. This endpoint should be publicly accessible and able to process the incoming webhook payload.
2. **Register Your Webhook** Navigate to *Webhooks* in the Business Portal and click *Add Endpoint*. Enter your enpoint URL and select the events you wish to subscribe to.
3. **Receive and Validate Webhook Events:** When an event occurs, Supertab will send a POST request to your webhook endpoint with the event payload. You should validate the request to ensure it is genuinely from Supertab. There is detailed documentation on how to do this on the [Svix website](https://docs.svix.com/receiving/verifying-payloads/why). The signing key is available in the Business Portal under the specific endpoint you created in the *Webhooks* section.
### Event Versioning
Webhook events are versioned to ensure that you can handle changes in the payload structure without breaking your application. Each event type has a version number associated with it, which is appended to the event type name and visible in the list of events when you register your webhook endpoint.
A new version of an event will be released if there is a breaking change in the payload. For example, if a field is removed or changed, then a new version will be released. If a new field is added, then the event will remain the same version.
If an event does not have a version associated with it, it is considered to be the oldest version of the event.
The current latest version is `2025-04-01`.
### Event Catalog
The event catalog is available to view [here](https://www.svix.com/event-types/eu/org_2m1kyxXSEnLSeEprUkWs7ksPdgf/), and under the *Event Catalog* tab of the *Webhooks* section of the Business Portal.
# Set up Experiences
Source: https://docs.supertab.co/supertab-experiences/experiences
Install the Supertab Paywall or Purchase Button - the button to push quality journalism.
## Paywall
The Paywall experience is best when you want a simple integration where Supertab manages access for you
Paywall display your website's time pass and subscription offerings to customers. The experience will launch automatically on page load and block access to your content until the customer makes a purchase or logs in to use an existing entitlement.
The Paywall is simple, yet adaptable:
* The layout will react to the number of Offerings you select
* A second screen can be added for more customization
* To align with your brand, colors can be customized and the logo will be displayed at the top of the Paywall (if you added it to the Website)
* Parts of the Paywall text can be edited in all languages we support.
### **Paywall Installation**
**Prerequisite:** you need to create your Websites and Offerings before setting up a Paywall.
We automatically create the first Paywall for each new Website using default time passes.
Head to **Experiences** section of the Business Portal and click the **Create Experience** button to go to the Experience Editor.
If you intend to use the automatically generated Paywall, click the **Edit** button next to it.
Select **Paywall** as the Experience type.
Paywall Redirect URL determines where we will redirect customers if they see the Paywall and close it. We automatically set it to your Website URL but it can redirect anywhere (e.g. to a dedicated page).
**Save** to continue.
In the **Offerings** section, you can choose 1 to 3 Offerings for the main screen. If you enable the **"More options" screen**, you will get three more Offering slots.
Use the Offering dropdowns to select what to sell and determine the order of Offerings. The preview is interactive and will show changes as you go.
You cannot use the same Offering on a screen twice.
If you choose two or three Offerings on one screen, you will have an option to select which one of them should be highlighted by default to grab the attention of customers.
Use **Button text color** to edit the **Put it on my Tab** and **More access options** button text.
**Button color** controls the background of the **Put it on my Tab** button, highlighted Offering box.
**Highlighted text color** controls the color of text on highlighted Offerings to ensure proper contrast.
Parts of Paywall text (such as title) can be edited in all languages we support. They will not be translated automatically. If you choose not to provide a translation, we will use default values.
Copy the provided code snippet and deploy it on pages you wish to monetize. Make sure to switch the snippet from [Test Mode](https://docs.supertab.co/supertab-experiences/test-mode) to Live Mode if you wish to process real transactions.
The experience will automatically launch when the page loads. Supertab manages customer access for you.
The Paywall will automatically update when you edit it, there is no need to update the snippet.
## Purchase Button
The button to push quality journalism
The Purchase Button experience is best when you need more control over how and when your customer is offered the option
to make a purchase
Purchase Buttons display a Supertab purchase button and send a message back to your website when a customer makes a purchase.
### Button Installation
**Prerequisite:** you need to create your websites
and offerings
before setting up a Paywall.
Head to **Experiences** section of the Business Portal and click the **Create Experience** button to go to the Experience Editor.
From the Website dropdown, choose the Website on which you will use the Button. Select **Purchase Button** as the Experience type.
Select an Offering which will be sold via the button. Remember that Supertab will not manage access in this scenario.
Copy the provided code snippet and deploy it wherever you want the button to appear. Make sure to switch the snippet from [Test Mode](https://docs.supertab.co/supertab-experiences/test-mode) to Live Mode if you wish to process real transactions.
For advanced usage review the Supertab.js documentation
# Get Started
Source: https://docs.supertab.co/supertab-experiences/introduction
Monetize premium content using Supertab Experiences
Supertab Experiences is a drop in paywall solution which handles customer purchasing, billing
and access entitlement to your premium content.
Tell us about your Websites and the Products you wish to sell.
Experiences control which products will be offered to your customers.
The Experience Editor automatically generates code to include on your Website.
Include the provided code snippet on pages you want to monetize with a paywall.
Supertab.js handles all user interaction and reports back to you when a customer has purchased an entitlement.
Supertab manages your customers' purchases and payments so that you can focus on what you do best.
# Configure Offerings and Pricing
Source: https://docs.supertab.co/supertab-experiences/products-offerings-pricing
Configure your inventory to start selling with Supertab
## Inventory Structure
### Websites
Your Websites control what access or entitlement a customer is purchasing.
### Offerings
Offerings detail how you will sell access to your Website.
You can sell access on a time pass, subscription, or single item (one-off basis).
#### Time passes
Time passes grant access to your Website for a fixed period of time.
When you create a new Website, we automatically generate several time passes for you.
You are free to change their duration or pricing.
The minimum time pass duration is 1 second.
#### Subscriptions
Subscriptions grant access to your Website for a fixed period of time, and automatically recur in line with the access period to ensure ongoing access to your website.
Minimum subscription duration is 1 day.
#### Single Item
Single item offerings can be used to sell on a one-off basis to your customers.
**Supertab does not manage access or entitlements for single item offerings.**
Single item offerings are useful if you wish to integrate Supertab Experiences with an existing entitlement management system.
### Pricing
Each offering can be priced individually in each currency your account supports.
Supertab uses the US Dollar as our main currency and will automatically suggest pricing in other currencies based on an average exchange rate.
## Configure your Offerings
Before configuring offerings you must first create a Website to hold your inventory.
When you create a Website, Supertab automatically creates three default time pass offerings for you, with durations of 24 hours, 3 days and 1 week, and accompanying default pricing.
Head to the Offerings section to create new time passes, subscriptions or single items. Specify prices in dollars, and choose duration for time passes and subscriptions.
Open offering details to edit prices, durations, or to remove an offering.
Continue by setting up your experiences to begin selling.
# Create Websites
Source: https://docs.supertab.co/supertab-experiences/sites
Create your Websites in order to begin using Supertab Experiences
Supertab organises your inventory into Websites. A Website is an online property where you use Supertab. It can be a website, blog, or SaaS product.
Register your merchant account and complete onboarding.
Use the Business Portal to create a Website.
You must provide a customer facing name for the Website and its root URL, including protocol.
It's important to get the URL correct as Supertab uses this to make sure customers are logged in securely when interacting with your Website.
The root URL should be the domain or subdomain of the website you intend to serve Supertab experiences from; for example `https://mypublication.com`, `https://blog.mywebsite.com`.
You can change the name or URL associated with your Website at any time.
Contact support if you need to serve the same experience from multiple domains or subdomains.
You can add a logo for each of your Websites. We will automatically use it in some Experiences (e.g. Paywall) and in the purchase flow to better align with your brand.
We accept SVG or PNG files with max size of 512x512px.
We generate a live and test API client for each Website.
You will need their IDs if you wish to swap between test and live mode.
Supertab includes the correct client ID in the code snipped generated from the
experience editor.
# Test Mode
Source: https://docs.supertab.co/supertab-experiences/test-mode
Understand how to use Test Mode to test integrations before go live
Test Mode allows developers to test Supertab Experiences without processing real transactions.
Using test cards, developers can simulate payment scenarios and toggle between Test and Live modes through the Experience Editor.
Identity verification (KYC) and providing financial information for payouts can be deferred until you’re ready to go live. You can create Websites, Offerings, and Experiences without completing this step; however, it must be finalized before enabling Live Mode and accepting payments.
## Key Features
* Test mode replicates Live Mode behavior, except no real transactions occur. This allows comprehensive testing of all APIs and integration flows.
* Each Website generates a Test Client and a Live Client. The Experience Editor automatically uses the correct ID based on the selected mode.
* The Installation tab in the Experience Editor allow toggling between modes and provides ready-to-use code snippets, eliminating the need for manual ID swapping.
## Creating and Editing Experiences
* To create or edit an Experience, go to the Experiences section of the Business Portal. Here, you'll find a list of existing Experiences and the option to add a new one.
* When adding a new Experience or editing an existing one, you will be taken to the Experience Editor.
* In the Installation tab of the Experience Editor, there is an option to toggle between Test Mode and Live Mode.
* Switching modes automatically updates the installation code provided, so developers can simply copy the correct snippet without changing client IDs manually.
* The code must be installed on all pages where the Experience is intended to be displayed.
## Using Stripe Test Cards
Use Stripe test cards to simulate various scenarios. Common test cards include:
* Successful Payment: `4242 4242 4242 4242` (Visa)
* Card Declined: `4000 0000 0000 0002`
* Insufficient Funds: `4000 0000 0000 9995`
* Incorrect CVC: `4000 0000 0000 0127`
* Expired Card: `4000 0000 0000 0069`
* 3D Secure Required: `4000 0025 0000 3155`
For more, refer to [Stripe's Testing Guide](https://docs.stripe.com/testing).
## Steps to Simulate a Test Transaction:
1. Install the Test Mode code snippet on all relevant pages.
2. Visit the page displaying the Test Mode Experience.
3. Keep adding Offerings to your Tab until you fill it up.
4. Proceed to payment, and enter a Stripe test card.
5. Complete the form and confirm the transaction. The system will simulate the payment and return the result.
## Post-Transaction Testing and Monitoring
* Use direct API calls to see test tabs, purchases, and payments.
* To see test transactions as an end user, log in to [my.supertab.co](https://my.supertab.co/) with appropriate login credentials and add `?testmode=true` at the end of the URL.
## Moving to Production
1. Once testing is complete, follow these steps to move your Experiences and integrations to production:
2. Switch to Live Mode in the Experience Editor and complete KYC if required.
3. Install the Live Mode code snippet on relevant pages.
4. Use real cards for live transactions.
5. Monitor live transactions in the Dashboard to ensure they process correctly.
# Custom Integrations
Source: https://docs.supertab.co/supertab-integrate/custom-integrations
Enable powerful custom integrations with, Supertab.js, the Supertab Customer API and the Supertab Merchant API
A convenient way to interact with Experiences, authenticate customers, and access the Customer API.
The Supertab Customer API allows you to interact with the Supertab platform in-browser on your website on behalf of your customers.
Server-to-server API for creating One-Time Offerings and responding to webhooks.
# With Google AdManager
Source: https://docs.supertab.co/supertab-integrate/google
Leverage Supertab integration with Google Offerwall for no-code monetization within Google AdManager.
## **What is Google Offerwall?**
**Google Offerwall** helps Merchants explore new monetization opportunities by allowing website visitors to access content through alternative methods, such as watching a short ad or paying a small fee via Supertab.
It is part of the **Privacy & Messaging** features of Google Ad Manager. [Learn more](https://support.google.com/admanager/answer/11897778).
## **How does Supertab work within Google Offerwall?**
When visitors land on your website, the Offerwall restricts access to your content and presents options to unlock it. If you enable Supertab, one of these options will allow visitors to pay a small fee to access your entire website for a set period of time.
When visitors choose Supertab and select one of the Offerings, they sign up to create a virtual Tab or log in to use an existing one. Their purchases accumulate on their Tabs until they reach the Tab limit, which is when they will be asked to pay the balance.
## **Configuring Supertab within the Google Offerwall**
Review Google's documentation. [Learn More](https://support.google.com/admanager/answer/12367687?hl=en\&ref_topic=13821812\&sjid=8896807766023023081-NC).
1. In Ad Manager, go to the Privacy & Messaging section.
2. Select Offerwall from the list of Monetization options.
3. Create an Offerwall message. [Learn more](https://support.google.com/admanager/answer/11897778).
4. In the User Choices section, you will see Supertab as an option, click the Set up button.
1. Accept the Ad Manager Offerwall Features Terms of Service.
2. Click on Create account. Supertab will open in a new browser tab.
3. Sign up using the Google account associated with your Ad Manager account.
1. Type in your company name (or personal name).
2. Select your country and continue. (NOTE: once selected, your country cannot be changed).
3. Click Save.
4. Once your Supertab account is created, switch back to AdManager.
4. Click Link your account.
5. Click confirm.
5. Publish the offerwall. This will initiate creating default offerings and paywall.
[Learn more about setting up Supertab within the Offerwall](https://support.google.com/admanager/answer/12367687).
## **KYC (Know Your Customer) and bank account setup**
In order to receive payouts, you need to confirm your identity and register your bank account with our provider, Stripe. To finish this process, you will need to provide your business details and bank information. As an example, if your business is located in USA, Stripe will need your business EIN.
## **Managing Offerings and the Paywall**
Once you publish an offerwall in Ad Manager, we automatically create three time passes and a Paywall to get you started. You can edit your Offerings and their prices or customize the Paywall's appearance anytime.
### Editing Offerings and their prices
1. Log into the Business Portal.
2. Navigate to the **Offerings** section in the left-hand menu. You will see three pre-configured time passes and their durations.
3. Click **Edit** to modify an Offering’s duration and prices in different currencies.
4. Save your changes. The modified Offerings will be automatically updated on your Paywall.
### Editing the Paywall
1. Log into the **Business Portal**.
2. Go to the **Experiences** section in the left-hand menu. You will see a list of Experiences with one Paywall.
3. Click **Edit** to open the **Experience Editor**.
4. Customize the design of your Paywall as desired and save changes.
# Off-App Purchases
Source: https://docs.supertab.co/supertab-integrate/off-app-purchases
Enable seamless purchases through your app with a simple redirect flow.
## Overview
Off-App Purchases let you generate a URL that your users can use to purchase a specific offering from your web or mobile app.
When opening the Off-App Purchase URL, customers sign up and confirm their purchase with Supertab. After completion,
Supertab redirects the customer back to your app.
## Prerequisites
Before generating a URL, make sure you have:
* A Website with a URL you wish to use as the post-purchase redirect destination.
* An Offering available for purchase.
## Creating a Purchase Link
Include the following required query parameters to generate a valid purchase link:
* `client_id` – A live or test client ID associated with the Website you created.
* `offering_id` – The ID of the Offering the user is purchasing.
```text Purchase URL theme={null}
https://purchase.supertab.co/?client_id=client.your_client&offering_id=offering.your_offering
```
### Metadata
You can optionally include a `metadata` parameter with custom key-value pairs. This metadata:
* Is returned in the `metadata` query parameter during the redirect back to your app.
* Is also attached to the purchase object after confirmation.
**How to encode metadata:**
1. Format metadata as a URL query string (e.g. `user_id=123&nonce=456`).
2. Then encode using URL component encoding (e.g. `user_id%3D123%26nonce%3D456`).
```javascript js theme={null}
const metadata = {
user_id: "123",
nonce: "456",
timestamp: Date.now()
};
const queryString = new URLSearchParams(metadata).toString();
const encodedMetadata = encodeURIComponent(queryString);
const purchaseUrl = `https://purchase.supertab.co/?client_id=client.your_client&offering_id=offering.your_offering&metadata=${encodedMetadata}`;
```
**Example with metadata:**
```text Purchase URL with Metadata theme={null}
https://purchase.supertab.co/?client_id=client.your_client&offering_id=offering.your_offering&metadata=user_id%3D123%26nonce%3D456
```
## Handling the Redirect
The customer is redirected to your app when they have completed the purchase flow.
| Parameter | Description | Example |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `purchase_id` | The ID of the purchase. | "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c" |
| `status` | The purchase status.
`completed` – the purchase was successful
`abandoned` – the user abandoned the purchase
| "completed" |
| `offering_id` | The ID of the selected offering, passed in the original purchase URL. | "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" |
| `metadata` | The custom key-value metadata you included in the original URL. | "user\_id=123\&nonce=456" |
# Account Management
Source: https://docs.supertab.co/supertab-introduction/account-management/account-kyc
Open a new Supertab account, manage your payouts and team members
Setting up a new business account is quite straightforward and will take between 2 and 10 minutes depending on whether you choose to finish the KYC (Know Your Customer) process upfront or not.
We want you to start building as quickly as possible, so KYC is not required upfront. As long as you don't finish it, all the experiences will only be available in Test Mode and you will not be able to process real transactions.
## Creating a new Account:
1. Go to [https://business.supertab.co](https://business.supertab.co/register)
2. Create an account by direct email setup or social login.
3. Verify your email address by clicking on the **Verify My Email** button and following the instructions.
At this point you can continue on to create your first Website and offerings. All experiences you create will be in Test Mode, meaning you will not be able to process real transactions and receive payouts. However, you will be able to test your integration with us.
## Inviting teammates
To manage or add new administrators to your account, use the Team section.
To add a new administrator to your account click Add User and enter their email address. They will receive an invitation email from Supertab to join this account.
To resend this invitation select the ellipsis menu beside their name and select Generate Link.
New users will be marked as Pending until they activate their account through their invitation. Then they will be marked as Active
Users can be removed at any time by clicking the ellipsis menu beside their name and selecting Remove User.
## KYC (Know Your Customer) and payment account setup
If you want to receive payouts, you need to confirm your identity and register your payment account with our provider, Stripe.
To finish this process, you will need to provide your business details and bank information (either your bank login or routing and account number). If your business is located in USA, Stripe will also need the last 4 digits of your SSN.
1. Click on the **Finish setting up your account** button on one of the pop-ups you will see after setting up a Website or creating an Experience.
2. On the Stripe Landing page Enter your phone number and email address. Verify with the code you receive.
3. Proceed with Stripe verification process. When asked, provide details of the bank account which we should use for payouts.
Once verified, you will be redirected back to the Business Portal.
## Payouts
Customer payments are processed immediately with payouts initiated monthly. You can track payouts in real time on the Business Portal Dashboard.
# Internationalization
Source: https://docs.supertab.co/supertab-introduction/internationalization
Lists the countries, languages, and currencies supported by Supertab for merchants and consumers.
## Supported Countries
Supertab supports the following countries for a merchant to register from:
### Americas
* 🇦🇷 Argentina
* 🇧🇷 Brazil
* 🇨🇦 Canada
* 🇨🇱 Chile
* 🇨🇴 Colombia
* 🇪🇨 Ecuador
* 🇲🇽 Mexico
* 🇵🇦 Panama
* 🇵🇪 Peru
* 🇵🇷 Puerto Rico
* 🇺🇾 Uruguay
* 🇺🇸 United States
### APAC
* 🇦🇺 Australia
* 🇧🇩 Bangladesh
* 🇧🇭 Bahrain
* 🇨🇳 China
* 🇭🇰 Hong Kong
* 🇮🇩 Indonesia
* 🇮🇳 India
* 🇯🇵 Japan
* 🇰🇷 South Korea
* 🇲🇾 Malaysia
* 🇳🇿 New Zealand
* 🇵🇭 Philippines
* 🇵🇰 Pakistan
* 🇸🇬 Singapore
* 🇹🇭 Thailand
* 🇹🇼 Taiwan
* 🇻🇳 Vietnam
### EMEA
* 🇦🇹 Austria
* 🇧🇦 Bosnia and Herzegovina
* 🇧🇪 Belgium
* 🇧🇬 Bulgaria
* 🇨🇭 Switzerland
* 🇨🇾 Cyprus
* 🇨🇿 Czechia
* 🇩🇪 Germany
* 🇩🇰 Denmark
* 🇪🇪 Estonia
* 🇪🇬 Egypt
* 🇪🇸 Spain
* 🇫🇮 Finland
* 🇫🇷 France
* 🇬🇷 Greece
* 🇭🇷 Croatia
* 🇭🇺 Hungary
* 🇮🇪 Ireland
* 🇮🇱 Israel
* 🇮🇹 Italy
* 🇯🇴 Jordan
* 🇰🇪 Kenya
* 🇱🇹 Lithuania
* 🇱🇺 Luxembourg
* 🇱🇻 Latvia
* 🇲🇦 Morocco
* 🇲🇹 Malta
* 🇳🇬 Nigeria
* 🇳🇱 Netherlands
* 🇳🇴 Norway
* 🇵🇱 Poland
* 🇵🇹 Portugal
* 🇷🇴 Romania
* 🇷🇸 Serbia
* 🇸🇦 Saudi Arabia
* 🇸🇪 Sweden
* 🇸🇮 Slovenia
* 🇸🇰 Slovakia
* 🇿🇦 South Africa
* 🇹🇷 Turkey
* 🇺🇦 Ukraine
* 🇦🇪 United Arab Emirates
* 🇬🇧 United Kingdom
***
## Supported Languages
Consumers can view Supertab Experiences in the following languages:
* English
* French
* German
* Italian
* Japanese
* Portuguese (Brazil)
* Spanish
***
## Supported Currencies
Consumers can make purchases using the following currencies:
* 🇦🇺 Australian Dollar
* 🇬🇧 British Pound
* 🇨🇦 Canadian Dollar
* 🇪🇺 Euro
* 🇮🇳 Indian Rupee
* 🇯🇵 Japanese Yen
* 🇳🇿 New Zealand Dollar
* 🇸🇬 Singapore Dollar
* 🇨🇭 Swiss Franc
* 🇺🇸 US Dollar
***
If you are interested in supporting additional countries, languages or currencies, please contact [sales@supertab.co](mailto:sales@supertab.co).
*Last updated: May 2025*
# About Supertab
Source: https://docs.supertab.co/supertab-introduction/overview/about-supertab
Supertab is a novel digital payment solution, specifically designed to make small payments possible.
For content and service providers, from GenAI to video to publishing, Supertab opens up a new revenue stream by monetizing users who would otherwise never subscribe. We enable users to unlock digital content without subscriptions, upfront payments, or long-term commitments.
## Understand
### Payment Aggregation
Supertab aggregates customer purchases onto a running Tab. Customers can make purchases until their personal Tab limit is reached, at which time they must pay it off. Customers' Tabs are global and shared between all Supertab merchants, making Supertab a convenient payment method used for a variety of digital goods and services across the web.
This approach enables Supertab to minimize transaction fees and make processing small transactions more cost-effective.
### Tab Limits
New customers receive Tabs with a limit of up to \$5 (or local equivalent).
### Prices
Supertab can be used to sell any item priced from \$0.01 to \$999.99 or equivalent in 134 other currencies we support.
### Payments
Supertab collects payment from the customer when:
* The customer's Tab exceeds its limit,
* *or* The customer's Tab is inactive
### Payouts
Supertab pays out funds received from customers to you immediately (less our fees)
## Start Building
Create an account and configure payouts
Test your integration without using a real credit card
## Integration Options
Easy integration through Google AdManager
Enable seamless purchases through your mobile app with a simple redirect flow.
Use Supertab's Browser SDK, Webhooks or our APIs for more control
# Paywall Experiences
Source: https://docs.supertab.co/supertab-js/experiences/paywall
Launch a Paywall and handle user choices
Supertab.js makes it simple to embed powerful monetization flows into your Website.
This guide will walk you through launching experiences and what information you
receive about choices your customers make when interacting with a Supertab experience.
#### Before You Begin
Make sure that you have:
* [Created an experience](/supertab-experiences/experiences) in the Business Portal
* [Installed Supertab.js](/supertab-js/installation) via npm or CDN.
## Initialize the Supertab.js Client
First, create a new `Supertab` instance using your client ID.
```javascript theme={null}
const supertabClient = new Supertab({clientId: "client.your_client"});
```
Replace `client.your_client` with the live or test client ID associated with Website you created
when setting up your experiences. Supertab.js uses this client ID to make sure its running
in the correct place.
## Display a Paywall
The Paywall is a customizable experience that handles login, entitlement checks and purchase flows for you.
You can launch it any time: on page load, after a user action or in response to app logic.
```javascript Quickstart theme={null}
// First create the paywall
// Replace `experience.your_experience` with your experience ID
// Supertab.js will fetch the configuration of the paywall for you.
// No paywall is shown at this point, you must call .show()
const supertabPaywall = await supertabClient.createPaywall({
experienceId: "experience.your_experience"
});
// Display the paywall to your user
// The paywall closes after a succesful purchase or on user abandonment
await supertabPaywall.show()
```
#### Options for `createPaywall`
Offerings available for sale, messaging text and styling are controlled from the Business Portal
| Key | Type | Required | Description |
| :----------------- | :------- | :------- | :------------------------------------------------------------------ |
| `experienceId` | `string` | Yes | ID of the Paywall experience created in the Business Portal |
| `purchaseMetadata` | `object` | No | Key-value pairs of custom information associated with the purchase. |
#### PaywallExperienceResult
`createPaywall` returns a `PaywallExperienceResult` object containing the initial state of the Paywall
and methods for showing it to users.
| Field | Type | Description |
| :------------- | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialState` | `ExperienceStateSummary` | The state of the paywall immediately after config is loaded, can be used to check if the user is logged in or has a prior entitlement already. |
| `logIn` | `() => Promise` | Launch an auth flow immediately, if necessary. The returned promise resolves when the login flow is completed. |
| `show` | `() => Promise` | Display the paywall to the user, the returned promise resolves when the paywall closes. |
| `destroy` | `() => void` | Clean up and remove all Supertab elements from the DOM. |
## Paywall Lifecycle
The state of the Paywall is generally returned to you as a promise which resolves when the Paywall exits.
The Paywall may exit as a result of a successful purchase or as a result of user abandonment.
```mermaid theme={null}
flowchart LR
create[createPaywall] --> show[show]
show -- Successful Purchase --> exit[ExperienceStateSummary]
show -- Prior Entitlement --> exit
show -- Abandonment --> exit
```
Supertab Experiences uses an async programming paradigm.
Each interaction returns a promise which resolves once the user has finished interacting with the Paywall.
You can handle these promises through the use of `async` / `await` or through promise chaining with `.then()`.
```javascript async / await theme={null}
async function showPaywall() {
const paywall = await supertabClient.createPaywall({ experienceId: "experience.your_experience" });
const state = await paywall.show();
// You can now work with the state
}
```
```javascript Promise chaining with .then() theme={null}
function showPaywall() {
supertabClient.createPaywall({
experienceId: "experience.abc",
}).then((paywall) => {
paywall.show()
.then((state) => {
// You can now work with the state
})
});
}
```
Examples on this page use `async` / `await`.
## Checking for Purchases
The experience state will tell you if your user made a purchase from the paywall.
| `ExperienceStateSummary` | Type | Description |
| :----------------------- | :----------------- | :------------------------------------------------------------ |
| `purchase` | `Purchase \| null` | The purchase made by the user. |
| `paymentResult` | `boolean` | `true` if the user made a payment to complete their purchase. |
You can find detail about any purchase the user made by inspecting the `purchase` field.
| `Purchase` | Type | Description |
| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | ID of the purchase. You can use this with the Merchant API for backend checks the purchase is valid. |
| `offeringId` | `string` | ID of the offering which was purchased. |
| `description` | `string` | Description of the offering which was purchased |
| `status` | `string` | Possible values: `completed`, `pending`.
A purchase may be created as `pending` when the user is required to make payment. If handling entitlements yourself, only grant access when a purchase is `completed`.
The paywall will automatically launch the payment flow when necessary. |
```javascript Check for a purchase theme={null}
// Show the Paywall and wait for the promise to resolve.
// The promise resolves once the paywall has exited and is no longer showing to the user.
const state = await supertabPaywall.show();
if (!state.purchase) {
// No purchase was made
return
}
if (state.purchase.status === 'completed') {
// A purchase has been made successfully!
console.log("Customer made a purchase!", state.purchasedOffering.offeringId)
}
if (state.paymentResult) {
// The user made a payment in order to complete their purchase
console.log("Customer made a payment!")
}
```
### Check For Prior Entitlement (Optional)
You may wish to check for any prior entitlement your user has purchased without immediately showing the paywall.
This is achieved by inspecting the initial state of the paywall immediately after creating it.
| `ExperienceStateSummary` | Type | Description |
| :----------------------- | :---------------------------- | :------------------------------------------------------ |
| `priorEntitlement` | `EntitlementStatus[] \| null` | Array of any prior entitlements the user has purchased. |
`EntitlementStatus` contains information on which `contentKey`s the user has an entitlement for
and when their entitlement expires.
| `EntitlementStatus` | Type | Description |
| :------------------ | :-------- | :------------------------------------------------------------------ |
| `contentKey` | `string` | ID of the content key which the user has an entitlement for. |
| `expires` | `string` | Date when the user's entitlement expires. e.g `2025-01-01 00:00:00` |
| `hasEntitlement` | `boolean` | `true` if the user has an entitlement for the content key. |
```javascript Prior Entitlements theme={null}
const supertabPaywall = await supertabClient.createPaywall({
experienceId: "experience.your_experience"
});
const state = supertabPaywall.initialState;
const entitlements = state.priorEntitlement;
// contentKey we wish to check entitlement for
const checkFor = "site.your_site_id";
for (const entitlement of entitlements) {
if (entitlement.contentKey === checkFor && entitlement.hasEntitlement) {
// The user has an entitlement
return true
}
}
// The user does not have an entitlement
return false;
```
You may also check for entitlements after the paywall has exited by inspecting the `priorEntitlement` field of
the resolves `ExperienceStateSummary` object.
### Force LogIn (Optional)
It is only possible to check for prior entitlements without starting the paywall experience when the user is
already logged in.
You can force an immediate login by calling `logIn` on the paywall itself.
```javascript Force Login theme={null}
const supertabPaywall = await supertabClient.createPaywall({
experienceId: "experience.your_experience"
});
// Supertab SSO will open in a popup and return to you the new paywall state
// WARNING: You should only open a popup in response to user action to avoid the browser blocking the popup.
const state = await supertabPaywall.logIn()
```
Because `.logIn()` immediately opens a popup it should only be called in response to a user action.
## Wrapping Up
We've covered:
* How to create and show a paywall
* The lifecycle of the paywall and its async programming model
* How to work with the state of the paywall to check for purchases and entitlements
# Installation
Source: https://docs.supertab.co/supertab-js/installation
Install, load and initialize Supertab.js on a Website
## Prerequisites
You'll need your Website's `clientId` to initialize Supertab.js. If you haven't created a Website yet, follow the guide [Create Websites](/supertab-experiences/sites) first.
To find your Website's `clientId`, log in to the [Business Portal](https://business.supertab.co/), navigate to Organization / Websites, then click the "..." button next to your Website.
## Quick Start
Choose an installation method based on your setup:
* **Using a bundler** (Webpack, Vite, Rollup, etc.) → [Install from npm](#from-npm)
* **Modern browsers with ES modules** → [CDN with ES Module import](#with-an-es-module-import)
* **Legacy browser support** → [CDN with global loader](#with-the-global-loader)
## From npm
Install Supertab.js from npm for use with bundlers like Webpack, Vite, or Rollup:
```bash theme={null}
npm install @getsupertab/supertab-js
```
Import, load and initialize the client in your application:
```javascript async/await theme={null}
import { loadSupertab } from "@getsupertab/supertab-js";
(async () => {
const { Supertab } = await loadSupertab();
const supertabClient = new Supertab({ clientId: "test_client.X" });
})();
```
```javascript .then() theme={null}
import { loadSupertab } from "@getsupertab/supertab-js";
loadSupertab().then(({ Supertab }) => {
const supertabClient = new Supertab({ clientId: "test_client.X" });
});
```
`loadSupertab()` loads the latest compatible Supertab.js version from our CDN. It must be called in a browser environment—it won't work server-side.
## Directly from CDN
Load Supertab.js directly from our CDN without a build step. Two options:
### With an ES Module import
Use this method for modern browsers that support ES modules:
```html theme={null}
```
### With the global loader
Use this method for environments without ES module support. The script `supertab.global.js` exposes the global function `window.loadSupertab()`:
```html async/await theme={null}
```
```html .then() theme={null}
```
## Versioning
CDN URLs are versioned. Using `v3` automatically loads the latest `3.x.x` version (patch and minor releases). Breaking changes are released as new major versions.
## Next Steps
Once installed, you can launch experiences or build custom purchase flows:
* [Starting experiences](/supertab-js/experiences/starting-experiences)
* [SDK Overview](/supertab-js/reference/overview)
# Getting Started
Source: https://docs.supertab.co/supertab-js/introduction
Build with Supertab in the browser
Use Supertab.js to launch [experiences](/supertab-js/experiences/starting-experiences) or build
[purchasing flows](/supertab-js/reference/overview) for your customers.
Supertab.js provides authentication, logic for purchasing & payments, and entitlement management in your customer's browser.
We recommend using Supertab.js over direct integration with the Customer API for most use cases.
***
Install Supertab.js via npm or from a CDN
Boot an experience
API Reference
# Supertab.api
Source: https://docs.supertab.co/supertab-js/reference/api
Methods reference for `Supertab.api`
`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
```typescript retrieveCustomer return type [expandable] theme={null}
{
authenticated: boolean;
user: {
id: string;
email: string;
firstName: string;
lastName: string;
};
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
```typescript theme={null}
await supertabClient.api.retrieveCustomer();
```
***
### `retrieveSite`
Retrieves the website object associated with the client ID used to [initialize Supertab.js](/supertab-js/installation).
**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
Website object. See Retrieve site.
Supertab.js returns the response object keys in camelCase.
#### Type
```typescript retrieveSite return type [expandable] theme={null}
{
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;
uiConfig?: unknown;
};
}[];
}
```
#### Example
```typescript theme={null}
await supertabClient.api.retrieveSite();
```
***
### `checkEntitlement`
This method checks the entitlement details for a given content key.
**Auth:** required
#### 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
```typescript checkEntitlement return type [expandable] theme={null}
{
contentKey: string;
hasEntitlement: boolean;
expires: string | (string | null)[] | null;
recursAt: string | (string | null)[] | null;
}
```
#### Examples
```typescript Check entitlement for a specific content key theme={null}
await supertabClient.api.checkEntitlement({
contentKey: "content-key"
});
```
```typescript Check entitlement for all site content keys theme={null}
// Retrieve website to get content keys
const { contentKeys } = await supertabClient.api.retrieveSite();
// Check entitlement
const entitlement = await Promise.all(
contentKeys.map(async (contentKey) => {
return await supertabClient.api.checkEntitlement({ contentKey });
})
);
```
***
### `purchase`
Purchases an offering or a one-time offering.
**Auth:** required
#### 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](/customer-api) for detailed list of returned properties.
Supertab.js returns the response object keys in camelCase.
#### Type
```typescript purchase return type [expandable] theme={null}
{
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
```typescript theme={null}
await supertabClient.api.purchase({
offeringId: "offering-id",
currencyCode: "USD"
});
```
***
### `retrievePurchase`
This method retrieves a purchase object for a given purchase ID.
**Auth:** required
#### Parameters
The purchase ID to retrieve.
#### Returns
Purchase object. See Retrieve a purchase.
Supertab.js returns the response object keys in camelCase.
#### Type
```typescript retrievePurchase return type [expandable] theme={null}
{
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
```typescript theme={null}
await supertabClient.api.retrievePurchase({
purchaseId: "purchase-id"
});
```
# Supertab.auth
Source: https://docs.supertab.co/supertab-js/reference/auth
Methods reference for `Supertab.auth`
`Supertab.auth` is an entry point for authenticating a user. It abstracts the authentication flow and auth state management, allowing your application to easily implement login functionality and make authenticated requests to the Customer API.
Once a user is authenticated, the necessary authorization headers are passed to each Customer API request dispatched via Supertab.api.
`Supertab.auth` handles the event of token expiration and refreshes the token
before attempting to make an authenticated call to the Customer API. There is no need to re-authenticate a user manually.
## Properties
### `session`
The user's session data. `null` if the user is not authenticated. See [AuthData](#authdata) for the type definition.
#### Example
```typescript theme={null}
const session = await supertabClient.auth.session;
```
### `status`
The authentication status of the user.
* `missing` - The user is not authenticated.
* `expired` - The user's session has expired and needs to be refreshed before making an authenticated request to the Customer API. See [start](#start) method for more details on how to refresh the session.
* `valid` - The user is authenticated.
#### Type
```typescript theme={null}
enum AuthStatus {
MISSING: "missing",
EXPIRED: "expired",
VALID: "valid",
}
```
#### Example
```typescript theme={null}
const status = await supertabClient.auth.status;
```
## Methods
### `start`
Initializes the authentication process when necessary and returns the user's session data.
Based on the presence of session data:
* If session already exists, returns auth data from the browser storage.
* If session has expired, refreshes the token.
* If session is missing, opens Supertab SSO in a popup window allowing users to sign up for an account or log in to an existing account.
#### Parameters
When set to `true`, the client does not open the Supertab SSO popup and
instead attempts to refresh the session in the background.
Refreshing the session is only possible if there as an existing expired session in browser storage
Returns `null` for unknown users with no prior session.
Specifies which screen to display in the Supertab SSO popup. Valid options are
`register` and `login`.
#### Returns
A promise which resolves with the user's session data object.
| Field | Type | Description |
| :------------- | :------- | :--------------------------------------------------------------------------- |
| `accessToken` | `string` | The access token used for making authenticated requests to the Customer API. |
| `refreshToken` | `string` | The token used to obtain a new access token when the current one expires. |
| `expiresAt` | `Date` | The date and time when the access token will expire. |
| `tokenType` | `string` | The type of authentication token, typically "Bearer". |
#### Type
```typescript theme={null}
type AuthData = {
accessToken: string;
refreshToken: string;
expiresAt: Date;
tokenType: string;
}
```
#### Examples
```typescript Authenticate user theme={null}
// Will open the Supertab SSO popup if there is
// no session data.
await supertabClient.auth.start();
```
```typescript Refresh token silently theme={null}
// Attempt to get session data or refresh session if
// expired. It will not open the Supertab SSO popup and
// will return `null` if the user is unknown.
await supertabClient.auth.start({ silently: true });
```
```typescript Authenticate user with screen hint theme={null}
// Send user to the login screen in Supertab SSO.
await supertabClient.auth.start({ screenHint: "login" });
```
### `reset`
Resets the authentication state by clearing the browser storage.
# Supertab.checkout
Source: https://docs.supertab.co/supertab-js/reference/checkout
Methods reference for `Supertab.checkout`
`Supertab.checkout` client handles the checkout flow for purchases requiring payment.
## Methods
### `start`
Starts the checkout process. Whenever the purchase requires payment (i.e. the tab reaches the limit or the purchased offering is of a "pay now" type),
use this method to start the checkout flow and allow user to pay for the tab.
The payment is completed in a a popup with Supertab checkout app. Supertab.js uses [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for signaling payment status back to the parent window.
Since this method opens a popup, it should be called in response to a user action, e.g. a button click.
#### Parameters
The URL of the checkout page found in `actionRequiredDetails` object of the [`Supertab.api.purchase`](/supertab-js/reference/api#purchase) response.
#### Returns
Boolean. `true` if the checkout was completed successfully, `false` otherwise (e.g. when the user closes the popup or cancels the payment).
#### Example
```typescript Make a purchase and get the checkout URL theme={null}
const purchaseResponse = await supertabClient.api.purchase({
offeringId: "test.offering-id"
});
const checkoutUrl = purchaseResponse.actionRequiredDetails.next;
```
```javascript Start the checkout process theme={null}
```
# Supertab.createPaygate
Source: https://docs.supertab.co/supertab-js/reference/create-paygate
API reference for `Supertab.createPaygate`
`Supertab.createPaygate` is deprecated. Use [`Supertab.createPaywall`](/supertab-js/reference/create-paywall) instead.
## Parameters
| Key | Type | Required | Description |
| :----------------- | :------- | :------- | :------------------------------------------------------------------ |
| `experienceId` | `string` | Yes | ID of the Paygate experience created in the Business Portal |
| `purchaseMetadata` | `object` | No | Key-value pairs of custom information associated with the purchase. |
## Returns
A promise that resolves to the initial state of the Paygate and methods for showing it to users. Type of the response is [`PaygateExperienceResult`](#paygateexperienceresult).
| Field | Type | Description |
| :------------- | :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialState` | `ExperienceStateSummary` | The state of the paygate immediately after config is loaded, can be used to check if the user is logged in or has a priort entitlement already. |
| `logIn` | `() => Promise` | Launch an auth flow immediately, if necessary. The returned promise resolves when the login flow is completed. |
| `show` | `() => Promise` | Display the paygate to the user, the returned promise resolves when the paygate closes. |
| `destroy` | `() => void` | Clean up and remove all Supertab elements from the DOM. |
## Example
```javascript theme={null}
const supertabClient = new Supertab({clientId: "client.your_client"});
const supertabPaygate = await supertabClient.createPaygate({
experienceId: "experience.your_experience"
});
```
## Types
### `ExperienceStateSummary`
```typescript ExperienceStateSummary type definition theme={null}
interface ExperienceStateSummary {
priorEntitlement: EntitlementStatus[] | null;
authStatus: AuthStatus;
purchase: Purchase | null;
purchasedOffering: Offering | null;
tab: Tab | null;
paymentResult: boolean;
}
type EntitlementStatus = {
contentKey: string;
hasEntitlement: boolean;
expires: string;
recursAt: Date | null;
}
enum AuthStatus {
MISSING = "missing",
EXPIRED = "expired",
VALID = "valid"
}
type Purchase = {
id: string;
offeringId?: string | null;
purchasedAt: string | null;
completedAt: string | null;
description: string;
price: Price;
status: PurchaseStatus;
metadata: Metadata;
entitlementStatus: EntitlementStatus | null;
}
type Metadata = Record;
enum PurchaseStatus {
PENDING = "pending",
COMPLETED = "completed",
ABANDONED = "abandoned"
}
type Price = {
amount: number;
currency: Currency;
}
type Currency = {
code: string;
symbol: string;
name: string;
baseUnit: number;
}
type Offering = {
id: string;
description: string;
entitlementDetails: EntitlementDetails;
price: Price;
isPayNow: boolean;
}
type EntitlementDetails = {
contentKey: string;
duration: string;
isRecurring: boolean;
}
type Tab = {
testMode: boolean;
currency: Currency;
total: Price;
limit: Price;
purchases: Purchase[];
}
```
### `PaygateExperienceResult`
```typescript PaygateExperienceResult type definition theme={null}
interface PaygateExperienceResult {
show: () => Promise;
logIn: () => Promise;
destroy: () => void;
initialState: ExperienceStateSummary;
}
```
# Supertab.createPaywall
Source: https://docs.supertab.co/supertab-js/reference/create-paywall
API reference for `Supertab.createPaywall`
## Parameters
| Key | Type | Required | Description |
| :----------------- | :------- | :------- | :------------------------------------------------------------------ |
| `experienceId` | `string` | Yes | ID of the Paywall experience created in the Business Portal |
| `purchaseMetadata` | `object` | No | Key-value pairs of custom information associated with the purchase. |
## Returns
A promise that resolves to the initial state of the Paywall and methods for showing it to users. Type of the response is [`PaywallExperienceResult`](#paywallexperienceresult).
| Field | Type | Description |
| :------------- | :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialState` | `ExperienceStateSummary` | The state of the paywall immediately after config is loaded, can be used to check if the user is logged in or has a priort entitlement already. |
| `logIn` | `() => Promise` | Launch an auth flow immediately, if necessary. The returned promise resolves when the login flow is completed. |
| `show` | `() => Promise` | Display the paywall to the user, the returned promise resolves when the paywall closes. |
| `destroy` | `() => void` | Clean up and remove all Supertab elements from the DOM. |
## Example
```javascript theme={null}
const supertabClient = new Supertab({clientId: "client.your_client"});
const supertabPaywall = await supertabClient.createPaywall({
experienceId: "experience.your_experience"
});
```
## Types
### `ExperienceStateSummary`
```typescript ExperienceStateSummary type definition theme={null}
interface ExperienceStateSummary {
priorEntitlement: EntitlementStatus[] | null;
authStatus: AuthStatus;
purchase: Purchase | null;
purchasedOffering: Offering | null;
tab: Tab | null;
paymentResult: boolean;
}
type EntitlementStatus = {
contentKey: string;
hasEntitlement: boolean;
expires: string;
recursAt: Date | null;
}
enum AuthStatus {
MISSING = "missing",
EXPIRED = "expired",
VALID = "valid"
}
type Purchase = {
id: string;
offeringId?: string | null;
purchasedAt: string | null;
completedAt: string | null;
description: string;
price: Price;
status: PurchaseStatus;
metadata: Metadata;
entitlementStatus: EntitlementStatus | null;
}
type Metadata = Record;
enum PurchaseStatus {
PENDING = "pending",
COMPLETED = "completed",
ABANDONED = "abandoned"
}
type Price = {
amount: number;
currency: Currency;
}
type Currency = {
code: string;
symbol: string;
name: string;
baseUnit: number;
}
type Offering = {
id: string;
description: string;
entitlementDetails: EntitlementDetails;
price: Price;
isPayNow: boolean;
}
type EntitlementDetails = {
contentKey: string;
duration: string;
isRecurring: boolean;
}
type Tab = {
testMode: boolean;
currency: Currency;
total: Price;
limit: Price;
purchases: Purchase[];
}
```
### `PaywallExperienceResult`
```typescript PaywallExperienceResult type definition theme={null}
interface PaywallExperienceResult {
show: () => Promise;
logIn: () => Promise;
destroy: () => void;
initialState: ExperienceStateSummary;
}
```
# Supertab.createPurchase
Source: https://docs.supertab.co/supertab-js/reference/create-purchase
API reference for `supertabClient.createPurchase`
## Parameters
| Key | Type | Required | Description |
| :----------------- | :-------------------------------------------------- | :------- | :------------------------------------------------------------------ |
| `offeringId` | `string` | Yes | ID of the offering created in the Business Portal |
| `merchantName` | `string` | No | The name of the merchant to display in the purchase widget. |
| `merchantLogoUrl` | `string` | No | URL of the merchant's logo to display in the purchase widget. |
| `purchaseMetadata` | `object` | No | Key-value pairs of custom information associated with the purchase. |
| `uiConfig` | [`CreatePurchaseUiConfig`](#createpurchaseuiconfig) | No | Custom color configuration for the purchase widget. |
## Returns
An object containing a `startPurchase` function and a `destroy` method to control the purchase widget programmatically. Type of the response is [`CreatePurchaseResult`](#createpurchaseresult).
| Field | Type | Description |
| :-------------- | :------------------------------------ | :------------------------------------------------------ |
| `startPurchase` | `() => Promise` | The startPurchase function to start the purchase flow. |
| `destroy` | `() => void` | Clean up and remove all Supertab elements from the DOM. |
## Example
```javascript theme={null}
const supertabClient = new Supertab({ clientId: "client.your_client" });
const { startPurchase, destroy } = await supertabClient.createPurchase({
offeringId: "offering.your-offering-id",
});
const result = await startPurchase();
// Then you can handle the result
if (result.purchase?.status === "completed") {
console.log("Purchase completed successfully:", result.purchase);
} else if (result.purchase?.status === "abandoned") {
console.log("Purchase cancelled:", result.purchase);
} else if (result.priorEntitlement) {
console.log("User already has entitlement:", result.priorEntitlement);
}
```
## UI Configuration
The `uiConfig` parameter allows you to customize the visual appearance of the purchase widget by overriding the default color scheme.
### Color Priority System
The purchase widget determines which colors to use based on a priority system:
1. **Highest Priority**: `uiConfig` passed directly to `createPurchase()`
2. **Medium Priority**: Experience configuration colors (if the offering is associated with an experience)
3. **Lowest Priority**: Default Supertab colors (`#ffffff` for text, `#000000` for background)
### Example with Custom Colors
```javascript theme={null}
const { startPurchase, destroy } = await supertabClient.createPurchase({
offeringId: "offering.premium-access",
merchantName: "Demo Merchant",
merchantLogoUrl: "https://example.com/logo.png",
uiConfig: {
colors: {
text: "#FFFFFF", // White text
background: "#0000FF", // Blue background
},
},
});
```
### How Colors Affect the Widget
**`colors.text`** controls:
* Button text (e.g., "Continue" button label)
* Text color contrast on colored backgrounds
* Any text overlaid on colored elements
**`colors.background`** controls:
* Primary action button background (e.g., "Continue" button)
* Progress indicator ring (Omega ring showing Tab balance)
* Visual accents and highlights throughout the widget
### Visual Examples
Default widget appearance without custom uiConfig
Widget with custom colors: white text (#FFFFFF) and blue background
(#0000FF)
The `uiConfig` always takes precedence over experience configuration colors.
This ensures you have full control over the widget appearance when needed.
Ensure sufficient contrast between text and background colors for
accessibility. Test your color combinations to verify readability.
## Types
### `PurchaseStateSummary`
```typescript PurchaseStateSummary type definition theme={null}
interface PurchaseStateSummary {
priorEntitlement: EntitlementStatus[] | null;
authStatus: AuthStatus;
purchase: Purchase | null;
purchasedOffering: Offering | null;
tab: Tab | null;
paymentResult: boolean;
}
type EntitlementStatus = {
contentKey: string;
hasEntitlement: boolean;
expires: string; // ISO 8601 date string (e.g., "2023-11-07T05:31:56Z")
recursAt: string | null; // ISO 8601 date string when not null (e.g., "2023-11-07T05:31:56Z")
};
enum AuthStatus {
MISSING = "missing",
EXPIRED = "expired",
VALID = "valid",
}
type Purchase = {
id: string;
offeringId?: string | null;
purchasedAt: string | null; // ISO 8601 date string when not null
completedAt: string | null; // ISO 8601 date string when not null
description: string;
price: Price;
status: PurchaseStatus;
metadata: Metadata;
entitlementStatus: EntitlementStatus | null;
};
type Metadata = Record;
enum PurchaseStatus {
PENDING = "pending",
COMPLETED = "completed",
ABANDONED = "abandoned",
}
type Price = {
amount: number;
currency: Currency;
};
type Currency = {
code: string;
symbol: string;
name: string;
baseUnit: number;
};
type Offering = {
id: string;
description: string;
entitlementDetails: EntitlementDetails;
price: Price;
isPayNow: boolean;
};
type EntitlementDetails = {
contentKey: string;
duration: string;
isRecurring: boolean;
};
type Tab = {
testMode: boolean;
currency: Currency;
total: Price;
limit: Price;
purchases: Purchase[];
};
```
### `CreatePurchaseResult`
```typescript CreatePurchaseResult type definition theme={null}
interface CreatePurchaseResult {
startPurchase: () => Promise;
destroy: () => void;
}
```
### `CreatePurchaseUiConfig`
```typescript CreatePurchaseUiConfig type definition theme={null}
interface CreatePurchaseUiConfig {
colors: {
text: string; // Text color for all text elements
background: string; // Background color for buttons and interactive elements
};
}
```
## Advanced Examples
### Override Experience Colors
```javascript theme={null}
// Even if this offering has yellow/black theme in the experience configuration,
// the custom uiConfig colors will be used instead
const { startPurchase, destroy } = await supertabClient.createPurchase({
offeringId: "offering.premium-access",
merchantName: "My Publication",
uiConfig: {
colors: {
text: "#FFFFFF", // White text
background: "#FF6B6B", // Coral background
},
},
});
```
### Conditional Color Theming
```javascript theme={null}
// Apply different themes based on user preferences or context
const isDarkMode = window.matchMedia("(prefers-color-scheme: dark)").matches;
const { startPurchase, destroy } = await supertabClient.createPurchase({
offeringId: "offering.premium-access",
uiConfig: isDarkMode
? {
colors: {
text: "#FFFFFF",
background: "#1E90FF", // Dodger blue
},
}
: {
colors: {
text: "#000000",
background: "#FFD700", // Gold
},
},
});
```
### Full Implementation Example
```javascript theme={null}
async function initializePurchase() {
const supertabClient = new Supertab({ clientId: "client.your_client" });
try {
const { startPurchase, destroy } = await supertabClient.createPurchase({
offeringId: "offering.premium-article",
merchantName: "Tech News Daily",
merchantLogoUrl: "https://example.com/logo.png",
purchaseMetadata: {
articleId: "article-123",
section: "technology",
author: "Jane Doe",
},
uiConfig: {
colors: {
text: "#2C3E50", // Dark blue-gray text
background: "#3498DB", // Bright blue background
},
},
});
const result = await startPurchase();
if (result.purchase?.status === "completed") {
// Unlock the content
unlockPremiumContent();
// Clean up the widget
destroy();
// Track the conversion
analytics.track("Purchase Completed", {
purchaseId: result.purchase.id,
offeringId: "offering.premium-article",
});
} else if (result.priorEntitlement) {
// User already has access
unlockPremiumContent();
destroy();
}
} catch (error) {
console.error("Purchase initialization failed:", error);
}
}
```
# Errors
Source: https://docs.supertab.co/supertab-js/reference/errors
Common Exceptions
Supertab.js throws different types of error objects depending on the nature and origin of the error.
This page documents all error types, their structure, and details specific to each error type.
## Error object structure
All error objects have the following structure:
```typescript theme={null}
interface Error {
message: string;
code: string;
error: TError; // Original error object
}
```
## Validation errors
#### RequestValidationError
Thrown when the request is invalid, e.g. missing required parameters. This error is thrown by the SDK before the request is sent to the server.
#### ResponseValidationError
Thrown when the response from the Customer API is invalid, i.e. the response body does not match the expected schema.
#### Validation error codes
* `missing_parameter`
* `invalid_parameter`
* `unrecognized_parameter`
* `missing_header`
* `invalid_header`
***
## Request errors
#### RequestError
Server errors thrown when Customer API responds with an error code.
#### Request error codes
* `unauthorized` (401)
* `forbidden` (403)
* `not_found` (404)
* `conflict` (409)
* `validation_error` (422)
* `server_error` (5xx)
* `bad_request` (400)
* `request_error` (catch-all)
* `unexpected` (catch-all)
***
## Client errors
Following are error types thrown by the individual [SDK clients](/supertab-js/reference/overview).
#### AuthError
Thrown by [Supertab.auth](/supertab-js/reference/auth) when the error is related to authentication.
**Auth error codes**
* `auth_error`
#### CheckoutError
Thrown by [Supertab.checkout](/supertab-js/reference/checkout) when the error is related to the checkout process.
**Checkout error codes**
* `checkout_error`
* `validation_error`
#### ClientError
Thrown when the error happens client side, i.e. when the error is not related to the server or the clients themselves. Consider this a catch-all client error type.
# SDK Overview
Source: https://docs.supertab.co/supertab-js/reference/overview
For custom integrations going beyond experiences
Supertab.js provides a comprehensive low-level SDK. It can be used in pair with [experiences](/supertab-js/experiences/starting-experiences) or as a standalone library to build custom flows.
This low-level SDK does not feature any UI components and is focused on providing a way to consume Customer API responses directly while handling authentication and error management for you.
This reference guide documents clients available in the `Supertab` class (see [Installation](/supertab-js/installation)) and their methods. There are following client properties available:
* auth - Manages OAuth2 authentication
flows and session data retrieval.
* api - Facilitates direct access to Customer
API endpoints.
* checkout - Manages Supertab
Checkout sessions for purchases requiring payment.
# Supertab.createPurchaseButton
Source: https://docs.supertab.co/supertab-js/reference/purchase-button
Invoking Purchase Button experience in Supertab.js
## `createPurchaseButton`
```html theme={null}
```
```javascript theme={null}
const supertabClient = new Supertab({ clientId: "test_client.abc" });
const { destroy, initialState } = await supertabClient.createPurchaseButton({
containerElement: document.getElementById("supertab-button-container"),
experienceId: "experience.abc",
});
```
### Parameters
`createPurchaseButton` accepts the object with following properties:
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.
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`
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.
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.
The total amount of the tab.
Amount in currency base units.
Example: `50`
The limit of the tab. When reached, the payment will be required.
Amount in currency base units.
Example: `50`
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 { destroy, initialState } = 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.
}
}
```
# Product Updates
Source: https://docs.supertab.co/updates/product
## [Trigger Purchases Anywhere with Supertab.js](/updates/trigger-purchase-flow-2025-10-02)
The new createPurchase method in Supertab.js, makes it easier for developers to bring Supertab’s purchase flow directly into their applications programatically. This speeds up custom integrations via a simple function call and allows customization to tailor the purchase flow to your brand's design. [Read more...](/updates/trigger-purchase-flow-2025-10-02)
## [New Purchase Flow and Tab auto-closing: better UX for users, improved fund collection and branding options for Merchants](/updates/context-aware-purchase-flow-2025-08-22)
Our new purchase flow delivers a smoother, more consistent experience—fully styled to match your brand.
You can now enable card capture on a per-site basis and activate Tab auto-closing: after 30 days of inactivity, open Tabs are automatically charged, helping you secure revenue more reliably. [Read more...](/updates/context-aware-purchase-flow-2025-08-22)
## [Off-App Purchase Flow](/updates/off-app-purchase-flow-2025-06-09)
Enable direct transactions outside of app stores with Supertab’s new Off-App Purchase flow, keeping more revenue in your hands while offering a seamless user experience. [Read more...](/updates/off-app-purchase-flow-2025-06-09)
## [Improved Navigation with Site-Driven Architecture](/updates/site-driven-architecture-2025-05-10)
We’ve restructured how you navigate Offerings, Experiences, and settings—so it’s easier to manage multiple Sites and stay focused. [Read more...](/updates/site-driven-architecture-2025-05-10)
## [Dynamic Tab Limits to Close Payments Faster](/updates/dynamic-tab-limits-2025-05-10)
First-time users now get a smaller Tab limit to start, making it easier to complete a payment early and unlock the full \$5 Tab. Faster conversions for Merchants, shorter time-to-value value for users. [Read more...](/updates/dynamic-tab-limits-2025-05-10)
## [Get Started Faster — KYC Now Only Required at Payout](/updates/kyc-at-payout-2025-05-10)
Whether you’re using Supertab directly or through our integration with Google Ad Manager, you can now start earning without completing KYC upfront. [Read more...](/updates/kyc-at-payout-2025-05-10)
## [Customize Your Paygate Messaging in Multiple Languages](/updates/editable-paygate-copy-2025-04-16)
Tailor your Paygate messaging to fit your use case, test what converts best, and speak to users in one of eight supported languages. [Read more...](/updates/editable-paygate-copy-2025-04-16)
## [Validate Purchases with Server-Side Webhooks](/updates/webhooks-2025-02)
You can now securely confirm purchases and trigger real-time workflows—grant access, send emails, update analytics, and more. Plus, `onPurchaseComplete` now gives you detailed purchase data. [Read more...](/updates/webhooks-2025-02)
## [New Basic Paygate, Changes to the Purchase Button and Unlimited Offerings](/updates/experiences-2025-02-06)
You can now use the all new Supertab Paygate to secure and monetize your content or access to your SaaS product. The new Basic Paygate replaces existing Paygate installations and offers enhanced options for controlling how you price and sell your content.
Setup and installation takes minutes, existing customers are encouraged to migrate to the new Paygate Experience. [Read more...](/updates/experiences-2025-02-06)