External Purchase

Manage Apple's External Purchase Custom Link entitlement (StoreKit external purchase API). This module lets you check eligibility, retrieve purchase tokens, display the mandatory Apple disclosure notice, and redirect the user to an external purchase page.

iOS only

This module relies on Apple StoreKit APIs and is only available on iOS devices that support the External Purchase entitlement.

Access: startiapp.ExternalPurchaseCustomLink

Methods

`getTokens(): Promise<TokensResponse>`

Retrieves acquisition and services tokens from StoreKit. These tokens are required when redirecting the user to your external purchase page so Apple can attribute the transaction.

This method is also called automatically when a user ID is registered via startiapp.User.registerId().

Returns: Promise<TokensResponse> — An object containing token data and eligibility status.

Example:

const response = await startiapp.ExternalPurchaseCustomLink.getTokens();

if (response.isEligible && response.tokens) {
  const acquisitionToken = response.tokens["ACQUISITION"]?.rawToken;
  console.log("Acquisition token:", acquisitionToken);
}

`showNotice(): Promise<NoticeResponse>`

Displays the Apple-mandated disclosure notice that must be shown before redirecting a user to an external purchase page. The notice informs the user they are about to leave the app to make a purchase.

Returns: Promise<NoticeResponse> — An object containing the user's response to the notice and token data.

Example:

const response = await startiapp.ExternalPurchaseCustomLink.showNotice();

if (response.status === "continued") {
  // User accepted the notice, proceed with external purchase
  window.location.href = "https://example.com/purchase";
} else {
  console.log("User cancelled the notice");
}

`getCountryCode(): Promise<string | null>`

Returns the App Store country code for the current user's account (e.g., "US", "DK"). Returns null if the information is unavailable.

Returns: Promise<string | null> —ISO 3166-1 alpha-2 country code, or null.

Example:

const country = await startiapp.ExternalPurchaseCustomLink.getCountryCode();
console.log("Store country:", country); // e.g., "DK"

`canMakePayments(): Promise<boolean>`

Checks whether the device is able to make payments (i.e., in-app purchases are not restricted by parental controls or device policy).

Returns: Promise<boolean> —true if the device can make payments.

Example:

const allowed = await startiapp.ExternalPurchaseCustomLink.canMakePayments();
if (!allowed) {
  console.log("Payments are restricted on this device");
}

`show(url): Promise<boolean>`

Convenience method that combines showNotice() and a redirect. It displays the Apple disclosure notice, and if the user accepts (status is "accepted" or "not-applicable"), the browser is redirected to the provided URL.

Parameters:

Parameter	Type	Required	Description
url	`string`	Yes	The external purchase URL to redirect to if the user accepts.

Returns: Promise<boolean> —true if the redirect was performed, false if the user declined the notice.

Example:

const redirected = await startiapp.ExternalPurchaseCustomLink.show(
  "https://example.com/purchase?plan=premium"
);

if (!redirected) {
  console.log("User chose not to proceed");
}

Events

`userTokensReceived`

Fired when new purchase tokens are received from StoreKit. The event's detail property contains the tokens dictionary.

Example:

startiapp.ExternalPurchaseCustomLink.addEventListener(
  "userTokensReceived",
  (event) => {
    const tokens = event.detail;
    console.log("Tokens received:", tokens);
  }
);

Types

`TokensResponse`

Response from getTokens() containing acquisition and services tokens.

type TokensResponse = {
  /** Whether the app is eligible for external purchase custom links. */
  isEligible: boolean;
  /** Dictionary of tokens by type (e.g., "ACQUISITION", "SERVICES"). */
  tokens?: Record<string, TokenInfo>;
  /** Error code if the request failed. */
  error?: string;
  /** Human-readable error message. */
  message?: string;
  /** Raw response string if deserialization failed. */
  raw?: string;
};

`NoticeResponse`

Response from showNotice() after displaying the external purchase disclosure.

type NoticeResponse = {
  /** Whether the app is eligible for external purchase custom links. */
  isEligible: boolean;
  /** Dictionary of tokens by type (e.g., "ACQUISITION", "SERVICES"). */
  tokens?: Record<string, TokenInfo>;
  /** Status of the user's interaction: "continued", "cancelled", or "unknown". */
  status?: string;
  /** Error code if the request failed. */
  error?: string;
  /** Human-readable error message. */
  message?: string;
  /** Raw response string if deserialization failed. */
  raw?: string;
};

`TokenInfo`

Information about a single token received from StoreKit.

type TokenInfo = {
  /** The raw Base64URL-encoded token string. */
  rawToken?: string;
  /** Indicates whether the token was successfully decoded. */
  decoded?: boolean;
  /** Error message if token retrieval failed. */
  error?: string;
  /** Any additional decoded data from the token. */
  additionalData?: Record<string, unknown>;
};

On this page