### Load Supertab.js via CDN (Global Loader - Promise Chaining)

Source: https://docs.supertab.co/supertab-js/installation

An alternative method using the global loader script from the CDN, this example shows how to initialize Supertab.js using promise chaining with `.then()`.

```javascript
<script src="https://js.supertab.co/v3/supertab.global.js"></script>
<script>
    window.loadSupertab().then(({ Supertab }) => {
        new Supertab({ clientId: "test_client.X" })
    });
</script>
```

--------------------------------

### Initialize Supertab.js with npm

Source: https://docs.supertab.co/supertab-js/installation

After installing via npm, import the `Supertab` class and instantiate it with your `clientId`. This sets up the Supertab client for your application.

```javascript
import { Supertab } from "@getsupertab/supertab-js";

const supertabClient = new Supertab({ clientId: "test_client.X" });
```

--------------------------------

### Load Supertab.js via CDN (Global Loader - Async/Await)

Source: https://docs.supertab.co/supertab-js/installation

Use the global loader script from the CDN for environments that do not support ES modules. This example demonstrates initialization using `async/await` to handle the promise returned by `window.loadSupertab()`.

```javascript
<script src="https://js.supertab.co/v3/supertab.global.js"></script>
<script>
    (async () => {
        const { Supertab } = await window.loadSupertab();
        const supertabClient = new Supertab({ clientId: "test_client.X" });
    })();
</script>
```

--------------------------------

### Content Key Example (String)

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

An example of a content key, which uniquely identifies the content being purchased when Supertab manages customer entitlements. This is a string value representing a specific offering.

```string
"site.cf637646-71a4-430d-aaea-a66f1a48a83c"
```

--------------------------------

### Currency Name Example (String)

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Example of a currency name, providing the full name of the currency. For example, 'United States Dollar' corresponds to the 'USD' currency code.

```string
"United States Dollar"
```

--------------------------------

### Install Supertab.js via npm

Source: https://docs.supertab.co/supertab-js/installation

Install the Supertab.js package using npm for use with module bundlers. This is the recommended approach for most modern JavaScript projects.

```bash
npm install @getsupertab/supertab-js
```

--------------------------------

### Create SuperTab Purchase Button

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

This example shows how to create a purchase button using the SuperTab client. It handles different scenarios like prior entitlement, successful completion, cancellation, and payment failures. Dependencies include the SuperTab client library and a container element in the DOM.

```javascript
const supertabButton = await supertabClient.createPurchaseButton({
  containerElement: document.getElementById("supertab-button-container"),
  experienceId: "experience.abc",
  onDone: ({ priorEntitlement, purchase }) => {
    if (priorEntitlement) {
      // User has prior entitlement to the content.
      return;
    }

    if (purchase) {
      if (purchase.status === "completed") {
        // Purchase was completed successfully.
      } else {
        // Purchase was not completed. User may have
        // canceled the payment dialog if purchase
        // required payment.
      }
    } else {
      // User has canceled the flow and did not
      // attempt to purchase the offering.
    }
  }
});
```

--------------------------------

### Example Currency Durations

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Illustrates various formats for specifying entitlement duration, including years, months, weeks, days, hours, minutes, and seconds. This is crucial for defining subscription periods.

```json
{
  "duration": "1y" // 1 year
},
{
  "duration": "2M" // 2 months
},
{
  "duration": "3w" // 3 weeks
},
{
  "duration": "4d" // 4 days
},
{
  "duration": "5h" // 5 hours
},
{
  "duration": "6m" // 6 minutes
},
{
  "duration": "7s" // 7 seconds
}
```

--------------------------------

### Purchase Button State Summary

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Details the structure of the `ExperienceStateSummary` object which is returned upon initialization and passed to the `onDone` callback.

