Create Transactions

Updated on 27 Mar 2025

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.

Endpoint

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.

Authentication

For this API it uses and API key (x-api-key) header for authentication. For details on how to set this up please continue here.

Body Parameters

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 this page.
awc	Conditional (any of)	String	The parameter Awin adds to the landing page URL to identify the source of the click. Fore more information about how to obtain the awc read here. Instead of using the awc value, it is possible to create transactions using the publisher ID, and the time that the click happened that drove the transaction. Both ‘publisherID’ and ‘clickTime’ need to be present for a transaction without ‘awc’ or voucher attribution to be valid.
publisherId	Conditional (any of)	Number	Required if clickTime is present. Populate with the Id of the publisher that generated the sale.
clickTime	Conditional (any of)	Integer	Required if publisherId is present. The time that the click that drove the transaction happened as a unix timestamp in seconds (length: 10).
voucher	Conditional (any of)	String	The voucher code used in the transaction. `Example:` 10_OFF Conversion API supports voucher attribution. The transaction will appear as a Voucher Attribution conversion in your reports, and not as a conversion API conversion.
currency	Yes	String	The ISO currency code of the currency.
transactionTime	No	Integer	The timestamp of when the transaction happened as a unix timestamp in seconds (length: 10). If you are not using the conversion API to send the transactions in real time, use the ‘transactionTime’ parameter to share the timestamp of when the transaction happened. Please send a message to your Awin contact to activate usage of transaction time first.
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. Read more below.

Example Request Body

{
   "orders":[
           {
               "orderReference": "#1100011",
               "amount": 111,
               "channel": "aw",
               "currency": "GBP",
               "voucher": "10_OFF",
               "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"
   }
}

Response

Response Codes

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.

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

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
}

Creating the Awin First Party Cookie (AWC)

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 “awc” 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);   
    }
}
?>

Was this article helpful?

What's Next

Create Offers

Table of contents

Endpoint
Authentication
Body Parameters
Response
Creating the Awin First Party Cookie (AWC)