Every subscription number you have ever seen for your own app came out of one of two reports. Apple's dashboard draws them, third party tools re-draw them, and both are reading columns from a tab separated file you can download yourself in about a minute.
The columns are where the trouble is. Several of them look like they belong in a total and do not, and adding those to your subscriber count or your MRR gives you a number that is wrong in a direction you will like. Here is what each one counts.
The two reports
GET /v1/salesReports serves both, keyed by reportType.
- SUBSCRIPTION, SUMMARY. A snapshot of who is subscribed right now, split by plan, country and customer currency. This is where active counts and MRR come from.
- SALES, SUMMARY. The transaction ledger. Units, proceeds and refunds, one row per product per day per territory. This is where money that moved comes from.
Neither report ever contains a row per subscriber. Apple aggregates before you see it, so per person history is out of reach whatever tool you use.
Billing Retry and Grace Period are not paying you
The subscription report has a column called Active Standard Price Subscriptions. That column, plus the paid introductory, promotional, offer code and win-back columns beside it, is what Apple means by Paid Plans.
Next to them sit Billing Retry and Grace Period. Those two hold subscribers whose last charge failed. Their Customer Price reads 0.00. They still have access to your app, because Apple keeps them in while it retries the card, and Apple's own Paid Plans figure leaves them out.
Sum every column that sounds active and the arithmetic runs away from you. Forty paying subscribers, twelve in billing retry and three in a grace period reads as fifty five active subscriptions. Fifteen of those people are one failed retry away from being gone, and none of the fifteen is money.
A billing retry column is a dunning signal. Read it on its own, watch it move, and keep it out of the total.
Active Free Trial Introductory Offer Subscriptions is a third case. Those are real users on a real trial, and they belong in a trial count and never in MRR. They are worth zero until they convert.
Do not sum Developer Proceeds
Now the sales report, where the mistake is easier to make and harder to see.
Developer Proceeds is denominated in the customer's local currency, per row. A Brazilian row is in BRL, a Japanese row is in JPY, a Taiwanese row is in TWD, and the column header does not change between them. Summing that column adds reais to yen. The result means nothing, and it will draw a perfectly convincing chart.
The way through is to value each row from your own catalog: list price in one currency, multiplied by the number of months in the billing period, multiplied by your share. Slower to build, and it is the only version that survives a portfolio with customers in more than one country.
Trial starts look exactly like sales
A free trial start appears in the sales report as an ordinary row for your product, with Developer Proceeds of 0.00. So does a redemption of a zero price offer code.
If you price rows from your catalog, as above, every one of those rows books full revenue for a customer who has paid nothing. The fix is one line and easy to miss: value only the rows whose proceeds are nonzero. The zero rows are still useful, as a trial count.
Two smaller shapes in the same file:
- Refunds arrive as negatives. Negative
Units, negative proceeds. Left alone they net themselves out of the total correctly, so resist the urge to filter them. - Billing periods come in two spellings. The same field holds prose like
1 Yearand ISO 8601 likeP1Y. Parse both, in one place, or your annual plans will quietly be worth a month.
Which identifier is which
A subscription row in the sales report carries the subscription's Apple identifier in the column you would expect to hold the app's. The app id is off to the side in Parent Identifier.
Joining rows to apps by the obvious column gives you nothing, and says nothing while it does. Match on SKU, which is your StoreKit product id, or join through Parent Identifier to the app's own SKU.
Gross or net, pick one and label it
The last one is a convention rather than a bug, and it is why two dashboards can both be right and disagree by about fifteen percent.
- MRR is conventionally gross. What customers were charged. This is what subscription analytics tools report, so it is the figure that compares to anything you read elsewhere.
- Proceeds are net. What Apple will pay you, after its commission. This is what App Store Connect means by the word.
Both are worth having on screen. The gap between them is Apple's cut. A total that does not say which one it is will be misread by whoever reads it next.
How StudioDash handles this
StudioDash reads both reports through Apple's API on your device and applies every rule above: billing retry and grace period are surfaced as their own signal instead of padding the active count, trial rows carry no revenue, and rows are valued from the catalog rather than added across currencies. MRR is labelled gross and proceeds are labelled net, on the same screen, for every app you ship.