```APIDOC
## Purchase Button State Summary

This documentation outlines the structure of the `ExperienceStateSummary` object, which is provided both as the initial state of the purchase button and as an argument to the `onDone` callback.

### Response Body Structure

`ExperienceStateSummary`:

- **priorEntitlement** (EntitlementStatus | null) - Information about the user's prior entitlement. `null` if no prior entitlement exists.
  - **contentKey** (string) - The content key associated with the entitlement. Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
  - **hasEntitlement** (boolean) - Indicates if the user has entitlement to the content key.
  - **expires** (string) - The expiration date and time of the user's access. Example: `"2025-04-30T12:00:00Z"`
  - **recursAt** (string) - The date and time when the next billing period starts, if it's a subscription. Example: `"2025-04-30T12:00:00Z"`

- **authStatus** (AuthStatus) - The current authentication status of the user. Possible values: `"missing"`, `"expired"`, `"valid"`.

- **purchase** (Purchase | null) - Details of a purchase made through the flow. `null` if no purchase occurred.
  - **id** (string) - The unique identifier for the purchase. Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
  - **offeringId** (string) - The identifier of the purchased offering. Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
  - **purchasedAt** (string | null) - The date and time when the purchase was made. Example: `"2025-04-30T12:00:00Z"`
  - **completedAt** (string | null) - The date and time when the purchase was successfully completed. Example: `"2025-04-30T12:00:00Z"`
  - **description** (string) - A summary description of the purchase. Example: `"The Leek - 24 Hours Time Pass"`
  - **price** (Price) - An object containing the price details of the purchase.
    - **amount** (number) - The purchase amount in the currency's base units. Example: `5000`
    - **currency** (Currency) - An object detailing the currency used for the purchase.
      - **code** (string) - The currency code. Example: `"USD"`
      - **name** (string) - The full name of the currency. Example: `"United States Dollar"`
      - **symbol** (string) - The currency symbol. Example: `"$"`
      - **baseUnit** (number) - The base unit of the currency. Example: `100`
  - **status** (PurchaseStatus) - The status of the purchase. Possible values: `"completed"`, `"pending"`, `"abandoned"`.
  - **metadata** (Metadata) - Custom key-value pairs associated with the purchase.
  - **entitlementStatus** (EntitlementStatus | null) - The entitlement status resulting from this purchase.
    - **contentKey** (string) - The content key of the entitlement. Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
    - **hasEntitlement** (boolean) - Indicates if the user has entitlement to the content key.
    - **expires** (string) - The expiration date and time of the entitlement. Example: `"2025-04-30T12:00:00Z"`
    - **recursAt** (string) - The date and time of the next billing period start for subscriptions. Example: `"2025-04-30T12:00:00Z"`
```

--------------------------------

### Customer Purchase Information

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Retrieves detailed information about a customer's purchases and their initial paywall experience state.

```APIDOC
## GET /customer/purchase

### Description
Retrieves detailed information about a customer's purchases and their initial paywall experience state.

### Method
GET

### Endpoint
/customer/purchase

### Parameters
#### Query Parameters
- **customerId** (string) - Required - The unique identifier for the customer.

### Request Body
None

### Response
#### Success Response (200)
- **purchases** (Array<Purchase>) - Details of all purchases made by the customer.
- **paymentResult** (boolean) - Indicates if a purchase required payment and was successful.
- **initialState** (ExperienceStateSummary) - The initial state of the paywall experience.

#### Response Example
```json
{
  "purchases": [
    {
      "id": "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c",
      "offeringId": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
      "purchasedAt": "2025-04-30T12:00:00Z",
      "completedAt": "2025-04-30T12:00:00Z",
      "description": "The Leek - 24 Hours Time Pass",
      "price": {
        "amount": 5000,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "baseUnit": 100
        }
      },
      "status": "completed",
      "metadata": {}
    }
  ],
  "paymentResult": true,
  "initialState": {
    "priorEntitlement": {
      "contentKey": "site.cf637646-71a4-430d-aaea-a66f1a48a83c",
      "hasEntitlement": true,
      "expires": "2025-04-30T12:00:00Z",
      "recursAt": "2025-04-30T12:00:00Z"
    },
    "authStatus": "valid",
    "purchase": null
  }
}
```

### Error Handling
- **400 Bad Request**: Invalid customer ID provided.
- **404 Not Found**: Customer not found.
- **500 Internal Server Error**: An unexpected error occurred.
```

