Skip to main content

​
Overview

As of February 20, 2026, Topsort auctions can incorporate third-party demand, allowing retailers to pass third-party bids into the Topsort auction where they compete directly against Topsort demand. The highest bid wins, regardless of the source.

​
What is Demand Mediation?

Previously, Topsort auctions only received demand from Topsort sources (either from vendors within a marketplace or via Toppie). With demand mediation, Topsort can now pull demand from third-party sources.
The first third-party demand source integrated is Criteo, a leading retail media ad platform with budgets from major brands around the world. For each sponsored listing placement, a retailer fetches bids from Criteo and passes them into Topsort. Topsort compares the Criteo bids with its own bids and selects the winning bids among them.
Topsort can easily accommodate other demand sources beyond Criteo, as long as their bids can be sent via the demandSources parameter of the auction endpoint.

​
How Billing Works

With demand mediation using Criteo:
  • The retailer owns the Criteo account/instance, not Topsort
  • Advertisers pay Criteo directly
  • Criteo bills advertisers, takes its platform fee, and pays the retailer their revenue share
  • Topsort bills the retailer separately (billing structure TBD)

​
Benefits for Marketplaces

Retailers can generate additional ad revenue through demand mediation:
  • Fill gaps: When there’s no Topsort demand for ad requests, Criteo demand may be available
  • Increase competition: When Topsort demand exists, Criteo demand may bid higher, increasing overall revenue

​
Which Clients Should Use This?

While any client can add Criteo demand, this integration is most relevant for clients likely to attract significant Criteo ad spend:
  • Large US marketplaces: Many major US brands bid on retail media ads via tools like Pacvue and Skai, which in turn bid on Criteo inventory. This setup allows big brands to avoid direct integration with every retailer they want to advertise on.
  • Large LATAM marketplaces: Criteo has a significant presence in Latin America, making this integration valuable for large LATAM marketplaces as well.

​
Onboarding Process

To onboard a marketplace with demand mediation:
1

Set up placements in Criteo

The marketplace should configure any placements they want to bring in Criteo demand for in their Criteo account.
2

Update frontend code

On page load, the marketplace needs to:
  1. Fetch bids from Criteo for the placement
  2. Send those bids to Topsort as an extra parameter in the auction request
3

Handle auction response

Topsort returns the winning bids, which may include both Topsort and Criteo winners.
4

Report events

If there are Criteo winners, the marketplace should report events to both Topsort and Criteo.

​
API Implementation

The auctions endpoint has been extended to support external demand sources. Adding external demand requires one new input field and two new response fields for auction winners.
The number of external bids is limited to 100 per auction request.

​
Request Changes

A new demandSources field has been added to the auctions object:
  • demandSources: Array of demandSource objects
    • source: Enum identifying the external demand source (e.g., "criteo")
    • bids: Array of Bid objects, one for each external bid
Each Bid object contains:
  • chargeType: Enum (only "CPC" is supported in the first version)
  • entity: Object with type and id fields identifying the sponsored product
  • bidAmount: Bid amount in marketplace currency
  • metadata: Free-form field for any metadata needed in the winner response (e.g., bid beacon URLs)

​
Response Changes

The Winner object has been updated with:
  • demandSource: String identifying the source of the winning bid (e.g., "topsort" or "criteo"). Only appears when external bids are included in the request.
  • metadata: For external bid winners, passes through the external bid’s input metadata. Omitted for internal/Topsort bids.
For external bids, the campaignId field will be omitted from the winner object.

​
Error Cases

New error cases specific to demand mediation:
  • External demand is not authorized for the marketplace
  • Invalid external bids (non-product entities, bad charge type, or negative bid amount)
  • Too many external bids (more than 100)
  • External demand with ad type other than listings
  • Invalid external demand source (only Criteo is currently supported)

​
Example Request

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "paper"
      },
      "opaqueUserId": "user123",
      "demandSources": [
        {
          "source": "criteo",
          "bids": [
            {
              "chargeType": "CPC",
              "entity": {
                "type": "product",
                "id": "product123"
              },
              "bidAmount": 0.75,
              "metadata": {
                "beaconUrls": ["https://example.com/beacon"],
                "clickUrls": ["https://example.com/click"]
              }
            }
          ]
        }
      ]
    }
  ]
}

​
Example Response

{
  "results": [
    {
      "resultType": "listings",
      "winners": [
        {
          "demandSource": "criteo",
          "type": "product",
          "id": "product123",
          "resolvedBidId": "UkoVYQoQBpaVc2jmdMO0BA4QS9VdHRIQAZgtj1MxeFGT5HL2fhBhKRoQBlhiMAUTfKyPJHhKpsqrQCIKCgZzdWJ3YXkQATCmFUDTBEgBUMXa8pu8Mw",
          "rank": 1,
          "metadata": {
            "beaconUrls": ["https://example.com/beacon"],
            "clickUrls": ["https://example.com/click"]
          }
        },
        {
          "demandSource": "topsort",
          "campaignId": "01982d6e-8655-70e2-94e3-3e5e764b4753",
          "type": "product",
          "id": "product456",
          "resolvedBidId": "zOzJwgoQBpaVfNrgdmeSBLgWZwYYmhIQAZgtboZVcOKU4z5edktHUxoQBlhiMAUTfKyPJHhKpsqrQCIQCgxwYW5lcmEtYnJlYWQQATCmFUDTBEgBUKH3-5u8Mw",
          "rank": 2
        }
      ],
      "error": false
    }
  ]
}
For more information on the auctions API, see theCreate Auctions API Reference.
Last updated: