Apple AppStore

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:

https://files.readme.io/ee37981-appl1.png

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.

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.

Target:
LeapfinInvoice (schema)
Source:
applestore-sales-transaction (schema)
objectType“invoice”
idsales_<report date>_<row number>_<Apple Identifier>
e.g. "sales_2020-09-01_0001820_897446215"
totalNone
subtotalNone
currencyCodeapplestore-sales-transaction.Currency of Proceeds
status“paid”
dateapplestore-sales-transaction.Begin Date
issuedDateapplestore-sales-transaction.Begin Date
uncollectibleDateNone
paidDateNone
dueDateNone
exchangeRateNone
customFieldsThe following fields from source record are added:
-- applestore-sales-transaction.Title
linksNone

Creating a LineItem

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

Target: leapfinLineItem(schema)Source:
applestore-sales-transaction (schema)
objectType“LineItem”
idsales_<report date>_<row number>_<Apple Identifier>
e.g. "sales_2020-09-01_0001820_897446215"
amount(applestore-sales-transaction.Developer Proceeds * applestore-sales-transaction.Units ) / proceedsRatio
(see proceedsRatio in "customFields" )
currencyCodeapplestore-sales-transaction.Currency of Proceed
dateapplestore-sales-transaction.Begin Date
descriptionnone
discountAmountnone
quantityapplestore-sales-transaction.Units
startDateapplestore-sales-transaction.Begin Date
endDateapplestore-sales-transaction.Begin Date + applestore-sales-transaction.Period (if exists) - 1 day
customFieldsThe following fields from source record are added:
-- customerPrice = applestore-sales-transaction.Customer Price
-- customerCurrency = applestore-sales-transaction.Customer Currency
-- proceedsRatio = 0.85 (if applestore-sales-transaction.Proceeds Reason = "Rate After One Year.") or 0.7 (if otherwise)
-- sku = applestore-sales-transaction.SKU
-- purchaseCountryCode = applestore-sales-transaction.Country Code
-- title = applestore-sales-transaction.Title
-- developerProceeds = applestore-sales-transaction.Developer Proceeds
linksAdd a link to the Invoice record with:
-- objectType = "invoice"
-- id = sales_<report date>_<row number>_<Apple Identifier>

Creating a Refund

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

Target: leapfinRefund(schema)Source:
applestore-sales-transaction(schema)
objectType“refund”
idsales_<report date>_<row number>_<Apple Identifier>
e.g. "sales_2020-09-01_0001820_897446215"
amountif applestore-sales-transaction.Units = 0 , amount = applestore-sales-transaction.Developer Proceeds / proceedsRatio
else, amount = negative (applestore-sales-transaction.Developer Proceeds * applestore-sales-transaction.Units) / proceedsRatio
NOTE: for refunds, Units is negative and Developer Proceeds is positive
(see proceedsRatio in "customFields" )
currencyCodeapplestore-sales-transaction.Currency of Proceeds
dateapplestore-sales-transaction.Begin Date
descriptionnone
status“succeeded”
customFieldsThe following fields from source record are added:
-- proceedCurrency = applestore-sales-transaction.Currency of Proceeds
-- proceedsRatio = 0.85 (if applestore-sales-transaction.Proceeds Reason = "Rate After One Year.") or 0.7 (if otherwise)
-- sku = applestore-sales-transaction.SKU
-- title = applestore-sales-transaction.Title
-- customerPrice = applestore-sales-transaction.Customer Price
-- customerCurrency = applestore-sales-transaction.Customer Currency
-- developerProceeds = applestore-sales-transaction.Developer Proceeds
-- units = negative applestore-sales-transaction.Units (NOTE: for refunds, Units is negative)
linksnone

Creating a Payment

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

