Documentation on Basket Tracking

(1)

(2)

Documentation on

Basket Tracking

Introduction _______________________________________________________________ 1 1. Tracking Code __________________________________________________________ 1 2. Argument definition ______________________________________________________ 2 2.1 ref ________________________________________________________________________ 2 2.2 affmt _____________________________________________________________________ 3 2.3 affmn _____________________________________________________________________ 3 2.4 site _______________________________________________________________________ 3 2.5 curr _______________________________________________________________________ 3 2.6 order ______________________________________________________________________ 3 2.7 vcode _____________________________________________________________________ 3 2.8 odate _____________________________________________________________________ 3 2.9 ordertime __________________________________________________________________ 4 2.10 psub1 / psub2 ____________________________________________________________ 4 2.11 basket __________________________________________________________________ 4 2.11.1 articlenb ______________________________________________________________ 4 2.11.2 productname ___________________________________________________________ 4 2.11.3 category _______________________________________________________________ 4 2.11.4 quantity _______________________________________________________________ 4 2.11.5 singleprice _____________________________________________________________ 4 2.11.6 brand _________________________________________________________________ 5 2.11.7 property1-5 ____________________________________________________________ 5 2.11.8 mode _________________________________________________________________ 5 2.11.9 leadtype _______________________________________________________________ 5

3. Order management interface ______________________________________________ 5 3.1 Order list___________________________________________________________________ 5 3.2 Order export / import _________________________________________________________ 6 3.3 Confirm or cancel baskets _____________________________________________________ 8

3.3.1 Column definition _________________________________________________________ 8 TransactionId ___________________________________________________________________ 8 ProgramId ______________________________________________________________________ 8 PublisherId _____________________________________________________________________ 8 Status _________________________________________________________________________ 8 OrderId ________________________________________________________________________ 8 RateMode ______________________________________________________________________ 8 RateNumber ____________________________________________________________________ 8 NetPrice _______________________________________________________________________ 9

(3)

CancellationReason ______________________________________________________________ 9 BasketId _______________________________________________________________________ 9 3.3.2 Examples ________________________________________________________________ 9

3.4 Create new baskets __________________________________________________________ 9

3.4.1 Column definition _________________________________________________________ 9 ProgramId ______________________________________________________________________ 9 PublisherId _____________________________________________________________________ 9 Status _________________________________________________________________________ 9 OrderId _______________________________________________________________________ 10 pSub1 / pSub2__________________________________________________________________ 10 VoucherCode __________________________________________________________________ 10 ArticleNumber _________________________________________________________________ 10 SinglePrice ____________________________________________________________________ 10 Currency (not supported in the 1st release) __________________________________________ 10 Quantity ______________________________________________________________________ 10 ProductName __________________________________________________________________ 10 Category ______________________________________________________________________ 10 Brand ________________________________________________________________________ 11 Property1-5 ____________________________________________________________________ 11 ItemRateMode _________________________________________________________________ 11 ItemRateNumber _______________________________________________________________ 11 3.4.2 Examples _______________________________________________________________ 11

3.5 Update or add basket items in existing baskets ___________________________________ 11 3.5.1 Column definition ________________________________________________________ 11 ProgramId _____________________________________________________________________ 11 PublisherId ____________________________________________________________________ 11 OrderId _______________________________________________________________________ 11 BasketId ______________________________________________________________________ 12 ArticleNumber _________________________________________________________________ 12 SinglePrice ____________________________________________________________________ 12 Quantity ______________________________________________________________________ 12 ProductName __________________________________________________________________ 12 Category ______________________________________________________________________ 12 Brand ________________________________________________________________________ 12 Property1-5 ____________________________________________________________________ 12 RateMode _____________________________________________________________________ 13 RateNumber ___________________________________________________________________ 13 Position _______________________________________________________________________ 13 ItemRateMode _________________________________________________________________ 13 ItemRateNumber _______________________________________________________________ 13 BasketItemCancellationReason ____________________________________________________ 13 3.5.2 Examples _______________________________________________________________ 14 3.6 Import history______________________________________________________________ 14 4. Rate Mapping __________________________________________________________ 14 5. Order web services _____________________________________________________ 15 6. FAQ __________________________________________________________________ 15

(4)

7. Best Practices _________________________________________________________ 16 8. Glossary ______________________________________________________________ 18

(5)

Introduction

The affilinet basket tracking system allows you to submit shopping basket information on item level to affilinet. That information enables you to perform detailed statistical analyses and allows your publishers to optimise their marketing activities even further. If you would like to make use of this tracking functionality, please call your account manager to activate basket tracking and change the registersale call on your order confirmation page according to this documentation.

In the affilinet basket tracking system, we destinguish between baskets and basket items. Baskets can be confirmed and cancelled like regular transactions, but before you do this, you can update the contained basket items: you can update the quantity of single items or remove single items from the basket (e.g. if the article was returned by the customer); the publisher’s commission is automatically updated.

