Syncing Order Data
Why Sync Order Data
Project Agora Commerce requires order data generate relevant ads and to disburse money properly to all entities involved in transactions (disbursement occurs only in the case of discounts. Project Agora Commerce charges only for impressions and clicks.).
Syncing orders is also valuable for advertiser and retailer dashboards in the Project Agora Commerce portal. Orders are used in sales, conversion, sale value and ROAS calculations. These are invaluable for advertiser teams to gauge their investment worth, and contribute additional spend.
Order Attribution Options
Project Agora Commerce supports the following option to attribute ads to orders.
Attribution Option: sessionId Attribution
This method shares attribution responsibility between the integrator and Project Agora Commerce. Project Agora Commerce is responsible for linking any adId served to the sessionId and then to the relevant products purchased.
sessionId Overview
A sessionId is an identifier for an individual user's session. Some integrators may refer to it as a cookie Id. This sessionId can be generated solely for Project Agora Commerce or have an existing cookie Id for a single session substituted as the sessionId value.
When requesting ads, integrators send the sessionId in the context, such as below:
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"pageType": "SEARCH",
"searchTerm”: "Computer",
"maxNumberOfAds": 4,
"sessionId": "23dn3923-323d"
}When submitting orders, the same sessionId needs to be communicated when a relevant order is submitted. This spares the integrator from the work required to store each adId. In an API push, the field is within the orders object:
{
"orders": [
{
"sessionId": "23dn3923-323d",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 5,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "5.00"
}
]
}
]
}The whole request should look like below:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"orders": [
{
"orderDate": "string (iso date)",
"sessionId": "sessionid",
"orderItems": [
{
"gtin": "string=pa_id",
"quantity": number,
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number"
}
]
}
]
}Here is a mock example:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"orders": [
{
"orderDate": "2019-12-02T15:00:00Z",
"sessionId": "23dn3923-323d",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 5,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "1.00"
}
]
}
]
}If successful, you will get the following object returned:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "",
"sessionId": "23dn3923-323d",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 5,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 1.00
}
],
"orderDate": "2019-12-02T15:00:00Z"
}
]
}The gtin field should contain the respective pa-id for this product, the quantity field should contain the quantity of the product that was ordered, and the reqularUnitPrice andtotalOrderItemPriceAfterDiscounts should contain both the final price of the product as exists in the product feed.
The retailer should sent to PA Commerce all the orders being made to his website(even the ones that don't include SPL/DSPL or products related with Static Banner campaigns) and Project Agora Commerce is responsible to detect the orders that include SPL/DSPL or Static Banner related products and make the proper attribution. Those orders will only be shown in the client's dashboard of the Project Agora Commerce platform.
If the integrator expire, rotate, or lose sessionId data between ad serving and order submission, there is no way for Project Agora Commerce to attribute orders. The sessionId submitted with orders must be identical to the sessionId sent in ad requests.
Some finals points that need to be taking care of regarding sessionId order attribution:
the sessionId sent in the ad request and the one in the order attribution should be the same
An ad should have received an impression and click in order to be properly attributed in an order
Time between requesting an ad and the order/purchase is less or equal to the attribution window (which is 2 days)
Ideally the value chosen to be sessionId needs to be unique per user and the same for different user sessions
All orders being made to the website should be sent in the order ad request as order objects and Project Agora Commerce will attribute the ones related with Project Agora Commerce formats.
Last updated