> ## 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.createPurchaseButton

> Invoking Purchase Button experience in Supertab.js

## `createPurchaseButton`

```html theme={null}
<div id="supertab-button-container"></div>
```

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

<ParamField path="containerElement" type="Element" required>
  Container element to render purchase button in. Elements are appended to the
  container, so original contents are not replaced.
</ParamField>

<ParamField path="experienceId" type="string" required>
  ID of the purchase button experience created in Business Portal.
</ParamField>

<ParamField path="purchaseMetadata" type="object">
  Key-value pairs of custom information associated with the purchase.
</ParamField>

<ParamField path="onDone" type="function">
  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.
</ParamField>

### Return value

A promise which resolves with an object with following properties:

<ResponseField name="destroy" type="function">
  Destroy Supertab button instance. This removes all nodes related to Supertab
  button from DOM.
</ResponseField>

<ResponseField name="initialState" type="object">
  Initial state of the purchase button. See [Purchase button
  summary](#purchase-button-summary) for more details.
</ResponseField>

## Purchase button summary

Both the returned `initialState` object and the object passed as an argument to the `onDone` callback contain the following properties:

<ResponseField name="priorEntitlement" type="EntitlementStatus | null">
  Any prior entitlement of the current user. `null` if user has no prior entitlement.

  <Expandable title="prior entitlement">
    <ResponseFieldsEntitlement />
  </Expandable>
</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.

  <Expandable title="purchase object">
    <ResponseField name="id" type="string">
      ID of the purchase.

      Example: `"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"`
    </ResponseField>

    <ResponseField name="offeringId" type="string">
      ID of the purchased offering.

      Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
    </ResponseField>

    <ResponseField name="purchasedAt" type="string | null">
      Date and time of the purchase.

      Example: `"2025-04-30T12:00:00Z"`
    </ResponseField>

    <ResponseField name="completedAt" type="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"`
    </ResponseField>

    <ResponseField name="description" type="string">
      A summary of the purchase, usually including the website name and the type of a given entitlement.

      Example: `"The Leek - 24 Hours Time Pass"`
    </ResponseField>

    <ResponseField name="price" type="Price">
      Price object of the purchase.

      <Expandable title="Price object">
        <ResponseField name="amount" type="number">
          Amount in currency base units.

          Example: `5000`
        </ResponseField>

        <ResponseField name="currency" type="Currency">
          <ResponseFieldsCurrency />
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="PurchaseStatus">
      Status of the purchase. Possible values: `completed`, `pending`, `abandoned`.
    </ResponseField>

    <ResponseField name="metadata" type="Metadata">
      Key-value pairs of custom information associated with the purchase.
    </ResponseField>

    <ResponseField name="entitlementStatus" type="EntitlementStatus | null">
      The customer's access (if any) as a result of this purchase.

      <Expandable title="Entitlement status object">
        <ResponseFieldsEntitlement />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="purchasedOffering" type="Offering | null">
  Offering object if user has purchased an offering. `null` otherwise.

  <Expandable title="offering object">
    <ResponseField name="id" type="string">
      ID of the offering.

      Example: `"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"`
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the offering.

      Example: `"24 Hours Time Pass to The Leek"`
    </ResponseField>

    <ResponseField name="entitlementDetails" type="EntitlementDetails">
      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.

      <Expandable title="Entitlement details object">
        <ResponseField name="duration" type="string">
          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"
          }
          ```
        </ResponseField>

        <ResponseField name="isRecurring" type="boolean">
          Whether the entitlement is sold on a recurring basis (subscription).
        </ResponseField>

        <ResponseField name="contentKey" type="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"`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="price" type="Price">
      Price object of the offering.

      <ResponseFieldsPrice />
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tab" type="Tab">
  The users tab

  <Expandable title="Tab object">
    <ResponseField name="testMode" type="boolean">
      Whether the tab is in test mode.
    </ResponseField>

    <ResponseField name="currency" type="Currency">
      The currency of the tab.

      <ResponseFieldsCurrency />
    </ResponseField>

    <ResponseField name="total" type="Price">
      The total amount of the tab.

      <Expandable title="Total object">
        <ResponseField name="amount" type="number">
          Amount in currency base units.

          Example: `50`
        </ResponseField>

        <ResponseField name="currency" type="Currency">
          <ResponseFieldsCurrency />
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="limit" type="Price">
      The limit of the tab. When reached, the payment will be required.

      <Expandable title="Limit object">
        <ResponseField name="amount" type="number">
          Amount in currency base units.

          Example: `50`
        </ResponseField>

        <ResponseField name="currency" type="Currency">
          <ResponseFieldsCurrency />
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="purchases" type="Array<Purchase>">
      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).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="paymentResult" type="boolean">
  If a purchase required payment, this will be `true` if payment was successful. `false` otherwise.
</ResponseField>

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