What each connection adds
- RevenueCat (per app). A daily check of who is paying right now. It keeps the paying-user count and the PRO badges exact, including people who paid before you connected the webhook, such as lifetime buyers.
- App Store Connect (per account). Daily App Store downloads, split into first-time downloads and redownloads, plus Apple's monthly financial reports: the money Apple pays out, which the P&L uses.
The RevenueCat connection is separate from the RevenueCat webhook in Getting started. The webhook delivers each purchase, renewal and cancellation as it happens. The secret key lets FolioKit check once a day who has an active subscription or purchase, including people the webhook never saw. Set up both.
Connect RevenueCat
Do this once for each app. You need two values from RevenueCat: a secret API key and the project ID.
- In the RevenueCat dashboard, open your project and go to Project settings > API keys.
- Click + New secret API key and pick API version
2. Name it
FolioKit. - Under permissions, set Customer information to Read only. That covers customers, subscriptions and purchases, which is all FolioKit reads. Leave the other groups at no access.
- Create the key and copy it. It starts with
sk_. - Go to Project settings > General and copy the
Project ID. It starts with
proj. - In FolioKit, open the app, click the gear icon next to its name, and scroll to Connections. Paste the project ID and the secret key into the RevenueCat form and save.
Use the secret key. Public keys start with appl_ and can't read
purchases, so the form rejects them.
Connect App Store Connect
Do this once for your developer account. One key covers every app in it, so all your
FolioKit apps share the connection. You need four things: an Issuer ID, a Key ID, the
.p8 key file, and your vendor number.
Create a Finance key
- In App Store Connect, go to Users and Access > Integrations > App Store Connect API and open Team Keys.
- Click +. Name the key
FolioKitand set Access to Finance. Keys with the App Manager role get "access denied" on sales reports, so they won't work. - Download the
.p8file right away. Apple offers the download only once. If you lose the file, revoke the key and create a new one. - Note the Issuer ID, shown above the list of keys, and the Key ID, shown next to your key.
Find your vendor number
Open Payments and Financial Reports in App Store Connect. Your vendor number is at the top of the page.
Paste it into FolioKit
Open any app's settings (the gear icon next to its name) and scroll to
Connections. In the App Store Connect form, enter the Issuer ID, Key
ID and vendor number, choose the .p8 file, and save. You do this once,
from whichever app you like. Your other apps use the same connection.
Set each app's App Store ID
Apple's reports name apps by their App Store ID, so FolioKit needs that number for
every app. It's the number at the end of the app's App Store link: for
apps.apple.com/app/id6757949814, the App Store ID is
6757949814. Enter it in each app's settings. Until it's set, FolioKit
can't tell which downloads and payouts belong to that app.
Subscriptions and in-app purchases in the financial reports are matched to apps through the product IDs RevenueCat has reported for each app. A product nobody has bought through RevenueCat yet shows as not matched yet in the connection's status. It matches once its first purchase comes in.
What happens after you save
- FolioKit tests the key right away. If it doesn't work, the message names the likely cause (see Troubleshooting).
- The first sync starts. You don't wait for the next scheduled run. It brings in the last 14 days of App Store downloads and the financial reports for the last three months that Apple has published. For RevenueCat, it checks every user FolioKit has seen for the app; a large app finishes during the next daily run.
- Scheduled syncs take over. All times below are UTC.
| Data | When it syncs |
|---|---|
| App Store downloads | Every day. Apple publishes each day's report the next day around 13:00. FolioKit fetches it at 13:10 and re-checks the last 4 days. |
| Financial reports | Monthly. Apple publishes each one about a week after its fiscal month ends. FolioKit checks every day and adds each report once it appears. |
| RevenueCat paying users | Every day, between 05:00 and 07:00. |
Troubleshooting
When a key doesn't work, the form says which service refused it and why. Here is what each case means and what to do.
| What you see | What to do |
|---|---|
| App Store Connect: 401 | The Issuer ID, Key ID and .p8
file don't belong together. Check that all three come from the same key. |
| App Store Connect: 403 | The key doesn't have Finance access. Create a new key with Finance access and replace the old one. |
| App Store Connect: server error | Usually a wrong vendor number, which Apple answers with a generic server error. Check the number at the top of Payments and Financial Reports. If it matches, try again later. |
| RevenueCat: 401 | The secret key is invalid or was revoked. Create a new one and paste it. |
| RevenueCat: 403 | The key can't read customer information. Give it Read only access to Customer information, or create a new key that has it. |
| RevenueCat: 404 | The project ID is wrong. Copy it again from Project settings > General. |
| A product shows "not matched yet" | Nobody has bought it through RevenueCat yet, so FolioKit can't tell which app it belongs to. It matches after its first purchase. Nothing to do. |
| An app has no App Store downloads | Check that its App Store ID is set in the app's settings. Apple's report for a day arrives the next afternoon (UTC), so today is always empty. |
Security and revoking
- Encrypted at rest. Keys are stored encrypted in Supabase Vault.
- Never shown again. After you save, nobody can view the key, you included. You can replace it or disconnect.
- Read only by the sync jobs. Only FolioKit's sync jobs can read a stored key. Each connection belongs to one account, and no other account can see or use it.
- Disconnect deletes the key. Disconnecting removes the stored key. Data that already synced stays in your dashboard.
- Limited access. The RevenueCat key can only read. The Finance key can read reports and payment data but can't change your apps, builds or prices.
- Revoke any time. In RevenueCat under Project settings > API keys, or in App Store Connect under Users and Access > Integrations. The syncs for that connection stop, and its status shows the error.
For everything FolioKit collects and stores, see Data & privacy. Questions go to contact@foliokit.io.