About Reporter

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 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.

What’s new in this version?

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 ID password or app-specific passwords. To continue using Reporter, generate a unique access token.

Get Started

Download Reporter

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.

Sign in to Reporter

Before using Reporter, make sure you have Java 1.8 or later installed.

After downloading Reporter, use an access token to sign in.

  1. 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.

  2. Add your access token.

    See Manage access token.

  3. Save the Reporter.properties file.

Manage access token

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.

Generate access token using generateToken command

  • 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.

Syntax

$ 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.

Example

$ 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):

If input is 'y':

Your access token has been generated.AccessToken:12abc345-de6f-7ghi-89jk123lmnoExpiration Date:2017-06-07

(Expiration Date format: YYYY-MM-DD)

If user already has a token:

$ 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):

Generate access token in iTunes Connect

  1. From the homepage, click Sales and Trends.

  2. From the left-hand side, click Sales and Trends Reports.

  3. In the upper-right corner, click on the tooltip next to About Reports.

  4. Click Generate Reporter Token.

  5. Copy the access token to your clipboard.

    Use the access token to sign in to Reporter.

View access token

  • The viewToken command returns your current access token. This command always returns plain text, even in Robot mode.

Syntax

$ java -jar Reporter.jar p=[properties file name] [application name].viewToken

[application name] - Replace with “Sales” or “Finance”

Examples

Unexpired token

$ 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)

Expired token

$ 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.

No token yet

$ 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.

Delete access token

  • 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.

Syntax

$ java -jar Reporter.jar p=[properties file name] [application name].deleteToken

[application name] - Replace with “Sales” or “Finance”

Example

$ java -jar Reporter.jar p=Reporter.properties Sales.deleteTokenYour existing access token has been deleted.

Use Reporter

To use Reporter, follow these steps:

  1. 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.

  2. Navigate to the directory of the Reporter.jar file.

  3. 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.

General Commands

Get Status

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.

Syntax

$ java -jar Reporter.jar p=[properties file] Sales.getStatus$ java -jar Reporter.jar p=[properties file] Finance.getStatus

Examples

Status of Sales and Trends When Available (Normal Mode)

$ java -jar Reporter.jar p=Reporter.properties Sales.getStatusSales and Trends is currently available.

Status of Sales and Trends When Available (Robot Mode)

$ 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>

