Conversions export file

Overview

In this article, we discuss how you can create an automated export for conversions based on an export file. There are four different types of files you can export:

  1. A comprehensive export file containing all data related to conversions.

  2. A limited export file containing only the conversion data relevant for the validation process. When you do not apply basket tracking, this file should be used for CAD-validation purposes.

  3. A touchpoint file containing detailed information for every touchpoint of the conversions.

  4. An export file containing all basket positions related to the conversions. When you apply basket tracking, this file should be used for CAD-validation purposes.

Please note that with regard to the possible use of Multi Touch Attribution the distinction between conversion and touchpoint becomes important. Conversions are the aggregated level of information for a conversion as a whole. Touchpoints, however, contain the information of every commercial touchpoint of a customer journey out of which a conversion is composed. The simplest example to this is two ad spaces which contributed to a sale and therefore are remunerated and appear as two touchpoints of this conversion.

To automate the validation process, you will have to compare the export file with the data warehouse of your advertiser and subsequently import the conversions or basket positions again. To find out how to take this last step, please read this article.

Creating export URLs

Export URL for conversions

The name of the export URL for conversions is adm-conversionexport. Please follow the instructions on creating an export URL in the article on automated exports. If you do so and you add some filters, your export URL for conversions will look more or less like this:

1 https://export.net.yourdomain.com/f0d58125-5489-4ac3-84b2-0417a3a85f65/adm-conversionexport.csv?filter[a:advertiser_program_id]=456&filter[from_date]=01.06.2019&filter[to_date]=27.06.2019

Export URL for touchpoints

The name of the export URL for touchpoints is adm-touchpointexport. Please follow the instructions on creating an export URL in the article on automated exports. If you do so and you add some filters, your export URL for conversions will look more or less like this:

1 https://export.net.yourdomain.com/f0d58125-5489-4ac3-84b2-0417a3a85f65/adm-touchpointexport.csv?filter[a:advertiser_program_id]=456&filter[from_date]=01.06.2019&filter[to_date]=27.06.2019

Export URL for basket positions

The name of the export URL for basket positions is adm-basketexport. Please follow the instructions on creating an export URL in the article on automated exports. If you do so and you add some filters, your export URL for basket positions will look more or less like this:

1 https://export.net.yourdomain.com/f0d188789-5420-4523-84b2-0417a3a85f58/adm-basketexport.csv?filter[advertiser_program_id]=456&filter[timerange_type]=absolute&filter[from_date]=01.06.2019&filter[to_date]=27.06.2019

Applying filters

For the conversion, touchpoint and the basket position export URL, the following filters can be applied:

Filter description

Filter name

Application

Value format

Filter description

Filter name

Application

Value format

This filter defines whether the time frame you select relates to the moment on which conversions were updated or tracked.

timetype

If the filter is not used, the time frame will relate to moment on which conversions were tracked.

Either use ‘tracking’ or ‘updated’.

This filter allows you to define whether the time frame for which you want a report on your conversions or basket positions is absolute (exact dates) or dynamic (for example: last ten days, last month, etc).

timerange_type

This filter is compulsory.

Either use ‘absolute’ or use ‘dynamic’.

If you are using a dynamic time frame, you need to specify it here.

timerange

This filter is compulsory when you use a dynamic time frame.

Please read this article for a full overview.

If you are using an absolute time frame, you need to define a date on which the range starts.

from_date

This filter is compulsory when you use an absolute time frame.

dd.mm.yyyy

If you are using an absolute time frame, you need to define a date on which the range ends.

to_date

This filter is compulsory when you use an absolute time frame.

dd.mm.yyyy

To limit the output to conversions or basket positions with a specific status, use this filter.

a:status

This filter should be applied when you are creating a report used for validation purposes.

0 for open, 1 for approved, 2 for rejected and 3 for confirmed. You can use multiple values.

This filter allows you to limit the conversions or basket positions you export to a specific currency.

currencycode

 

Use the ISO 4217 currency codes. Please note you cannot use only one currency code at a time.

This filter allows you to limit the conversions or basket positions you export by a specific advertiser program.

a:advertiser_program_id

This filter allows you to create export files per advertiser, which is highly recommended.

Use the MID you find on the overview page of all the advertisers on your platform.

This filter allows you to limit the conversions or basket positions you export by a specific partner.

a:affiliate

 

Use the UID you find on the overview page of the partners on your plaform.

This filter allows you to include the brand and the shopping categories the advertiser applied in the basket export.

fullBasket

This filter is only available for the basket export.