We offer several means to submit and manage baskets and basket items, all of which are described in this documentation.

1. Tracking Code

As soon as your program has been activated for basket tracking, you can send us registersale calls with the new parameter "basket" and of course you can continue to send us the unchanged

registersale calls which you are sending today. Everything you send us with this "basket" parameter will be treated as a shopping basket in our system. Everything you send us with registersale calls without the basket parameter will be treated as stand-alone transactions.

If you would like to use registersale.aspx to submit baskets to us, please note that it must be called within a <form> element, as opposed of embedding it in an <img> notation which you are probably using today. The main reason for this is the fact that <img>-elements cannot exceed a certain length, which depends on your web server configuration and - what’s worse - on the browser which your customer is using. <form> calls on the other hand (if submitted using POST instead of GET) can grow to practically any size without the risk of losing data. In order to rule out any influence on the design of your web page, we recommend to place the form element in a separate HTML file and include that in an iframe on your order confirmation page, somewhere outside of the visible range of the page.

Here is an example for such a registersale call using the <form> syntax. In this example, a basket with 3 different articles is being submitted (article numbers ABCD_000055, ABCD_000047 and ABCD_000039). The form is automatically submitted with a little JavaScript call, but it could just aswell be sent using cURL or other methods:

(6)

gory=Women%20%3E%20Coats%20%26%20Jackets%20%3E%20Coats&Quantity=1&SinglePrice =60.99&Brand=Aber%2C%20Cromby%20%26%20Fich&Property1=White&Property2=New&Prop erty3=Wool&Property4=Made%20in%20UK&Property5= ArticleNb=ABCD_000047&ProductName=Windbreaker%20%22Petersburg%22%2C%20Dark%20 gray&Category=Women%20%3E%20Coats%20%26%20Jackets%20%3E%20Jackets&Quantity=1& SinglePrice=126.99&Brand=Connvers&Property1=Dark%20gray&Property2=New&Propert y3=PVC&Property4=&Property5= ArticleNb=ABCD_000039&ProductName=T-bar%20flat%20heel%20%22Salt%20Lake%20City%22%2C%20Green&Category=Women%20%3E% 20Shoes%20%26%20Boots%20%3E%20Sandals&Quantity=3&SinglePrice=29.99&Brand=Jame s%20Sheepskin&Property1=Olive&Property2=New&Property3=&Property4=Made%20in%20 USA </textarea> </form> <script type="text/javascript"> document.affilinetTrackingForm.submit(); </script> </body> </html>

If a program has been activated for basket tracking, it can use that basket functionality. But it can still stick to the regular syntax, which of course generates orders with no basket information. <img src="http://[*affilinet tracking

domain]/registersale.asp?site=12345&mode=ppl&ltype=1&order=OrderId234567" width="1" height="1" />

Note:

Please replace [*affilinet tracking domain]with the domain of the affilinet country you are working

with: DE partners.webmasterplan.com UK being.successfultogether.co.uk FR clic.reussissonsensemble.fr ES web.epartner.es NL zijn.samenresultaat.nl

2. Argument definition

Please note: all parameter values must be URL-encoded. So instead of “a b” please submit

“a%20b”, instead of “+” please submit “%2B” etc.

2.1 ref

This is the referrer argument. Typically, this is the Id of the referring publisher, but it can additionally contain the publisher sub-Id, a string which the publisher can use to transfer additional information for his own purposes (e.g. the customer account number of a bonus network, the website on which the creative was located, etc.). If present, then the publisher’s sub-Id is appended to the publisher’s Id, with “-” as a separation character. This argument is normally filled through the cookie, which the customer has on his machine. Optional.

(7)

Please note: you can only use this parameter if affilinet has activated it for you. Please contact you

account manager for details.

2.2 affmt

The “affilinet media type” - in short: the type of creative, which was clicked on. Can represent textlink, HTML or banner. This argument is normally filled through the cookie, which the customer has on his machine. Optional.

2.3 affmn

The “affilinet media number” - the number of the banner, textlink or HTML creative, which was clicked on. Together with the affilinet media type, this uniquely identifies the creative which lead to the transaction. This argument is normally filled through the cookie, which the customer has on his machine. Optional.

2.4 site

This argument must be filled with your program Id. Must be an integer > 0. Mandatory.

2.5 curr

The currency which shall be applied to the monetary values you submit in the call. At the time of the registersale call, we convert this value into EUR or GBP, depending on your program’s currency. Values have to follow the ISO standard 4217 and can have 3-character-abbreviations like “CHF”, “GBP”, “USD”, “EUR”, etc., case insensitive. If a submitted value cannot get recognized, we reject

the whole basket. We support all reference currencies of the European Central Bank. Optional.

2.6 order

