App Store Connect API
App Store Connect vendor number and the salesReports API
Every sales report request to the App Store Connect API needs one number most developers have never looked at: the vendor number. Here is where it lives, which key can use it, and how to turn `GET /v1/salesReports` into per-country sales you can actually work with.
Where to find your App Store Connect vendor number
Your vendor number is in Payments and Financial Reports. Sign in to App Store Connect, open Payments and Financial Reports, select Reports at the top of the page, and the number appears in the top-left corner under your Legal Entity Name. The API expects it as filter[vendorNumber] (Apple’s help).
- Sign in to App Store Connect with the Account Holder, Admin or Finance role — the roles Apple lists for Payments and Financial Reports.
- Open Payments and Financial Reports.
- Select Reports at the top of the page.
- Read the vendor number under your Legal Entity Name, top left, and copy it.
Two shortcuts. If you have ever downloaded a sales report from Trends → Sales and Trends Reports, the vendor number is in the file name: daily summary files are named S_D_<vendor number>_<date>, for example S_D_80012345_20130919 (report file names). And if you only have the Sales role, ask someone with the Admin or Finance role to read it for you, since it is shown on the financial page.
More than one vendor number
The menu next to your vendor name can list several vendor numbers. Apple gives a new one when you change your Legal Entity Name, and separate ones for Apple News+ or Apple Arcade agreements. Reports are split by vendor number, so after a legal-name change you need the new number for new sales and the old one for history.
Which roles can read sales reports
Two different permissions are involved: seeing the vendor number (Payments and Financial Reports) and reading Sales and Trends. The API key that downloads reports needs the second. From Apple’s role permissions and help pages:
| Role | Sales and Trends reports | Payments and Financial Reports | Change prices |
|---|---|---|---|
| Admin | Yes | Yes | Yes |
| Finance | Yes | Yes | No |
| Sales | Yes | No | No |
| App Manager | Not listed by Apple | No | Yes |
| Developer, Marketing, Customer Support | No | No | No |
Apple suggests the Sales role (its API docs call it Sales and Reports) for a key you hand to a third party that only analyses reports: it can call GET /v1/salesReports but not the finance reports endpoint (Apple’s note). If one key must both read sales and change prices, the only key role that does both is Admin. The alternative is two keys — App Manager for pricing, Sales for reports — which is tidier if your tool supports it. How to create either is in creating an API key.
Sales and Trends report types
GET /v1/salesReports serves every downloadable Sales and Trends report. Each type accepts only certain combinations of sub type, frequency and version; anything else is an error. The valid combinations, from Apple’s endpoint reference:
| reportType | reportSubType | frequency | version |
|---|---|---|---|
SALES | SUMMARY | DAILY, WEEKLY, MONTHLY, YEARLY | 1_0 |
PRE_ORDER | SUMMARY | DAILY, WEEKLY, MONTHLY, YEARLY | 1_0 |
SUBSCRIPTION | SUMMARY | DAILY | 1_3 |
SUBSCRIPTION_EVENT | SUMMARY | DAILY | 1_3 |
SUBSCRIBER | DETAILED | DAILY | 1_3 |
SUBSCRIPTION_OFFER_CODE_REDEMPTION | SUMMARY | DAILY | 1_0 |
WIN_BACK_ELIGIBILITY | SUMMARY | DAILY | 1_0 |
NEWSSTAND | DETAILED | DAILY, WEEKLY | 1_0 |
FIRST_ANNUAL | DETAILED / SUMMARY | DAILY / YEARLY | 1_0 |
For sales by country, the one you want is SALES / SUMMARY: aggregated units, prices and proceeds for apps and in-app purchases, one row per product, country, price and transaction type. Daily is the most useful frequency because you can rebuild any period from days, and days are what you need to see the effect of a price change.
Download a sales report with GET /v1/salesReports
| Parameter | Required | Value for a daily sales report | Notes |
|---|---|---|---|
filter[vendorNumber] | Yes | 85012345 (yours) | From Payments and Financial Reports. |
filter[reportType] | Yes | SALES | See the table above for other types. |
filter[reportSubType] | Yes | SUMMARY | Must match the report type. |
filter[frequency] | Yes | DAILY | DAILY, WEEKLY, MONTHLY or YEARLY. |
filter[reportDate] | No | 2026-11-09 | Apple documents YYYY-MM-DD and says DAILY doesn’t require a date. Send one anyway so you know which day you got. |
filter[version] | No | 1_0 | The version Apple lists for the report type. |
- Create a team API key with the Admin, Finance or Sales role, and keep its Issuer ID, Key ID and
.p8file. - Sign a JWT with the key (generating tokens). For most requests Apple rejects tokens that live longer than 20 minutes, so mint a fresh one per batch.
- Request the day:
GET https://api.appstoreconnect.apple.com/v1/salesReports?filter[frequency]=DAILY&filter[reportType]=SALES&filter[reportSubType]=SUMMARY&filter[vendorNumber]=85012345&filter[reportDate]=2026-11-09&filter[version]=1_0, withAuthorization: Bearer <token>andAccept: application/a-gzip. URL-encode the square brackets if your HTTP client does not. - The 200 response body is gzip (
application/a-gzip). Decompress it — with curl, save to a file and rungunzipon it. - You now have tab-separated text: a header row, then one row per product, country, price and transaction type. Parse columns by header name, not position.
- Store the day. Apple keeps daily reports for one year only, so anything you want to compare year over year has to be saved on your side.
- Repeat for each day you need, pacing yourself: every response carries an
X-Rate-Limitheader with your remaining hourly requests (rate limits).
Weekly, monthly and yearly reports work the same way with a different frequency. Apple’s file-name examples date a weekly report on a Sunday and give monthly and yearly files only the month or year, which is a useful check on which period you received. Remember that summing 30 daily files gives you a month you can slice any way you like; a monthly file does not give you days.
The file format and the columns that matter
The Summary Sales Report field reference documents every column (it describes version 1_3 of the layout; Apple adds columns over time, which is another reason to match on header names). The ones you need for per-country sales:
| Column | What it holds | Use it for |
|---|---|---|
| Apple Identifier | The Apple ID of the app or in-app purchase | Joining to your products in the API |
| SKU / Parent Identifier | Your SKU; for in-app purchases, Parent Identifier is the SKU of the app | Grouping in-app purchases under their app |
| Title | App name for downloads, product ID for in-app purchases | Labels |
| Product Type Identifier | The transaction type, such as 1F or IAY | Separating downloads, purchases, updates and redownloads |
| Units | Aggregated units; negative for refunds | Counting downloads and purchases |
| Developer Proceeds | What you receive per unit, after taxes and Apple’s commission | Proceeds = Units × Developer Proceeds |
| Customer Price / Customer Currency | The price per unit the customer was billed, and its currency | Checking the price people actually paid |
| Country Code | Two-letter code of the App Store country or region of the purchase | The per-country breakdown |
| Currency of Proceeds | The currency of the Developer Proceeds figure | Converting before you compare countries |
| Subscription / Period | New or renewal, and the subscription duration | Telling new subscribers from renewals |
Product type identifiers sort the rows (full list): 1, 1F, 1T and F1 are app downloads, free or paid; 3 and 3F are redownloads; 7, 7F, 7T and F7 are updates; IA1, IA9, IAY, FI1 and their -M variants are in-app purchases and subscriptions; IA3 is a restored non-consumable.
- Developer Proceeds is per unit. Multiply by Units before adding rows together.
- Refunds have negative Units and positive Developer Proceeds, so Units × Developer Proceeds correctly subtracts them.
- Leave out updates and redownloads before counting downloads — they are free and usually far outnumber real downloads.
- The same product and country can appear on several rows (different prices, devices, promo codes). Sum them.
- Days run midnight to midnight Pacific Time, not UTC.
- Amounts are in local currencies. Convert with one set of rates before ranking countries; sales by country walks through a fair comparison.
When reports are ready and how long they stay
From Apple’s availability page: daily reports are available the following day, weekly reports on Mondays, monthly reports five days after the month ends and yearly reports six days after the year ends, generally by 8 a.m. Pacific Time. Daily, weekly and monthly reports are kept for one year; yearly reports for ten. A Summary Sales report only exists for a period with at least one app unit sold, so a quiet day simply has no file.
Common salesReports errors
| Response | What it usually means | What to do |
|---|---|---|
400 PARAMETER_ERROR.REQUIRED | A required filter is missing, e.g. “The parameter 'filter[vendorNumber]' is required but was not provided” | Send all four required filters. |
| 400 (other) | A combination Apple does not offer — a sub type, frequency or version that does not match the report type | Check your values against the allowed-values table above. |
401 NOT_AUTHORIZED | The token is malformed, expired or signed with a revoked key | Mint a new token; check the Key ID, Issuer ID and .p8 belong together. |
| 403 | The key’s role cannot read sales reports | Use a key with the Admin, Finance or Sales role. |
| 404 | No report for that date: not published yet, nothing sold that day, or older than Apple keeps | Treat it as “no data”, retry recent days later. |
| 429 | Hourly rate limit reached for this key | Back off and resume; spread historical downloads over time. |
500 UNEXPECTED_ERROR | Apple’s server failed. When we sent a vendor number that did not belong to the key’s team, this is what came back rather than a clear message | Retry once; if it persists, double-check the vendor number before anything else. |
How RepriceCat uses your vendor number
RepriceCat changes prices with your App Store Connect key; with your vendor number it can also see what those prices do. Add it in Settings → Sales reports. Your key needs the Admin, Finance or Sales role to read reports — so Admin if the same key also changes prices. From then on RepriceCat downloads Apple’s daily SALES / SUMMARY reports, each day once, and keeps only daily totals per product and country. Updates and redownloads are left out.
- The Sales screen: per-country units, downloads, purchases, proceeds (in USD at today’s rates), share and trend, with a world map, daily and weekday charts, and filters by app and product.
- Pricing hints, such as countries with many downloads but few purchases, or ones that buy far more often than average.
- Impact of each price change in Activity: units and proceeds before and after the change, per product and country.
- Experiments: change the price in a few countries, keep the rest as a comparison, and keep or roll back the result (how to run a price test).
If you would rather not maintain the download-and-parse script yourself, compare RepriceCat with API scripts or start with a free month.
Frequently asked
Where do I find my vendor number in App Store Connect?
Open Payments and Financial Reports, select Reports at the top, and read the number in the top-left corner under your Legal Entity Name. It also appears in the file name of any sales report you have downloaded, such as S_D_80012345_20130919.
Is the vendor number the same as my Team ID or app Apple ID?
No. The vendor number is tied to your legal entity in Payments and Financial Reports. The Team ID and app Apple IDs are separate identifiers and will not work as filter[vendorNumber].
What role does an API key need to download sales reports?
Admin, Finance or Sales. App Manager can change prices but is not one of the roles Apple lists for Sales and Trends, so a single key that does both needs Admin.
Why does GET /v1/salesReports return 404?
There is no report for that date: the day has not been published yet, nothing sold that day, or the date is older than the one year Apple keeps daily reports. Treat it as no data and retry recent days later.
How far back can I download App Store sales reports?
Daily, weekly and monthly reports are kept for one year after they become available, and yearly reports for ten years. Save the files yourself if you need longer daily history.
What version should I use for the daily sales report?
Apple’s endpoint reference lists version 1_0 for SALES and SUMMARY. Parse the file by column names rather than positions, because Apple adds columns between layout versions.
Try it
Reprice every territory from one base price
Tiers, price-point snapping, one review table, one confirmation — through the App Store Connect API. First month free, then $1 per app per month.