Use ‘true’ to include the additional data.

This filter allows you to include any sub IDs related to the conversion in your export file.

allsmcs

This filter is only available for the comprehensive conversion report.

Use ‘true’ if you want to export the sub IDs.

This filter allows you to include all additional parameters (customer age and gender, new customer, custom values, etc.) related to the conversion in your export file.

trackingParams

This filter is only available for the comprehensive conversion report.

Use ‘true’ if you want to export the additional parameters.

Output

Conversion export file

Header name

Explanation

Format

Delimeter

Example

Header name

Explanation

Format

Delimeter

Example

partner_id

The ID of the partner who generated the conversion.

Numeric

n/a

1234

partner_firstname

The first name of the partner who generated the conversion.

Alphabetic

n/a

Mary

partner_lastname

The last name of the partner who generated the conversion.

Alphabetic

n/a

Poppins

partner_company

The company name of the partner who generated the conversion.

Alphabetic

n/a

Walt Disney Productions

conversion_target_type

The type of the conversion target of the conversion.

Alphabetic

n/a

Sale

conversion_target_label

The label of the conversion target of the conversion.

Alphabetic

n/a

Sport sales

conversion_hidden_status

The visibility of the conversion target of the conversion for the partners. Possible values are false (visible) and true (hidden).

Alphabetic

n/a

fales

external_advertiser_id

An internal advertiser ID used for tracking purposes.

Alphanumeric

n/a

i12345678

internal_conversion_id

An internal advertiser ID used for rating purposes.

Numeric

n/a

123456789

conversion_product_category_id

The ID of the tracking category applied to the conversion.

Numeric

n/a

5678

adspace_id

The ID (PID) of the ad space via which the conversion was generated.

Numeric

n/a

142536

conversion_status

The status of the conversion. Possible values are 0 (open), 1 (approved), 2 (rejected) and 4 (confirmed).

Numeric

n/a

0

conversion_id

The ID of the conversion. Usually, this ID will correspond with the order ID generated by the advertiser, but in some cases it is replaced with an internal ID. If this is the case, the ID will contain the word 'auto'.

Alphanumeric

n/a

1608010800207180980_auto

conversion_commission_model

The name of the rating model applied to the conversion.

Alphanumeric

n/a

Premium commission

conversion_tracking_time

The time and date on which the conversion was originally tracked.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2016-08-20 15:00:00

click_id

The ID of the click via which the conversion was generated.

Numeric

n/a

987654321

click_time

The time and date on which the click was tracked via which the conversion was generated.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2016-08-20 15:00:00

click_referrer

The referrer, i.e. the URL of the website on which the click was generated.

URL

n/a

fashionblog.com

click_subid

The first sub ID of the click via which the conversion was generated. Please note you will only find a value here when a sub ID was attached to the click URL.

Alphanumeric

n/a

mp1234

conversion_commission_rate_id

An internal ID used to identify the way in which the conversion was rated.

Numeric

n/a

74859

conversion_commission_rate

The rate of the commission applied to the conversion.

Numeric

Period

2.5

conversion_commission_type

The type of the commission applied to the conversion. Possible values are fix and percent.

Alphabetic

n/a

percent

conversion_order_value

The order value of the conversion. Please note this amount does not include shipping costs and VAT.

Numeric: #.#

Period

142.45

conversion_order_value_rejected

The rejected amount of order value. Please note you will only see a value here in case of partial cancelations.

Numeric: #.#

Period

35.75

conversion_commission_total

The total commission value applied to the conversion.

Numeric: #.#

Period

3.56

click_admedia_id

The ID of the ad media item used for the click via which the conversion was generated.

Numeric

n/a

98745

conversion_last_modified_time

The time and date on which the conversion was last modified, i.e. edited or validated.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2016-08-20 15:00:00

conversion_currency_code

The ISO 4217 currency code in which the values of the conversion were defined.

Alphabetic

n/a

EUR

conversion_reason_canceled

The reason the conversion was rejected during the validation process. Please note this field is not mandatory and will be empty in most cases.

Alphabetic

n/a

Order was canceled.

conversion_uniqid

The unique ID is used to identify conversions during the validation process.

Alphanumeric

n/a

1650cd4d-9d57-34b4-80b4-34579d4dcd50

internal_tracking_id

An internal ID of the conversion, used for tracking purposes.

Numeric

n/a

1608010800207180000

internal_accounting_id

An internal ID of the conversion, used for rating purposes.

Numeric

n/a

160801080300000000

conversion_fee_total

The total amount of fee applied to the conversion. Please note you will only see a value here when you charge your advertisers.

Numeric: #.#

Period

45.65

conversion_num_products

The total numer of products ordered for this conversion

Numerical

n/a

5

maturity_date

The time and date on which the conversion will be approved automatically. Please note that if you do not see a value here, the conversion will never be approved automatically.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2016-08-20 15:00:00

conversion_type

The type of conversion. Possible values are postclick and postview.

Alphabetic

n/a

postclick

conversion_product_category_label

The name of the tracking category applied to the conversion.

Alphabetic

n/a

default

advertiser_label

The name of the advertiser for which the conversion was generated.

Alphanumeric

n/a

Fashion shop

advertiser_id

The ID of the advertiser (MID) used on the platform

Numeric

n/a

7485

partner_adspace_label

The name of the ad space via which the conversion was generated.

Alphanumeric

n/a

Fashion blog

adspace_subcategory_label

The name of the subcategory of the ad space via which the conversion was generated.

Alphanumeric

n/a

Fashion blogs

adspace_subcategory_type

The type of the subcategory of the ad space via which the conversion was generated.

Alphanumeric

n/a

Consumer guides and bloggers

adspace_category_label

The name of the category of the ad space via which the conversion was generated.

Alphanumeric

n/a

Fashion content

adspace_category_type

The type of the category of the ad space via which the conversion was generated.

Alphanumeric

n/a

Content

voucher_code

The code of the voucher applied to the conversion. You will only see a value here when the customer placing the order used a voucher.

Alphanumeric

n/a

SV258569

voucher_code_id

The ID of the voucher applied to the conversion. You will only see a value here when the customer placing the order used a voucher registered on the platform.

Numeric

n/a

1234

voucher_currencycode

The ISO 4217 currency code of the voucher applied to the conversion. You will only see a value here when the customer placing the order used a voucher.

Alphabetic

n/a

EUR

device_type

The type of device the customer used to place the order related to the conversion.

Alphabetic

n/a

Desktop

conversion_checksum

An internal code used to identify the conversion.

Alphanumeric

n/a

27a2dccfb0362a10c0c82904c8dfd52d

click_subid_2

The second sub ID of the click via which the conversion was generated. Please note you will only find a value here when a second sub ID was attached to the click URL and you have used the 'allsmcs' filter.

Alphanumeric

n/a

dc5678

click_subid_3

The third sub ID of the click via which the conversion was generated. Please note you will only find a value here when a third sub ID was attached to the click URL and you have used the 'allsmcs' filter.

Alphanumeric

n/a

ef9012

click_subid_4

The fourth sub ID of the click via which the conversion was generated. Please note you will only find a value here when a fourth sub ID was attached to the click URL and you have used the 'allsmcs' filter.

Alphanumeric

n/a

gh3456

click_subid_5

The fifth sub ID of the click via which the conversion was generated. Please note you will only find a value here when a fifth sub ID was attached to the click URL and you have used the 'allsmcs' filter.

Alphanumeric

n/a

ij7890

click_subid_6

The sixth sub ID of the click via which the conversion was generated. Please note you will only find a value here when a sixth sub ID was attached to the click URL and you have used the 'allsmcs' filter.

Alphanumeric

n/a

kl1234

conversion_target_alias

The value transmitted to identify the conversion target of the conversion and you have used the 'allsmcs' filter.

Alphanumeric

n/a

sale

conversion_tracking_category_alias

The value transmitted to identify the tracking category of the conversion and you have used the 'allsmcs' filter.

Alphanumeric

n/a

default

invoice_value

The total value of the order, including shipping costs and VAT. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Numeric: #.#

Period

144.56

customer_new

Whether the customer was new to the advertiser. Possible values are true (new) and false (recurring). Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphabetic

n/a

True

customer_gender

The gender of the customer who placed the order. Possible values are f (female) and m (male). Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphabetic

n/a

f

customer_age

The age of customer who placed the order. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Numeric

n/a

45

customer_survey

Questions and answers to surveys held upon placing the order. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphanumeric: {"#":"#"}. Please note JSON format is higly recommended.

Bracket, double quotation marks and colon.

{"Your favorite movie":"Moonraker","Your favorite actor":"Sean Connery"}

user_value_1

Contains the values of the first custom tracking parameter. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphanumeric

n/a

ab12345

user_value_2

Contains the values of the second custom tracking parameter. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphanumeric

n/a

cd67891

user_value_3

Contains the values of the third custom tracking parameter. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphanumeric

n/a

ef23456

user_value_4

Contains the values of the fourth custom tracking parameter. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphanumeric

n/a

gh78901

additional_data

Contains the values of the additional data tracking parameter, mostly used for CRM related information. Please note you will only see a value here when the corresponding tracking parameter was implemented and you have used the 'trackingParams' filter.

Alphanumeric: {"#":"#"}. Please note JSON format is highly recommended.

Bracket, double quotation marks and colon.

{"number_prev_cancellations":"12","recommended_by":"user_id: 15"}

payment_method

The payment methode the customer chose when placing an order, for example 'creditcard' or 'paypal'.

Alphanumeric

n/a

paypal

 

 

Touchpoint export file

Header name

Explanation

Format

Delimeter

Example

Header name

Explanation

Format

Delimeter

Example

conversion_tracking_time

The time and date on which the transaction was originally tracked.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2019-04-20 15:00:00

conversion_id

The ID of the transaction. Usually, this ID will correspond with the order ID generated by the advertiser, but in some cases it is replaced with an internal ID. If this is the case, the ID will contain the word 'auto'.

Alphanumeric

n/a

1608010800207180980_auto

conversion_target_id

The ID of the conversion target of the transaction.

Numeric

n/a

174

conversion_category_id

The ID of the category of the transaction.

Numeric

n/a

19

advertiser_id

The ID of the advertiser for which the transaction was generated, corresponding with the MID in the UI.

Numeric

n/a

1234

advertiser_name

The name of the advertiser for which the transaction was generated.

Alphanumeric

n/a

Shopping.com

conversion_status

The status of the conversion. Possible values are 0 (open), 1 (approved), 2 (rejected) and 3 (confirmed).

Numeric

n/a

0

partner_id

The ID of the partner who generated the touchpoint.

Numeric

n/a

1234

partner_first_name

The first name of the partner who generated the touchpoint.

Alphanumeric

n/a

Mary

partner_last_name

The last name of the partner who generated the touchpoint.

Alphanumeric

n/a

Poppins

partner_company_name

The company name of the partner who generated the touchpoint.

Alphanumeric

n/a

Walt Disney Productions

adspace_id

The ID (PID) of the ad space via which the touchpoint was generated.

Numeric

n/a

142536

adspace_name

The name of the ad space via which the touchpoint was generated.

Alphanumeric

n/a

Special Offers

adspace_category_name

The name of the category of the ad space via which the touchpoint was generated.

Alphanumeric

n/a

Content Publisher

adspace_subcategory_name

The name of the sub category of the ad space via which the touchpoint was generated.

Alphanumeric

n/a

Blogger

touchpoint_position

The chronological position of the touchpoint in the customer journey that led to the transaction.

Numeric

n/a

2

touchpoint_credit

The share/contribution that was attributed to this touchpoint for generating the transaction. All touchpoint credits of a transaction add up to 100.

Numeric

Period

20.00

touchpoint_type

The type of the touchpoint (click or view).

Alphanumeric

n/a

Click

touchpoint_time

The time and date on which the touchpoint was tracked.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2019-04-20 14:00:00

touchpoint_commission_model

The commission model of the ad space that is used for (proportionate) remuneration. If Multi Touch Attribution is used it is recommended to give all ad spaces the same commission model in order to enable a clear attribution of commission.

Alphanumeric

n/a

10 percent + 2 EUR fix

touchpoint_revenue

The share of the tracked revenue that was allocated to the touchpoint. All touchpoint revenues add up to the total revenue sum of the transaction.

Numeric

Period

6.30

touchpoint_commission

The share of the transaction commission that was allocated to the touchpoint. All touchpoint commissions add up to the total commission sum of the transaction.

Numeric

Period

0.70

conversion_currency_code

The ISO 4217 currency code in which the values of the transaction were defined.

Alphanumeric

n/a

EUR

touchpoint_revenue_'ISO3'

The share of the tracked revenue that was allocated to the touchpoint in display currency of the user creating the export. All touchpoint revenues add up to the total revenue sum of the transaction.

Numeric

Period

8.00

touchpoint_commission_'ISO3'

The share of the transaction commission that was allocated to the touchpoint in display currency of the user creating the export. All touchpoint commissions add up to the total commission sum of the transaction.

Numeric

Period

0.90

admedia_id

The ID of the ad media item used for which the touchpoint was generated.

Numeric

n/a

56789

admedia_name

The name of the ad media item used for which the touchpoint was generated.

Alphanumeric

n/a

Banner summer special 2019

