Select a topic from the table of contents or search the guide.
Reporter is a command-line tool that you can use to download your Sales and Trends reports and Payments and Financial Reports. It allows you to easily switch accounts if you use one Apple Account for multiple developer accounts. You can also look up descriptions for errors and view the estimated time of availability for any delayed reports.
Reporter 2.2 contains the following enhancements:
We've updated Reporter to let you generate an access token with the new generateToken command. To use this new command, download Reporter 2.2.
Starting August 10, 2017, you will no longer be able to sign in to Reporter with your Apple Account password or app-specific passwords. To continue using Reporter, generate a unique access token.
To get started, download the latest version of Reporter 2.2.
The package contains two files:
Reporter.jar
Reporter.properties
Tip: Use Get Version to see the version of Reporter that you’re using.
Before using Reporter, make sure you have Java 1.8 or later installed.
After downloading Reporter, use an access token to sign in.
Open the Reporter.properties file using a text editor.
Configuration settings for Reporter are specified in a properties file, where each property consists of a key-value pair on a separate line. Save the properties file in the same directory as the Reporter.jar file, using the ".properties" file extension.
Add your access token.
See Manage Access Token.
Save the Reporter.properties file.
An access token is a unique code used in your Reporter properties file that lets you download sales and financial reports with Reporter.
Notes:
You can generate only one access token at a time per Apple Account. Your access token will automatically expire after 180 days. If you generate a new access token, your previous access token immediately expires.
Token management methods are not intended for automated use and access may be rate limited.
The generateToken command generates an access token to input into your properties file. This command always returns plain text, even in Robot mode.
Note: This command requires Reporter 2.2 or later. To download the latest version of Reporter, see Download Reporter.
$ java -jar Reporter.jar p=[properties file name] [application name].generateToken[application name] - Replace with “Sales” or “Finance”
Note: You only need to generate one access token to access both the Sales and Finance applications. You do not need to generate separate access tokens.
$ java -jar Reporter.jar p=Reporter.properties Sales.generateTokenPlease type in your username: ********Please type in your password: ********Once you generate an access token, you won't be able to log in to Reporter with your username and password. Do you still want to continue? (y/n):Your access token has been generated.AccessToken:12abc345-de6f-7ghi-89jk123lmnoExpiration Date:2017-06-07(Expiration Date format: YYYY-MM-DD)
$ java -jar Reporter.jar p=Reporter.properties Sales.generateTokenPlease type in your username: ********Please type in your password: ********If you generate a new access token, your existing token will be deleted. Do you still want to continue? (y/n):From the homepage, click Sales and Trends.
From the left-hand side, click Sales and Trends Reports.
In the upper-right corner, click on the tooltip next to About Reports.
Click Generate Reporter Token.
Copy the access token to your clipboard.
Use the access token to sign in to Reporter.
The viewToken command returns your current access token. This command always returns plain text, even in Robot mode.
$ java -jar Reporter.jar p=[properties file name] [application name].viewToken[application name] - Replace with “Sales” or “Finance”
Examples
$ java -jar Reporter.jar p=Reporter.properties Sales.viewTokenPlease type in your username: ********Please type in your password: ********AccessToken:12abc345-de6f-7ghi-89jk123lmnoExpiration Date:2017-06-07(Expiration Date format: YYYY-MM-DD)
$ java -jar Reporter.jar p=Reporter.properties Sales.viewTokenPlease type in your username: ********Please type in your password: ********AccessToken:12abc345-de6f-7ghi-89jk123lmnoExpiration Date:2017-06-07Your existing token is expired. Type generateToken to generate a new one.$ java -jar Reporter.jar p=Reporter.properties Sales.viewTokenPlease type in your username: ********Please type in your password: ********You currently don't have an access token. Type generateToken to generate a new one.The deleteToken command deletes your existing access token. You will no longer be able to use a deleted access token. This command always returns plain text, even in Robot mode.
$ java -jar Reporter.jar p=[properties file name] [application name].deleteToken[application name] - Replace with “Sales” or “Finance”
$ java -jar Reporter.jar p=Reporter.properties Sales.deleteTokenYour existing access token has been deleted.To use Reporter, follow these steps:
Open a command-line tool (for example, Terminal in OS X).
Note: Reporter works with any command-line interface that supports Java, including on PC.
Navigate to the directory of the Reporter.jar file.
Use any of the commands described in this guide, such as getReport, using the syntax below.
$ java -jar Reporter.jar p=[properties file name] a=[account number] m=[mode] Sales.[command]$ java -jar Reporter.jar p=[properties file name] a=[account number] m=[mode] Finance.[command]Note: If your Apple Account has access to multiple iTunes Connect accounts, you’ll need to specify the account number you’d like to use. The command-line parameters, if specified, will override the value in the properties file. To see a list of your accounts, use the Get Accounts command.
The getStatus command returns the status of the Reporter service for your Sales and Trends reports or your financial reports.
In Robot mode, if the service is available, getStatus will return a “0” code. If the service is unavailable, getStatus will return a “1” error code.
If an estimated time of availability is known, getStatus will return a “retry” value. The retry value is expressed in milliseconds, and indicates how long to wait before trying again.
$ java -jar Reporter.jar p=[properties file] Sales.getStatus$ java -jar Reporter.jar p=[properties file] Finance.getStatusExamples
$ java -jar Reporter.jar p=Reporter.properties Sales.getStatusSales and Trends is currently available.$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getStatus<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Status> <Message>Sales and Trends Reporter is currently available.</Message> <Code>0</Code></Status>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getStatusSales and Trends is currently unavailable. Please try again in 15 minutes.$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getStatus<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Error> <Code>1</Code> <Message>Sales and Trends is currently unavailable. Please try again in 15 minutes.</Message> <Retry>875000</Retry></Error>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getStatusFinanceFinance Reporter is currently available.$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getStatus<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Status> <Message>Finance Reporter is currently available.</Message> <Code>0</Code></Status>The getVersion command returns the version of Reporter that you’re using. This command always returns plain text, even in Robot mode.
$ java -jar Reporter.jar getVersion$ java -jar Reporter.jar getVersion1.0The getAccounts command returns a list of your accounts for your Sales and Trends reports or your Financial reports.
In Normal mode, each account is on a separate line with the account name and account ID, separated by a comma.
$ java -jar Reporter.jar p=[properties file] Sales.getAccounts$ java -jar Reporter.jar p=[properties file] Finance.getAccountsAccounts for Sales and Trends (Normal Mode)
$ java -jar Reporter.jar p=Reporter.properties Sales.getAccountsJane Appleseed Inc, 12345John Appleseed Inc, 67890Accounts for Sales and Trends (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getAccounts<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Accounts> <Account> <Name>Jane Appleseed Inc</Name> <Number>12345</Number> </Account> <Account> <Name>John Appleseed Inc</Name> <Number>67890</Number> </Account></Accounts>The getReportVersion command lets you know what is the latest available version of a report.
Required role: Admin, Finance, Sales
$ java -jar Reporter.jar p=[properties file] Sales.getReportVersion [report type], [report subtype]$ java -jar Reporter.jar p=[properties file] Finance.getReportVersion [report type], [report subtype]Examples
$ java -jar Reporter.jar p=[properties file] Sales.getReportVersion Sales, DetailedThe current version of the Sales (Summary) report is 1_2$ java -jar Reporter.jar p=[properties file] Sales.getReportVersion Sales, Detailed<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Report Version>The current version of the Sales (Summary) report is 1_2</Report Version>The Sales.getVendors command returns a list of vendor numbers for which you can download reports.
In Normal mode, each vendor is on a separate line.
$ java -jar Reporter.jar p=[properties file] Sales.getVendorsNormal mode
$ java -jar Reporter.jar p=Reporter.properties Sales.getVendors8001234580067890Robot mode
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getVendors<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Vendors> <Vendor>80012345</Vendor> <Vendor>80067890</Vendor></Vendors>The Finance.getVendorsAndRegions command returns a list of report types you can download by vendor number and region. See the getReport command for a description of report types.
$ java -jar Reporter.jar p=[properties file] Finance.getVendorsAndRegionsNormal Mode
$ java -jar Reporter.jar p=Reporter.properties Finance.getVendorsAndRegionsThe following reports are available for vendor 80012345:US: FinancialJP: FinancialThe following reports are available for vendor 80067891:CA: FinancialRobot Mode
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getVendorsAndRegions<?xml version="1.0" encoding="UTF-8" standalone="yes"?><VendorsAndRegions> <Vendor> <Number>80012345</Number> <Region> <Code>US</Code> <Reports> <Report>Financial</Report> </Reports> </Region> <Region> <Code>JP</Code> <Reports> <Report>Financial</Report> </Reports> </Region> </Vendor> <Vendor> <Number>80067891</Number> <Region> <Code>US</Code> <Reports> <Report>Financial</Report> </Reports> </Region> </Vendor></VendorsAndRegions>The Sales.getReport command downloads Sales and Trends reports.
Required role: Admin, Finance, Sales with Reports. See Role Permissions.
$ java -jar Reporter.jar p=[properties file] Sales.getReport [vendor number], [report type], [report subtype], [date type], [date], [version]* (if applicable)* Required for Subscription Reports.
Parameter | Description |
|---|---|
Vendor Number | Vendor number of the report to download. For a list of your vendor numbers, use the getVendors command. |
Report Type | Type of information contained in report (for example, Sales). See Report Types (Sales and Trends). |
Report Subtype | Level of detail in the report (for example, Summary). See Report Types (Sales and Trends). |
Date Type | Length of time covered by the report (for example, Daily or Weekly). See Date Types. |
Date Format | Specific time covered by the report (for example, 20150201). See Date Types. |
Report Version | Version of the report you want to download. See Report Types (Sales and Trends). Report Version is required for subscription reports, but optional for sales reports. |
Sales Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Sales, Summary, Daily, 20150201<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded S_D_80012345_20150201.txt.gz.</Message></Output>Sales Report When Delayed (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Sales, Summary, Daily, 20150201<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Error> <Code>117</Code> <Message>Daily reports are delayed. Please try again in 1 hour.</Message> <Retry>3600000</Retry></Error>Subscription Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Subscription, Summary, Daily, 20160901<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded Subscription_80012345_20160901.txt.gz.</Message></Output>Subscription Report (Robot Mode with Version option)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Subscription, Summary, Daily, 20160901, 1_1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded Subscription_80012345_20160901_V1_1.txt.gz.</Message></Output>Subscription Event Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, SubscriptionEvent, Summary, Daily, 20160901<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded Subscription_Event_80012345_20160901.txt.gz.</Message></Output>Subscription Event Report (Robot Mode with Version option)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, SubscriptionEvent, Summary, Daily, 20160901, 1_1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded Subscription_Event_80012345_20160901_V1_1.txt.gz.</Message></Output>Subscriber Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Subscriber, Detailed, Daily, 20161201<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded Subscriber_80012345_20161201.txt.gz.</Message></Output>Subscriber Report (Robot Mode with Version option)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Subscriber, Detailed, Daily, 20161201, 1_1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded Subscriber_80012345_20161201_V1_1.txt.gz.</Message></Output>Pre-Order Summary Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Pre-Order, Summary, Daily, 20171031<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded P_S_D_80012345_20171031.txt.gz</Message></Output>Newsstand Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Newsstand, Detailed, Weekly, 20150208<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded N_D_W_80012345_20150208.txt.gz.</Message></Output>Sales Opt-In Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Sales, Opt-In, Weekly, 20150208<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded O_S_W_80012345_20150208.zip</Message> <Password>ABCD-EFGH-IJKL</Password></Output>Wrong Vendor Number (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 90012345, Sales, Summary, Daily, 20150201<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Error> <Code>200</Code> <Message>Invalid vendor number specified. Try again.</Message></Error>The Finance.getReport command downloads a financial report for you.
Required role: Admin or Finance. See Role Permissions.
$ java -jar Reporter.jar p=[properties file] Finance.getReport [vendor number], [region code], [report type], [fiscal year], [fiscal period], [version] (if applicable)Parameter | Description |
|---|---|
Vendor Number | Use the vendor number for the report you want to download. For a list of your vendor numbers, use the getVendorsAndRegions command. |
Region Code | Two-character code of country of report to download. For a list of country codes by vendor number, use getVendorsAndRegions command. For a consolidated report which shows all available currencies, use region ZZ. Reporter will provide the consolidated report instead of individual reports by country. |
Report Type | Specific type of report to download (for example, Financial). |
Fiscal Year | Four-digit year of report to download. Year is specific to Apple’s fiscal calendar. |
Fiscal Period | This is the period in fiscal year for the report you’re downloading (1–12). The period is specific to Apple’s fiscal calendar. |
Financial Report (Robot Mode)
$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getReport 80012345, US, Financial, 2015, 1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded 80012345_1015_US.txt.gz</Message></Output>The following are report types and subtypes for Sales and Trends Reports.
| Report Name | Report Type | Report Subtype | Date Types | Description | Latest Version, Previous Version |
|---|---|---|---|---|---|
| Summary Sales | Sales | Summary | Daily, Weekly, Monthly, Yearly | At least one app unit sold. | 1_0 |
| Subscription | Subscription | Summary | Daily | At least one auto-renewable subscription sold, including free trials. | 1_1, 1_0 (Available until March 2018) |
| Subscription Event | Subscription Event | Summary | Daily | At least one auto-renewable subscription sold, including free trials. | 1_1, 1_0 (Available until March 2018) |
| Subscriber | Subscriber | Detailed | Daily | At least one auto-renewable subscription sold, including free trials. | 1_1, 1_0 (Available until March 2018) |
| Magazines & Newspapers Detailed | Newsstand | Detailed | Daily, Weekly | Magazines & Newspapers apps that use Newsstand Kit and have sold at least one auto-renewable subscription, including free trials. | 1_0 |
| Marketing Opt-In | Sales | Opt-In | Weekly | Magazines & Newspapers apps that use Newsstand Kit and have sold at least one auto-renewable subscription, including free trials. | 1_0 |
| Pre-Order | Pre-Order | Summary | Daily, Weekly, Monthly, Yearly | At least one pre-ordered item. | 1_0 |
| Date Type | Date Format | Example |
|---|---|---|
| Daily | YYYYMMDD | 20150201 |
| Weekly* | YYYYMMDD | 20150208 |
| Monthly | YYYYMM | 201502 |
| Yearly | YYYY | 2015 |
*Weekly reports cover Monday through Sunday. The day used is the Sunday that week ends.
The table below describes possible errors returned by Reporter. In Robot mode, errors are returned with a code, as listed below:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Error> <Code>101</Code> <Message>Invalid command.</Message> </Error>| Error Code | Error Description |
|---|---|
| 100 | Application and method name are incorrectly specified. Use format ApplicationName.MethodName. For example, Sales.getHelp. |
| 101 | Invalid method is specified. Call ApplicationName.getHelp for a list of valid methods for the application. |
| 102 | Too few or too many parameters specified for the method. Call ApplicationName.getHelp for a list of valid methods and their parameters. |
| 103 | Properties file not specified. Use format p=PropertiesFile. |
| 104 | Cannot find properties file. Make sure it resides in the same directory. |
| 105 | Cannot read properties file. Check the file format and try again. |
| 108 | Invalid username and password. Change values and try again. |
| 109 | Properties file does not contain an endpoint. Add to file and try again. |
| 110 | Network is not available. Check connection and try again. |
| 111 | Network is available but cannot connect to application. Check your proxy and firewall settings and try again. |
| 112 | Cannot save file. Make sure you have enough space and have write access to the current directory. |
| 113 | Invalid output style format. |
| 114 | API Version is not specified in service end point. |
| 115 | API Version Of Service Endpoint is not matching with Application's service API. |
| 117 | [Type of report] reports are delayed. Please try again in [Availability estimate]. If an estimated time of availability is known, a “retry” value is also returned. The retry value is expressed in milliseconds, and indicates how long to wait before trying again. |
| 119 | Report was not fully downloaded. Please try again. |
| 120 | The version parameter you have specified is invalid. |
| 121 | Please include the version parameter. |
| 123 | Your Access Token is expired. Please regenerate your Access Token. |
| 124 | Your Access Token is invalid. |
| 125 | Your Access Token is incorrectly specified. Please use the following format: |
| 131 | Username and password are incorrectly entered. Use format: Please type in your username: =value Please type in your password: =value |
| 132 | You are required to use your Access Token in your Reporter properties file. You may no longer use your username and password in your Reporter properties file. |
| 200 | Invalid vendor number specified. Try again. |
| 201 | Invalid report type specified. Valid values include: Sales, Newsstand, Pre-order, Cloud, Event, Customer, Content, Station, Control, amEvent, amContent, amControl, amStreams, Subscription, SubscriptionEvent, and Subscriber. |
| 202 | Invalid report subtype specified. Valid values include: Detailed and Summary. |
| 203 | Invalid combination of report type and report subtype. Try again. |
| 204 | Invalid date type specified. Valid values include: Daily, Weekly, Monthly, and Yearly. |
| 205 | Invalid date. For weekly reports, please specify the date of the Sunday ending the desired week. |
| 206 | Invalid combination of report subtype and date type. Try again. |
| 207 | Invalid date. |
| 208 | Invalid combination of date type and date. For daily and weekly reports, use format YYYYMMDD. For monthly, use YYYYMM. For yearly, use YYYY. |
| 209 | Report is no longer available. Daily reports are available for 365 days, weekly reports for 52 weeks, monthly reports for 12 months, and yearly reports indefinitely. |
| 211 | Report is unexpectedly not available. Try again later. |
| 212 | An unexpected error occurred. Try again later. |
| 213 | There were no sales for the date specified. |
| 214 | You have access to more than one account. Please specify an account number in your properties file or on the command line. To see a list of accounts, run the command getAccounts. |
| 215 | Invalid account number specified. To see a list of accounts, run the command getAccounts. |
| 216 | Invalid account number specified in properties file. To see a list of accounts, run the command getAccounts. |
| 300 | Invalid vendor number specified. Try again. |
| 316 | Invalid region code. |
| 314 | Invalid fiscal year. |
| 315 | Invalid fiscal period. |
Reporter has two modes of operation: Normal and Robot.
Normal mode is intended for an actual user that executes ad-hoc commands. Messages are displayed in easily readable text.
Robot mode is intended for an automated script that’s used regularly. Messages in robot mode are displayed in XML for easy parsing.
You can specify the mode in the properties file or directly on the command line. The command line mode, if specified, will override the value in the properties file.
| Mode | Properties File Format | Command Line Format |
|---|---|---|
| Normal | Mode=Normal | m=Normal |
| Robot | Mode-Robot.XML | m=Robot.XML |
The table below describes the properties used by Reporter, all of which are required.
| Property | Description |
|---|---|
| AccessToken | Your Access Token for Reporter. See Manage Access Token. |
| Account | If your Apple Account has access to multiple accounts, you’ll need to specify the account number you’d like to use. You can also specify an account number as a parameter in the command line. The command-line mode, if specified, will override the value in the properties file. To see a list of your accounts, use the Get Accounts command. |
| Mode | See Modes. |
| SalesUrl | URL of the Sales and Trends service for Reporter. You can change the URL to specify different versions of the service. Only version 1 is currently available. Unless you upgrade to a new version, you usually won’t need to change this. |
| FinanceUrl | URL of the Payments and Financial Reports service for Reporter. You can change the URL to specify different versions of the service. Only version 1 is currently available. Unless you upgrade to a new version, you usually won’t need to change this. |