Advanced Reports [1.

0]
NEED. MORE. DATA. You hear that all the time, right? Well, the Advanced Reports request will
allow you to integrate the Rakuten Affiliate Network data into your existing applications and
backend systems. And the next time someone wants the data as soon as you have a chance
(translation = yesterday), you dont have to worry. Each report can be requested up to 15,000
times a day! We upped the ante considerably so you never have to wait to get the details you
need.
This document provides the steps necessary to request the following reports: Sales & Activity,
Revenue, Individual Item, Link Type, Product Success, Program Level, Non-Commissionable
Sales, Signature Activity, Signature Order, the Media Optimization Report, the Payment History
Summary, Advertiser Payments History, and Payment Details.
The URL syntax used for the three payment reports differs from the syntax used in the other
reports. For the steps required to run the payment reports, please see the section Requesting
Payment Reports below.

Requesting a Report
To request a specific advanced report, you need only submit the following GET request with
appropriate API Developer Portal authentication header:
https://api.rakutenmarketing.com/advancedreports/1.0?bdate=YYYYMMDD
&edate=YYYYMMDD&token=securitytoken&nid=networkid&reportid=reportid
number&mid=advertiserid&lang=fr&locale=fr
For details on the authentication header and how to acquire your access token, please review
Acquiring your Access Token or the Getting Started Guide in footer of the API Developer
Portal.
You must supply all parameters, except for nid, mid, lang, and locale.

Parameter
bdate

Description
The start date for the report you would like to generate in YYYYMMDD
format.
The end date for the report you would like to generate in YYYYMMDD
format.

edate
Reports can be run for up to 365 days (366 days in a leap year); but please
be aware: The more data you request, the longer the report will take to run.

Parameter

Description
Due to the sensitivity of available reporting data, this service requires the
Security Token as a parameter in addition to the access token found in the
authentication header. The Security Token can be found on the Publisher
Dashboard by going to Links > Web Services.
Please note: the Security Token differs from the access token found in the
header and the former Web Services Token, which the API Developer
Portal eliminates

token

Your Security Token appears on

the Web Services page in the
Publisher Dashboard, directly
below the Web Services Token.

This parameter is optional. Use it to specify the network you want to run a
report for. If you don't include it, the report will be run for all networks. The
possible values are
nid

nid=1 for US
nid=5 for Canada
nid=8 for Brazil
nid=41 for Australia

nid=3 for UK
nid=7 for France
nid=9 for Germany

This identifies the report you are requesting.

reportid

Sales & Activity=4

Revenue=5
Link Type=6
Individual Item=7
Product Success=8

Program Level=9
Non-Commissionable Sales Report=10
Signature Activity Report=11
Signature Order=12
Media Optimization Report=14

Parameter

Description
This is the advertiser ID, a numeric value that Rakuten Affiliate Network
uses to identify an advertiser (merchant). It is an optional parameter.
Include it if you want to run the report for a single advertiser in your program
and exclude it to run the report for all the advertisers in your program.

mid
An advertiser's ID can be found in the Publisher Dashboard on the
Advertiser Details page: Select My Advertisers from the Programs dropdown menu, click on the link for the advertiser, and then click the Advertiser
Info box in the left margin.

lang

This parameter is optional. Use it to change the language of the column

headers in your report to French: lang=fr, German: lang=de or
Portuguese Brazilian: lang=pt. English is the default.
This parameter is optional. Provide one of the following locales to display
amounts with a comma: locale=fr, locale=de or locale=pt-br.
Default is a decimal point.

locale

Note: When amounts appear separated by commas, the whole value for
that field appears in double quote marks; for example:
384,LinkShare Test Act,0,0,0,4,0,0,7,2,"1,98",3,6,9

Sample URLs
The URL below will download a Sales & Activity Report for all transactions that occurred in
April 2013 in the U.S. network for all the advertisers in the publisher's program.
https://api.rakutenmarketing.com/advancedreports/1.0?bdate=20130401
&edate=20130430&token=0f9fc835fb1b231e273d88f0c34gb70c5718f4e8717ff
1ggfb6196908edf0ee5&nid=1&reportid=4
The URL below will download a Media Optimization Report for all transactions that occurred
during the first four days of April 2013 in the U.S. network for advertiser ID 1234.
https://api.rakutenmarketing.com/advancedreports/1.0?bdate=20130401
&edate=20130404&token=0f9fc835fb1b231e273d88f0c34gb70c5718f4e8717ff
1ggfb6196908edf0ee5&nid=1&reportid=14&mid=1234

