Suborbital Reports FAQ

Suborbital Reports Version 1.2

Where can I find my iTunes Connect Token?

Apple recently replaced the old username/password login scheme with a more modern user generated access token login. Each iTunes Connect account can have now one user generated token for sales report access.

This has the advantage that a malicious party can not use the token to make changes to your iTunes Connect account. They even can't use that token to sign in with ITC. The token is only valid for report downloads.

To generate your token follow these steps:

  1. Log into iTunes Connect
  2. Go to the "Sales and Trends" tab
  3. From the left pulldown select "Reports" (as opposed to "Sales")
  4. Click on the question mark icon next to "About Reports"
  5. Select "Generate Access Token" from the pop up
  6. Copy your access token and paste it into Suborbital Reports account settings pane

If you need further help just email us or refer to Apple's guide: https://help.apple.com/itc/appsreporterguide/#/apd2f1f1cfa3

What is the Vendor ID and where can I find it?

This section currently is obsolete as Suborbital Reports can automatically retrieve your Vendor ID via the Retrieve… button

The Vendor ID is a unique ID number each app store developer account gets assigend on creation. You can find your Vendor ID by logging into iTunes Connect (https://itunesconnect.apple.com). There go to the "Sales and Trends" section (fig#1) and click on the "Top Content" drop down in the upper left corner. Select "Reports" from the drop down (fig#2). The vendor ID will then be displayed next to your (or your company's) name. (fig#3)

A quick shortcut is this link: https://reportingitc2.apple.com/reports.html (If you are redirected to the login form just log in and click this link once more. ITC is a little buggy and won't automatically redirect you from the login to the reports.)


Fig. #1 - click on "Sales and Trends"


Fig. #2 - click on "Reports"


Fig. #3 - the 8-digit number next to your name is your vendor ID

Suborbital Reports parses and analyzes the financial sales reports which Apple publishes every day. The web based iTunes Connect "Sales and Trends" tool seems to use different sales numbers which are shifted in time. Though daily reports can be different over longer time spans (4 days+) both methods report exactly the same revenue numbers.

How does SR handle currencies and why is everything in USD?

When a report from Apple is downloaded and parsed the revenues which are provided in regional currencies are converted to USD by using the current official exchange rate. This converted value is then saved to the database and won't change - even if the exchange rates change. USD has been chosen because that's what most developers we interviewed tend to prefer.

Is my data with SR secure?

Generally speaking: Yes. Suborbital Reports is not cloud based so the downloaded reports don't go through any 3rd party server you have no control over. Sales reports are downloaded to your Mac, proccessed there and never leave your Mac. In addition your login credentials are securely stored in the encrypted OS X System Keychain. So even if someone should somehow get access to your database file they won't be able to login into iTunes Connect and do any harm.

As long as you don't anything too risky (putting the database in a shared folder in DropBox, etc.) there's no risk of your data being stolen. It all depends on how well you can protect your Mac from unauhtorized access which usually boils down to having good common sense.

I have noticed that SR connects to some non-Apple servers. What's up with that?

Suborbital Reports regularly connects to our update server to check if a new version is available. It also sends some anonymized usage statistics (OS X version, Mac model and screen resolution). In case of a crash an anonymized crash report is sent to us (which only contains the location of the crash - no memory dump is included!).

Other than that Suborbital Reports doesn't transmit any data. It will NEVER send any sensitive data to us or any other party. Your sales data is safe all the time and no one but you has access to it.

What format does SR use to store the data and is there a vendor lock in?

Suborbital Reports uses a plain Sqlite 3 database to store all analytics data. The downloaded sales reports are stored next to the database in their unchanged original form. Your data is stored in "~/Documents/Suborbital Reports/". The report files can be found in the "reports/vendor_id" subdirectory.

So if you should decide to stop using Suborbital Reports you won't encounter any problems migrating your data to a different application. Furthermore we have included a SQL schema file in the application bundle for you so you can understand the table layout of the database better and write your own analytics scripts if you wish to.

Do I need to backup my data?

Yes! Suborbital Reports doesn't backup your data for you. You're responsible for doing so!

We suggest you add "~/Documents/Suborbital Reports/" to your backup software. Also it's a good idea to turn that folder into a git repository and to add and commit new reports regularly just in case something corrupts the database or report files.

Please take backing up your raw reports files seriously! Apple will (and do) delete daily sales reports after 30 days. Weekly sales reports get deleted after a year. If you lose your reports and will have to re-download everything you will end with a very coarse data set! The overall revenue and download numbers will be correct but the resolution of that data set will be months or years instead of days!

Please note that we CAN NOT generated original sales reports from the database! The database does not replace your sales reports!

Deleting Accounts

Whenever you delete an account in Suborbital Reports all the data associated with an account WILL BE PURGED FROM THE DATABASE. If you lost access to the account or don't want to update it further consider unchecking "Download Reports for this Account" in the Accounts preferences pane.

But if you decide to delete the account note that THIS CAN NOTE BE UNDONE and you will need to re-import the report files whenever you'll want to restore the data.

Note: The report files are not deleted from disk and kept in your ~/Documents/Suborbital Reports/reports/ folder.

Why does SR display only monthly/weekly average data instead of daily data?

Sadly Apple will purge your daily sales reports after 30 days and only leave weekly/monthly/yearly reports. That means that we can not know how much an app sold on a Monday when all we have is a weekly report saying that the app sold 20 times that week. So we simply display an average of 20/7 units per day.

But it gets worse! Apple will even purge your weekly and monthly reports after some time. So some day you might end up with only yearly reports where every day's value will be equal to the annual average.

That's why it's important to run SR every day and to backup your "~/Documents/Suborbital Reports" folder regularly!

I have multiple Macs. Is there a sync function planned?

No. Sync is a hard to get right. And syncing Sqlite databases is notoriously hard. That's why we opted not to include any sync features.

If you need your sales data on multiple macs we suggest you set up Suborbital Reports on each of them and let every Mac download reports.

A solution with git, a local git server and cronjobs is also imaginable. (If you don't provide credentials for an account Suborbital Reports will be able to display the data from a database but won't be able to download new reports. So that way you can have a 'read only' instance of SR running).

Word of caution: Don't put the SR database onto Dropbox. It most likely will just corrupt the database. Dropbox and Sqlite databases don't play well together.

So I didn't listen and my database got corrupted. What should I do?

If you initialized a git repo in "~/Documents/Suborbital Reports/" just check out the last working revision. (Don't forget to quit SR before doing this).

If you didn't then just follow this procedure:

1. Quit Suborbital Reports
2. Open "~/Documents/Suborbital Reports/" in Finder
3. Delete "analytics.db"
4. Move all files from the "reports/*vendor_id*/" subdirectories into the "inbox" subdirectory.
5. Start Suborbital Reports
6. Add all your accounts
7. Click the "Update" button

This way Suborbital Reports will re-import all files from "inbox" and re-generate all analytics data. But that's a lot of work so it's better to use git instead :)

I noticed that older daily reports seem to be rather "wonky"?!

Sadly Apple only provides daily reports for the last 30 days and weekly reports for the last 52 weeks. So if you don't continuously download new daily reports that information will get lost and Suborbital Reports will have to use an average value calculated from the next "coarser" report type. So if December 2013 has 31 days all with $74.55 revenue that's why. It's just the daily average through the month (monthly_revenue/days_in_month).

If you should happen to have older reports (older Appviz installation for example) you can drop them into the "~/Documents/Suborbital Reports/inbox" folder and Suborbital Report will import and parse those reports the next time you perform a data update.

I have a large Appviz / Appviz 2 database. Can I import it?

Yes. Just drop the report files (ending with .txt, .txt.gz, .tgz) from the Appviz reports folder into "~/Documents/Suborbital Reports/inbox" and press the "Update" button. Suborbital Reports will then parse those reports and import them into the database.

The Appviz reports folder is usually located in "~/Library/Application Support/AppViz 2/AppViz 2.appviz2data/Reports/some-cryptic-UUID/". Just copy all the report files from there into "~/Documents/Suborbital Reports/inbox".

Will importing large Appviz databases impact performance?

No. We use Suborbital Reports with a database that contains three accounts with each having daily data from 2008 till now and we expect 0 performance degradation. The main reason is that SR uses Sqlite directly and not through an ORM layer. So that's why you don't have to wait 30 seconds when you select a larger data set (which often happened with Appviz).

In fact having better performance than Appviz was one of the main reasons behind developing Suborbital Reports in the first place.

If Apple changes/updates iTunes Connect will SR stop working?

No. Suborbital Reports uses the official auto ingestion API which Apple's auto ingestion tool uses. There's no web scraping going on. So if Apple decides to update iTunes Connect or if ITC is temporarily offline Suborbital Reports will still be able to download sales reports. (For example we had no problems with downloading fresh reports during the last Christmas Holidays ITC shutdown).

A scenario as with Appviz 2 where the software stops working after an iTunes Connect update is highly unlikely.

I need to recover a lost license. What should I do?

Contact us and mention your order number/id, email address you purchased with, name (or anything else that we can use to find your order in the database).

I get a "max activation limit reached" error when I try to unlock SR with my license.

Oh boy, you somehow managed to unlock SR on more than 512 Macs ;) Contact us and we'll fix that.

I have read the manual and still need help!

Don't panic! ;) We're here to help you out. Just drop us an email and describe what problems you have with Suborbital Reports. We'll try our best to help you! (Please mention what Mac you use, which version of OS X is installed and what version of Suborbital Reports you're running).