Koddi

Datafly Signal delivers conversion events to Koddi, a commerce media / retail media advertising platform, server-to-server using Koddi’s Event Collection conversion beacon. Conversions are matched to prior ad impressions and clicks using a stable user GUID, so Koddi can attribute revenue to the ads it served.

Prerequisites

Before configuring Koddi in Signal, your Koddi onboarding team must provide:

Your client subdomain — the host prefix for your beacon endpoint (for example acme, giving acme.koddi.io).
Your client name — the client_name string Koddi assigns to your account.
An API key, if your Koddi deployment requires authentication on the conversion beacon. Many deployments identify you by subdomain and client name alone — confirm with Koddi.

Koddi attributes conversions by joining the user GUID on each conversion to the GUID sent on the impression and click beacons fired by your ad-serving layer. The GUID must be identical across all three event types and contain only letters and numbers (no special characters). Signal uses the Datafly anonymous_id as the GUID — ensure the same identifier is used when your front end fires Koddi impression/click beacons.

Configuration

Field	Required	Description
`client_subdomain`	Yes	The part before `.koddi.io` (e.g. `acme` for `acme.koddi.io`).
`client_name`	Yes	The `client_name` string Koddi assigned to your account.
`api_key`	No	Sent as the `x-api-key` header if your deployment requires auth. Leave blank otherwise.

Configure in Signal

Add the integration

In the Management UI, go to Integrations > Add Integration > Koddi and choose the Default preset.

Enter your credentials

Enter your client_subdomain and client_name, and your api_key if Koddi provided one.

Select the consent categories that gate advertising delivery (typically advertising or marketing). Conversions are only delivered for visitors who have granted the matching consent.

Save

Click Save. Signal will begin delivering Order Completed events to Koddi as conversions.

API Endpoint

POST https://{client_subdomain}.koddi.io/event-collection/beacon/conversion

The conversion is sent as a JSON body. The visitor’s IP and User-Agent are forwarded as request headers.

Identity Signals

Koddi matches conversions to served ads using the user GUID, and improves attribution with hashed contact details.

Signal	Field	Notes
User GUID	`user_guid`	Datafly `anonymous_id`. Must match the GUID on impression/click beacons.
Email	`attributes.hashed_email`	SHA-256 of the trimmed, lower-cased email. Hashed server-side.
Phone	`attributes.hashed_phone`	SHA-256 of the E.164-normalised phone. Hashed server-side.
IP / User-Agent	request headers	Forwarded from the original browser request.

⚠️

Raw PII is never sent to Koddi. Email and phone are normalised and SHA-256 hashed by Signal before delivery. Koddi documents hashes as Base64-encoded; confirm the expected encoding with your Koddi team during onboarding so match rates are correct.

How to send user data

Call datafly.identify() when a customer logs in or checks out so the hashed email and phone are attached to the conversion:

datafly.identify("user-123", {
  email: "jane.doe@example.com",
  phone: "+44 7700 900123"
});

Event Mapping

Signal event	Koddi event
`Order Completed`	`conversion`

Only purchase conversions are delivered through this S2S API. Impression and click beacons are fired by your ad-serving layer, not by Signal. All other Signal events are dropped.

Example: Order Completed

Datafly.js call:

datafly.track("Order Completed", {
  order_id: "ORD-001",
  currency: "USD",
  revenue: 129.99,
  products: [
    { product_id: "SKU-A", price: 49.99, quantity: 2 },
    { product_id: "SKU-B", price: 30.01, quantity: 1 }
  ]
});

Koddi conversion payload sent by Signal:

{
  "client_name": "Acme Inc",
  "domain": "https://example.com/checkout/confirmation",
  "culture": "en-US",
  "currency": "USD",
  "user_guid": "a1b2c3d4e5f6",
  "conversion_source": "datafly_signal",
  "transaction_id": "ORD-001",
  "unixtime": 1727717516,
  "bidders": [
    { "bidder": "SKU-A", "count": 2, "base_price": 49.99, "total_price": 99.98 },
    { "bidder": "SKU-B", "count": 1, "base_price": 30.01, "total_price": 30.01 }
  ],
  "attributes": {
    "hashed_email": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
    "hashed_phone": "a3f1..."
  }
}

The bidders array represents the purchased line items. By default Signal maps each product’s product_id to bidder, quantity to count, and price to base_price / total_price. If your Koddi setup expects the winning-ad (auction) identifier in bidder instead of the product SKU, adjust the integration’s script in the Management UI.

Testing

Place a test order on your site, or fire datafly.track("Order Completed", { ... }) from the browser console.
In Signal’s Event Debugger, confirm the event maps to the Koddi conversion shape and the delivery returns 200.
Confirm the conversion appears in your Koddi reporting, attributed to the correct campaign. Attribution requires the user_guid to match a GUID from a recent impression or click beacon.

Troubleshooting

Problem	Solution
`400` response	A required field is missing — check `client_name`, `culture`, `currency`, `user_guid`, `transaction_id`, and that `bidders` is non-empty. Review the payload in the Event Debugger.
`401` / `403` response	The deployment requires an API key, or the key is wrong. Confirm the `api_key` and header name with your Koddi team.
`404` response	Wrong `client_subdomain`. Confirm the host with Koddi.
Conversions deliver but aren’t attributed	The `user_guid` doesn’t match any impression/click GUID. Ensure your ad-serving beacons use the same Datafly `anonymous_id`.
Low match rate on hashed email/phone	Confirm with Koddi whether hashes should be Base64- or hex-encoded, and that PII is normalised identically on both sides.

Topsort Epsilon