--------------------------------

### Amount Example (Number)

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Example of an amount, representing a numerical value in the currency's base units. This is often used for prices, totals, or limits.

```number
50
```

--------------------------------

### Currency Symbol Example (String)

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Example of a currency symbol, the common graphical representation used for a particular currency. For example, '$' is the symbol for the United States Dollar.

```string
"$"
```

--------------------------------

### Entitlement Duration Examples (JSON)

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Examples demonstrating the format for entitlement duration, specifying length and unit (e.g., years, months, days, hours, minutes, seconds). This format is used when Supertab manages customer entitlements for content offerings.

```json
{
  "duration": "1y"
}
{
  "duration": "2M"
}
{
  "duration": "3w"
}
{
  "duration": "4d"
}
{
  "duration": "5h"
}
{
  "duration": "6m"
}
{
  "duration": "7s"
}
```

--------------------------------

### Currency Code Example (String)

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Example of a currency code, typically a three-letter ISO 4217 code, used to identify the currency for transactions or limits. For instance, 'USD' represents the United States Dollar.

```string
"USD"
```

--------------------------------

### Hide Function and State Summary

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Documentation for the `hide` function, which hides the paywall UI, and the `StateSummary` object it returns.

```APIDOC
## Function: `hide`

### Description
Hides the paywall UI.

Returns a promise which resolves with the paywall summary.

### Method
function

### Returns
`Promise<StateSummary>`

### `StateSummary` Object Details:

- **`priorEntitlement`** (EntitlementStatus | null) - Any prior entitlement of the current user. `null` if the user has no prior entitlement.
  - **`contentKey`** (string) - The content key of the entitlement. Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
  - **`hasEntitlement`** (boolean) - Whether the customer has entitlement to the content key.
  - **`expires`** (string) - When the customer's access will expire. Example: `"2025-04-30T12:00:00Z"`
  - **`recursAt`** (string) - If this access is a result of a subscription, this will be the date and time when the next billing period starts. Example: `"2025-04-30T12:00:00Z"`

- **`authStatus`** (AuthStatus) - Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.

- **`purchase`** (Purchase | null) - Purchase object if launching the flow resulted in a purchase. `null` otherwise.
  - **`id`** (string) - ID of the purchase. Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
  - **`offeringId`** (string) - ID of the purchased offering. Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
  - **`purchasedAt`** (string | null) - Date and time of the purchase. Example: `"2025-04-30T12:00:00Z"`
  - **`completedAt`** (string | null) - Date and time of the purchase completion, i.e., when payment was successful if purchase required payment. Example: `"2025-04-30T12:00:00Z"`
  - **`description`** (string) - A summary of the purchase, usually including the site name and the type of a given entitlement. Example: `"The Leek - 24 Hours Time Pass"`
  - **`price`** (Price) - Price object of the purchase.
    - **`amount`** (number) - Amount in currency base units. Example: `5000`
    - **`currency`** (Currency) - Currency object detailing the currency of the purchase.
      - **`code`** (string) - Currency code. Example: `"USD"`
      - **`name`** (string) - Currency name. Example: `"United States Dollar"`
      - **`symbol`** (string) - Currency symbol. Example: `"$"`
      - **`baseUnit`** (number) - Base unit of the currency. Example: `100`
```

--------------------------------

### Paywall API

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

This API section describes the functionality related to displaying and managing the paywall UI, including details about the returned promise and its resolution object.

