From Wiki

Contents 1 Introduction 1.1 Intended Audience 1.2 The MerchantService 1.3 Updates and versioning 1.4 Other services 2 API Overview 2.1 WSDL 2.2 User authentication 2.3 Quota 2.4 SOAP Request Format 2.5 SOAP Response Format 3 API Methods 3.1 Headers 3.2 Requests 4 Data Types 4.1 UserType 4.2 Transaction 4.3 TransactionStatus 4.4 TransactionType 4.5 TransactionPart 4.6 CommissionType 4.7 DateType 4.8 CommissionRange 4.9 PlatformPerformance 4.10 RowCounts

Introduction

Intended Audience

This document is intended for advertisers who want to have Affiliate Window account activity reports automatically created. This document and the system require the reader to be familiar with ‘web services’ and with the programming language that will be used when integrating the reports into your own system (e.g. php, asp etc.).

The MerchantService

The MerchantService provides the necessary functionality to retrieve all the information about an advertiser’s transactions and link performance statistics. The API is built on the core open source standards of SOAP and WSDL. To use the API to programmatically access an advertiser account you will need to build a web service client in your chosen language.

Updates and versioning

The current version of the MerchantService is version 3. As the service is updated, new versions will be deployed and old versions will stop being supported. They will however be left on our servers for a limited time to allow developers a smooth transition from one version to another.

Other services

• ProductServeService – provides access to Affiliate Window product data to allow development of products such as the ShopWindow Toolkit.
• AffiliateService – provides access to Affiliate Window publisher accounts – the type of information available includes, but not limited to, transactions, advertiser lists, transaction queries and link performance stats.

API Overview

WSDL

The current version of the MerchantService WSDL can be found at http://api.affiliatewindow.com/v3/MerchantService?wsdl

User authentication

User authentication is performed by SOAP-Headers, which must be passed with every single request.

Quota

Every user has an allocated operations quota. The remaining quota is returned as a SOAPHeader, in the response of every request.

The quota is specific to this service and has no relation to any quota you may have for any other Affiliate Window service.

SOAP Request Format

SOAP requests are "envelopes" of specially formatted XML data posted to a URL. You can find out more about SOAP at http://www.w3.org/TR/soap/.

Each request must contain the following 2 parts.

• Header
  • UserAuthentication - The header must contain element required to authenticate the user.
  • getQuota - The header can optionally contain a call to the method getQuota
• Body
  • getLinkPerformanceOverview - Gets platform performance stats
  • getTransaction - Gets the requested transactions
  • getTransactionList - Gets the requested transactions

Sample SOAP request

SOAP Response Format

In response to each request the MerchantService API will send back a SOAP response.

If getQuota was called in the request header, the remaining quota will be returned in the header of the request.

Sample SOAP response

API Methods

Headers

UserAuthentication

(SOAP-Header) The authentication element, has to be sent with every single request Parameters

iId	int	The user id
sPassword	string	The user password
sType	UserType	The user type

Response

None

getQuota

(SOAP-Header) Gets the remaining quota back int he response headers, with every single request

Parameters

None

bool

Indicate if the quota should be returned or not

Response

None

int

The number of remaining operations

Requests

getTransaction

Gets the requested transactions

Parameters

atransactionIds

int[]

the ids of the transactions to get

Response

getTransactionReturn

Transaction[]

Array of Transaction objects

getTransactionList

Gets the transactions that fall under the specified criteria

Parameters

aAffiliateIds	int[]	The publisher ids to limit the results to
dStartdate	dateTime	first date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to
sTransactionStatus	Transactionstatus	The transaction status

Response

getTransactionReturn

Transaction[]

Array of Transaction objects

getLinkPerformanceOverview

Get an overview of each linking platforms performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getLinkPerformanceReturn

PlatformPerformance[]

Result set

getSWClientPerformanceBreakdown

Get a breakdown of the ShopWindow client performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getSWClientPerformanceBreakdownReturn

SWClientPerformanceBreakdown[]

Result set

getProductPerformanceBreakdown

Get a breakdown of product performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getProductPerformanceBreakdownReturn

ProductPerformanceBreakdown[]

Result set

getWidgetPerformanceBreakdown

Get a breakdown of widget performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getWidgetPerformanceBreakdownReturn

WidgetPerformanceBreakdown[]

Result set

getBannerPerformanceBreakdown

Get a breakdown of banner performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getBannerPerformanceBreakdownReturn

BannerPerformanceBreakdown[]

Result set

getTextLinkPerformanceBreakdown

Get a breakdown of text link performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getTextLinkPerformanceBreakdownReturn

TextLinkPerformanceBreakdown[]

Result set

getAffiliatePerformanceReport

Get a breakdown of text link performance

Parameters

dStartDate	dateTime	First date of the list, inclusive
dEndDate	dateTime	Last date of the list, inclusive
sDateType	DateType	Which date the date limits will apply to

Response

getAffiliatePerformanceReportReturn

AffiliatePerformance[]

Result set

Data Types

UserType

The type of the user

Values

string

• affiliate
• merchant

Transaction

The Transaction object

Values

sId	int	The id
sStatus	TransactionStatus	The status
sType	Transactiontype	The transaaction type
bPaid	bool	Has commission been paid
iPaymentId	int	The payment id - only supplied when bPaid=1
sDeclinedReason	string	The reason why the transaction has been declined
iAffiliateId	int	The publisher 's id
fSaleAmount	float	The basket value
fCommissionAmount	float	The commission due
dClickDate	dateTime	The date of the click, which resulted in the transaction
dTransactionDate	dateTime[]	The date of the transaction
dValidationDate	dateTime	The date of validation
sClickref	string	A custom ref
sSearchSiteName	string	The search site's name
sSearchSiteKeyword	string	The phrase the user searched for, coming from a search site
aTransactionParts	TransactionPart[]	The transaction parts

TransactionStatus

The status of the transaction

Values

string

• pending - Not yet validated
• confirmed - Validated and confirmed
• declined - Validated and declined

TransactionType

The type of the transaction

Values

string

• normal
• bonus
• second tier
• untracked

TransactionPart

The parts of a transaction

Values

sCommissionGroupName	string	The name of the CG
fSaleAmount	float	The part's basket value
fCommissionAmount	float	The part's commission due
iCommission	int	The commission factor
sCommissionType	CommissionType	The type of the commission

CommissionType

The type of the commission

Values

string

• percentage - The commission factor will be used as a percentage
• amount - The commission factor will be used as a set amount

DateType

The type of date to apply the limits to

Values

string

• transaction - The transaction date
• validation - The validation date

CommissionRange

The range of commission potential across all CGs, for that advertiser and publisher

Values

sCommissionType	CommissionType	The type of the commission
fMin	float	The minimum commission available to that publisher
fMax	float	The maximum commission available to that publisher

PlatformPerformance

An overview of a single platforms performance

Values

sPlatform	string	The name of the platform
iImpressions	int	The number of impressions
iClicks	int	The number of clicks
fCtr	float	The click through rate
iTransactions	int	Number of transactions
fTransactionValue	float	Total sale value of transactions
fConversion	int	The conversion ratio
fEpc	float	Earnings per click

RowCounts

Counts on the returned information. This should be used to aid paginations.

iRowsReturned	int	The number of rows returned in the requestk
iRowsAvailable	int	The total number of results that are available without a limit clause - use the offset to retrieve different result parts.