Report Output
The output for all reports contains comma-separated columns with new records appearing on a
new line. If a report contains no data, only the header rows will be displayed.
Please note: If you are using a text editor like Notepad, any data value in a response that
contains a comma, a new line, or double quotes will place the entire value in double quotes.
See the sample output for the Link Type Report below.
In addition, any double-quote character that is part of a data value will be accounted for by
escaping it with another double-quote character. That is, each instance of a double-quote
character found within the original data will be replaced by two consecutive double-quote
characters.
Since the output of each report differs, a sample of each follows. For descriptions of the
columns included in reports, please see Appendix A.

Sales & Activity

AdvertiserID,Advertiser,Impressions,Clicks,CTR,Orders,Orders/Click,EPC,
Items,Cancelled Items,Sales,Baseline Commissions,Adjusted Commissions,
Actual Commissions
1234,widgets.com,145,34,23.44,8,23,24.55,12,0,149.43,8.35,0.00,8.35

Revenue
Date,Impressions,Clicks,CTR,Orders,Orders/Click,EPC,Sales,Avg.
Order,Baseline Commissions,Adjusted Commissions,Actual Commissions
09/05/2012,45,4,8.88,2,50,2.56,149.43,74.71,10.24,0.00,10.24

Link Type
Link Type,Impressions,Clicks,CTR,Orders,Orders/Click,EPC,Items,Cancelled
Items,Sales,Baseline Commissions,Adjusted Commissions,Actual Commissions
banner,"3,838",119,3.10,3,3,14.92,14,0,818.09,17.75,0.00,17.75

Individual Item
OrderID,Date,Time,AdvertiserID,Advertiser,SKU,ProductName,Sales,Items,
Commissions
8323087,09/08/2012,15:09:00,8973,stereos.com,WRE13317323,subwoofer,85.99,
1,5.63
4

Product Success
SKU#,Product Name,Advertiser,Orders,Items,Items Canceled,Sales,Baseline
Commissions,Adjusted Commissions,Actual Commissions
BF0292B,Gel Seat,advanced bicycles,1,3,0,149.97,12.00,0.00,12.00

Program Level
Advertiser Name,Offer Name,Impressions,Clicks,CTR,Orders,Items,Items
Canceled,Orders/Click,EPC,Sales,Baseline Commissions,Adjusted Commissions,
Total Commissions
bidets.com,baseline - 6%,98,15,15.31,2,2,0,13,3.38,845.74,50.74,0.00,50.74

Non-Commissionable Sales
Process Date,Advertiser Name,Order ID,Product SKU,Product Name,Sales,
Reason
09/04/2012,FancyFixtures.com,172808,FLR-8119-232,"country kitchen",
175.00,return exceeded

Signature Activity
Member ID,Advertiser ID,Advertiser Name,Clicks,Sales,Commissions
1015c8972,87153,backpacks unlimited,15,49.99,3.25

Signature Orders
Member ID,Merchant ID,Merchant Name,Order ID,Transaction Date,Transaction Time,
SKU Number,Sales($),Quantity,Commissions($),Process Date,Process Time
331def,1234,AdvertiserName,2163,8/24/2011,8:58,PROD32,7.99,1,0.3995,8/26/2012,21:
05

Media Optimization
U1,Advertiser ID,Advertiser Name,Order ID,Transaction Date,Transaction
Time,SKU,Product Name,Sales,Quantity,Estimated Commissions
331def,1234,Advertiser Name.com,2163,04/02/2012,08:58,PROD32,"Flash
Drive",120.00,2,6.00

Requesting Payment Reports

The Payment History Summary, Advertiser Payments History, and Payment Details Report are
requested in a similar fashion to the reports above, using a GET request with appropriate API
Developer Portal authentication header.

Payment History Summary

To request the Payment History Summary, use this URL syntax:
https://api.rakutenmarketing.com/advancedreports/1.0?bdate=YYYYMMDD
&edate=YYYYMMDD&token=tokenid&nid=networkid&reportid=reportidnumber
You must supply all parameters, except for nid.

Parameter

Description

bdate

The start date for the report you would like to generate in YYYYMMDD
format.

edate

The end date for the report you would like to generate in YYYYMMDD
format.
Due to the sensitivity of available reporting data, this service requires the
Security Token as a parameter in addition to the access token found in the
authentication header. The Security Token can be found on the Publisher
Dashboard by going to Links > Web Services.

token
Please note: the Security Token differs from the access token found in the
header and the former Web Services Token, which the API Developer Portal
eliminates

nid

