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 Subscriptions Reports and Payments and Financial Reports. It allows you to easily switch accounts if you use one Apple ID for multiple content provider 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.
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.
Note: You can generate only one access token at a time per Apple ID. Your access token will automatically expire after 180 days. If you generate a new access token, your previous access token immediately expires.
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):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 ID has access to multiple 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 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] Finance.getStatusExamples
$ 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 Subscriptions 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 Subscriptions (Normal Mode)
$ java -jar Reporter.jar p=Reporter.properties Sales.getAccountsJane Appleseed Inc, 12345John Appleseed Inc, 67890Accounts for Subscriptions (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, Legal
$ 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 apSubscriptionsSales, SummaryThe current version of the apsubscriptionssales (summary) report is 1_0.$ 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 (Detailed) 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: Financial,Match,Radio,RadioSummaryJP: Financial,MatchThe following reports are available for vendor 80067891:CA: Financial,Match,Radio,RadioSummary,AppleMusic,AppleMusicSummaryRobot 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> <Report>Match</Report> <Report>Radio</Report> <Report>RadioSummary</Report> </Region> <Region> <Code>JP</Code> <Reports> <Report>Financial</Report> <Report>Match</Report> </Reports> </Region> </Vendor> <Vendor> <Number>80067891</Number> <Region> <Code>CA</Code> <Reports> <Report>Financial</Report> <Report>Match</Report> <Report>Radio</Report> <Report>RadioSummary</Report> <Report>AppleMusic</Report> <Report>AppleMusicSummary</Report> </Reports> </Region> </Vendor></VendorsAndRegions>The Sales.getReport command downloads Subscription reports.
Required role: Admin, Finance, Legal.
$ java -jar Reporter.jar p=[properties file] Sales.getReport [vendor number], [report type], [report subtype], [date type], [date], [version] (if applicable)Parameter | Description |
|---|---|
Vendor Number | Vendor number of the report to download. For a list of your vendor numbers, use the getVendors command. |
Report Type | The type of report to download (for example, apSubscriptionsSnapshot). |
Report Subtype | The level of detail of the report (for example, Summary). |
Date Type | The length of time covered by the report (for example, Daily). |
Date Format | The date or date range specified for the report to download. Date format: YYYYMMDD |
Report Version | The version of the report to download. Report Version is required only when more than one version of a report exists. |
Aggregated Subscriptions sales report
Report Type | Report Subtype | Date Type | Version |
|---|---|---|---|
apSubscriptionsSales | Summary | Daily | 1_0 |
Format:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport <vendor id>, <report type>, <report subtype>, <date type>, <date>Example:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport 80012345, apSubscriptionsSales, Summary, Daily, 20210101Aggregated subscriptions activity report
Report Type | Report Subtype | Date Type | Version |
|---|---|---|---|
apSubscriptionsEvents | Summary | Daily | 1_0 |
Format:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport <vendor id>, <report type>, <report subtype>, <date type>, <date>Example:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport 80012345, apSubscriptionsEvents, Summary, Daily, 20210101Aggregated subscriptions state report
Report Type | Report Subtype | Date Type | Version |
|---|---|---|---|
apSubscriptionsSnapshot | Summary | Daily | 1_0 |
Format:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport <vendor id>, <report type>, <report subtype>, <date type>, <date>Example:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport 80012345, apSubscriptionsSnapshot, Summary, Daily, 20210101The Sales.getReport command downloads listening reports.
Required role: Admin, Finance, Legal.
$ java -jar Reporter.jar p=[properties file] Sales.getReport [vendor number], [report type], [report subtype], [date type], [date], [version] (if applicable)Parameter | Description |
|---|---|
Vendor Number | Vendor number of the report to download. For a list of your vendor numbers, use the getVendors command. |
Report Type | The type of report to download (for example, apContentPerformance). |
Report Subtype | The level of detail of the report (for example, Summary). |
Date Type | The length of time covered by the report (for example, Monthly). |
Date | The date or date range specified for the report to download. Date format: YYYYMMDD |
Version | The version of the report to download. Report Version is required only when more than one version of a report exists. |
Report Type | Report Subtype | Date Type | Description | Content Report Version | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
apContentPerformance | Summary | Monthly | Aggregated unique listener and play activity report. | 1_0 | |||||||
Format:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport <sap_vendor id>, <report type>, <report subtype>, Monthly, <YYYYMM>Example:
$ java -jar Reporter.jar p=Reporter.properties Sales.getReport 80012345, apContentPerformance, Summary, Monthly, 20210101The Finance.getReport command downloads a financial reports for you.
Required role: Admin, Legal, or Finance.
$ 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. |
Version | This is the version of the report you want to download. |
java -jar Reporter.jar p=abc.properties finance.getReport 87654321,EU,financial,2021,04 a=1234The 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 ID 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. |