Skip to main content

​
Overview

Topsort offers two ways to integrate third-party demand into your ad stack:
  • Demand Mediation – For sponsored listings, pass bids from external demand sources (e.g., Criteo) into the Topsort auction where they compete directly against Topsort demand. The highest bid wins, regardless of source.
  • Demand Fallback – For banner ad slots, Topsort can return a Google Ad Manager (GAM) tag when no Topsort demand is available, earning the marketplace incremental revenue from programmatic ads.

​
Demand Mediation

​
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

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

​
Who is it For?

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

​
Demand Fallback

​
What is the GAM Fallback Integration?

For clients that are set up for this integration, the Topsort auction endpoint returns a Google Ad Manager (GAM) tag — a few lines of code — for banner ad slots that are enabled for GAM demand, whenever there is no Topsort demand for an ad request on these slots.
The retailer renders the GAM tag, which displays a GAM banner ad, earning the retailer incremental revenue from otherwise unfilled inventory.
GAM fallback flow diagram showing the auction returning a GAM tag when no Topsort demand exists

​
Benefits

  • Monetize unsold inventory: Marketplaces can earn revenue from banner ad slots even when there is no Topsort demand
  • Flexible demand sources: Topsort can configure GAM placements to pull in demand from either open auction (non-endemic advertisers linking to other websites) or direct deals

​
Who is it For?

Any client that can bring in GAM demand from GAM open auction is eligible for this integration.
It is ideal for marketplaces with unsold or low-demand banner inventory in Topsort.

​
Onboarding Process

If your marketplace is interested in GAM fallback, reach out to your Topsort account team. From there, we will work with you to develop a timeline for integration.
The typical integration takes 3–4 weeks and follows these steps:
1

Align on pilot scope

Select 2–3 banner ad slots and agree on content moderation policies.
2

Set up GAM MCM connection

Link Topsort and retailer accounts, and update ads.txt and sellers.json. Topsort uses GAM’s Multiple Customer Management (MCM), which allows the Topsort GAM account to control other accounts (e.g., retailer accounts).
3

Configure shared ad slot registry

Ensure matching ad unit IDs, dimensions, and placements exist across Topsort and GAM.
4

Implement passback flow

Topsort will apply settings in the GAM UI and generate GPT passback tags (snippets of JavaScript code). Topsort will update its configuration to return GAM tags for any banner auction where there is no Topsort demand. The retailer will update frontend logic to render a passback tag if the Topsort auction returns one.
5

Testing

Topsort will validate the integration via controlled test slots.
6

Go live

Once testing is complete, the integration goes live across the agreed-upon ad slots.

​
Example Request

When no Topsort demand is available for a banner slot enabled for GAM fallback, the auction endpoint returns a GAM snippet in the winner’s asset field. The retailer renders this snippet to display a GAM banner ad.
{
  "auctions": [
    {
      "type": "banners",
      "slots": 1,
      "slotId": "fake-slot-2",
      "products": {
        "ids": ["prod-a1b2c3d4"]
      }
    }
  ]
}

​
Example Response

{
  "results": [
    {
      "resultType": "banners",
      "winners": [
        {
          "asset": [
            {
              "content": "{\"type\": \"gam_snippet\", \"content\": \"<div id=\\\"gam-ad\\\"><script>googletag.cmd.push(function() { googletag.display(\\\"div-gpt-ad-12345\\\"); });</script></div>\"}"
            }
          ],
          "type": "url",
          "id": "https://www.example.com",
          "resolvedBidId": "PHRSCwoQBpvFL1sveOSZBCyVii_LCRIQAAAAAAAAAAAAAAAAAAAAABoQAAAAAAAAAAAAAAAAAAAAACIbChdodHRwczovL3d3dy5leGFtcGxlLmNvbRAFUIDQzO7O7_H__wFyEAAAAAAAAAAAAAAAAAAAAAA",
          "rank": 1
        }
      ],
      "error": false
    }
  ]
}
Each entry in the asset array contains a content field with a JSON string of type gam_snippet. The retailer should parse this content and render the embedded HTML/JavaScript to display the GAM banner.