This parameter is optional. Use it to specify the network you want to run a
report for. If you don't include it, the report will be run for all networks. The
possible values are nid=1 for US; nid=3 for UK; nid=5 for Canada and
nid=41 for Australia.

reportid

This identifies the report you are requesting. Set to 1 to select the Payment
History Summary report.

Sample request:
https://api.rakutenmarketing.com/advancedreports/1.0?bdate=20120401
&edate=20120430&token=0f9fc835fb1b231e273d88f0c34gb70c5718f4e8717ff
1ggfb6196908edf0ee5&nid=1&reportid=1

Sample response:
Payment ID,Date,Payment Type,Check Number,Currency Code,Total Commission
Amount Paid,Payment Status
883463,4/19/2012,Direct Deposit,NA,USD,568.24,Issued

Advertiser Payments History

This report shows all the advertisers who paid you during a specific time period, the amount
they paid you, and other details.
To request it, use this URL syntax:
https://api.rakutenmarketing.com/advancedreports/1.0?token=tokenid&
reportid=reportidnumber&payid=paymentid

You must supply all parameters.

Parameter

token

Description
Due to the sensitivity of available reporting data, this service requires the
Security Token as a parameter in addition to the access token found in
the authentication header. The Security Token can be found on the
Publisher Dashboard by going to Links > Web Services.
Please note: the Security Token differs from the access token found in
the header and the former Web Services Token, which the API
Developer Portal eliminates

reportid
payid

This identifies the report you are requesting. Set to 2 to select the
Advertiser Payments History report.
This is the unique number that Rakuten Affiliate Network assigns to every
payment. It can be retrieved from the Payment History Summary.

Sample request:
https://api.rakutenmarketing.com/advancedreports/1.0?token=0f9fc835
fb1b231e273d88f0c34gb70c5718f4e8717ff1ggfb6196908edf0ee5&reportid=2
&payid=872590

Sample response:
Advertiser ID,Advertiser,Invoice Number,Transaction
Commissions,Bonus Amount, CPM & CPC Commissions,Cancelled
Commissions,Previously Held Commissions,Payment Amount,Advertiser
Payment Date
34290,Auto Parts Warehouse,1142851,90.39,0,0,0,0,90.39,4/25/2012

Payment Details Report

This report provides the advertiser name, product name, SKU, commission, and other
transaction level details for a particular invoice.
To request it, use this URL syntax:
https://api.rakutenmarketing.com/advancedreports/1.0?token=security
token&reportid=reportidnumber&invoiceid=invoiceid
You must supply the token, reportid and the invoiceid.

Parameter

token

Description
Due to the sensitivity of available reporting data, this service requires the
Security Token as a parameter in addition to the access token found in
the authentication header. The Security Token can be found on the
Publisher Dashboard by going to Links > Web Services.
Please note: the Security Token differs from the access token found in
the header and the former Web Services Token, which the API
Developer Portal eliminates

reportid

invoiceid

This identifies the report you are requesting. Set to 3 to select the
Payment Details report.
This is the unique number that Rakuten Affiliate Network assigns to every
invoice. It can be retrieved from the Advertiser Payments History. If you
include the invoiceid, the system will return payment details for all
transactions on the invoice you specify.

Sample request that includes the invoiceid:

https://api.rakutenmarketing.com/advancedreports/1.0?token=0f9fc835
fb1b231e273d88f0c34gb70c5718f4e8717ff1ggfb6196908edf0ee5&reportid=3
&invoiceid=1142851

Here's a sample output for a request that includes the invoiceid:

Date,Time,Advertiser ID,Advertiser,Order ID,SKU #,Product Name,Items,
Sales,Baseline Commission,Adjusted Commission,Actual
Commission,Reason,Advertiser Payment Memo,Advertiser Payment Date
2/2/2012,18:36:00,34573,Auto Parts Warehouse,8323087,WRE13317323,
Antenna,1,14.42,5.5179,0,4.5179,UNKNOWN,N/A, 4/25/2012

Appendix A: Output Column Definitions

Column

Definitions

Actual
Commissions

Baseline commissions plus or minus any adjustments.

Adjusted
Commissions

Any additions or deletions from the baseline commission that an

advertiser may have made because of Special Offers, cancellations,
returns, etc.

Advertiser ID

The numeric value that Rakuten Affiliate Network uses to identify a

particular advertiser. This value will remain the same over time.

Advertiser Name

An advertisers name as it appears to publishers within the Rakuten

Affiliate Network. The advertiser can alter this value without notice to
either Rakuten Affiliate Network or the publisher.

Average Order

The total sales divided by the number of orders.

