Conversion API

Updated on 18 Nov 2024

Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

This service accepts batches of orders and registers them in the Awin system. The API allows for transactions to be sent in an authenticated manner from your server directly to Awins server.

Authentication

For the conversion API it uses x-api-key header which is where a custom HTTP header can be used to secure the API calls. Keep in mind this is different to the rest of the Awin APIs where the Bearer followed by the token is parsed in the header. See the example of x-api-key header in screenshot below:

Creating the Awin First Party Cookie

Before getting to how to send the orders, first we shall outline how to capture the "awc" which is a required part of each valid transaction.

The "awc" is an information Awin appends to your website at the moment of the click. This information is used like a key, to attribute conversions to specific publishers safely and correctly. It is also used, to make sure that the conversion gets recorded, if it happened inside the agreed upon attribution window.

You must configure your site to record the awc value in a cookie with both ‘Secure’ and ‘HTTPOnly’ flags when the user lands on your site. The value within this cookie should then be used to populate the “cks” parameter on conversion.

To create Awin's First Party Cookie using the information inside of the "awc" parameter, please use the following code, or similar:

<?php
function setAwc() {
    if (!empty($_GET['awc'])) {
        setcookie("awc",$_GET['awc'],time()+ 60 * 60 * 24 * 365,"/", "example.com", true, true);   
    }
}
?>

Sending transaction information with the Conversion API

Endpoint (POST)

https://api.awin.com/s2s/advertiser/{advertiser_id}/orders

{advertiser_id} is the ID of your advertiser account.

Each batch of requests can have a maximum of 1000 orders.

JSON request Body

{
   "orders":[
           {
               "orderReference": "#1100011",
               "amount": 111,
               "channel": "aw",
               "currency": "GBP",
               "voucher": "10_OFF",
               "isTest": false,
               "awc": "1001_xxx_xxx",
               "customerAcquisition": "NEW",
               "commissionGroups": [
                   {
                       "code": "DEFAULT",
                       "amount": 111
                   }
                   ...
               ],
               "custom": {"1":"s2sAPI"},
               "basket": [
                   {
                       "id": "123",
                       "name": "Fish",
                       "price": 111,
                       "quantity": 1,
                       "commissionGroupCode": "DEFAULT",
                       "category": "Food",
                       "sku": "111"
                   }
                   ...
               ]
           }
           ...
   ],
   "webhook": {
     "url": "https://example-webhook-url.com"
   }
}

Order:

Field name	Required?	Type	Description
orderReference	Yes	String	The reference id for your booking or order. It truncates at 50 characters.
amount	Yes	Float	The order subtotal amount after discounts are added but before additional fees such as taxes, delivery charges, or service charges are added. The value must be a float, thousand separators aren't accepted. The decimal place must be a period, for `example:`'1083.29'. If the transaction type is a lead, then instead declare the number of leads, for `example:`'1'
channel	Yes	String	The name of the channel that identified as the last click referrer. Use "aw" for Awin. For information about the Channel Parameter, see https://wiki.awin.com/index.php/Advertiser_Tracking_Guide/De-duplication#Channel_Parameter
awc	Yes	String	The parameter Awin adds to the landing page URL to identify the source of the click.
currency	Yes	String	The ISO currency code of the currency.
voucher	No	String	The voucher code used in the transaction. `Example:` 10_OFF
isTest	No	Boolean	When tracking is in live mode, it must be false. When tracking is in test mode, it must be false. When set to test mode, the incoming tracking requests aren't processed.
CustomerAcquisition	No	String	Type of customer. NEW and RETURNING are accepted ENUM values.
commissionGroups	Yes	Array	Use commission groups to attribute the whole or parts of the transaction to a commission percentage or amount. The groups are created and maintained in Commission Management on the Awin platform.
custom	No	Object	The key is a number (maximum 127) and the value is a custom value.
basket	No	Array	Object array of basket items.

Commission Groups:

Field name	Required?	Type	Description
code	Yes	String	Accepted characters for the CommissionGroup code are alphanumerics (use upper case letters), underscore (_), period (.), and hyphen (-).
amount	Yes	Float	The total amount of money spent in the give commission group. The value must be a float, thousand separator aren't accepted. The decimal place has to be a period.

Basket Item:

Field name	Required?	Type	Description
id	Yes	String	The product ID. It must be unique. It truncates at 75 characters.
name	Yes	String	The product name. It truncates at 255 characters.
price	Yes	Float	The value must be a float, thousand separators aren't accepted. The decimal place must be a period.
quantity	Yes	Integer	The quantity of items. The value must be an integer.
commissionGroupCode	Yes	String	The commission group code the product belongs to. It has to match the breakdown you declared in AWIN.Tracking.Sale.parts. If you don't map products to specific commission groups, or you're an Awin Access client, then populate with a static "DEFAULT".
category	Yes	String	Use this to record the category that the product belongs to. It truncates at 255 characters.
sku	Yes	String	Use this to record the product's SKU. It truncates at 255 characters.

