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

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

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_target_id

The id of the conversion target of the conversion.

Alphabetic

n/a

4711

conversion_target_name

The ma,e of the conversion target of the conversion.

Alphabetic

n/a

Sport sales

conversion_category_id

The ID of the tracking category applied to the conversion.

Numeric

n/a

5678

conversion_category_name

The name of the tracking category applied to the conversion.

Alphabetic

n/a

default

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

revenue

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

Numeric: #.#

Period

142.45

revenue_ejected

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

Numeric: #.#

Period

35.75

total_commission

The total commission value applied to the conversion.

Numeric: #.#

Period

3.56

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

discount_value

The discount applied to revenue. This will also affect the calculation of commission and fee

Numeric: #.#

Period

42.43

conversion_update_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

total_fee

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

advertiser_name

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

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

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

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

time_zone

Indicates the time zone for all date time values

Alphanumeric

n/a

Europe/Berlin

 

 

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

conversion_uniqid

unique identifier of the conversion

Alphanumeric (UUID)

n/a

ce7bcd17-1b7a-442d-96d4-bf0f88a4798e

time_zone

Indicates the time zone for all date time values

Alphanumeric

n/a

Europe/Berlin

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