In this argument, you have to specify an identifier for the order. Within your program, this Order-Id must be unique, could be e.g. the invoice number. Can be an alphanumeric string with up to 40 characters, case insensitive. Special characters like é, è, í, %, §, etc. are not supported. Mandatory.

2.7 vcode

In this parameter, you can submit to us the voucher code string, which your customer has entered. You can later extract this information from our system for your inspection or analysis. Publishers only get to see whether or not a voucher was used in the transaction, they don’t see the voucher code string itself. Can be an alphanumeric string with up to 25 characters, case insensitive. Special characters like é, è, í, %, §, etc. are not supported. Optional.

(8)

The creation date of the order. By default, we assume the date of the registersale call, but if necessary, you can send us an earlier date in this parameter, which we will then use instead. If specified, it must be in the format YYYY-MM-DD. Can be up to 60 days in the past. Optional.

2.9 ordertime

The creation time of the order. By default, we assume the time of the registersale call, but if necessary, you can send us some other time in this parameter, which we will then use instead. If you specify ordertime, you also have to specify odate. The combination of odate and ordertime must result in a timestamp which lies in the past. If specified, it must be in the format hh:mm:ss. Optional.

2.10 psub1 / psub2

With these parameters, you can submit to us additional order information for your own purposes (e.g. the payment method, the customer’s time spent on the site, a representation of his click sequence, etc.). Can be an alphanumeric string with up to 30 characters, case insensitive. Special characters like é, è, í, %, §, etc. are not supported. Optional.

2.11 basket

This is the parameter, through which you can send us the shopping basket information. You can submit us any amount of products. Between the products, you have to place a newline character, which we use to separate the single products after the call was made. Optional. If specified, then the value of this parameter must/can contain these parameters:

2.11.1 articlenb

The SKU which the bought product has within your system. Can be an alphanumerical string of up to 80 characters. Exceeding characters will be cut off. Mandatory.

Please note: ArticleNumber doesn’t have to be unique within a basket - you can submit to us

baskets, which contain the same ArticleNumber more than once - e.g. if the same pair of shoes have been bought in different sizes.

2.11.2 productname

The name of the product, e.g. “Apple iPod Nano 8 GB”. Can be an alphanumerical string of up to 255 characters. Exceeding characters will be cut off. Mandatory.

2.11.3 category

The category, in which you keep the bought article, including category path, if available. E.g. “Electronics > Portable devices > Mp3 players”. Can be an alphanumerical string of up to 255 characters. Exceeding characters will be cut off. Mandatory.

2.11.4 quantity

The amount of items with this ArticelNb, which have been bought. If e.g. somebody bought the same article in the same order process 5 times, then this parameter must be set to 5. Can be any integer > 0. Mandatory.

(9)

The individual price of this article. We assume that this single price multiplied with the quantity results in the NetPrice, based on which we calculate the publisher commission. Mandatory. The single price cannot be changed in the order management for any given order.

2.11.6 brand

The make of the bought article. E.g. “Apple” or “Nike”. Mandatory, but can be the empty string.

2.11.7 property1-5

Each of these 5 separate parameters can be used to submit additional information at your own wish. This information is also displayed to the publisher. Typical use cases is product data, which only applies to a certain subset of products - e.g. in the case of clothing, you could submit the size, colour, material, etc. of the product. Each property can contain up to 255 characters. Optional.

2.11.8 mode

The commission model you wish this article to be remunerated with. Can be “pps” (for sale mode) or “ppl” (for lead mode). Optional. If absent, the RateMapping settings are applied. If this is specified, ltype must be specified, too.

2.11.9 leadtype

The Id of the commission rate you wish this article to be remunerated with. Must be an integer > 0 and refer to an existing rate within this program. If absent, the RateMapping settings are applied. If this is specified, mode must be specified, too. Optional.

3. Order management interface

3.1 Order list

On the advertiser platform, you find the submitted baskets in the order management interface (“Orders” > “Order List”), along with transactions without basket information (e.g. newsletter subscriptions).

Baskets have a control, which allows you to open the basket to see the items within (1). Clicking on it a second time closes the basket again. The figures next to the control tell you, how many different items are contained in the basket (2) and how many of them currently entitle the publisher to receive commission (3) (the other items could have been cancelled because the customer sent them back, they were not in stock or s.th. similar).

Transactions with no basket information don’t have the basket control, but instead display the unique TransactionId, which identifies this transaction within our platform (4).

(10)

confirmed or cancelled). While a basket is in status “open”, you can manage the basket items contained within: you can change the quantity of the single items and if you want to remove the item from the basket, select a specific reason why this was necessary in the “Action” column (6).

Please note: we differentiate between 2 basic operations:

• updating basket items and

• updating shopping baskets / transactions.

Updating the basket items affects the content of the basket and its total worth (which normally influences the height of the publisher commission) - but it does not affect the status of the order as a whole: it remains open.