device_type

The type of device the customer used during touchpoint.

Alphanumeric

n/a

Desktop

original_adspace_id

The ID of the ad space for which the touchpoint was originally generated. Might differ from adspace_id in case of e.g. a voucher rule that changed the attribution of the touchpoint retroactively.

Numeric

n/a

45780

smc_1

The additional parameter of the touchpoint that was set by the partner.

Alphanumeric

n/a

Free text field

smc_2

The additional parameter of the touchpoint that was set by the partner.

Alphanumeric

n/a

Free text field

smc_3

The additional parameter of the touchpoint that was set by the partner.

Alphanumeric

n/a

Free text field

smc_4

The additional parameter of the touchpoint that was set by the partner.

Alphanumeric

n/a

Free text field

smc_5

The additional parameter of the touchpoint that was set by the partner.

Alphanumeric

n/a

Free text field

smc_6

The additional parameter of the touchpoint that was set by the partner.

Alphanumeric

n/a

Free text field

request_id

unique identifier of the touchpoint

Numeric

n/a

2001201520357490208

Basket position export file

Header name

Explanation

Format

Delimiter

Example

Header name

Explanation

Format

Delimiter

Example

internal_conversion_ID

An identifying the transaction to which the basket position belongs.

Numeric

n/a

4376671

order_ID

The ID of the order to which the basket position belongs.

Numeric

n/a

ORD123456

conversion_target_ID

TheID of the conversion target of the transaction to which the basket position belongs.

Numeric

n/a

174

conversion_target_name

The name of the transaction target related to the basket position.

Alphanumeric

n/a

Purchase

product_basket_index

The rank of the basket position within the basket.

Numeric

n/a

1

product_number

The name of the product as it was transmitted from the advertiser’s shopping system. In case a discount position is added to the basket, you will find it named 'discount calculation' here. These positions are only added when the discount rating was activated in the commission model that was applied. For more information, please read this paragraph.

Alphanumeric

n/a

Socks, pullover, mobile phone, discount calculation.

product_ID

The ID of the product coming from the advertiser’s shopping system.

Numeric

n/a

6543

product_currency_code

The ISO 4217 currency code in which the values of the transaction were defined.

###

n/a

EUR

product_category_ID

The ID of the product category of the basket position.

Numeric

n/a

386

product_category_name

The name of the product category of the basket position.

Alphanumeric

n/a

default

product_price

The price of the product in the basket position.

Numeric: #.#

Period

30.00

product_quantity

The total number of products ordered for the basket position.

Numeric

n/a

5

product_total_price

The product price multiplied by the number of products ordered for the basket position.

Numeric

Period

150.00

product_commission_fix

The fix value used for the commission calculation.

Numeric: #.#

Period

3.00

product_commission_percent

The percentage value used for the commission calculation.

Numeric: #.#

Period

5.00

product_commission_total

The total amount of commission attributed to the basket position.

Numeric: #.#

Period

22.50

product_fee_fix

If the advertiser is billed by the network owner, this field will contain the fix value used for the calculation of the fee.

Numeric: #.#

Period

.00

product_fee_percent

If the advertiser is billed by the network owner, this field will contain percentage value used for the calculation of the fee.

Numeric: #.#

Period

3.00

product_fee_total

If the advertiser is billed by the network owner, this field will contain the fee the advertiser will have to pay for this transaction.

Numeric: #.#

Period

3.00

product_uniqid

The unique ID of the transaction to which the basket position is related. This ID is used during the validation process.

Alphanumeric and printable special characters

n/a

14x66c23-084f-3784-8084-c74f08536ce6

product:_checksum

An internal validation code.

Alphanumeric and printable special characters

n/a

097df04754f3524930b1f62e8296c845

position_status

The status of the basket position: 0 means the position is open, 1 means the position has been confirmed, 2 means the position has been rejected. For more information, please read this article.

Numeric

n/a

2

advertiser_id

The ID of the advertiser for which the basket position was generated.

Numeric

n/a

123

advertiser_title

The name of the advertiser for which the basket position was generated.

Alphanumeric and printable special characters

n/a

Fashion Shop

conversion_tracking_time

The time and date on which the basket position was tracked.

yyyy-mm-dd hh:mm:ss

Hyphen and colon

2016-04-28 22:00:08

brand

The brand of the product in the basket position.

Alphanumeric and pritable special characters

n/a

Nike

advertiser_product_category

The category the advertiser applied for the product on the website.

Alphanumeric and pritable special characters

n/a

Sport shoes