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.

The sessionId must be generated for each single session.

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:

HTTP

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"
                  
                }
              ]
            }
    ]
}

cURL

curl -iX POST "$BASE_URL/v1/orders?" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "orders": [
       {
        "orderDate": "string (iso date)",
        "sessionId": "sessionid",
        "orderItems": [
            {
                  "gtin": "string=pa_id",
                  "quantity": number,
                  "regularUnitPrice": "number",
                  "totalOrderItemPriceAfterDiscounts": "number"

                }
              ]
            }
    ]
}'

Here is a mock example:

HTTP

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"
                  
                }
              ]
            }
    ]
}

cURL

curl -iX POST "$BASE_URL/v1/orders?" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "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

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"
        }
    ]
}

cURL

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

The gtin field in orderItems element above is the <pa_id> of this product

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.