Overview
This article explains you how can fully automate your validation process using so called CAD (conversion additional data) requests. Via the CAD request, you communicate from your data warehouse to the platform whether an order has been canceled or confirmed and whether there were any changes to the order value.
There are two options to automate your validation using CAD requests. What option you can use, depends on whether you can generate unique IDs on the confirmation pages of your advertiser’s website.
Two automated validation options
The first automated validation option is relevant when you do not generate unique IDs on the confirmation page of advertiser’s website. In this case, you automatically export conversions or basket positions from the platform. How you do this, is described in this article. The data you export needs to be compared with the information in your data warehouse. Subsequently, you adjust the status of the conversions and basket positions on the platform using the CAD requests. In case of partial cancellations, you will also adjust the order value or, when you are working with basket positions, the value of the basket position.The second option is relevant when you and your advertiser are capable of generating unique IDs on the confirmation page of the advertiser’s website. In this case, you simply send out a CAD request whenever you have relevant information about conversions or basket positions available in your data warehouse. The conversion and the basket position will be identified using the unique ID transmitted when they were original
...
Creating CAD requests
Getting started
Domain
A CAD request has the following basic structure:
| Code Block |
|---|
https://[tracking_domain]/ts/[external_advertiser_ID]/tsa?typ=d |
As you have probably noticed, you cannot use the export domain of your platform for your CAD request. Instead, you need to use the tracking domain. If you are using several tracking domains on your platform, make sure you use the tracking domain of the advertiser you are validating conversions or basket positions for.
Security
Please note that while both secured and unsecured protocols are allowed, but using a secured protocol (https) is higly recommended. Apart from that, make sure that the CAD requests are send via a server, not via a browser.
Format
The conversions and basket positions are identified by adding data parameters to the CAD request. These data parameters are discussed in more detail below. Please make sure you separate all data parameters with an ampersand.
Data parameters for conversions
If you want to create a CAD request for your conversions, you need to add the following parameters to the request:
Show 102550100 entries
Search:
...
...
Parameter name
...
Explanation
...
Mandatory
...
Corresponding field in export file
...
Example
...
tst
...
The UNIX timestamp of your request, will be filled out automatically.
...
No
...
n/a
...
1429018671
...
trc
...
The tracking category of the conversion. The tracking category can be changed, please note that in this case update notification (3rd party tracking) may be affected.
...
Yes
...
conversion_product_category_label
...
basket
...
ctg
...
The conversion target of the conversion.
...
Yes
...
conversion_target_label
...
sale
...
cid
...
The order ID of the conversion.
...
Yes
...
conversion_id
...
1234567asd
...
cfs
...
The status of the conversion. Possible values are either:
cnf (confirmed), rjt (rejected) and opn (open).
...
Yes
...
conversion_status
...
cnf
...
cfd
...
The time and date on which the conversion was validated. Please note that the format from the export file (yyyy-mm-dd hh:mm:ss) must be URL encoded.
...
No
...
2015-04-14 15:37:51
...
2015-04-14%2015%3A37%3A51
...
ovn
...
The new order value of the conversion. Please use this parameter only when you want to adjust the order value.
...
No
...
conversion_order_value
...
25.45
...
ctp
...
The type of commission that should be attributed to the ad space, according to the commission model applied to the transaction. Possible values are fix or percent. Please use this parameter only when you want to adjust the commission.
...
No
...
conversion_commission_type
...
percent
...
crt
...
The new commission rate of the conversion. Please use this parameter only when you want to adjust the commission.
...
No
...
conversion_commission_rate
...
2.5
...
unqid
...
A unique ID identifying the conversion, used for security purposes.
...
Yes
...
conversion_uniqid
...
14e31669-6940-2204-8004-8340696916e3
...
cre
...
You can use this parameter to explain the reason why a conversion was canceled.
...
No
...
conversion_reason_canceled
...
Order%20was%20canceled.
...
mkey
...
The magic key identifies the user processing the automated validation, making the process transparent and secure.
...
Yes
...
n/a
...
0b539c09-e0de-42c6-9b9c-f4a42d92d389
Showing 1 to 12 of 12 entries
PreviousNext
For more information about the magic key, please read this article.
Example CAD request for conversions
If you implement the data parameters (including the non-mandatory ones), the CAD requests for conversions will look more or less like this:
| Code Block |
|---|
https://marketing.net.yourdomain.com/ts/i1234567/tsa?typ=d&tst=1429018671&trc=basket&ctg=sale&cid=1234567asd&cfs=cnf&cfd=2015-04-14%2015%3A37%3A51&ovn=20.00&ctp=percent&crt=5.00&unqid=4e31885-6940-2204-8784-8340696916e3&cre=Order%20was%20canceled&mkey=0b539c09-e0de-42c6-9b9c-f4a42d92d389 |
Note for developers: There will be no response to your request.
Validation of basket positions: The basics
A conversion that contains basket information contains two levels:
the conversion level (it contains the order ID, conversion target, tracking category “basket”, the status (open, approved, rejected, confirmed) and others)
the positions of the basket (they contain product id, product name, product price, quantity, a tracking category and a status (open, approved, rejected, confirmed)
Please note, that the order value of the conversion is calculated from the prices and quantities of the basket positions. This means, the Order Value that is transmitted on the conversion level with the parameter “orv” will be ignored.
When confirming baskets, the following logic applies:
validation of the basket positions
as soon as all basket positions are validated, the conversion status will automatically change: To approved, as long as at least one position is approved, to rejected in case all positions are rejected.
Data parameters for basket positions
Show 102550100 entries
Search:
...
Parameter name
...
Description
...
Mandatory
...
Corresponding field in export file
...
Example
...
tst
...
The UNIX timestamp of your request. Please note the value will be filled out automatically.
...
No
...
n/a
...
trc
...
The tracking category of the transaction to which the basket position belongs. Please note the tracking category must always be basket.
...
Yes
...
conversion_product_category_label
...
basket
...
ctg
...
The conversion target of the transaction to which the basket position belongs.
...
Yes
...
conversion_target_label
...
newSale
...
cid
...
The order ID of the transaction to which the basket position belongs.
...
Yes
...
conversion_id
...
1234567asd
...
unqid
...
A unique ID identifying the transaction, used for security purposes.
...
Yes
...
conversion_uniqid
...
14e31669-6940-2204-8004-8340696916e3
...
mkey
...
The magic key identifies the user processing the automated validation, making the process transparent and secure.
...
Yes
...
n/a
...
0b539c09-e0de-42c6-9b9c-f4a42d92d389
...
bsknew
...
This parameter contains all details of the basket position in JSON format (URL encoded), including the basket status that needs to be adjusted for the validation process.
...
Yes
...
n/a
...
%5B%7B%22price%22%3A%22182%22%2C%22quantity%22%3A%220%22%2C%22commissionFix%22%3A%220%22%2C%22commissionPercent%22%3A%2211%22%2C%22categoryId%22%3A%223682%22%2C%22productId%22%3A%22MA339HL84SEDLMX-893765%22%2C%22productNumber%22%3A%22Green%20Hoover%20vacuum%20cleaner%22%2C%22positionId%22%3A%221%22%2C%22status%22%3A%221%22%7D%5D%0A%0A
Showing 1 to 7 of 7 entries
PreviousNext
For more details on the basket parameter, please read this article. A comprehensive documentation on the magic key can be found here.
Possible actions for basket positions
Updating a basket is done with the help of the parameter “bsknew:” The value transmits the new basket including the changes. When validating basket positions, there are 3 options, that can be executed:
updating a basket position
example: Change status to approved
how it is done: The parameters with the changes are transmitted and will be applied to the according positions (defined by position id)deleting a basket position
example: removing a position because the item was returned by the client
how it is done: Either by changing the status of the basket position to rejected (“2”) or by setting the quantity to “0”inserting a basket position
example: adding a position when an additional item was sent out
how it is done: Add a position string with the position id “0”
For more details on the basket parameter and how to work with it, please read this article.
Example CAD request for basket positions
If you implement all the parameters mentioned above, your CAD request for basket positions will look more or less like this:
| Code Block |
|---|
https://marketing.net.yourdomain.com/ts/i1234567/tsa?typ=d&tst=1429018671&trc=basket&ctg=sale&cid=1234567asd&unqid=4e31669-6940-8905-8004-8340696916e3&bsknew=%5B%7B%22price%22%3A%22182%22%2C%22quantity%22%3A%220%22%2C%22commissionFix%22%3A%220%22%2C%22commissionPercent%22%3A%2211%22%2C%22categoryId%22%3A%223682%22%2C%22productId%22%3A%22MA339HL84SEDLMX-893765%22%2C%22productNumber%22%3A%22Green%20Hoover%20vacuum%20cleaner%22%2C%22positionId%22%3A%221%22%2C%22status%22%3A%221%22%7D%5D%0A%0A&mkey=0b539c09-e0de-42c6-9b9c-f4a42d92d389 |
Note for developers: There will be no response to your request.
Please note this example contains one basket position only. In many cases, you will find that a conversion contains multiple basket positions, representing all the different products ordered by the customer. For further details, please read this articleWhat is a unique ID?
A unique ID identifies a conversion on the platform and is primarily used to make the validation process more secure. In general, conversions and corresponding basket positions are identified using the order ID. But the order ID is generated and visible on the website of your advertiser and is therefore semi-public. The unique ID is used on the platform only. Therefore, it is added to the conversion and basket position data to ensure no third parties can manipulate the validation process.
Generating unique IDs
Overview
There are two ways to generate unique IDs:
You let the platform generate the unique IDs. This is done when you export conversions or basket positions from the platform using the export/import feature or via an automated export.
You can generate the unique IDs on the website of the advertiser and make sure it is transmitted as a parameter value with the conversion code.
Unique IDs generated via the platform
As was mentioned above, the platform generates unique IDs when you export conversions or basket positions automatically, both when you use the export/import feature or when you export them via an automated export. If you use the export/import feature, you need to make sure the unique IDs remain in the file when you import the conversions or basket positions after comparing them with the information in your data warehouse.
The format of a unique ID follows the so called Universally Unique ID according to ISO/IEC 9834-8:2008. An example would be:
| Code Block |
|---|
cadO06e3-eabc-5c9b-ac7b-2fa3430f4b16 |
If you are working with automated validation via CAD-requests, you need to make sure the unique ID is transmitted as a parameter value. The name of the parameter is ‘unqid‘. For more information, please read the article on automated validation via CAD-requests.
Working with your own unique IDs
You can also work with your own unique IDs. To do this, you need to make sure the unique IDs are generated on the confirmation page of the advertiser’s website and transmitted via the conversion code as a parameter value. The name of the parameter is uref.
Working with your own unique IDs has the advantage that you no longer need to export conversions or basket positions from the platform. If you receive information on whether an order was canceled, partially accepted or fully accepted, you can immediately send out a CAD-request and validate the conversion or basket position on the platform. For more information, please read the article on automated validation via CAD-requests.