Target: leapfinPayment(schema)Source:
applestore-sales-transaction (schema)
objectType“payment”
idsales_<report date>_<row number>_<Apple Identifier>
e.g. "sales_2020-09-01_0001820_897446215"
amount(applestore-sales-transaction.Developer Proceeds * applestore-sales-transaction.Units ) / proceedsRatio
(see proceedsRatio in "customFields" )
currencyCodeapplestore-sales-transaction.Customer Currency
dateapplestore-sales-transaction.Begin Date
succeededDateapplestore-sales-transaction.Begin Date
descriptionnone
status“succeeded”
customFieldsThe following fields from source record are added:
-- proceedAmount = applestore-sales-transaction.Developer Proceeds * applestore-sales-transaction.Units
-- proceedCurrency = applestore-sales-transaction.Currency of Proceeds
-- proceedsRatio = 0.85 (if applestore-sales-transaction.Proceeds Reason = "Rate After One Year.") or 0.7 (if otherwise)
-- title = applestore-sales-transaction.Title
-- units = applestore-sales-transaction.Units
linksAdd a link to the Invoice record with:
-- objectType = "invoice"
-- id = sales_<report date>_<row number>_<Apple Identifier>

Creating a Settlement

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

Target:
leapfinSettlement(schema)
Source:
applestore-sales-transaction (schema)
objectType"settlement"
idsales_<report date>_<row number>_<Apple Identifier>
e.g. "sales_2020-09-01_0001820_897446215"
amountapplestore-sales-transaction.Developer Proceeds * applestore-sales-transaction.Units
currencyCodeapplestore-sales-transaction.Currency of Proceeds
dateapplestore-sales-transaction.Begin Date
expectedArrivalDatenone
descriptionnone
status“paid”
customFieldsThe following fields from source record are added:
-- customerPrice = applestore-sales-transaction.Customer Price
-- customerCurrency = applestore-sales-transaction.Customer Currency
•-- proceedsRatio = 0.85 (if applestore-sales-transaction.Proceeds Reason = "Rate After One Year.") or 0.7 (if otherwise)
-- title = applestore-sales-transaction.Title
-- units = applestore-sales-transaction.Units
linksAdd a link to the Payment record with:
-- objectType = "payment"
-- id = sales_<report date>_<row number>_<Apple Identifier>

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

Target:
leapfinPayment(schema)
Source:
applestore-finance-transaction (schema)
objectType"payment"
idfinance_<report month>_<row number>_<Apple Identifier>
e.g. "finance_2020-08-01_0000001_911260480"
amountapplestore-finance-transaction.Customer Price * applestore-finance-transaction.Quantity
currencyCodeapplestore-finance-transaction.Customer Currency
dateif applestore-finance-transaction.Settlement Date is not null, date = applestore-finance-transaction.Settlement Date
else date = applestore-finance-transaction.Start Date
succeededDateif applestore-finance-transaction.Settlement Date is not null, date = applestore-finance-transaction.Settlement Date
else date = applestore-finance-transaction.Start Date
descriptionapplestore-finance-transaction.Title
status“succeeded”
customFieldsThe following fields from source record are added:
-- proceedAmount = applestore-finance-transaction.Extended Partner Share
-- proceedCurrency = applestore-finance-transaction.Partner Share Currency
-- title = applestore-finance-transactiona.Title
linksnone

Creating a Settlement

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

Target:
leapfinSettlement (schema)
Source:
applestore-finance-transaction (schema)
objectType"settlement"
idfinance_<report month>_<row number>_<Apple Identifier>
e.g. "finance_2020-08-01_0000001_911260480"
amountapplestore-finance-transaction.Extended Partner Share
currencyCodeapplestore-finance-transaction.Extended Partner Share Currency
dateif applestore-finance-transaction.Settlement Date is not null, set date = applestore-finance-transaction.Settlement Date
else date = applestore-finance-transaction.Start Date
expectedArrivalDatenone
descriptionapplestore-finance-transaction.Title
status“paid”
customFieldsThe following fields from source record are added:
-- customerPrice = applestore-finance-transaction.Customer Price
-- customerCurrency = applestore-finance-transaction.Customer Currency
-- title = applestore-finance-transaction.Title
linksAdd a link to the Payment record with:
-- objectType = "payment"
-- id = finance_<report month>_<row number>_<Apple Identifier>