```APIDOC
## Show Paywall UI

### Description
Displays the paywall UI to the user. This function returns a promise that resolves with a summary of the paywall state, including entitlement and authentication status.

### Method
```
Promise
```

### Endpoint
```
Not applicable (function call)
```

### Parameters
None

### Request Example
```javascript
// Example of calling the function
supertab.showPaywall().then(paywallSummary => {
  console.log(paywallSummary);
});
```

### Response
#### Success Response
- **show** (function) - A function that displays the paywall UI and returns a promise resolving to `StateSummary`.

  <Expandable title="StateSummary">
    <ResponseField name="priorEntitlement" type="EntitlementStatus | null">Any prior entitlement of the current user. `null` if user has no prior entitlement.</ResponseField>
    <ResponseField name="authStatus" type="AuthStatus">Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.</ResponseField>
    <ResponseField name="purchase" type="Purchase | null">Purchase object if launching the flow resulted in a purchase. `null` otherwise.</ResponseField>
  </Expandable>

#### Response Example
```json
{
  "priorEntitlement": {
    "contentKey": "site.cf637646-71a4-430d-aaea-a66f1a48a83c",
    "hasEntitlement": true,
    "expires": "2025-04-30T12:00:00Z",
    "recursAt": "2025-04-30T12:00:00Z"
  },
  "authStatus": "valid",
  "purchase": null
}
```

### Error Handling
- If the current user has prior entitlement to the content, the paywall will not show.
```

--------------------------------

### Load Supertab.js via CDN (ES Module)

Source: https://docs.supertab.co/supertab-js/installation

Load Supertab.js directly as an ES Module from the CDN. This method is suitable for projects that support ES modules and allows direct import of the `Supertab` class.

```javascript
<script type="module">
    import { Supertab } from "https://js.supertab.co/v3/supertab.js"

    const supertabClient = new Supertab({ clientId: "test_client.X" });
</script>
```

--------------------------------

### Response Field Details

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Details on various response fields including limits, purchases, and payment results.

```APIDOC
## Response Fields

### Response Field: `limit`

**Type:** `Price`

**Description:** The limit of the tab. When reached, payment will be required.

#### `limit` Object Details:

- **`amount`** (number) - Amount in currency base units. Example: `50`
- **`currency`** (Currency) - Currency object detailing the currency used for the limit.
  - **`code`** (string) - Currency code. Example: `"USD"`
  - **`name`** (string) - Currency name. Example: `"United States Dollar"`
  - **`symbol`** (string) - Currency symbol. Example: `"$"`
  - **`baseUnit`** (number) - Base unit of the currency. Example: `100`

### Response Field: `purchases`

**Type:** `Array<Purchase>`

**Description:** 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 [Purchase object](#param-purchase).

### Response Field: `paymentResult`

**Type:** `boolean`

**Description:** If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
```

--------------------------------

### Offering Object Structure

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Describes the structure of an offering object, representing a purchasable item. It includes the offering ID, description, entitlement details, and price.

```json
{
  "id": "string",
  "description": "string",
  "entitlementDetails": { ... },
  "price": { ... }
}
```

--------------------------------

### Purchase Button Creation API

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Provides instructions and parameters for creating a Supertab purchase button within a specified HTML container element.

```APIDOC
## POST /websites/supertab_co/createPurchaseButton

### Description
Creates a Supertab purchase button and renders it within a provided container element.

### Method
POST

### Endpoint
/websites/supertab_co/createPurchaseButton

### Parameters
#### Request Body
- **containerElement** (Element) - Required - The HTML element where the purchase button will be rendered.
- **experienceId** (string) - Required - The ID of the purchase button experience configured in the Business Portal.
- **purchaseMetadata** (object) - Optional - Key-value pairs for custom purchase information.
- **onDone** (function) - Optional - A callback function executed when the user exits the purchase flow. It returns a promise that resolves with a purchase button summary.

### Request Example
```javascript
const supertabButton = supertabClient.createPurchaseButton({
  containerElement: document.getElementById("supertab-button-container"),
  experienceId: "experience.abc",
  purchaseMetadata: { userId: "user123" },
  onDone: async (summary) => {
    console.log("Purchase flow ended:", summary);
  }
});
```

### Response
#### Success Response (200)
An object containing methods to manage the button instance and its initial state.

#### Response Example
```json
{
  "destroy": "function",
  "initialState": {
    "state": "initial",
    "purchaseId": "purchase-xyz",
    "amount": {
      "amount": 1000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    },
    "limit": {
      "amount": 5000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    },
    "purchases": [],
    "paymentResult": false
  }
}
```

### Error Handling
- **400 Bad Request**: If required parameters are missing or invalid.
- **500 Internal Server Error**: If there is a server-side issue.
```

