Sie sind auf Seite 1von 11

Technical Guidelines

Using Web Services to Run Reports 2.3


You can now access most of your reports just like the Signature Orders Report and the
Payment Reportswithout logging into the Publisher Dashboard. You run these reports the
same way you run the others, using a direct URL call. This document provides the steps to run
these 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.
Each report can be run up to 300 times a day.
The URL syntax used for the three payment reports differs from the syntax used in the other
reports. For the steps to run the payment reports, please see the section Downloading Payment
Reports below.
If you are a Lead Advantage publisher and would like to use Web Services to run reports,
please see this article.

Downloading a Report
To download a report, place a Web Services call using REST. Here is the URL syntax:
https://reportws.linksynergy.com/downloadreport.php?bdate=YYYYMMDD&
edate=YYYYMMDD&token=securitytoken&nid=networkid&reportid=reportidn
umber&mid=advertiserid&lang=fr&locale=fr
You must supply a value for all of the fields, except for nid, mid, lang, and locale. Once
you have entered values into the required fields, put the URL into a browser to test it.

Field
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.
This is your Security token. It can be found on the Publisher Dashboard by
going to Links > Web Services.
token
Please note: the Security token differs from the Web Services token. See
the screen shot on the next page.
This field is optional. Use it to specify the Rakuten LinkShare 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=9 for Germany

Revision date: April 17, 2014

nid=3 for UK
nid=7 for France
nid=41 for Australia

Technical Guidelines
Using Web Services to Run Reports 2.3
Field

Description
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

This is the advertiser ID, a numeric value that Rakuten LinkShare uses to
identify an advertiser (merchant). It is an optional field. 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 field is optional. Use it to change the language of the column headers
in your report to French using lang=fr or German lang=de. English is
the default.
This field is optional. Enter either of these values to display amounts with
a comma: locale=fr or locale=de. 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

Your Security Token appears on


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

Sample URLs
The URL below will download a Sales &
Activity Report for all transactions that
occurred in April 2012 in the U.S. network
for all the advertisers in the publisher's
program.
Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3

https://reportws.linksynergy.com/downloadreport.php?bdate=20120401&
edate=20120430&token=0f9fc835fb1b231e273d88f0c34gb70c5718f4e8717ff1
ggfb6196908edf0ee5&nid=1&reportid=4
The URL below will download a Media Optimization Report for all transactions that occurred
during the first week of April 2012 in the U.S. network for advertiser ID 1234.
https://reportws.linksynergy.com/downloadreport.php?bdate=20120401&
edate=20120407&token=0f9fc835fb1b231e273d88f0c34gb70c5718f4e8717ff1
ggfb6196908edf0ee5&nid=1&reportid=14&mid=1234

Report Output
The output for all reports contains comma-separated fields 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 fields
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

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
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,Co
mmissions
8323087,09/08/2012,15:09:00,8973,stereos.com,WRE13317323,subwoofer,85.99,
1,5.63

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,2
1:05

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
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

Downloading Payment Reports


The Payment History Summary, Advertiser Payments History, and Payment Details Report are
run the same way as the reports above are, using a direct URL call.

Payment History Summary


To download the Payment History Summary, use this URL syntax:
https://reportws.linksynergy.com/downloadreport.php?bdate=YYYYMMDD&
edate=YYYYMMDD&token=tokenid&nid=networkid&reportid=reportidnumber
You must supply information for all of the fields, except for nid.

Field

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.

token

This is your Security token. It can be found on the Publisher Dashboard by


going to Links > Web Services.
Please note: the Security token differs from the Web Services token.

nid

reportid

This field is optional. Use it to specify the Rakuten LinkShare 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.
This identifies the report you are requesting. Payment History = 1

Here is a URL with sample values:


https://reportws.linksynergy.com/downloadreport.php?bdate=20120401&
edate=20120430&token=0f9fc835fb1b231e273d88f0c34gb70c5718f4e8717ff1
ggfb6196908edf0ee5&nid=1&reportid=1

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
Here is a 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 download it, use this URL syntax:
https://reportws.linksynergy.com/downloadreport.php?token=tokenid&
reportid=reportidnumber&payid=paymentid

You must supply data for all the fields.

Field
token

reportid
payid

Description
This is your Security token. It can be found on the Publisher Dashboard
by going to Links > Web Services.
Please note: the Security token differs from the Web Services token.
This identifies the report you are requesting. Advertiser Payments History
=2
This is the unique number that Rakuten LinkShare assigns to every
payment. It can be retrieved from the Payment History Summary.

Here is a URL with sample values:


https://reportws.linksynergy.com/downloadreport.php?token=0f9fc835f
b1b231e273d88f0c34gb70c5718f4e8717ff1ggfb6196908edf0ee5&reportid=2&
payid=872590
Here's a 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

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
Payment Details Report
This report provides the advertiser name, product name, SKU, commission, and other
transaction level details for a particular invoice.
To download it, use this URL syntax:
https://reportws.linksynergy.com/downloadreport.php?token=security
token&reportid=reportidnumber&invoiceid=invoiceid
You must supply data for token, reportid, and the invoiceid.

Field

Description

token

This is your Security token. It can be found on the Publisher Dashboard


by going to Links > Web Services.
Please note: the Security token differs from the Web Services token.

reportid

invoiceid

This identifies the report you are requesting. Payment Details = 3


This is the unique number that Rakuten LinkShare 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.

Here's a sample URL that includes the invoiceid:


https://reportws.linksynergy.com/downloadreport.php?token=0f9fc835f
b1b231e273d88f0c34gb70c5718f4e8717ff1ggfb6196908edf0ee5&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

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
Appendix A: Output Field Definitions
Field Name

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 LinkShare uses to identify a particular


advertiser. This value is a constant.

Advertiser Name

An advertisers name as it appears to publishers within the Rakuten


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

Average Order

The total sales divided by the number of orders.

Advertiser
Payment Date

The date that Rakuten LinkShare receives 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 LinkShare issues you. Please note:
When the payment type is something other than a check, this field
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.

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
Field Name

CTR

Definitions
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 field 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

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.

Invoice Number

A unique number that Rakuten LinkShare assigns to every invoice. It is


found on the Advertiser Payments History.

Items

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

Member ID

Used in Signature Reports, this is a variable field 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.

Process Date

The date that Rakuten LinkShare receives and processes an advertiser's


transaction file. A transaction may contain transactions from the day it was
submitted or from two months earlier.

Revision date: April 17, 2014

Technical Guidelines
Using Web Services to Run Reports 2.3
Field Name

Definitions

Payment
Amount

This field sums transaction commissions, bonus, CPM & CPC, and
previously held commissions and subtracts cancelled commissions.

Payment ID

A unique number that Rakuten LinkShare assigns to every payment.

Payment Status

Indicates whether or not a payment has been issued.

Payment Type

How a payment is made; eg, Direct Deposit, or Check.

Process Time

The time the transaction was processed through the Rakuten LinkShare
system.

Product Name

Name of product that was purchased from the advertiser.

Quantity

The number of each product a consumer buys 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

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

Total
Commission
Amount Paid

The total amount of a payment.

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

Revision date: April 17, 2014

10

Technical Guidelines
Using Web Services to Run Reports 2.3
Field Name
Transaction
Time

U1

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

Revision date: April 17, 2014

11