Topsort

Datafly Signal delivers events to Topsort server-to-server using the Events API (/v2/events). Topsort is a retail-media platform: marketplaces report shopper interactions so vendors can measure the effectiveness of their sponsored-product campaigns.

This integration focuses on purchase attribution — Signal forwards completed orders to Topsort so purchases can be matched back to the ads a shopper saw or clicked. Delivery is server-side, so it is unaffected by ad blockers or browser tracking prevention, and no personally identifiable information leaves your infrastructure: Topsort matches purchases using a pseudonymous opaque user ID only.

Prerequisites

Before configuring Topsort in Signal you need a Topsort marketplace account and a Marketplace API key.

Step 1: Generate a Marketplace API Key

1. Sign in to the Topsort Auction Manager dashboard.
2. Go to Settings > API Integration.
3. Click Generate API key.
4. Choose the Marketplace key type. The Marketplace key is the one that grants access to the /auctions and /events endpoints. (The Advanced key is for catalog and campaign management and will not work here.)
5. Copy the key immediately and store it securely.

Step 2: Confirm the Opaque User ID Strategy

Topsort correlates the auction a shopper saw with the purchase they later made using an opaque user ID — a long-lived, anonymised identifier that is consistent across both requests. Signal sends its own pseudonymous anonymous_id (a first-party identifier stored as a cookie that lives for at least a year) as the opaqueUserId.

For purchase attribution to work, the same identifier must be used when your storefront runs the Topsort auction (client-side /v2/auctions call). If you already run Topsort listings via their JavaScript SDK, ensure it is configured to use the same persistent identifier that Datafly.js uses, or pass Datafly’s anonymous_id into the SDK.

Configure in Signal

Configuration Fields

Management UI Setup

API Endpoint

POST https://api.topsort.com/v2/events
Authorization: Bearer {api_key}
Content-Type: application/json

Events are grouped into named arrays by type. Signal sends completed orders in the purchases array. A successful request returns 204 No Content.

{
  "purchases": [ { "...": "..." } ]
}

Identity Signals

Topsort does not accept hashed email, phone, or other PII. Matching relies on a single pseudonymous identifier plus a stable, idempotent event ID.

Event Mapping

Default preset

Purchase item fields

Each product in the order maps to one element of the Topsort items array:

Example: Purchase Event

Datafly.js call:

datafly.track("Order Completed", {
  order_id: "ORD-001",
  total: 26.39,
  currency: "USD",
  products: [
    { product_id: "p_SA0238", name: "Whole Milk", quantity: 2, price: 12.95 },
    { product_id: "p_oajf2D", name: "Cookies", quantity: 1, price: 1.49 }
  ]
});

Topsort Events API payload sent by Signal:

{
  "purchases": [
    {
      "id": "ORD-001",
      "occurredAt": "2026-06-06T12:59:59Z",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "items": [
        { "productId": "p_SA0238", "quantity": 2, "unitPrice": 12.95 },
        { "productId": "p_oajf2D", "quantity": 1, "unitPrice": 1.49 }
      ]
    }
  ]
}

occurredAt is an RFC 3339 timestamp including a UTC offset, derived from the event time. opaqueUserId is Datafly’s anonymous_id.

Testing Your Integration

Troubleshooting

Rate Limits

Topsort accepts up to 50 events per array per request. Signal batches purchases automatically up to this limit; for most deployments the default settings are sufficient.