--------------------------------

### Purchase Response Fields

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Details on the fields returned in a purchase response, including status, metadata, entitlement status, and purchased offering information.

```APIDOC
## Response Fields

### Response Body

This section details the fields within the response body for purchase-related API calls.

#### Response Fields

- **purchase** (object) - Information about the purchase.
  - **currency** (object) - Details about the currency used for the purchase.
    - **code** (string) - Currency code. Example: `"USD"
    - **name** (string) - Currency name. Example: `"United States Dollar"
    - **symbol** (string) - Currency symbol. Example: `"$"
    - **baseUnit** (number) - Base unit of the currency. Example: `100
  - **status** (PurchaseStatus) - Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
  - **metadata** (object) - Key-value pairs of custom information associated with the purchase.
  - **entitlementStatus** (EntitlementStatus | null) - The customer's access (if any) as a result of this purchase.
    - **contentKey** (string) - The content key of the entitlement. Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"
    - **hasEntitlement** (boolean) - Whether the customer has entitlement to the content key.
    - **expires** (string) - When the customer's access will expire. Example: `"2025-04-30T12:00:00Z"
    - **recursAt** (string) - If this access is a result of a subscription, this will be the date and time when the next billing period starts. Example: `"2025-04-30T12:00:00Z"
  - **purchasedOffering** (object | null) - Offering object if user has purchased an offering. `null` otherwise.
    - **id** (string) - ID of the offering. Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"
    - **description** (string) - Description of the offering. Example: `"24 Hours Time Pass to The Leek"
    - **entitlementDetails** (object) - Specifies the nature and duration of purchased entitlement.
      - **duration** (string) - The duration of the entitlement as `{length}{unit}`. Examples: `"1y"`, `"2M"`, `"3w"`, `"4d"`, `"5h"`, `"6m"`, `"7s"
      - **isRecurring** (boolean) - Whether the entitlement is sold on a recurring basis (subscription).
      - **contentKey** (string) - 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) - Price object of the offering.
  - **tab** (object) - The users tab.
    - **testMode** (boolean) - Whether the tab is in test mode.
    - **currency** (object) - The currency of the tab.

### Response Example

```json
{
  "purchase": {
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "baseUnit": 100
    },
    "status": "completed",
    "metadata": {},
    "entitlementStatus": {
      "contentKey": "site.cf637646-71a4-430d-aaea-a66f1a48a83c",
      "hasEntitlement": true,
      "expires": "2025-04-30T12:00:00Z",
      "recursAt": null
    },
    "purchasedOffering": {
      "id": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
      "description": "24 Hours Time Pass to The Leek",
      "entitlementDetails": {
        "duration": "1y",
        "isRecurring": false,
        "contentKey": "site.cf637646-71a4-430d-aaea-a66f1a48a83c"
      },
      "price": {
        "currency": "USD",
        "amount": 1000,
        "currencySymbol": "$"
      }
    },
    "tab": {
      "testMode": false,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    }
  }
}
```
```

--------------------------------

### Create and Show Paywall with Supertab.js

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Demonstrates how to create a paywall instance using the Supertab client and then display it to the user. This requires a pre-configured experience ID from the Business Portal.

```javascript
const supertabClient = new Supertab({ clientId: "test_client.abc" });

const supertabPaywall = await supertabClient.createPaywall({
  experienceId: "experience.abc",
});

supertabPaywall.show()
```

--------------------------------

### Customer API Authentication Guide

Source: https://docs.supertab.co/customer-api/authentication

All requests to the Customer API require authentication with a bearer token and specific headers. This section outlines the requirements and provides examples.

```APIDOC
## Customer API Authentication

> Generate bearer tokens for usage with the Customer API

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, and an `x-api-version` 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.

### Headers

- **Authorization** (string) - Required - The bearer token for authentication. Format: `Bearer YOUR_TOKEN`
- **x-supertab-client-id** (string) - Required - Your unique client ID.
- **x-api-version** (string) - Required - The version of the API to use. Format: `YYYY-MM-DD`

### API Settings

- **Base URL**: `https://tapi.supertab.co/capi/`
- **Supported Grants**: `Authorization Code + PKCE`, `Refresh Token`
- **Token Type**: `bearer`

