Advertiser Service API

From Wiki

Revision as of 13:11, 29 May 2012 by Jimmy Dixon (Talk | contribs)
Jump to: navigation, search

Contents

Introduction

Intended Audience

This document is intended for merchants 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 affiliate accounts – the type of information available includes, but not limited to, transactions, merchant 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

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns1="http://api.affiliatewindow.com/">

<SOAP-ENV:Header>
<ns1:UserAuthentication>

SOAP-ENV:mustUnderstand="1"
SOAP-ENV:actor="http://api.affiliatewindow.com">
<ns1:iId>*****</ns1:iId>
<ns1:sPassword>*****</ns1:sPassword>
<ns1:sType>merchant</ ns1:sType>

</ns1:UserAuthentication>

<ns1:getQuota SOAP-ENV:mustUnderstand="1" SOAP-ENV:actor="http://api.affiliatewindow.com">true</ns1:getQuota>
</SOAP-ENV:Header>

<SOAP-ENV:Body>
<ns1:getTransactionList>
<ns1:dStartDate>2006-08-04T00:00:00</ns1:dStartDate>
<ns1:dEndDate>2006-08-14T23:59:59</ns1:dEndDate>
<ns1:sDateType>transaction</ns1:sDateType>
</ns1:getTransactionList>
</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

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

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope>
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://api.affiliatewindow.com/">

<SOAP-ENV:Header>
<ns1:getQuotaResponse>14951</ns1:getQuotaResponse>
</SOAP-ENV:Header>

<SOAP-ENV:Body>
<ns1:getTransactionListResponse>
<ns1:getTransactionListReturn>
<ns1:Transaction>
<ns1:iId>7302200</ns1:iId>
<ns1:sStatus>declined</ns1:sStatus>
<ns1:sDeclinedReason>Duplicate</ns1:sDeclinedReason>
<ns1:iAffiliateId>1286</ns1:iAffiliateId>
<ns1:fSaleAmount>22.6</ns1:fSaleAmount>
<ns1:fCommissionAmount>4.52</ns1:fCommissionAmount>
<ns1:dClickDate>2006-08-06 16:36:21</ns1:dClickDate>
<ns1:dTransactionDate>2006-08-07 22:31:48</ns1:dTransactionDate>
<ns1:dValidationDate>2006-08-08 17:21:13</ns1:dValidationDate>
<ns1:aTransactionParts>
<ns1:TransactionPart>
<ns1:sCommissionGroupName>Default Commission</ns1:sCommissionGroupName>
<ns1:fSaleAmount>22.6</ns1:fSaleAmount>
<ns1:fCommissionAmount>4.52</ns1:fCommissionAmount>
<ns1:iCommission>10</ns1:iCommission>
<ns1:sCommissionType>percentage</ns1:sCommissionType>
</ns1:TransactionPart>
</ns1:aTransactionParts>
</ns1:Transaction>
</ns1:getTransactionListReturn>
</ns1:getTransactionListResponse>
</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

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

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 affiliate'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 merchant and affiliate

Values

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

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.

Privacy

Due to new European legislation regarding how websites store information about you, AWIN is updating its privacy policy. You can see the new version of our policy here. If you would like to see the information we capture on this website, please click here for further details. In order to accept cookies on this site please click the 'I ACCEPT' button