Setting a whole basket to “confirmed” or “cancelled” is a separate action.

Only when the basket is explicitly set to “confirmed” (no matter whether manually in the order management page, via list import, via web service or through automatic order management), the commission is assigned to the publisher’s account.

Please note: If you give a cancellation reason to a basket item, this item status is changed to

“cancelled”. You cannot change the status, quantity or any other parameter after that.

Please note: Basket items cannot individually be set to “confirmed”. Only the basket, to which they

belong, can be set to “confirmed”. However, basket items can be flagged as “cancelled” with the effect that they don’t contribute any more to the commission paid for the basket. They remain cancelled, even if the basket is set to “confirmed”.

3.2 Order export / import

In order to facilitate the order management, we offer an export/import system, so the advertisers’ own backend can take over the update, confirmation and cancellation of orders. Whenever you define a filter for orders, you can export the resulting list of orders. Please note that we make a difference between baskets and the basket items contained within:

Baskets represent complete shopping processes. Each basket stands for a single shopping

session, regardless on how many items were bought in this process. Baskets can get confirmed or cancelled as a whole. All items which are contained in the basket and which are not cancelled for some reason are used to calculate the publisher and network commission for the basket. As long as a basket is in status “open” (that is: it is neither cancelled nor confirmed), the content of this basket can be changed:

• Single items can be added to the basket.

• Single items can get cancelled with a certain reason. • The quantities of single items can be changed.

These two independent operations - managing baskets and managing basket items - make different sets of information necessary, which means: different file formats - which are explained further down in this chapter.

Clicking on “Download list” triggers the export. You are asked which type of export you wish to generate: the one for basket items or the one for baskets - or both at the same time. Choose the file type you desire and click “Start export”. Depending on the amount of baskets and basket items involved, the preparation of the export might take a while. You can see the process and the resulting export file in “Account > Download center”.

Both file types can be exported in CSV or in XLS format. In the case of CSV, you can adjust the format definition which serves best for your further process. Both file formats will contain a certain set of columns, which we will need for a later import. On top of those mandatory columns, you can optionally add further columns, if they help you processing the baskets and basket items.

(11)

Transactions or baskets:

BasketItems

Exported and edited or completely newly generated CSV or XLS files can be imported into our system under “Orders > Import”.

Before uploading a file, you have to choose what kind of import you wish to perform: • Confirm or cancel complete orders

• Create new baskets

• Update or add basket items in existing baskets

Depending on your selection, different sets of columns are required.

Please note: import files can contain any amount of columns which are not defined below. Only

columns with the column headers defined below will be considered during the import, all others will be ignored.

Please note: the columns can be sorted in any order, but the column headers have to be unique. Please note: Uploading, importing and validating the files can take a while, depending on their size

and other processes running in parallel. Once an import has been completed, you see a summary on its outcome below in the import history.

(12)

3.3 Confirm or cancel baskets

With this type of file, you can set baskets or transactions to the status “confirmed” or “cancelled”. When you confirm an order, the commission involved is added to the publisher’s account. If you set an order to status “cancelled”, the commission is not added to the publisher’s account and you have to specify a reason, why the order was cancelled.

Please note: if you wish to add transactions (as opposed of baskets) to our system, please use this

file format.

3.3.1 Column definition TransactionId

If you wish to confirm or cancel a transaction, you can specify its TransactionId here. If you don’t have the TransactionId, then the fields PublisherId, OrderId, RateMode and RateNumber must be filled. If you wish to confirm or cancel a basket and not a transaction, please omit this column or leave it empty, but instead specify either the BasketId or the OrderId.

ProgramId

Your affiliate program’s Id. Mandatory.

PublisherId

The Id of the publisher which shall be remunerated. Mandatory if a new transaction shall be generated or

BasketId or TransactionId is not specified and OrderId is not unique.

Status

The status which the order shall have. Can be “Open”, “Confirmed” or “Cancelled”. Mandatory.

OrderId

The identifier, which this order has within your program. Must be unique among all orders of this ProgramId. Mandatory if neither TransactionId nor BasketId is filled.

RateMode

If you wish to generate a new transaction (as opposed of basket), you can specify the desired remuneration mode here. Can be “Sale” or “Lead”. Mandatory if a new transaction shall be generated.

RateNumber

If you wish to generate a new transaction (as opposed of basket), you can specify the number of the desired remuneration mode here. Must be a positive integer. Mandatory if a new transaction shall be generated.

(13)

NetPrice

If you wish to generate a new transaction of the type “Sale” or to adjust the NetPrice of an existing “Sale” transaction, you have to specify here the turnover value, based on which the publisher commission shall be calculated. Mandatory if a new transaction (not basket!) with RateMode “Sale” shall be generated. This field is ignored, if it would change the NetPrice of an existing basket.

CancellationReason

