Conversion API
From Wiki
Conversion API
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.
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);
}
}
?>Authentication
In the header, provide a valid token. To find out how to get a token, see the API authentication and authorization page.
To use your token for authentication, send it using the headers. Use "x-api-key" as the key. Use your token as the value.
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 attribuition. 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.