Syncing Order Data
CitrusAd 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. CitrusAd charges only for impressions and clicks.).
Syncing orders is also valuable for advertiser and retailer dashboards in the CitrusAd 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.
CitrusAd supports multiple options to attribute ads to orders.
The first attribution option can be used if an explicit association between a single order item and a single ad id can be provided. This method places the attribution responsibility on the integrator.
The integrator is required to store the adId relevant to each product ordered until the order is submitted. In an API push, the field is within the individual product's . orderItems object:
{"orderDate": "2019-12-02T15:00:00Z","customerId": "wertg5432a","orderItems": [{"gtin": "9891998566P","quantity": 3,"regularUnitPrice": "10.00","totalOrderItemPriceAfterDiscounts": "30.00","adId": "display_zeowj3jV8VRxB1w_iEPy_upxFPc5ODkxNTY2UA=="}]}
This attribution method relies on the integrator to make the attribution between purchases and adIds. It is not advised for banner attribution.
The second attribution option can be used if an explicit association between a single order item and a single ad id cannot be provided. This method shares attribution responsibility between the integrator and CitrusAd. CitrusAd are responsible for linking any adId served to the relevant products purchased.
The integrator is required to store every adId served in a customer's session and communicate them when an order is submitted. In an API push, the field is within the orders object:
{"orders": [{"orderDate": "2019-12-02T15:00:00Z","customerId": "wertg5432a","adIds": ["1985988a-6f9f-4ce8-8d4a-0a4b559206ca", "23423423-6f9f-4ce8-sdf23-0a4b559206ca"],"orderItems": [{"gtin": "9891998566P","quantity": 2,"regularUnitPrice": "4.00","totalOrderItemPriceAfterDiscounts": "8.00"}]}]}
The third attribution option can be used if the integrator's system is incapable of storing every adId across the customer's journey from browsing to purchasing. This can occur if third party product's are integrated for different functions, or in legacy systems incapable of supporting attribution option 1 or 2.
This method shares attribution responsibility between the integrator and CitrusAd. CitrusAd are responsible for linking any adId served to the sessionId and then to the relevant products purchased.
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 CitrusAd 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""customerId": "wertg5432a",}
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": [{"orderDate": "2019-12-02T15:00:00Z","sessionId": "23dn3923-323d","customerId": "wertg5432a","orderItems": [{"gtin": "9891998566P","quantity": 5,"regularUnitPrice": "1.00","totalOrderItemPriceAfterDiscounts": "5.00"}]}]}
If the integrator expire, rotate, or lose sessionId data between ad serving and order submission, there is no way for CitrusAd to attribute orders. The sessionId submitted with orders must be identical to the sessionId sent in ad requests.
You can sync your order data with CitrusAd in two ways, via our API or File