Status of Sales and Trends When Unavailable (Normal Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getStatusSales and Trends is currently unavailable. Please try again in 15 minutes.

Status of Sales and Trends When Unavailable (Robot Mode)

$ 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>

Status of Payments and Financial Reports When Available (Normal Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getStatusFinanceFinance Reporter is currently available.

Status of Payments and Financial Reports When Available (Robot Mode)

$ 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>

Get Version

The getVersion command returns the version of Reporter that you’re using. This command always returns plain text, even in Robot mode.

Syntax

$ java -jar Reporter.jar getVersion

Example

$ java -jar Reporter.jar getVersion1.0

Get Accounts

The 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.

Syntax

$ java -jar Reporter.jar p=[properties file] Sales.getAccounts$ java -jar Reporter.jar p=[properties file] Finance.getAccounts

Examples

Accounts for Sales and Trends (Normal Mode)

$ java -jar Reporter.jar p=Reporter.properties Sales.getAccountsJane Appleseed Inc, 12345John Appleseed Inc, 67890

Accounts 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>

Get Report Version

The getReportVersion command let’s you know what is the latest available version of a report.

Required role: Admin, Finance, Sales

Syntax

$ 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

Report Versions for Sales and Trends (Normal Mode)

$ java -jar Reporter.jar p=[properties file] Sales.getReportVersion Sales, DetailedThe current version of the Sales (Detailed) report is 1_2

Report Versions for Sales and Trends (Robot Mode)

$ 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>

Get vendor numbers (Sales and Trends)

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.

Syntax

$ java -jar Reporter.jar p=[properties file] Sales.getVendors

Examples

Normal mode

$ java -jar Reporter.jar p=Reporter.properties Sales.getVendors8001234580067890

Robot 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>

Get vendor numbers and regions (Financial reports)

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.

Syntax

$ java -jar Reporter.jar p=[properties file] Finance.getVendorsAndRegions

Examples for Music

Normal 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,AppleMusicSummary

Robot 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> </Reports> </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>

Examples for Movies, TV

Normal 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: Financial

Robot 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>

Download Reports

Download Sales and Trends reports

The Sales.getReport command downloads Sales and Trends reports.

Required role: Admin, Finance, Sales.

Syntax

$ 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

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.

Examples for Music

Apple Music Event Reports (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amEvent, Detailed, Daily, 20150201

Apple Music Event Reports (Robot Mode with Version option)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amEvent, Detailed, Daily, 20190513, 1_2

Apple Music Detailed Streams Reports (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amStreams, Detailed, Daily, 20150201

Apple Music Detailed Streams Reports (Robot Mode with Version option)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amEvent, Detailed, Daily, 20190513, 1_2

Apple Music Subscription Reference Reports (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amSubscriptionReference, Summary, Daily, 20201201

Apple Music Subscription Reference Reports (Robot Mode with Version option)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amSubscriptionReference, Summary, Daily, 20201201, 1_0

Apple Music Library Events Reports (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties Sales.getReport 80012345, amLibraryEvents, Detailed, Daily, 20190513

Apple Music Total Library Adds Reports (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties Sales.getReport 80012345, amTotalLibraryAdds, Summary, Daily, 20190513

Apple Music Editorial Playlist Adds Reports (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amEditorialPlaylistAdds, Summary, Daily, 20200101<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded AppleMusic_EditorialPlaylistAdds_ 80012345_ 20200101.txt.gz</Message></Output>

Shazams Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amShazam, Summary, Daily, 20190808<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded AMShazam_80012345_20190808.txt.gz.</Message></Output>

Sales Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Sales, Detailed, Daily, 20190513, 1_2<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded D_D_80012345_20190513_V1_2.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>

Pre-Order Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Pre-Order, Summary, Weekly, 20150208<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded P_S_W_80012345_20150208.txt.gz.</Message></Output>

Cloud Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Cloud, Detailed, Daily, 20190513, 1_1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded C_D_80012345_20190513_V1_1.txt.gz.</Message></Output>

Wrong Vendor Number (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 90012345, Event, Detailed, Daily, 20150201<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Error> <Code>200</Code> <Message>Invalid vendor number specified. Try again.</Message></Error>

Demographic Reports (Daily) (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, ArtistDemographics, Summary, Daily, 20170801, 1_1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded iTunes_ArtistDemographics_80012345_20170320_V1_1.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, ContentDemographics, Summary, Daily, 20170801, 1_1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded iTunes_ContentDemographics_80012345_20170320_V1_1.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amContentDemographics, Summary, Daily, 20170801, 1_1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded AppleMusic_ContentDemographics_80012345_20170320_V1_1.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amArtistDemographics, Summary, Daily, 20170801, 1_1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded AppleMusic_ArtistDemographics_80012345_20170320_V1_1.txt.gz.</Message> </Output>

Demographics (Weekly) (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, ArtistDemographics, Summary, Weekly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded iTunes_ArtistDemographicsWeekly_80012345_20170320.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, ContentDemographics, Summary, Weekly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded iTunes_ContentDemographicsWeekly_80012345_20170320.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amContentDemographics, Summary, Weekly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded AppleMusic_ContentDemographicsWeekly_80012345_20170320.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amArtistDemographics, Summary, Weekly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded AppleMusic_ArtistDemographicsWeekly_80012345_20170320.txt.gz.</Message> </Output>

Demographics (Monthly) (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, ArtistDemographics, Summary, Monthly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded iTunes_ArtistDemographicsMonthly_80012345_20170320.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, ContentDemographics, Summary, Monthly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded iTunes_ContentDemographicsMonthly_80012345_20170320.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amContentDemographics, Summary, Monthly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded AppleMusic_ContentDemographicsMonthly_80012345_20170320.txt.gz.</Message> </Output>$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, amArtistDemographics, Summary, Monthly, 20170801 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Output> <Message>Successfully downloaded AppleMusic_ArtistDemographicsMonthly_80012345_20170320.txt.gz.</Message> </Output>

Examples for TV

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>

Cloud Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Cloud, Detailed, Daily, 20190513, 1_1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded C_D_80012345_20190513_V1_1.txt.gz.</Message></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>

Examples for Movies

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>

Pre-Order Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Pre-Order, Summary, Weekly, 20150208<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded P_S_W_80012345_20150208.txt.gz.</Message></Output>

Cloud Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Sales.getReport 80012345, Cloud, Detailed, Daily, 20190513, 1_1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded C_D_80012345_20190513_V1_1.txt.gz.</Message></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>

Download Financial Reports

The Finance.getReport command downloads a financial report for you.

Required role: Admin or Finance.

Syntax

$ java -jar Reporter.jar p=[properties file] Finance.getReport [vendor number], [region code], [report type], [fiscal year], [fiscal period], [version] (if applicable)

Parameters

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.

Report Type for Movies and TV

Currently only one report type is available: Financial.

Examples for Movies and TV

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>

Report Type for Music

The table below describes the valid values to use for each report type with getReport.

Report Type

Report Subtype

Date Types

Description

Current Report Version

Sales

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report.

1_0

Sales

Detailed

Daily, Weekly

Transaction-level sales report.

1_0

Pre-Order

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report for pre-orders.

1_0

Pre-Order

Detailed

Daily, Weekly

Transaction-level sales report for pre-orders.

1_0

Cloud

Detailed

Daily

Aggregated report for iTunes in the Cloud content that is downloaded again.

1_0

Event

Detailed

Daily

Event-level report on customer listening activity for Radio.Event report for a day consists of four parts, and each one must be downloaded separately. See Date Format below for details.

1_0

Customer

Detailed

Daily

Customer metadata report for Radio.

1_0

Content

Detailed

Daily

Content metadata report for Radio.

1_0

Station

Detailed

Daily

Station metadata report for Radio.

1_0

Control

Detailed

Daily

List of MD5 checksums for each of the Radio reports.

1_0

amEvent

Detailed

Daily

Event-level report on streaming activity for Apple Music. Event report for a day consists of two parts, and each one must be downloaded separately. See Date Format below for details.

1_1

amContent

Detailed

Daily

Content metadata report for Apple Music.

1_0

amControl

Detailed

Daily

List of MD5 checksums for each of the Apple Music reports.

1_0

amStreams

Detailed

Daily

Transactional-level information about streams of your catalog on Apple Music. Reports are unaggregated. Using a database application is recommended.

1_1

amContentDemographics

Summary

Daily

Aggregated information about listener membership type, age, and gender, grouped by content.

1_1

amArtistDemographics

Summary

Daily

Aggregated information about listener membership type, age, and gender, grouped by artist.

1_1

ContentDemographics

Summary

Daily

Aggregated information about customer age and gender, grouped by content.

1_1

ArtistDemographics

Summary

Daily

Aggregated information about customer age and gender, grouped by artist.

1_1

amContentDemographics

Summary

Weekly, Monthly

Aggregated information about listener membership type, age, and gender, grouped by content.

1_0

amArtistDemographics

Summary

Weekly, Monthly

Aggregated information about listener membership type, age, and gender, grouped by artist.

1_0

ContentDemographics

Summary

Weekly, Monthly

Aggregated information about customer age and gender, grouped by content.

1_0

ArtistDemographics

Summary

Weekly, Monthly

Aggregated information about customer age and gender, grouped by artist.

1_0

Examples for Music

Financial Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getReport 80012345, US, Finance, 2015, 1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded 80012345_1015_US.txt.gz</Message></Output>

Radio Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getReport 80012345, US, Radio, 2015, 1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded R1_80012345_1015_US.txt.gz</Message></Output>

Apple Music Summary Report (Robot Mode)

$ java -jar Reporter.jar p=Reporter.properties m=Robot.XML Finance.getReport 80012345, US, AppleMusicSummary, 2015, 1<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Output> <Message>Successfully downloaded S1_80012345_1015_US.txt.gz</Message></Output>

Appendices

Report Types (Sales and Trends)

Parameter Combinations for Music

The table below describes the valid values and combinations of parameters to use with getReport.

Report Type

Report Subtype

Date Types

Description

Current Report Version

Updated Report Version

Notes

Sales

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report.

1_0

Sales

Detailed

Daily, Weekly

Transaction-level sales report.

1_3

1_3

Version updated to 1_3 on November 9, 2020

Pre-Order

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report for pre-orders.

1_0

Pre-Order

Detailed

Daily, Weekly

Transaction-level sales report for pre-orders.

1_3

1_3

Version updated to 1_3 on November 9, 2020

Cloud

Detailed

Daily

Aggregated report for iTunes in the Cloud content that is downloaded again.

1_1

Version updated to 1_1 on May 6, 2019

amEvent

Detailed

Daily

Event-level report on streaming activity for Apple Music.

Event report for a day consists of two parts, and each one must be downloaded separately. See Date Format below for details.

1_1

1_2

Version updated to 1_2 on May 13, 2019

amContent

Detailed

Daily

Content metadata report for Apple Music.

1_0

1_2

Version updated to 1_2 on May 13, 2019

amControl

Detailed

Daily

List of MD5 checksums for each of the Apple Music reports.

1_0

amStreams

Detailed

Daily

Transactional-level information about streams of your catalog on Apple Music. Reports are unaggregated. Using a database application is recommended.

1_3

1_3

Version updated to 1_3 on November 9, 2020

amContentDemographics

Summary

Daily

Aggregated information about listener membership type, age, and gender, grouped by content.

1_1

amArtistDemographics

Summary

Daily

Aggregated information about listener membership type, age, and gender, grouped by artist.

1_1

ContentDemographics

Summary

Daily

Aggregated information about customer age and gender, grouped by content.

1_1

ArtistDemographics

Summary

Daily

Aggregated information about customer age and gender, grouped by artist.

1_1

amShazam

Summary

Daily

Aggregated data for Shazam, including date, artist, title, city, and country.

1_2

1_2

Version updated to 1_2 on February 28, 2020

amLibraryEvents

Detailed

Daily

Aggregated counts of subscriber’s adds and removes for your pre-add and released content.

1_0

amTotalLibraryAdds

Summary

Daily

Aggregated information about the addition of your content in a subscriber’s library.

1_0

amEditorialPlaylistAdds

Summary

Daily

Aggregated information about adds, removals and track position updates of your content in Apple Music Editorial Playlists.

1_0

amSubscriptionReference

Summary

Daily

Subscription metadata report for Apple Music.

1_0

Parameter Combinations for TV

The table below describes the valid values and combinations of parameters to use with getReport.

Report Type

Report Subtype

Date Types

Description

Current Report Version

Updated Report Version

Notes

Sales

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report.

1_0

Sales

Detailed

Daily, Weekly

Transaction-level sales report.

1_3

1_3

Version updated to 1_3 on November 9, 2020

Cloud

Detailed

Daily

Aggregated report for iTunes in the Cloud content that's downloaded again.

1_0

1_1

Version updated to 1_1 on May 13, 2019

Parameter Combinations for Movies

The table below describes the valid values and combinations of parameters to use with getReport.

Report Type

Report Subtype

Date Types

Description

Current Report Version

Updated Report Version

Notes

Sales

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report.

1_0

Sales

Detailed

Daily, Weekly

Transaction-level sales report.

1_3

1_3

Version updated to 1_3 on November 9, 2020

Pre-Order

Summary

Daily, Weekly, Monthly, Yearly

Aggregated sales report for pre-orders.

1_0

Pre-Order

Detailed

Daily, Weekly

Transaction-level sales report for pre-orders.

1_3

1_3

Version updated to 1_3 on November 9, 2020

Cloud

Detailed

Daily

Aggregated report for iTunes in the Cloud content that’s downloaded again.

1_0

1_1

Version updated to 1_2 on May 13, 2019

Date Types

Date Format for Music

The date parameter uses different formats, depending on the report type and date type:

  • Daily reports use YYYYMMDD (for example, 20150201)

  • Weekly reports use YYYYMMDD, where the day used is the Sunday that week ends (for example, 20150208)

    Exception - Weekly Demographic Reports use YYYYMMDD, where the day used is the Thursday that week ends

  • Monthly reports use YYYYMM (for example, 201502)

  • Yearly reports use YYYY (for example, 2015)

  • Daily Radio Event reports use YYYYMMDDPP, where PP is one of the four parts (for example, 2015020101, 2015020102, 2015020103, 2015020104)

  • Daily Apple Music Event reports use YYYYMMDD (for example, 20150201)

Date Format for TV

The date parameter uses different formats, depending on the report type and date type:

  • Daily reports use YYYYMMDD (for example, 20150201)

  • Weekly reports use YYYYMMDD, where the day used is the Sunday that week ends (for example, 20150208)

  • Monthly reports use YYYMM (for example, 201502)

  • Yearly reports use YYYY (for example, 2015)

Date Format for Movies

The date parameter uses different formats, depending on the report type and date type:

  • Daily reports use YYYYMMDD (for example, 20150201)

  • Weekly reports use YYYYMMDD, where the day used is the Sunday that week ends (for example, 20150208)

  • Monthly reports use YYYYMM (for example, 201502)

  • Yearly reports use YYYY (for example, 2015)

Errors

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: AccessToken=value.

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.

210

Report is not available yet. Daily reports for the Americas are available by 5 am Pacific Time; Japan, Australia, and New Zealand by 5 am Japan Standard Time; and 5 am Central European Time for all other territories.

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.

301

Invalid report type specified. Valid values include: Financial, Match, Radio, RadioSummary, AppleMusic, AppleMusicSummary, News, and BeatsRadio.

316

Invalid region code.

314

Invalid fiscal year.

315

Invalid fiscal period.

Modes

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

Properties File

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.