If the status of an order shall be set to “Cancelled”, then you have to specify here a reason which explains to the publisher, why he does not get a commission for this order. Can be any

alphanumerical string with 5 to 100 characters. Mandatory if “Status” is set to “Cancelled” or if NetPrice has changed.

BasketId

If you wish to confirm or cancel a basket, you can either specify its OrderId (the unique identifier within your own system) or its BasketId (the unique identifier within the affilinet system).

3.3.2 Examples

A sample file containing all optional columns can be found here: CSV versionXLS version

A sample file with just the absolute minimum columns can be found here: CSV versionXLS version

3.4 Create new baskets

New baskets can be added to the affilinet system in 3 ways: either by sending a registersale call, through our web services or by importing a CSV or XLS list. This chapter describes the latter

method. New baskets are getting created simply by uploading a set of basket items with an OrderId, which doesn’t exist in the given program yet.

Please note: For reasons of performance, all basket items with the same OrderId have to appear

next to another, which e.g. can be achieved by sorting the CSV/XLS list by OrderId.

3.4.1 Column definition ProgramId

PublisherId

The Id of the publisher which shall be remunerated. Can be suffixed with the publisher’s sub-Id. If present, then the publisher’s sub-Id has to be appended to the publisher’s Id, with “-” as a separation character. Mandatory.

Status

The status which the order shall have. Can be “Open”, “Confirmed” or “Cancelled”. Optional. If not specified, “Open” is assumed.

(14)

OrderId

The identifier, which this order has within your program. Must be unique among all orders of this ProgramId. Mandatory.

pSub1 / pSub2

With these columns, you can submit to us additional order information for your own purposes (e.g. the payment method, the customer’s time spent on the site, a representation of his click sequence, etc. - whatever helps you later analysing the orders generated through affilinet). Can be an

alphanumeric string with up to 30 characters, case insensitive. Special characters like é, è, í, %, §, etc. are not supported. Optional.

VoucherCode

In this column, you can submit to us the voucher code string, which your customer has entered. You can later extract this information from our system for your inspection or analysis. Publishers only get to see whether or not a voucher was used in the transaction, they don’t see the voucher code string itself. Can be an alphanumeric string with up to 25 characters, case insensitive. Special characters like é, è, í, %, §, etc. are not supported. Optional.

ArticleNumber

The SKU which the bought product has within your system. Can be an alphanumerical string of up to 80 characters. Exceeding characters will be cut off. Mandatory.

SinglePrice

The individual price of this article. We assume that this single price multiplied with the quantity results in the NetPrice, based on which we calculate the publisher commission. Mandatory.

Currency (not supported in the 1st release)

The 3-letter abbreviation of the currency, which shall be used to interpret the price information of this new item. Optional.

Quantity

The amount of items with this ArticelNb, which have been bought. If e.g. somebody bought the same article in the same order process 5 times, then this parameter must be set to 5. Can by any integer > 0. Mandatory.

ProductName

The name of the product, e.g. “Apple iPod Nano 8 GB”. Can be any alphanumerical string of up to 255 characters. Exceeding characters will be cut off. Mandatory.

Category

The category, in which you keep the bought article, including category path, if available. E.g. “Electronics > Portable devices > Mp3 players”. Can be an alphanumerical string of up to 255 characters. Exceeding characters will be cut off. Mandatory, but can be the empty string.

(15)

Brand

The make of the bought article. E.g. “Apple” or “Nike”. Mandatory, but can be the empty string.

Property1-5

Each of these 5 separate parameters can be used to submit additional information at your own wish. This information is also displayed to the publisher. Typical use cases is product data, which only applies to a certain subset of products - e.g. in the case of clothing, you could submit here the size, colour, material, etc. of the sold product. Optional.

ItemRateMode

The commission model you wish this article to be remunerated with. Can be “Sale” or “Lead”. If

absent, then the Rate-Mapping settings are applied. If RateMode is specified, RateNumber must be

specified, too. Optional.

ItemRateNumber

The rate Id of the commission model you wish this article to be remunerated with. Can be an integer > 0 and must refer to an existing rate of this ProgramId. If absent, then the Rate-Mapping settings are applied. If RateNumber is specified, RateMode must be specified, too. Optional.

3.4.2 Examples

3.5 Update or add basket items in existing baskets

If you wish to e.g. cancel a basket item for a certain reason, or if you want to update its quantity, or if you wish to add an item to an already existing basket, this is the option you should choose.

3.5.1 Column definition ProgramId

PublisherId

The Id of the publisher which shall be remunerated. Mandatory if OrderId is not unique or if BasketId is not specified.

OrderId

The identifier, which this order has within your program. Must be unique among all orders of this ProgramId. Mandatory if BasketId is not specified.

(16)

BasketId

If you wish to identify a basket, you can either specify its OrderId (the unique identifier within your own system) or its BasketId (the unique identifier within the affilinet system). Mandatory if OrderId is not specified.

