<!--
{
  "availability" : [
    "iOS: 18.1.0 -",
    "iPadOS: 18.1.0 -",
    "macOS: 15.1.0 -",
    "tvOS: 18.1.0 -",
    "visionOS: 2.1.0 -",
    "watchOS: 11.1.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "StoreKit",
  "identifier" : "/documentation/StoreKit/ExternalPurchaseCustomLink",
  "metadataVersion" : "0.1.0",
  "role" : "Enumeration",
  "symbol" : {
    "kind" : "Enumeration",
    "modules" : [
      "StoreKit"
    ],
    "preciseIdentifier" : "s:8StoreKit26ExternalPurchaseCustomLinkO"
  },
  "title" : "ExternalPurchaseCustomLink"
}
-->

# ExternalPurchaseCustomLink

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

```
enum ExternalPurchaseCustomLink
```

## Overview

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

- <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.custom-purchase-link.allowed-regions>
- <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.external-purchase-link>
- <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.external-purchase-link-streaming>

For more information, see:

- [Communication and promotion of offers on the App Store in the EU](https://developer.apple.com/support/communication-and-promotion-of-offers-on-the-app-store-in-the-eu/)
- [Distributing music streaming apps in the EEA that provide an external purchase link](https://developer.apple.com/support/music-streaming-services-entitlement-eea/)
- [Payment options on the App Store in Brazil](https://developer.apple.com/support/payment-options-on-the-app-store-in-brazil)
- [Payment options on the App Store in Japan](https://developer.apple.com/support/payment-options-on-the-app-store-in-japan)

### Implement external purchase for apps available in Brazil

If your account receives the StoreKit External Custom Purchase Link Regions entitlement, in Brazil your app can use the [`ExternalPurchaseCustomLink`](/documentation/StoreKit/ExternalPurchaseCustomLink) API to implement external purchases starting in iOS 26.5.  To use this API, complete the following steps:

- Configure the <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.custom-purchase-link.allowed-regions> entitlement for your app.
- Check the [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible) property of the [`ExternalPurchaseCustomLink`](/documentation/StoreKit/ExternalPurchaseCustomLink) API to determine whether the API is available at runtime. If the value is `false`, don’t continue to use this API. For more information, see  [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible).
- Call the [`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/token(for:)) function before every potential transaction to request external purchase tokens, using the token types `IN_APP` or `LINK_OUT`. For more information, see [`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/token(for:)).
- Before routing customers to external purchase options, display an in-app disclosure sheet that lets people know they’ll be transacting with you and not Apple. For more information, including downloadable resources, see the “In-app disclosure sheet” section of [Payment options on the App Store in Brazil](https://developer.apple.com/support/payment-options-on-the-app-store-in-brazil).
- Report the external purchase tokens and the transactions associated with the tokens using the <doc://com.apple.documentation/documentation/ExternalPurchaseServerAPI>. Otherwise, report transactions as indicated in [Payment options on the App Store in Brazil](https://developer.apple.com/support/payment-options-on-the-app-store-in-brazil).

### 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`](/documentation/StoreKit/ExternalPurchaseCustomLink) API to implement external purchases starting in iOS 26.2.  To use this API, complete the following steps:

- Configure the <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.custom-purchase-link.allowed-regions> entitlement for your app.
- Check the [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible) property of the [`ExternalPurchaseCustomLink`](/documentation/StoreKit/ExternalPurchaseCustomLink) API to determine whether the API is available at runtime. If the value is `false`, don’t continue to use this API. For more information, see  [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible).
- Starting in iOS 26.4, call the [`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/token(for:)) function before every potential transaction to request external purchase tokens, using the token types `IN_APP` or `LINK_OUT`. For more information, see [`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/token(for:)).
- Before routing customers to external purchase options, display an in-app disclosure sheet that lets people know they’ll be transacting with you and not Apple. For more information, including downloadable resources, see the “In-app disclosure sheet” section of [Payment options on the App Store in Japan](https://developer.apple.com/support/payment-options-on-the-app-store-in-japan).
- Starting in iOS 26.4, report the external purchase tokens and the transactions associated with the tokens using the <doc://com.apple.documentation/documentation/ExternalPurchaseServerAPI>. Otherwise, report transactions as indicated in [Payment options on the App Store in Japan](https://developer.apple.com/support/payment-options-on-the-app-store-in-japan).

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

- Depending on the entitlement you receive, configure the <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.custom-purchase-link.allowed-regions> entitlement for your app, or configure the <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.external-purchase-link> entitlement and the <doc://com.apple.documentation/documentation/BundleResources/Information-Property-List/SKExternalPurchaseCustomLinkRegions> property list key, including the country code for each permitted region where your app implements external purchases.
- Check the [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible) property of the `ExternalPurchaseCustomLink` API to determine whether the API is available at runtime. If the value is false, don’t continue to use this API. See [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible) for more details.
- At launch and before every potential transaction, call the [`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/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:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/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 <doc://com.apple.documentation/documentation/ExternalPurchaseServerAPI>.

For information about testing in the sandbox environment, see [Testing transactions that use custom link tokens](/documentation/StoreKit/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 <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.storekit.external-purchase-link-streaming> entitlement for your app and the <doc://com.apple.documentation/documentation/BundleResources/Information-Property-List/SKExternalPurchaseLinkStreamingRegions> property list key, providing the country code for each permitted region where your app implements external purchases.
- Check the [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/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`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible) for more details.
- At launch and before every potential transaction, call the [`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/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:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/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 <doc://com.apple.documentation/documentation/ExternalPurchaseServerAPI>.

### Check eligibility and request tokens for apps available in the EU

When your app launches, check whether it’s eligible to use the `ExternalPurchaseCustomLink` API. For more information, see [`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible) and [`canMakePayments`](/documentation/StoreKit/AppStore/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:

```swift
// 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.

> Note: For more information on displaying developer- or system-provided disclosure notices in Brazil and Japan, see the *User disclosures* section in
> [Payment options on the App Store in Brazil](https://developer.apple.com/support/payment-options-on-the-app-store-in-brazil)
> or [Payment options on the App Store in Japan](https://developer.apple.com/support/payment-options-on-the-app-store-in-japan).

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

[`isEligible`](/documentation/StoreKit/ExternalPurchaseCustomLink/isEligible)

A Boolean value that indicates at runtime whether the app can use this API for external purchases.

### Getting external purchase tokens

[`token(for:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/token(for:))

Requests an external purchase token of the specified type.

[`Token`](/documentation/StoreKit/ExternalPurchaseCustomLink/Token)

A token you use with the External Purchase custom link API.

[Receiving and decoding external purchase tokens](/documentation/StoreKit/receiving-and-decoding-external-purchase-tokens)

Receive tokens for external purchases that you use to report transactions to Apple.

### Displaying the disclosure sheet

[`showNotice(type:)`](/documentation/StoreKit/ExternalPurchaseCustomLink/showNotice(type:))

Displays the system disclosure notice sheet and asks the customer whether to continue.

[`NoticeType`](/documentation/StoreKit/ExternalPurchaseCustomLink/NoticeType)

The custom link out style that informs the type of disclosure notice to display.

[`NoticeResult`](/documentation/StoreKit/ExternalPurchaseCustomLink/NoticeResult)

The result of showing the disclosure notice.

### Testing external purchase transactions

[Testing transactions that use custom link tokens](/documentation/StoreKit/testing-transactions-that-use-custom-link-tokens)

Recognize custom link tokens that your app receives in the sandbox testing environment, and use them to test reporting transactions.

## Relationships

### Conforms To

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Sendable`](/documentation/Swift/Sendable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)