> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sponsored Listing Demand Mediation

> Bring external sponsored listing bids into Topsort auctions

export const LastUpdated = ({date, lang = "en"}) => {
  const translations = {
    en: "Last updated:",
    es: "Última actualización:",
    pt: "Última atualização:",
    fr: "Dernière mise à jour:",
    de: "Zuletzt aktualisiert:"
  };
  const label = translations[lang] || translations.en;
  return <>
<style>{`
.last-updated-component {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 10px 16px;
border-radius: 8px;
margin-top: 12px;
margin-bottom: 16px;
font-size: 14px;
background-color: rgba(0, 0, 0, 0.05);
border: 1px solid rgba(0, 0, 0, 0.12);
color: rgba(0, 0, 0, 0.75);
line-height: 1;
}

        .last-updated-component svg {
          flex-shrink: 0;
          vertical-align: middle;
        }

        .last-updated-component span {
          display: inline-flex !important;
          align-items: center !important;
          line-height: 1 !important;
        }

        [data-theme="dark"] .last-updated-component {
          background-color: #3a3a3a;
          border: 2px solid #888888;
          color: #ffffff;
        }

        [data-theme="dark"] .last-updated-component svg {
          stroke: #ffffff;
        }
      `}</style>
      <div className="last-updated-component">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <circle cx="12" cy="12" r="10" />
          <polyline points="12 6 12 12 16 14" />
        </svg>
        <span>
          <strong style={{
    fontWeight: 600
  }}>{label}</strong> 
          <time dateTime={date}>{date}</time>
        </span>
      </div>
    </>;
};

### What is Sponsored Listing Demand Mediation?

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  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.
</div>

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  The first third-party demand source integrated is <strong>Criteo</strong>, 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.
</div>

<Note>
  Topsort can easily accommodate other demand sources beyond Criteo, as long as
  their bids can be sent via the <code>demandSources</code> parameter of the
  auction endpoint.
</Note>

### How Billing Works

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  With demand mediation using Criteo:
</div>

* 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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  Retailers can generate additional ad revenue through demand mediation:
</div>

* **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?

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  While any client can add Criteo demand, this integration is most relevant for
  clients likely to attract significant Criteo ad spend:
</div>

* **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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  To onboard a marketplace with demand mediation:
</div>

<Steps>
  <Step title="Set up placements in Criteo">
    The marketplace should configure any placements they want to bring in Criteo
    demand for in their Criteo account.
  </Step>

  <Step title="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
  </Step>

  <Step title="Handle auction response">
    Topsort returns the winning bids, which may include both Topsort and Criteo
    winners.
  </Step>

  <Step title="Report events">
    If there are Criteo winners, the marketplace should report events to both
    Topsort and Criteo.
  </Step>
</Steps>

### API Implementation

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  The <a href="/en/api-reference/auctions/create-auctions">auctions endpoint</a>{" "}
  has been extended to support external demand sources. Adding external demand
  requires one new input field and two new response fields for auction winners.
</div>

<Note>
  The number of external bids is limited to 100 per auction request.
</Note>

#### Request Changes

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  A new <code>demandSources</code> field has been added to the auctions object:
</div>

* **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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  Each <code>Bid</code> object contains:
</div>

* **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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  The <code>Winner</code> object has been updated with:
</div>

* **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.

<Note>
  For external bids, the `campaignId` field will be omitted from the winner
  object.
</Note>

#### Error Cases

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  New error cases specific to demand mediation:
</div>

* 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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
    }
  ]
}
```

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  For more information on the auctions API, see the{" "}

  <a href="/en/api-reference/auctions/create-auctions">
    Create Auctions API Reference
  </a>
</div>

***

<LastUpdated date="2026-03-19" />