ArticleNumber

The SKU which the bought product, which shall be added to an existing basket, has within your system. Can be an alphanumerical string of up to 80 characters. Exceeding characters will be cut off. Mandatory.

SinglePrice

The individual price of this article. We assume that this single price multiplied with the quantity results in the NetPrice, based on which we calculate the publisher commission. In the case of updating a basket item within an existing basket, this field is ignored, while in the case of adding a basket item to an existing basket, this field is mandatory.

Quantity

The amount of items with this ArticelNb, which have been bought. If e.g. somebody bought the same article in the same order process 5 times, then this parameter must be set to 5. Can by any integer > 0. In the case of updating a basket item within an existing basket, this field is optional - if it is not specified, the quantity is not changed. In the case of adding a basket item to an existing basket, this field is mandatory.

ProductName

The name of the product, e.g. “Apple iPod Nano 8 GB”. Can be an alphanumerical string of up to 255 characters. Exceeding characters will be cut off. In the case of updating a basket item within an existing basket, this field is ignored, while in the case of adding a basket item to an existing basket, this field is mandatory.

Category

The category, in which you keep the bought article, including category path, if available. E.g. “Electronics > Portable devices > Mp3 players”. Can be an alphanumerical string of up to 255 characters. Exceeding characters will be cut off. In the case of updating a basket item within an existing basket, this field is ignored, while in the case of adding a basket item to an existing basket, this field is mandatory.

Brand

The make of the bought article. E.g. “Apple” or “Nike”. In the case of updating a basket item within an existing basket, this field is ignored, while in the case of adding a basket item to an existing basket, this field is mandatory, but can be the empty string.

Property1-5

Each of these 5 separate parameters can be used to submit additional information at your own wish. This information is also displayed to the publisher. Typical use cases is product data, which only

(17)

applies to a certain subset of products - e.g. in the case of clothing, you could submit here the size, colour, material, etc. of the sold product. Optional.

RateMode

The commission model you wish this article to be remunerated with. Can be “Sale” or “Lead”. Is only considered in cases when new articles are added to an existing basket. Optional. If absent, then the Rate-Mapping settings are applied. If RateMode is specified, RateNumber must be specified, too.

RateNumber

The rate Id of the commission model you wish this article to be remunerated with. Can be an integer > 0 and must refer to an existing rate of this ProgramId. Is only considered in cases when new articles are added to an existing basket. Optional. If absent, then the Rate-Mapping settings are applied. If RateNumber is specified, RateMode must be specified, too.

Position

The position of the basket item within the basket. If e.g. 2 separate basket items within the same basket have the same ArticleNumber (e.g. the same pair of shoes, but in different sizes), Position can be used to exactly specify, which of the articles shall be edited. Optional. If not specified, then in this example the first of the 2 BasketItems gets changed, the other remains unchanged.

ItemRateMode

Only considered if a new item is added to a basket, otherwise this column is ignored. The

commission model you wish this article to be remunerated with. Can be “Sale” or “Lead”. If absent,

then the Rate-Mapping settings are applied. If RateMode is specified, RateNumber must be

specified, too. Optional.

ItemRateNumber

Only considered if a new item is added to a basket, otherwise this column is ignored. The rate Id of the commission model you wish this article to be remunerated with. Can be an integer > 0 and must refer to an existing rate of this ProgramId. If absent, then the Rate-Mapping settings are applied. If RateNumber is specified, RateMode must be specified, too. Optional.

BasketItemCancellationReason

If for some reason you wish to cancel one basket item, then please specify a reason for doing so. All basket items which have the BasketItemCancellationReason “NotCancelled” are used to calculate the commission for the basket. Possible other values are:

• FailedCreditCheck (e.g. if a mobile phone contract was sold but the customer’s rating was not sufficient)

• SaleCanceledByCustomer (if the customer cancelled the order before it was sent out) • ItemReturned (if he sends back a single item of the order)

• ItemOutOfStock (if the advertiser was unable to deliver the item) • DuplicatedOrder (e.g. if some error occurred in a manual import)

• BreachOfCampaignTermsAndConditions (if the publisher didn’t comply with the advertiser’s rules)

(18)

3.5.2 Examples

3.6 Import history

Once an import has taken place, its results can be found beneath the import control. It displays a short summary, which tells you if the operation was successful or what errors or notices occurred during the import.

For each upload in the history, you can download either • the originally uploaded file or

• an export file with orders or basket items, which caused warnings or • an export file with orders or basket items, which caused errors.

This way you can separately download the orders or items, which were not processed successfully, in order to correct them and import them anew.

Please note: elements of the import, which could not get executed (e.g. because an mandatory field

was missing), are called errors, whereas elements, which got written successfully to our DB but were somewhat noteworthy (e.g. if unchanged records are imported), are called warnings.