Webhook:

Field name	Required?	Type	Description
url	No	String	This is the url that the response of transaction status will be sent to

Response

{   
   "message": "",
   "batchId": "1111-1692271186-8274157a-bd07-4b7a-a8d4-ddb21e741d11",
   "successfulOrders": [
       {
           "orderReference": "#1100011",
           "amount": 10,
           "channel": "aw",
           "currency": "GBP",
           "voucher": "10_OFF",
           "isTest": false,
           "awc": "1111_xxx_xxx",
           "customerAcquisition": "NEW",
           "commissionGroups": [
               {
                   "code": "DEFAULT",
                   "amount": 1.2
               },
               ...
           ],
           "custom": {
               "1": "s2sAPI"
           },
           "basket": [
               {
                   "id": "125",
                   "name": "Fish",
                   "price": 10,
                   "quantity": 1,
                   "commissionGroupCode": "DEFAULT",
                   "category": "Food",
                   "sku": "11111"
               }
               ...
           ],
           "advertiserId": 1111,
           "correlationId": "e653481f-94d6-497d-8279-8c925b3a1cc8"
       }
       ...
    ],
    "failedOrders": [
       {
           "order":
           {
               "orderReference": "#1100012",
               "amount": "123",
               "channel": "aw",
               "currency": "GBP",
               "voucher": "10_OFF",
               "isTest": false,
               "awc": "1111_xxx_xxx",
               "customerAcquisition": "NEW",
               "commissionGroups": [
                   {
                       "code": "DEFAULT",
                       "amount": 1
                   },
                   ...
               ],
               "custom": {
                   "1": "s2sAPI"
               },
               "basket": [
                   {
                       "id": "",
                       "name": "",
                       "price": 20,
                       "quantity": 1,
                       "commissionGroupCode": "DEFAULT",
                       "category": "",
                       "sku": ""
                   },
                   ...
               ],
               "advertiserId": 1111,
               "correlationId": "55d2ee39-eae1-440c-a3ff-bc2fba496c8f"
           },
           "errors":   [
               {
                   "field":"amount",
                   "message":"Property 'amount' must be of type 'number'"  
               },
               ...
           ]
       },
       ...
   ]
}

batchId : Unique identifier for each transaction.
correlationId : Unique identifier for each order inside the transaction.

Response Code	Description
200	OK. All orders registered successfully.
202	Accepted. Your request has been accepted and will be processed later.
206	Partially OK. Some orders registered successfully, while others encountered errors.
400	Bad Request. All objects in the request are invalid or the payload is malformed or there were more than 1000 orders in the request.
401	Unauthorized. Invalid authentication credentials. Please provide valid credentials to access the resource.
406	Not acceptable. Your request has been rejected because it cannot be processed immediately and some/all orders are invalid.
500	Internal Server Error. Unable to process your orders please try again later.

Webhook Details

The Webhook notifier feature can be used by advertisers who want the get the real-time processing details of Orders sent to S2S API. The Notifier will send the Webhook request with details of all the orders as soon as all the orders are processed. If there are questions about a failed order, please share the code with the order id.

Webhook notifier example

{   
   "batchId": "15716-1697459823-d5d0d86d-eb5b-423b-a70e-03551219eb67",
   "successfulOrders": [
        {
           "orderReference": "#1100011",
           "correlationId": "52ee5b94-e5eb-4d21-88ee-22fe07cd1238"
        }
    ],
    "pendingOrders": [
        {
           "orderReference": "#2200022",
           "correlationId": "52ee5b94-e5eb-4d21-88ee-22fe07cd1248"
        }
    ],
    failedOrders": [
        {
           "orderReference": "#3300033",
           "correlationId": "52ee5b94-e5eb-4d21-88ee-22fe07cd1258",
           "code": "VAL_NO_CLICKS_MATCHED",
           "message": "No clicks matched to transaction"
        }
    ],
           "timestamp": 16492495245
}

Voucher Attribution

Conversion API supports voucher attribution. To achieve this the 'awc' must be empty or not present, and there must be a value in the 'voucher' parameter. This will appear as a Voucher Attribution conversion in future reports, and not as a conversion API conversion.

Was this article helpful?

Table of contents

Authentication
Creating the Awin First Party Cookie
Sending transaction information with the Conversion API