Attribution for Kevel Ad Server

Customers using Kevel Ad Server often need to attribute product purchases to the ad campaigns that influenced them. This is done by sending order data to Kevel’s Purchase Events API, after which the ad server evaluates whether any prior ad events are attributable to the purchase. To understand how the Ad Server attributes purchases and how this API relates to ad campaigns and the product catalog, refer to Attribution Overview.

Audience integrates seamlessly with the Ad Server by sending data to the Purchase Events API whenever an Order Place event is registered.

How It Works

When an Order Place is detected, Audience communicates one purchase request for each line item found in that order, using the Purchase Events API.

Audience communicates the following information to the Attribution API:

• userKey: Audience determines all the user ids that are part of the user profile that made the Order Place event and sends them to the Ad Server. This helps reduce conversion underreporting in cases where the user identifiers at the time of the ad event differ from those present in the Order Place event — a common scenario for retailers operating both online and offline, who want to attribute offline purchases to online engagement.
• timestamp: The timestamp on which the OrderPlace event occurred.
• productId: The product identifier.
• quantity: The purchased quantity of the product, reported as a whole number of units. See Quantity Constraints for how fractional quantities are handled.
• price: The unit price of the purchased product. Audience derives it by dividing each line item's total by the quantity reported to the Ad Server, so that quantity multiplied by price always equals the line item total.
• transactionId: The identifier of the order that contains the purchased product.

The price is communicated in the default system currency configured for the Audience instance. Audience automatically converts the monetary values of every Order Place to this currency before sending them to the Ad Server. This means the values reported to the Ad Server are always in a single, consistent currency, regardless of the currency in which each order was originally placed.

Audience only processes an Order Place once. If the same Order Place is sent multiple times, Audience will only communicate purchases to the Ad Server once. This is done to prevent duplicate purchases from being sent, which could lead to incorrect attribution and ad serving behavior.

Quantity Constraints

The Ad Server records the purchased quantity as a whole number of units and uses it to count the conversions attributed to a purchase. To stay consistent with this, Audience only reports whole-number quantities to the Ad Server.

When a line item carries a fractional quantity (common for products sold by weight, length, or volume, such as 1.5 kg of coffee or 7.5 ft of rope) Audience rounds the quantity up to the next whole unit before sending it. The unit price is then recalculated against the rounded quantity, so the order's monetary value is never distorted: the reported quantity multiplied by the price always equals the line item total.

For example, a line item with a quantity of 1.5 and a total of 9.00 is reported to the Ad Server with a quantity of 2 and a unit price of 4.50 (9.00 ÷ 2), preserving the 9.00 total. Quantities that are already whole numbers are reported unchanged.

Kevel Ad Server Customers with Multiple Networks

Most customers have multiple Ad Server Networks — typically one for production and another for development, or even different business units within a conglomerate — but just one Audience instance. By default, Audience sends purchase events to all networks associated with a customer's organization. This applies to both real-time Order Place events and bulk imports via Order Import.

However, this default behavior can lead to issues, such as:

• A small risk of duplicate or incorrect attribution
• Development environments inadvertently receiving real user data, which may violate internal policies or data handling practices
• Potential data spillage between businesses of a conglomerate.

To address this, customers are strongly encouraged to include the networkId in their Order Place events. This allows Audience to send purchase data only to the specified, whitelisted Network, giving customers greater control over where their business data is sent.

If a networkId is missing or invalid, Audience will fall back to the default behavior and send the purchase event to all of the customer's whitelisted networks. Importantly, Audience never sends data outside the customer's organization — even in cases of misconfiguration.