# Connect App Store Connect to StoreScope Analytics

> Downloads, impressions, conversion, sales, subscriptions and reviews for every iOS and macOS app.

## What it unlocks in StoreScope Analytics

- Downloads, product page views, impressions and conversion for every iOS and macOS app (Apple's Analytics Reports).
- Ratings and reviews, and replying to them.
- With the vendor number: proceeds, units and subscriptions from Apple's sales reports.
- Listing suggestions built on that data.

## The access it needs

| For | Least role or permission |
|---|---|
| Analytics (downloads, impressions, conversion) | Admin. Apple only lets an Admin key start the analytics reports, and they are requested for each app on the first sync. |
| Reviews, listings, versions, submissions and releases | App Manager |
| Sales and subscriptions (the vendor number) | Admin, Finance or Sales |

- Create a Team key (Users and Access, Integrations, App Store Connect API, Team Keys). An individual key has no issuer ID and is not accepted.
- Storevisor alone works with an App Manager key. StoreScope Analytics needs Admin unless an Admin key already requested the analytics reports for every app, in which case App Manager reads them.
- The same connection serves both products: connecting it on one host connects it on the other.

## Steps

1. Open App Store Connect, Users and Access, Integrations, Team Keys. [Open Team Keys](https://appstoreconnect.apple.com/access/integrations/api)
2. Generate a key with the Admin role. Download the .p8 file; Apple only lets you download it once.
3. Why Admin: Apple only lets an Admin key start the analytics reports (downloads, impressions, conversion); we request them for each app on the first sync. App Manager is enough for reviews, listings and releases, but then analytics only arrive if an Admin already requested them.
4. Copy the Issuer ID shown above the keys table.
5. Optional, for sales and subscriptions: your vendor number, top left of Payments and Financial Reports. Apple serves those reports to keys with the Admin, Finance or Sales role; we check that before saving. [Open Payments and Financial Reports](https://appstoreconnect.apple.com/itc/payments_and_financial_reports)
6. In StoreScope Analytics, open Connections, choose App Store Connect, fill in the form and save. The connection is checked live with the store first; a connection that fails the check is never saved.

## What the form asks for

- The .p8 key file (optional): The key ID is read from the file name (AuthKey_XXXXXXXXXX.p8).
- Or paste the key (optional)
- Key ID (optional): Only needed when it is not in the file name.
- Issuer ID (required)
- Vendor number (optional)

## After connecting

- The first sync asks Apple for each app's analytics reports. Apple sends the first data 24 to 48 hours later; until then the App Store Connect card says the reports were requested.
- Apple stops a report request nobody reads for a while. Every sync checks for one, and a stopped one is requested again.
- If the key cannot request reports, the card says: Apple analytics are not started: only an App Store Connect key with the Admin role can request them. Reconnect with an Admin key; the next sync requests them.

## Errors the check can show

The exact sentence the Connections page shows (<angle brackets> are your own values), then what to do.

- "The .p8 key is required."
  Upload the AuthKey_<KEYID>.p8 file, or paste its contents.
- "That is not a .p8 key: it should start with -----BEGIN PRIVATE KEY-----."
  Upload the private key itself, not a certificate or a provisioning file.
- "Key ID is required (10 letters and digits), or upload the file with its original AuthKey_<KEYID>.p8 name."
  Type the key ID from the Team Keys table, or upload the file without renaming it.
- "Issuer ID should look like 69a6de7e-xxxx-xxxx-xxxx-xxxxxxxxxxxx."
  Copy the Issuer ID shown above the Team Keys table.
- "Vendor number is digits only."
  Copy the number at the top left of Payments and Financial Reports, or leave the field empty.
- "401 from App Store Connect: key <key ID> / issuer <issuer ID> / PEM do not match — regenerate at https://appstoreconnect.apple.com/access/integrations/api"
  The key ID, the issuer ID and the file are not from the same key, or the key was revoked. Check all three, or generate a new key.
- "403: key <key ID> has no app access — give it the Admin role (Apple only lets an Admin key start analytics reports; App Manager covers reviews and listings) at https://appstoreconnect.apple.com/access/integrations/api"
  The key's role cannot read apps. Generate a key with the Admin role (or App Manager for Storevisor alone).
- "Apple refused the sales report (<status>): sales and subscriptions need a key with the Admin, Finance or Sales role, and the vendor number must be this team's. Leave the vendor number empty to connect without sales."
  Use a key with one of those roles, check the vendor number belongs to this team, or connect without it.
- "Apple refused the sales report request (400): check the vendor number (Payments and Financial Reports, top left). Leave the vendor number empty to connect without sales."
  The vendor number is wrong. Copy it again, or leave it empty.
- "App Store Connect answered <status>: <answer>"
  Apple answered something unexpected. Try again in a few minutes; if it stays, tell us from the Support page.

Errors any connection can show: https://storescope.devino.ca/docs/connect.md