Contents

External Purchase Server API

Send and manage reports you send to Apple for tokens you receive when your app provides external purchases for digital goods and services.

Overview

Call this REST API from your server to report external purchase tokens and your customers’ transactions related to the tokens. Use this API if your app uses the External Purchase API or MarketplaceKit and receives external purchase tokens.

Report all tokens, including those that didn’t result in a transaction, and report the transactions associated with the tokens. For more information on the reporting requirements, see Reporting tokens and transactions to Apple.

Authorize your API calls

Calls to the API require JSON Web Tokens (JWTs) for authorization. Get keys to create JWTs from your organization’s App Store Connect account. See Creating API keys to authorize API requests to create your keys. See Generating JSON Web Tokens for API requests to generate tokens using your keys, and send API requests.

Report external purchase tokens and transactions

When customers initiate an external purchase, your app or website receives a token. You need to report the token and the transactions associated with the token. For more information on how you receive tokens, see Receiving and decoding external purchase tokens. To send a report, call the Send External Purchase Report endpoint for each token. Send reports in all of the following cases:

  • To report a token, with line items, when a customer completes one or more transactions.

  • To report a token, without line items, when a customer doesn’t complete any transactions.

  • To report an unrecognized token, when you receive an App Store Server Notification about a token that you don’t have recorded in your system.

  • To report duplicate ACQUISITION and SERVICES tokens.

For more information, see Reporting tokens with transactions and Reporting unrecognized and transactionless tokens.

If you successfully send a report that you later find to be incorrect, you need to correct your submission. For more information, see Reporting corrections.

Retrieve reports

Call the Retrieve External Purchase Report endpoint to get reports you previously sent to Apple. Specify which report to retrieve by using the same requestIdentifier value that you provide when you send the report.

Receive notifications for unreported tokens

The App Store server sends an EXTERNAL_PURCHASE_TOKEN notificationType to your App Store Server Notifications V2 endpoint in the following cases:

  • To indicate unreported tokens, using the UNREPORTED subtype

  • To remind you of active custom link tokens, using the ACTIVE_TOKEN_REMINDER subtype.

If you receive the EXTERNAL_PURCHASE_TOKEN notification, send a report for the token the notification specifies. To check for notifications you might have missed — for example, due to a server outage — send a request to the Get Notification History endpoint to get a list of notifications that App Store Server Notifications attempted to send to your server.

For more information on notifications, see Enabling App Store Server Notifications. Configure the App Store Server Notifications V2 endpoint on your server to receive version 2 notifications.

Test using the sandbox environment

When you test your app in the sandbox environment, the External Purchase API returns tokens that are valid only in that environment. These tokens have an externalPurchaseId that starts with the string “SANDBOX”. To test your server’s token reporting implementation, send reports for sandbox tokens to the Sandbox URL of the Send External Purchase Report endpoint.

Topics

Essentials

External purchase tokens

External purchase reporting

External purchase report transactions

External purchase report without transactions

External purchase report retrieval

Error handling