--- title: External Purchase Server API framework: External Purchase Server API role: collection role_heading: Framework platforms: [external purchase server api 1.0.0+] path: externalpurchaseserverapi --- # 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 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. important: External purchase tokens generated in the sandbox environment are for testing only. The sandbox tokens and any test transaction data you submit through the sandbox URLs of the External Purchase Server API are not actual transactions. ## Topics ### Essentials - [Creating API keys to authorize API requests](appstoreserverapi/creating-api-keys-to-authorize-api-requests.md) - [Generating JSON Web Tokens for API requests](appstoreserverapi/generating-json-web-tokens-for-api-requests.md) - [External Purchase Server API changelog](externalpurchaseserverapi/changelog.md) ### External purchase tokens - [Receiving and decoding external purchase tokens](storekit/receiving-and-decoding-external-purchase-tokens.md) ### External purchase reporting - [Send External Purchase Report](externalpurchaseserverapi/send-external-purchase-report.md) - [ExternalPurchaseReport](externalpurchaseserverapi/externalpurchasereport.md) - [SendReportSuccessResponse](externalpurchaseserverapi/sendreportsuccessresponse.md) - [SendReportErrorResponse](externalpurchaseserverapi/sendreporterrorresponse.md) ### External purchase report transactions - [Reporting tokens with transactions](externalpurchaseserverapi/reportwithtransactions.md) - [Reporting corrections](externalpurchaseserverapi/reportcorrections.md) - [OneTimeBuyLineItem](externalpurchaseserverapi/onetimebuylineitem.md) - [RefundLineItem](externalpurchaseserverapi/refundlineitem.md) - [SubscriptionBuyLineItem](externalpurchaseserverapi/subscriptionbuylineitem.md) - [Line item fields](externalpurchaseserverapi/lineitems.md) ### External purchase report without transactions - [Reporting unrecognized and transactionless tokens](externalpurchaseserverapi/reportwithouttransactions.md) ### External purchase report retrieval - [Retrieve External Purchase Report](externalpurchaseserverapi/retrieve-external-purchase-report.md) - [RetrieveReportSuccessResponse](externalpurchaseserverapi/retrievereportsuccessresponse.md) ### Error handling - [Error messages and codes](externalpurchaseserverapi/errorcodes.md)