Supertab.createPurchase

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

Field	Type	Description
startPurchase	() => Promise<PurchaseStateSummary>	The startPurchase function to start the purchase flow.
destroy	() => void	Clean up and remove all Supertab elements from the DOM.

Example

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

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

PurchaseStateSummary type definition

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<string, string | number | boolean | null>;

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

CreatePurchaseResult type definition

interface CreatePurchaseResult {
  startPurchase: () => Promise<PurchaseStateSummary>;
  destroy: () => void;
}

CreatePurchaseUiConfig

CreatePurchaseUiConfig type definition

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

// 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

// 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

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);
  }
}