Supertab.createPurchaseButton

Invoking Purchase Button experience in Supertab.js

createPurchaseButton

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

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:

containerElement · Element · required

Container element to render purchase button in. Elements are appended to the container, so original contents are not replaced.

experienceId · string · required

ID of the purchase button experience created in Business Portal.

purchaseMetadata · object

Key-value pairs of custom information associated with the purchase.

onDone · 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 for more details.

Return value

A promise which resolves with an object with following properties:

destroy · function

Destroy Supertab button instance. This removes all nodes related to Supertab button from DOM.

initialState · object

Initial state of the purchase button. See 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:

priorEntitlement · EntitlementStatus | null

Any prior entitlement of the current user. null if user has no prior entitlement.

Show prior entitlement

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.

Show purchase object

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 website name and the type of a given entitlement.

Example: "The Leek - 24 Hours Time Pass"

price · Price

Price object of the purchase.

Show Price object

amount · number

Amount in currency base units.

Example: 5000

currency · Currency

status · PurchaseStatus

Status of the purchase. Possible values: completed, pending, abandoned.

metadata · Metadata

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.

Show Entitlement status object

purchasedOffering · Offering | null

Offering object if user has purchased an offering. null otherwise.

Show offering object

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

Show Entitlement details object

duration · 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"
}

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 · Price

Price object of the offering.

tab · Tab

The users tab

Show Tab object

testMode · boolean

Whether the tab is in test mode.

currency · Currency

The currency of the tab.

total · Price

The total amount of the tab.

Show Total object

amount · number

Amount in currency base units.

Example: 50

currency · Currency

limit · Price

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

Show Limit object

amount · number

Amount in currency base units.

Example: 50

currency · Currency

purchases · 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.

paymentResult · boolean

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

Example

Example

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