### Example Authenticated Request (curl)

```bash
curl --location 'https://tapi.supertab.co/capi/customers/me' \
--header 'Authorization: Bearer ••••••' \
--header 'x-supertab-client-id: ••••••' \
--header 'x-api-version: 2025-04-01'
```

### Example Authenticated Request (JavaScript)

```javascript
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();
})
```

### Scopes

The Customer API is scoped to allow issuing tokens with minimum permissions.

- `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.
```

--------------------------------

### User Purchase and Entitlement Details

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

This section details the structure of responses related to user purchases and their associated entitlements. It includes information about the purchase itself, the offering, and the status of the user's access to content.

```APIDOC
## User Purchase and Entitlement Details

### Description
Provides details about a user's purchase, including the offering, price, status, and entitlement information. This is useful for understanding user access rights and purchase history.

### Endpoint
N/A (This describes response structures, not a specific endpoint)

### Response
#### Success Response (200)
- **authStatus** (AuthStatus) - Current authentication status of the user. Possible values: `missing`, `expired`, `valid`.
- **purchase** (Purchase | null) - Purchase object if launching the flow resulted in a purchase. `null` otherwise.
  - **purchase.id** (string) - ID of the purchase. Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
  - **purchase.offeringId** (string) - ID of the purchased offering. Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
  - **purchase.purchasedAt** (string | null) - Date and time of the purchase. Example: `"2025-04-30T12:00:00Z"`
  - **purchase.completedAt** (string | null) - Date and time of the purchase completion. Example: `"2025-04-30T12:00:00Z"`
  - **purchase.description** (string) - A summary of the purchase. Example: `"The Leek - 24 Hours Time Pass"`
  - **purchase.price** (Price) - Price object of the purchase.
    - **purchase.price.amount** (number) - Amount in currency base units. Example: `5000`
    - **purchase.price.currency** (Currency) - Currency object.
      - **purchase.price.currency.code** (string) - Currency code. Example: `"USD"`
      - **purchase.price.currency.name** (string) - Currency name. Example: `"United States Dollar"`
      - **purchase.price.currency.symbol** (string) - Currency symbol. Example: `"$"`
      - **purchase.price.currency.baseUnit** (number) - Base unit of the currency. Example: `100`
  - **purchase.status** (PurchaseStatus) - Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
  - **purchase.metadata** (Metadata) - Key-value pairs of custom information associated with the purchase.
  - **purchase.entitlementStatus** (EntitlementStatus | null) - The customer's access (if any) as a result of this purchase.
    - **purchase.entitlementStatus.contentKey** (string) - The content key of the entitlement. Example: `"site.cf637646-71a4-430d-aaea-a66f1a48a83c"`
    - **purchase.entitlementStatus.hasEntitlement** (boolean) - Whether the customer has entitlement to the content key.
    - **purchase.entitlementStatus.expires** (string) - When the customer's access will expire. Example: `"2025-04-30T12:00:00Z"`
    - **purchase.entitlementStatus.recursAt** (string) - When the next billing period starts. Example: `"2025-04-30T12:00:00Z"`
- **purchasedOffering** (Offering | null) - Offering object if user has purchased an offering. `null` otherwise.
  - **purchasedOffering.id** (string) - ID of the offering. Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
  - **purchasedOffering.description** (string) - Description of the offering. Example: `"24 Hours Time Pass to The Leek"`
  - **purchasedOffering.entitlementDetails** (EntitlementDetails) - Specifies the nature and duration of purchased entitlement.

#### Response Example
```json
{
  "authStatus": "valid",
  "purchase": {
    "id": "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c",
    "offeringId": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "purchasedAt": "2025-04-30T12:00:00Z",
    "completedAt": "2025-04-30T12:00:00Z",
    "description": "The Leek - 24 Hours Time Pass",
    "price": {
      "amount": 5000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    },
    "status": "completed",
    "metadata": {},
    "entitlementStatus": {
      "contentKey": "site.cf637646-71a4-430d-aaea-a66f1a48a83c",
      "hasEntitlement": true,
      "expires": "2025-04-30T12:00:00Z",
      "recursAt": "2025-04-30T12:00:00Z"
    }
  },
  "purchasedOffering": {
    "id": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "description": "24 Hours Time Pass to The Leek",
    "entitlementDetails": {
      "duration": "24h",
      "expiresAt": "2025-04-30T12:00:00Z"
    }
  }
}
```
```

