Topsort

Datafly Signal reports marketplace orders to Topsort server-to-server through the Events API, for retail-media attribution.

Prerequisites

Create a Marketplace API key

In Topsort create a Marketplace API key (TSE_...); events need this key type.

Use one opaque user ID

Send the Datafly anonymous ID as opaqueUserId in your /v2/auctions calls too. Topsort attributes a purchase only when the IDs match.

Configure in Signal

Configuration Fields

Field	Required	Description
`api_key`	Yes	Your Topsort Marketplace API key. Generate it in the Auction Manager dashboard under Settings > API Integration. The Marketplace key (not the Advanced key) is required for the /auctions and /events endpoints. Keep it server-side only.

Management UI Setup

Go to Integrations > Add Integration > Topsort.
Choose a preset: Default (default), Retail (ecommerce).
Fill in the fields above and click Save.

Request format

POST https://api.topsort.com/v2/events

{
  "purchases": [
    {
      "channel": "onsite",
      "id": "ORD-1001",
      "items": [
        {
          "productId": "SKU_1",
          "quantity": 2,
          "unitPrice": 120
        },
        {
          "productId": "SKU_2",
          "quantity": 1,
          "unitPrice": 19.99
        }
      ],
      "occurredAt": "2025-09-22T00:13:20Z",
      "opaqueUserId": "df_anon_e3"
    }
  ]
}

Each order is one purchases[] entry with id (idempotency key, the order ID), occurredAt (RFC 3339), opaqueUserId and items (productId and unitPrice required, quantity, vendorId). Up to 50 purchases per request.

Event Mapping

Signal event	Vendor event	Presets
`purchase`	`purchase`	Default, Retail

Signal forwards properties the preset does not map unless the integration’s strict output contract is on. Turn on strict_output_contract for this integration so only the documented fields are sent.

Identity

The opaque user ID is the Datafly anonymous ID. No personal data is sent. Impressions and clicks need the resolvedBidId from the auction and are reported from the storefront.

Topsort is an advertising destination and requires marketing consent by default.

Troubleshooting

Problem	Solution
Purchases not attributed	The auction calls used a different opaque user ID.

Blueprint

The Topsort blueprint version is 0.7.0. It was last reviewed against the vendor’s documentation on 2026-09-22.