Please note: imports are available in the history for your inspection for a total duration of 30 days

and then get removed from our system.

4. Rate Mapping

When basket tracking has been activated for a program, rate mapping rules can be created for this program: instead of specifying the appropriate rate for each and every basket item over and over again, one can map a product category or article number to a certain rate.

Rate mappings can not only be created based on category information, but also based on article number. If you wish to remunerate a certain product with a certain rate, regardless within which category this product currently is, then you can define the rate mapping based on the article number. This has priority over category mapping.

(19)

Whenever this program submits to us a basket with article number ABCD_000039, then this article (not the entire basket) gets commissioned with sale rate #3 (whose rate name is in this example “Low Commission”). The whole ArticleNumber must match, partial matches or wildcards are not supported.

In this example, all products within “Women” shall be remunerated with sale rate #1, except for the category “Women > Coats & Jackets”, to which sale rate #2 shall be applied instead.

Whenever the category mapping gets checked, we proceed “longest match first”: An article in category “Women > Coats & Jackets > Coats > Trenchcoats” would get remunerated with sale rate #3, because the best matching category mapping is the one for category “Women > Coats & Jackets > Coats”. Articles coming with category “Men > Shoes” would get mapped to sale rate #2, because the best matching category mapping is the one for category “Men”.

As soon as a program gets activated for basket tracking, we need a default rate mapping, which is applied whenever we don’t have any more detailed directive which rate to remunerate. In this example, the default mapping is set to sale rate #1.

Whenever a new basket item gets submitted to our system, the following hierarchy of checks is being used:

• if the parameters “mode” and “ltype” are specified explicitly, then this rate gets applied. • Otherwise, if a rate mapping exists for this ArticleNumber, then this rate gets applied.

• Otherwise, if a rate mapping exists for this Category (or any of its parent categories), then this rate gets applied.

• Otherwise, the default rate mapping is used.

Please note: the matching of the submitted category or ArticleNumber categories to the rate

mappings is case insensitive. Also make sure that when submitting baskets via registersale calls, the URL-decoded product category looks excactly like the categories of the rate mapping.

5. Order web services

Through the affilinet order web services you can continuously update orders or basket items fully automatedly. They cover the whole life cycle of orders: creation of new orders, updates of basket items and confirmation / cancellation of orders. This enables e.g. online shop software like Magento, xt:Commerce, Demandware etc... to automatically update the orders in our platform in real time. Our order web services are part of our advertiser web services. The latest version of their documentation can be found in the developer portal in the “HELP” section.

6. FAQ

Question Answer

When my program has been activated for basket tracking, do I have to change my

implementation?

The registersale call can stay the way it is now. Activating your program for basket tracking means that you CAN send us baskets from then on, but you don't have to. However, your order export will get several additional columns. Refer to the chapter “Order export / import” for details.

(20)

If in my shopping process a voucher has been used, which reduced the whole shopping basket value (e.g. by 5 EUR), how do I transmit this information to affilinet?

The fact that a voucher has been used, can be submitted with the vcode parameter in the tracking pixel.

However, we do not change the price (and therefore the commission) on our side. If e.g. 3 products were bought, all with different commissions, the advertiser has to decide for himself, which SinglePrice to reduce due to the used voucher - we cannot take this

decision for him, because it affects the publisher’s commission.

How do lead rates work in affilinet basket tracking?

You can use lead rates for basket items, if you want. The commission of each lead rate is added to the publisher commission only once - no matter how many basket items it is applied to.

Example: a basket contains 3 basket items. 1 (worth 10 EUR) gets commissioned with sale rate #2 (which is 5%), the other 2 get commissioned with lead rate #1 (which is 5 EUR). Then the publisher commission consists of 0,50 EUR for the sale rate and 5 EUR for the lead items - totalling to 5,50 EUR and not to 10,50 EUR.

Background: several online retailers grant a certain lead commission for each shopping process - no matter how many articles have been bought or how expensive they were.

7. Best Practices

A convenient way to use integrate the form in an iframe, but to avoid physically creating a .html file for that, is the integration via JavaScript. Here is an adapted version of the example in the section „Tracking-Code“:

<html>

style="position:absolute;left:-10000px;width:0px;height:0px;border:0px;display:none"></iframe> 1

Please replace [*affilinet tracking domain]

with the domain of the affilinet country you are working with: DE partners.webmasterplan.com

UK being.successfultogether.co.uk FR clic.reussissonsensemble.fr ES web.epartner.es

(21)

<form name="affilinetTrackingForm" target="affilinetIFrame" 2 method="post" action="https:// [*affilinet tracking

domain]/registersale.aspx" id="affilinetTrackingForm">

<input type="hidden" id="site" name="site" value="1234"/> <input type="hidden" id="order" name="order"

value="OrderId12345_54321"/>