--------------------------------

### Create Supertab Paygate Example (JavaScript)

Source: https://docs.supertab.co/supertab-js/reference/create-paygate

This JavaScript code snippet demonstrates how to initialize the Supertab client and create a paygate using the `createPaygate` method. It requires the `experienceId` as a parameter and returns a promise that resolves with paygate state and methods to interact with it.

```javascript
const supertabClient = new Supertab({clientId: "client.your_client"});

const supertabPaygate = await supertabClient.createPaygate({
    experienceId: "experience.your_experience"
});
```

--------------------------------

### Make Authenticated Request to Customer API (JavaScript)

Source: https://docs.supertab.co/customer-api/authentication

Example of how to make an authenticated GET request to the Customer API using JavaScript's fetch API. It shows how to include the Authorization, x-supertab-client-id, and x-api-version headers.

```javascript
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();
})
```

--------------------------------

### Create Purchase Button with Supertab

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Renders a Supertab purchase button within a specified HTML container element. It requires a container element and an experience ID. Optional parameters include custom purchase metadata and a callback function executed upon completion of the purchase flow. The function returns a promise that resolves with methods to destroy the button instance and its initial state summary.

```html
<div id="supertab-button-container"></div>
```

```javascript
const supertabButton = supertabClient.createPurchaseButton({
  containerElement: document.getElementById("supertab-button-container"),
  experienceId: "experience.abc",
});
```

--------------------------------

### Make Authenticated Request to Customer API (curl)

Source: https://docs.supertab.co/customer-api/authentication

Example of how to make an authenticated GET request to the Customer API using curl. It demonstrates passing the bearer token, client ID, and API version in the headers.

```bash
curl --location 'https://tapi.supertab.co/capi/customers/me' \
--header 'Authorization: Bearer ••••••' \
--header 'x-supertab-client-id: ••••••' \
--header 'x-api-version: 2025-04-01'
```

--------------------------------

### User Access and Offering Details

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

Retrieve detailed information about a user's access, including expiration dates and any purchased offerings. This section details the structure of the response when fetching user-specific data, focusing on entitlement and subscription details.