Advertiser
Payment Date

The date that Rakuten Affiliate Network received the advertiser's payment.

Baseline
Commissions

The amount of commissions you earned from this advertiser or with this
link type before adjustments.

Canceled Items

The total number of items canceled in all orders for this advertiser.

Check Number

The number of the check Rakuten Affiliate Network issued you. Please
note: When the payment type is something other than a check, this
column typically repeats the Payment ID.

Clicks

The number of times visitors to your site have clicked on your advertiser's
link. On the Link Type Report, this is the total clicks a particular link type
received.

The dollar amount of the commission earned by the referring publisher. All
Commissions ($) commissions are pending credit card authorization and returned
merchandise.

CPM & CPC

Commissions

Amount paid for impressions or for driving traffic to a site rather than for
sales like Transaction Commissions.

10

Column

Definitions

CTR

The CTR is obtained by dividing the number of visitors who click an

advertiser's ad on your web page (click-throughs) by the number of times
the ad is displayed on your page (impressions). For instance, if a banner
ad is delivered 100 times on a site and one person clicks it, the CTR is 1
percent.

Currency Code

This column indicates the currency the payment was issued in USD, GBP,
CAD, or AUD.

Date
(Transaction
Date)

The date a transaction actually occurred. The format is MM/DD/YYYY.

Example: 08/05/2012

EPC

Earnings per click the number of clicks divided into actual commissions.
Expressed as a percentage.

Estimated
Commissions

The amount of the estimated pre-tiering, pre-adjustment commission you

earned. All commissions are pending credit card authorization and
returned merchandise.

Impressions

Invoice Number
Items

The number of times a web page that displays an advertiser's link has
been viewed. In the Link Type Report, this is the total impressions a
particular link type received.
A unique number that Rakuten Affiliate Network assigns to every invoice.
It is found on the Advertiser Payments History.
The total number of items purchased in all orders for this advertiser.

Member ID

Used in Signature Reports, this is a variable column defined by you. It can

contain up to 72 alphanumeric characters, with mixed-case letters.

Offer Name

The name of the offer that you are participating in this for this advertiser.

Orders

The number of orders placed by visitors that you referred to an advertiser.

On the Link Type Report, this is the number of orders that a particular link
type generated.

Order ID

The order number that is assigned by the advertiser. This represents one
shopping session.

Orders per Click

A rate that is calculated by dividing the number of orders into the number
of clicks. For example, if you receive 1,000 clicks and 10 orders, the
Orders/Click rate is 1 percent.

11

Column
Process Date

Payment
Amount

Payment ID

Definitions
The date that Rakuten Affiliate Network received and processed an
advertiser's transaction file. A transaction may contain transactions from
the day it was submitted or from two months earlier.
This column sums transaction commissions, bonus, CPM & CPC, and
previously held commissions and subtracts cancelled commissions.
A unique number that Rakuten Affiliate Network assigns to every
payment.

Payment Status

Indicates whether or not a payment has been issued.

Payment Type

How a payment is made (e.g. direct deposit or check).

Process Time

The time the transaction was processed through the Rakuten Affiliate
Network system.

Product Name

Name of product that was purchased from the advertiser.

Quantity

The number of each product a consumer purchased in his or her order.

Reason

Used in the Non-Commissionable Sales Report to indicate why a

transaction was not commissionable.

Sales

SKU Number

Time
Total
Commission
Amount Paid

The total amount of sales you generated for an advertiser or with a

particular link type.
The stock-keeping unit that is assigned by the advertiser. Each product in
an advertisers inventory has a unique SKU value.
The time in Greenwich Mean Time (GMT). (GMT is a 24-hour timekeeping standard based on the time of day in Greenwich, England; in
GMT, 2:30pm is 14:30.) The format is HH:MM. Example: 00:35
The total amount of a payment.

12

Column

Definitions

Transaction
Commissions

Commission amount paid for actual sales rather than for impressions or
for driving traffic to a site like CPM & CPC Commissions.

Transaction
Date

The date a transaction actually occurred. The format is MM/DD/YYYY.

Example: 08/05/2012

Transaction
Time

U1

The time a consumer completes their order. Displayed in Greenwich

Mean Time (GMT). (GMT is a 24-hour time-keeping standard based on
the time of day in Greenwich, England; in GMT, 2:30pm is 14:30.) The
format is HH:MM. Example: 00:35
This column consists of a variable field defined by the publisher. This can
contain up to 72 alphanumeric characters, with mixed-case letters. In
case of no matching u1 value, the response will contain the value
'UNKNOWN,' excluding quotes.

13