Authentication

Connecting your Apple AppStore account with Leapfin is simple, and should take ~5-10 minutes. There are 4 keys we need in order to import your Apple AppStore data on your behalf:

1. Private API Key
2. Key ID
3. Issuer ID
4. Vendor ID.

Please follow the instructions below step-by-step:

1. First, please login Leapfin, and navigate to the integrations set up page.
2. Next, click on Connect button next to Apple AppStore. There are 4 keys Leapfin needs:

Please follow the instructions below to gather each of the IDs and Private API Key:

1. Private API Key
   Reference to Apple's documentation on Creating API Keys for App Store Connect API.
   You will need to generate the api-key. To generate keys, you must have an Admin account in App Store Connect.
   1. To generate an API key to use with the App Store Connect API, log in to App Store Connect.
   2. Select Users and Access, and then select the API Keys tab.
   3. Click Generate API Key or the Add (+) button.
   4. Enter a name for the key. The name is for your reference only and is not part of the key itself.
   5. Under Access, select the role for the key. We recommend selecting Finance.
   6. Click Generate.
   7. The new key's name, key-id , a download link, and other information will appear on the page. Click the download link to download the api-key.
2. Key ID. Example: 2X9R4HXF34
   Reference to Apple's documentation on Generating Tokens for API Requests.
   1. Log in to App Store Connect:
   2. Select Users and Access, then select the API Keys tab.
   3. The key IDs appear in a column under the Active heading. Hover the cursor next to a key ID to display the Copy Key ID link.
   4. Click Copy Key ID.
3. Issuer ID Example: 57246542-96fe-1a63-e053-0824d011072a
   Reference to Apple's documentation on Generating Tokens for API Requests.
   1. Log in to App Store Connect:
   2. To get your issuer ID, log in to App Store Connect and:
   3. Select Users and Access, then Select the API Keys tab.
   4. The issuer ID appears near the top of the page. To copy the issuer ID, click Copy next to the ID.
4. Vendor ID
   1. Reference to Apple's documentation on Viewing Payments and Proceeds.
   2. You can view your Vendor Number at any time in App Store Connect. Vendor Numbers are needed for downloading reports using the App Store Connect API.
   3. From the homepage, click Payments and Financial Reports.
   4. Your Vendor Number appears in the top left hand corner under your Legal Entity Name.

Data Type

Once authenticated, Leapfin will fetch and process the following two reports from the Apple AppStore.

• Summary Sales Report
• Financial Report

These two reports are accessed via endpoints defined here.

Summary Sales Report

The summary sales report contains aggregated sales and downloads data for your apps and In-App Purchases. The report is generated by Apple on a daily basis and downloaded by Leapfin via the web service endpoint here. For more information, refer to the schema of Summary Sales Report.

📘

Summary Sales Report is not a transaction level report. The transactions has been aggregated by date and SKU. Unfortunately, Apple does not provide any transaction level report at the moment. It is not possible to split transactions into individual invoices and line items.

The report does not contain any unique identifier for each row. Leapfin imports each row as an applestore-sales-transaction record. A unique identifier is constructed as "sales-report date-row index-apple identifier".

Sample Data

{
    "CMB": "",
    "SKU": "COMP-POSR-1",
    "Title": "Company: 3D Grame",
    "Units": "1",
    "Client": " ",
    "Device": "iPhone",
    "Period": " ",
    "Version": "3.65.0",
    "Category": "Graphics & Design",
    "End Date": "09/01/2020",
    "Provider": "APPLE",
    "Developer": "company",
    "Begin Date": "09/01/2020",
    "Order Type": " ",
    "Promo Code": " ",
    "Country Code": "HN",
    "Subscription": " ",
    "Customer Price": "0.00",
    "Proceeds Reason": " ",
    "Apple Identifier": "897446999",
    "Provider Country": "US",
    "Customer Currency": "USD",
    "Parent Identifier": " ",
    "Preserved Pricing": " ",
    "Developer Proceeds": "0.00",
    "Supported Platforms": "iOS",
    "Currency of Proceeds": "USD",
    "Product Type Identifier": "3X"
}

Financial Report

Financial reports show your monthly proceeds, as well as final unit sales by territory and order type. They are automatically generated once a month, based on Apple’s fiscal calendar, and are only generated if there are purchases or refunds during that fiscal period. (reference)

There are two types of financial reports: "FINANCIAL" and "FINANCIAL_DETAIL" (refer to reportType here). Leapfin downloads the latter on a monthly basis via the web service endpoint here. For more information, refer to the schema of Financial Report.

The report does not contain any unique identifier for each row. Leapfin imports each row as an applestore-finance-transaction record. A unique identifier is constructed as "sales-report month-row index-apple identifier".

Sample Data

{
    "UPC": "",
    "Grid": "",
    "Title": "Company Credit Pack",
    "End Date": "08/29/2020",
    "Quantity": "5",
    "ISRC/ISBN": "",
    "Promo Code": "",
    "Start Date": "08/02/2020",
    "Partner Share": "29.99",
    "Customer Price": "64.99",
    "Pre-order Flag": "",
    "Country Of Sale": "AE",
    "Sales or Return": "S",
    "Apple Identifier": "911633999",
    "Customer Currency": "AED",
    "Vendor Identifier": "com.company.creditpack",
    "ISAN/Other Identifier": "",
    "Extended Partner Share": "49.95",
    "Partner Share Currency": "AED",
    "Product Type Identifier": "IS1",
    "Artist/Show/Developer/Author": "",
    "Label/Studio/Network/Developer/Publisher": ""
}

Mapping Logic

applestore-sales-transaction

Leapfin imports each row on Apple's Summary Sales Report as an applestore-sales-transaction record. Each record contains information on sales or refunds aggregated at day and SKU levels.

When mapping data, Leapfin creates Invoices, LineItems or Refunds records based on the direction of the transaction amount.

Creating an Invoice

Leapfin creates an Invoice record if applestore-sales-transaction.Customer Price ≥ 0.

Creating a LineItem

Leapfin creates an Invoice record if applestore-sales-transaction.Customer Price ≥ 0.

Creating a Refund

Leapfin creates a Refund record if applestore-sales-transaction.Customer Price < 0

Creating a Payment

Leapfin creates a Payment record if applestore-sales-transaction.Customer Price ≥ 0

Creating a Settlement

Leapfin creates a Settlement record if applestore-sales-transaction.Customer Price ≥ 0

applestore-finance-transaction

Leapfin imports each row on Apple's Finance Report as an applestore-finance-transaction record. Each record contains information on either a purchase or return made within the fiscal period from all countries and/or regions.

When mapping data, Leapfin creates Payment or Settlement records based on the direction of the transaction amount.

Creating a Payment

Condition: When applestore-sales-transaction.Customer Price ≥ 0

Creating a Settlement

Condition: When applestore-sales-transaction.Customer Price ≥ 0