```APIDOC
## GET /users/{userId}/access

### Description
Retrieves the access details for a specific user, including information about any purchased offerings and the user's tab configuration.

### Method
GET

### Endpoint
/users/{userId}/access

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **expiresAt** (string) - The date and time when the customer's access will expire.
- **recursAt** (string) - If this access is a result of a subscription, this will be the date and time when the next billing period starts.
- **purchasedOffering** (object | null) - Offering object if user has purchased an offering. `null` otherwise.
  - **id** (string) - ID of the offering.
  - **description** (string) - Description of the offering.
  - **entitlementDetails** (object) - Specifies the nature and duration of purchased entitlement.
    - **duration** (string) - The duration of the entitlement as `{length}{unit}` (e.g., "1y", "2M", "3w", "4d", "5h", "6m", "7s").
    - **isRecurring** (boolean) - Whether the entitlement is sold on a recurring basis (subscription).
    - **contentKey** (string) - The content key being purchased, if Supertab manages customer entitlement.
  - **price** (object) - Price object of the offering.
    - **amount** (number) - Amount in currency base units.
    - **currency** (object) - Currency details.
      - **code** (string) - Currency code.
      - **name** (string) - Currency name.
      - **symbol** (string) - Currency symbol.
      - **baseUnit** (number) - Base unit of the currency.
- **tab** (object) - The users tab.
  - **testMode** (boolean) - Whether the tab is in test mode.
  - **currency** (object) - The currency of the tab.
    - **code** (string) - Currency code.
    - **name** (string) - Currency name.
    - **symbol** (string) - Currency symbol.
    - **baseUnit** (number) - Base unit of the currency.
  - **total** (object) - The total amount of the tab.
    - **amount** (number) - Amount in currency base units.
    - **currency** (object) - Currency details.
      - **code** (string) - Currency code.
      - **name** (string) - Currency name.
      - **symbol** (string) - Currency symbol.
      - **baseUnit** (number) - Base unit of the currency.

#### Response Example
```json
{
  "expiresAt": "2025-04-30T12:00:00Z",
  "recursAt": "2025-04-30T12:00:00Z",
  "purchasedOffering": {
    "id": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "description": "24 Hours Time Pass to The Leek",
    "entitlementDetails": {
      "duration": "1y",
      "isRecurring": true,
      "contentKey": "site.cf637646-71a4-430d-aaea-a66f1a48a83c"
    },
    "price": {
      "amount": 5000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    }
  },
  "tab": {
    "testMode": false,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "baseUnit": 100
    },
    "total": {
      "amount": 5000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    }
  }
}
```
```

--------------------------------

### Entitlement Duration Examples

Source: https://docs.supertab.co/supertab-js/reference/purchase-button

This snippet provides examples of how entitlement durations are represented. Durations are specified as a numerical value followed by a unit of time (y for year, M for month, w for week, d for day, h for hour, m for minute, s for second).

```json
{
  "duration": "1y" // 1 year
}
{
  "duration": "2M" // 2 months
}
{
  "duration": "3w" // 3 weeks
}
{
  "duration": "4d" // 4 days
}
{
  "duration": "5h" // 5 hours
}
{
  "duration": "6m" // 6 minutes
}
{
  "duration": "7s" // 7 seconds
}
```

--------------------------------

### User Authentication and Purchase Information

Source: https://docs.supertab.co/supertab-js/experiences/starting-experiences

This section details the structure of the response object for user authentication and purchase-related information. It includes details about the tab, total amount, limit, purchases, and payment results.

```APIDOC
## GET /user/tab

### Description
Retrieves the current user's tab information, including total amount, limits, purchase history, and payment status.

### Method
GET

### Endpoint
/user/tab

### Parameters

### Request Body
None

### Request Example
```json
{
  "example": "No request body for this GET endpoint."
}
```

### Response
#### Success Response (200)
- **tab** (object) - Details about the user's current tab.
  - **total** (Price) - The total amount of the tab.
    - **amount** (number) - Amount in currency base units. Example: `50`
    - **currency** (Currency) - Currency details.
      - **code** (string) - Currency code. Example: `"USD"`
      - **name** (string) - Currency name. Example: `"United States Dollar"`
      - **symbol** (string) - Currency symbol. Example: `"$"`
      - **baseUnit** (number) - Base unit of the currency. Example: `100`
  - **limit** (Price) - The limit of the tab. When reached, the payment will be required.
    - **amount** (number) - Amount in currency base units. Example: `50`
    - **currency** (Currency) - Currency details.
      - **code** (string) - Currency code. Example: `"USD"`
      - **name** (string) - Currency name. Example: `"United States Dollar"`
      - **symbol** (string) - Currency symbol. Example: `"$"`
      - **baseUnit** (number) - Base unit of the currency. Example: `100`
  - **purchases** (Array<Purchase>) - Details of all purchases made by the customer.
- **paymentResult** (boolean) - If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.

#### Response Example
```json
{
  "tab": {
    "total": {
      "amount": 50,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    },
    "limit": {
      "amount": 50,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "baseUnit": 100
      }
    },
    "purchases": [
      {
        "id": "purchase_123",
        "amount": 25,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "baseUnit": 100
        },
        "timestamp": "2024-01-01T10:00:00Z"
      }
    ]
  },
  "paymentResult": true
}
```
```