Contents

ExternalPurchaseCustomLink

An enumeration that enables qualifying apps to offer custom links for external purchases and use alternative payment service providers.

Declaration

enum ExternalPurchaseCustomLink

Mentioned in

Overview

This functionality is only available to apps with the any of the following entitlements:

For more information, see:

Implement external purchase for apps available in Japan

If your account receives the StoreKit External Custom Purchase Link Regions entitlement, in Japan your app can use the ExternalPurchaseCustomLink API to implement external purchases starting in iOS 26.2. To use this API, complete the following steps:

Implement external purchase for apps available in the European Union (EU)

If your account receives the StoreKit External Purchase Link (EU) entitlement or the StoreKit External Custom Purchase Link Regions entitlement, in the EU your app can use the ExternalPurchaseCustomLink API to implement external purchases. To use this API, complete the following steps:

For information about testing in the sandbox environment, see Testing transactions that use custom link tokens.

Implement external purchase for music streaming apps in the European Economic Area (EEA)

If your account receives the Music Streaming Services EEA entitlement, in the EEA your music-streaming app can use the ExternalPurchaseCustomLink API to implement external purchases. To use this API, complete the following steps:

  • Configure the com.apple.developer.storekit.external-purchase-link-streaming entitlement for your app and the SKExternalPurchaseLinkStreamingRegions property list key, providing the country code for each permitted region where your app implements external purchases.

  • Check the isEligible property of the ExternalPurchaseCustomLink API to determine whether external purchase is available at runtime. If the value is false, don’t continue to use this API. See isEligible for more details.

  • At launch and before every potential transaction, call the token(for:) function to request the external purchase tokens, using the token types ACQUISITION and SERVICES. Associate these tokens with a customer account on your server.

  • Call the showNotice(type:) function after a deliberate customer interaction, such as tapping a button, that can lead to a potential external purchase.

  • From your server, report the external purchase tokens and the transactions associated with the tokens by using the External Purchase Server API.

Check eligibility and request tokens for apps available in the EU

When your app launches, check whether its eligible to use the ExternalPurchaseCustomLink API. For more information, see isEligible and canMakePayments.

If your app is eligible, request both the ACQUISITION and SERVICES external purchase tokens. Associate and store these tokens with a customer account on your server. Use the tokens to report transactions to Apple.

The following example code shows how to check for eligibility and request custom link tokens:

// Ensure the app is eligible to use the external purchase custom link API.
guard await ExternalPurchaseCustomLink.isEligible else { return }

// Declare the tokens and the token types.
var tokens: [String : String] = [:]
let tokenTypes = ["ACQUISITION", "SERVICES"]

// Request the tokens.
for tokenType in tokenTypes {
    do {
        let token = try await ExternalPurchaseCustomLink.token(for: tokenType)
        if let token {
            tokens[tokenType] = token.value
        }
    }
    catch {
        // Failed to get a token of type `tokenType`.
        // Add your code to handle errors.
    }
}

// Add your code to manage the tokens, for example to associate them
// with a customer account on your server.

Display the disclosure notice before displaying external purchases

The following SwiftUI code example shows how to check for eligibility, and then show the disclosure notice to determine whether to continue to display external purchases:

struct MyView: View {

    func openStore() async {
        guard await ExternalPurchaseCustomLink.isEligible else {
            return
        }
        // Show the disclosure notice.
        do {
            let result = try await ExternalPurchaseCustomLink.showNotice(type: .withinApp)
            guard case .continued = result else {
                // Customer chooses not to continue. Don't display external purchases.
                return
            }
            // Customer chooses to continue. 
            // Proceed with the custom link out and offer external purchases...
        }
        catch {
            // Add error handling here... 
        }
    }

    var body: some View {
        Button("Open store") {
            Task { await openStore() }
        }
    }
}

Topics

Checking eligibility

Getting external purchase tokens

Displaying the disclosure sheet

Testing external purchase transactions

See Also

Implementing external purchases in the EU