App Store Sync

Overview

99.94% match with bank payout

Implementation

  • Core sync logic: src/lib/server/apple-app-store-sync.ts
  • API endpoints: src/routes/api/sync/app-store/

More details

Primary source: Apple Financial report

  • Extremely accurate - 99.94% match with bank payout
  • Available on 7th day for the previous apple's fiscal month
    • Note that apple's fiscal month differs like +-6 days from calendar months
  • Apple uses FX rates right on bank payout date, which is around 33 days after the end of the fiscal month
  • When assigning revenue to dates, we use settlement date
    • It's when apple processed the customer's payment. Most of the time it's the same day as the purchase (51%), or within 3 days (72%), or within 14 days (99.8%), or within 2 months (100%)
  • Dates input for fetch: apple's fiscal month
  • When data becomes available, how many days may the source adjust them: 0days (Claude told me)

Secondary source: Apple Sales report

  • Less accurate - 95% match with bank payout - but available almost immediately (1-2 days delay). Can be fetched only last 365 days
  • Will be overwritten by financial report when available
  • When assigning revenue to dates, we use purchase date
  • Dates input for fetch: day
  • When data becomes available, how many days may the source adjust them: 32days (Claude told me, conservative)

How sync works

<!-- The sync can be triggered any time. So it needs to be idempotent,
can handle situations when it's wasn't run for a long period of time,
and also don't do anything if already ran today.

The fetching function will write the data to DB, and immediately update
the lastSyncDate if got higher value. So if it sucessfuly saved data for 12 december, and 
the lastSyncDate is currently 8 december it would udpate it to 12 december.

Note the date ranges are always inclusive. -->


if ( lastSyncDate < today ):
    <!-- Order matter here -->

    <!-- So this would correctly update's the earnings with the correct fx rates -->
    fetchDataFromFinancialReports( months: getMonthsBetweenInclusive(2_months_before_last_sync_date, previous_month))

    <!-- 40 days, becuase for the previous month we got the financial report on the 7th day, so we need to be able to fetch the whole previous month through this sales report.-->
    fetchDataFromSalesReports ( range: { start: today - 40days, end: today - 1day } )
How the accuracy was measured + ground truth data for testing

Using only Financial report

  • apple app store revenue - 29 dec 2024 - Nov 29, 2025 (UTC) (intentionally aligned this way so it matches with apple's fiscal months dates)
    • arrived to bank account - 90746 €
    • reported by this finboard - 90801.26 €

Using only Sales reports

  • apple app store revenue - 2 feb - Nov 29, 2025 (UTC) (intentionally aligned this way so it matches with apple's fiscal months dates)
    • arrived to bank account - 83964 €
    • reported by this finboard - 85476 €