Automated update of conversions and basket positions

Owned by Former user (Deleted)
Last updated: Aug 24, 2022 by Siamak Haschemi (Deactivated)
5 min read

Overview

This article explains how you can fully automate updates on conversions (validation process) using requests. You transfer changes from your system (data warehouse, ERP, …) to your Partner Marketing Platform for the following (non exhaustive list of) use cases:

  1. Let the Ingenious Platform recalculate the commissions and fees by:

  • Updating the status (approve, reject, reopen)

  • Changing the revenue

  • Adding or changing basket entries

  • Changing conversion target or tracking categories of conversions

2. Supply commissions calculated by an external system

Understanding the basics

The Ingenious Platform supports two types of conversions:

  • conversion without basket entries

  • conversions with basket entries, often used in an E-Commerce use case

When values of a conversion or the basket entries are changed, in most cases a recalculation of the commission and fee is the effect of your change. The conversion update process supports changing values for both types of conversions. However, for each conversion type, a different set of parameters is changeable. The following diagram illustrates your options:

 

Conversion without basket entries:

  • You currently cannot provide an externally calculated fee. However, you can influence the fee by changing calculation-related fields, which will trigger recalculation.

Conversion with basket entries:

  • The tracking category, revenue, and commission cannot be changed on the top-level. You have to change it on basket-level.

  • You currently cannot provide an externally calculated fee for basket entries. However, you can influence the fee by changing calculation related fields, which will trigger recalculation.

  • When you want to change the status of an individual basket entry, you have to set the status on the basket-level.

  • For your convenience, there are some handy automated status changes implemented:

    • When you change the status of a conversion on the top-level, all basket elements will inherit this status change. Use this option if you want to change all basket entries to the same status.

    • When at least one basket entry is approved (status = "1”), the top-level conversion status will also automatically change to approved.

    • When all basket entries are rejected (status = "2”), the top-level conversion status will also automatically change to rejected.

  1. confirmed, rejected, rejected => conversion=approved → conversion=confirmed

  2. confirmed, rejected, open => request is rejected

Getting started

Domain

A CAD request has the following basic structure:

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:

Parameter name

Explanation

Mandatory

Corresponding field in export file

Example

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

uniqid

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 API key to identify the user, making the process transparent and secure.

Yes

n/a

0b539c09-e0de-42c6-9b9c-f4a42d92d389

preview_mode

Activate preview mode to process request without saving

No

n/a

1 or true

For more information about the API keys, please read this article.

For more information about the preview mode, 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:

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&uniqid=4e31885-6940-2204-8784-8340696916e3&cre=Order%20was%20canceled&mkey=0b539c09-e0de-42c6-9b9c-f4a42d92d389

CAD response

Http Status

  • 200 on success

  • 422 "Unprocessable Entity"on processing error

Default Content Type Json

Content

Json object containing

  • params - all decoded query string parameters

  • request_subtype - "AdditionalData"

  • conversion_id - checked conversion id (when present)

  • basket_new - checked basket object (when present)

  • all checked numeric parameters (ovn, crt) in Preview Mode

  • cfd - checked timestamp (when present) in Preview Mode

  • error object (on processing error) containing code, reason and optional message

Example CAD response

{ "params" : { "uniqid" : "fdsfdsafdsa435435243fdfdsaf" , "typ" : "d"} , "request_subtype" : "AdditionalData" , "error" : {"code" : 88 , "reason" : "ConversionAdditionalDataRequest" , "message" : "uniqid: fdsfdsafdsa435435243fdfdsaf is not a valid UUID"}}

Validation of basket positions: The basics

A conversion that contains basket information contains two levels:

  1. the conversion level (it contains the order ID, conversion target, tracking category "basket", the status (open, approved, rejected, confirmed) and others)

  2. 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:

  1. validation of the basket positions

  2. 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

Parameter name

Description

Mandatory

Corresponding field in export file

Example

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

uniqid

A unique ID identifying the transaction, used for security purposes.

Yes

conversion_uniqid

14e31669-6940-2204-8004-8340696916e3

mkey

The API key to identify 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

For more details on the basket parameter, please read this article. A comprehensive documentation on the API 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:

  1. 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)

  2. 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"

  3. 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:

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 article.