<textarea type="hidden" id="basket" name="basket" style="display:none;"> ArticleNb=ABCD_000055&ProductName=Classic%20wool%20coat%20%22Brasilia%22&Cate gory=Women%20%3E%20Coats%20%26%20Jackets%20%3E%20Coats&Quantity=1&SinglePrice =60.99&Brand=Aber%2C%20Cromby%20%26%20Fich&Property1=White&Property2=New&Prop erty3=Wool&Property4=Made%20in%20UK&Property5= ArticleNb=ABCD_000047&ProductName=Windbreaker%20%22Petersburg%22%2C%20Dark%20 gray&Category=Women%20%3E%20Coats%20%26%20Jackets%20%3E%20Jackets&Quantity=1& SinglePrice=126.99&Brand=Connvers&Property1=Dark%20gray&Property2=New&Propert y3=PVC&Property4=&Property5= ArticleNb=ABCD_000039&ProductName=T-bar%20flat%20heel%20%22Salt%20Lake%20City%22%2C%20Green&Category=Women%20%3E% 20Shoes%20%26%20Boots%20%3E%20Sandals&Quantity=3&SinglePrice=29.99&Brand=Jame s%20Sheepskin&Property1=Olive&Property2=New&Property3=&Property4=Made%20in%20 USA </textarea> </form> <script type="text/javascript"> window.onload = function() { document.getElementById("affilinetTrackingForm").submit(); 3 } </script> </body> </html>

Please note: in HTML 4.01 Strict / XHTML 1.0 Strict, the use of the „target“ attribute within form

elemets has been marked as „deprecated“, therefore in documents of this type it is not entirely sure (but still very likely), that it is interpreted by all browsers.

1

Invisible iFrame, initially with no content.

2

Form element with target=affilinetIFrame; the result of sending off this form is displayed in the iframe and not in the page, which contains the form.

3

(22)

8. Glossary

Term Definition

Article → BasketItem

ArticleNumber Unique Id of a product within an advertiser’s system.

ArticleNumber-Rate-Mapping The assignment of an article number to the rate, which shall

be applied to that sale. Details can be found in the chapter Rate Mapping.

Basket Structured list of products (→ BasketItems), which have been

bought by the customer. Each Basket has a unique →

BasketId within our system.

BasketId Our internal Id, which a basket receives directly after it has

been registered, either through a registersale call, in a list import or via web service call.

BasketItem One article within the → basket. Normally, this refers to a

single product (or multiple instances of the same product, →

Quantity).

CancellationReason Whenever advertisers cancel baskets, transactions or single

basket items, they have to specify a reason, which then is displayed to the publisher. For baskets and transactions, they can enter just any text as long as it contains 5 to 25

characters, whereas for basket items, they have to choose one out of a set of pre-defined standardised cancellation reasons.

Category In the context of basket tracking, this is the category, in which

an advertiser keeps this product.

Category-Rate-Mapping The assignment of the category of an article to the rate,

which shall be applied to that sale. Details can be found in the chapter Rate Mapping.

Lead The commission type, through which the publisher gets an

absolute amount of money as opposed of a relative share of the sale (which would be a → Sale). Please note our

behaviour regarding lead commission in our basket tracking.

Order A representation of a sales process. Orders are either →

Baskets (if basket information is present) or they are →

Transactions (if no basket information is present).

Order Import The functionality, through which the advertiser can upload flat

files (CSV or XLS) in order to update existing or add new (→) baskets, (→) transactions or (→) basket items.

(23)

Order Export The functionality, through which the advertiser obtains a set of Transactions and Baskets or BasketItems as a flat file: either as CSV, XLS(X) or XML.

OrderId This is the identifier, which the advertiser submitted initially

for a transaction or basket. It should refer to the internal identifier of the shopping process within the advertiser’s system.

OrderList The page „Orders > Edit Orders“ in the advertiser portal

Property1-5 Optional parameters, which can hold details about the bought

products: size, colour, capacity, material, ...

Quantity The amount of bought products with the same ArticleNumber

in the same order. If e.g. an advertiser’s shop system has an ArticleNumber X for a pair of shoes, no matter what size they are in, and somebody buys 2 pairs of these shoes (in

different sizes), then Quantity ought to be 2.

Rate-Mapping The assignment of rates based on article number or category.

For details see the Rate Mapping chapter.

Sale The commission type, through which the publisher gets a %

share of the sale (as opposed of a → Lead).

ShoppingBasket → Basket

Transaction A transaction is the combination of ProgramId, OrderId,

RateMode and RateNumber. Orders are either transactions or baskets.

TransactionId The internal Id (integer) through which a (→) transaction can

(24)

History:

Date Kind of Change Detail of Change Author Comment

14.10.2013 Change Page 13 St Replaced

„SaleCancelledByCustomer” with “SaleCanceledByCustomer”

Documentation on Basket Tracking