API DocsKnowledge BaseSystem StatusContact SupportContact Sales
API Documentation

Purchase Events

get https://e-YOUR-NETWORKID.adzerk.net/c//purchase

Send sales transaction data to Kevel for attribution processing.

Sample purchase event fully constructed: https://e-123.adzerk.net/c/123/purchase?userKey=marketplaceshopper-456-abc&transactionId=1234567&timestamp=2022-11-02T16%3A27%3A20.974Z&productId=11982758&quantity=1&price=200&merchantId=12478&ltvQuantity=6&ltvValue=1200

It is important to send a consistent UserKey in both the Ad Decision and the Purchase event request so that Kevel is able to perform a look back to determine whether the purchase can be attributable to an ad view or click (depending on attribution settings defined Flight settings).

Generally, this is done by generating a random UserKey on session start and persisting that locally (local storage, or a cookie). Even if the user authenticates midway through their journey, it is important that the same UserKey is sent in purchase events in order for Kevel to be able to correctly attribute conversions to Ads.

Additionally, if products are sold across multiple markets (with multiple currencies), the price value must first be converted to a single currency (defined by the customer).

When the Kevel Ad Server logs a conversion due to attribution:

  • A Server to Server Conversion is logged for the relevant ad using event ID 3. (See Event ID definitions)
  • The GMV for the relevant ad is incremented by the value of the price value * quantity value in the purchase event.
  • The CustomEventCount value in the logged event will be set to the quantity value in the purchase event.
    • There is a single ("EventId": 3) log per attributed purchase event and those logs have CustomEventCount equal to quantity provided on the purchase event—so, if a purchase event includes quantity=2, the event log will contain "CustomEventCount": 2. Kevel's reporting systems honor this event multiplier and increment conversion events per the CustomEventCount value. Therefore the "purchases" column in reports reflects units sold.

Response Codes

  • 200: Purchase attributed to an Ad; conversion recored
  • 204: Purchase not attributable; addition details in kevel-debug response header:
    • "product not found: {productId}" - If the productId was not found in the Catalog
    • "no attributable item was found for productId {productId}" - ProductId was found in the Catalog, but no matching touch points were found for the user key(s) for this product and/or its category + brand.
  • 400: Invalid request; addition details in response body:
    • "required parameter missing: expected userKey, timestamp, productId, quantity and price" - If any of the required parameters are missing.
    • "maximum of 100 userKeys exceeded" - If there are too many user keys.
Language