> ## Documentation Index
> Fetch the complete documentation index at: https://supertab-feature-merchant-auth-change-again.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Supertab.api

> Methods reference for `Supertab.api`

`Supertab.api` provides a streamlined interface for making authenticated requests to the <a href="/customer-api">Customer API</a>. 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 <a href="/supertab-js/reference/auth">Supertab.auth</a> 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

<Info>Each method returns a promise which resolves with the response from the Customer API endpoint with object keys transformed from snake\_case to camelCase.</Info>

See <a href="./errors">Errors</a> for a list of common exceptions.

### `retrieveCustomer`

Retrieves the current customer.

<Info>
  **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 <a href="/supertab-js/reference/auth">after auth</a> to get limits in the user's tab currency.

  You must re-fetch this information after a new auth session is started.
</Info>

#### Returns

Customer object. See <a href="/customer-api/endpoints/retrieve-customer">Retrieve current customer</a>.
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).

<Info>
  **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 <a href="/supertab-js/reference/auth">after auth</a> 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.
</Info>

#### Returns

Website object. See <a href="/customer-api/endpoints/retrieve-site">Retrieve site</a>.
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.

<Warning>**Auth:** required</Warning>

#### Parameters

<ParamField path="contentKey" type="string" required>
  The content key of the entitlement to check.
</ParamField>

#### Returns

An object with the entitlement details. See <a href="/customer-api/endpoints/retrieve-entitlement-status">Retrieve entitlement status</a>.
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.

<Warning>**Auth:** required</Warning>

#### Parameters

<Info>Either `offeringId` or `onetimeOfferingId` must be provided.</Info>

<ParamField path="offeringId" type="string">
  The offering ID to purchase.
</ParamField>

<ParamField path="onetimeOfferingId" type="string">
  The onetime offering ID to purchase.
</ParamField>

<ParamField path="currencyCode" type="string" required>
  ISO4217 currency code.
  <Warning>Must match the currency of user's tab, otherwise the purchase will fail.</Warning>
</ParamField>

<ParamField path="metadata" type="object">
  Free-form metadata to associate with the purchase.
</ParamField>

#### Returns

Purchase object. See <a href="/customer-api/endpoints/purchase-an-offering">Purchase an offering</a> 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.

<Warning>**Auth:** required</Warning>

#### Parameters

<ParamField path="purchaseId" type="string" required>
  The purchase ID to retrieve.
</ParamField>

#### Returns

Purchase object. See <a href="/customer-api/endpoints/retrieve-a-purchase">Retrieve a purchase</a>.
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"
});
```