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

# Running auctions

> Learn how to use the auctions API to create auctions for listings and banners.

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>
    </>;
};

The auctions API enables you to create a wide variety of [auctions](/en/ad-server/auctions/auctions-api).

Whether you want to include sponsored listings in search results or banners on your homepage, we've got you covered.

## Before you begin

Before you're ready to use the auctions API, you need to:

1. [Obtain an API key](/en/api-reference/authentication#obtaining-an-api-key) to authenticate.
2. [Create several campaigns](/en/knowledge-base/ad-platform/campaign-creation/), to have bids available for the auctions.

<Warning>
  **Ensure your campaigns have sufficient budget!** The most common reason for empty auction results is budget exhaustion. Campaigns with zero remaining budget cannot participate in auctions, leading to no winners. Check your campaign budgets before testing auctions.
</Warning>

## Request

The `/auctions` endpoint allows you to run up to 5 auctions in one request.

The full spec for this endpoint [is found here](/en/api-reference/auctions/create-auctions).

This can be quite a lot to take in at once, so let's stick to the basics now.

Every request body should be provided as JSON and is generally structured as follows.

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2
    },
    {
      "type": "banners",
      "slots": 1
    }
  ]
}
```

There are several interesting things about this (incomplete) snippet:

* Auctions are provided as an array to the `auctions` field. You can provide 1 to 5 auctions in a single request.
* Each auction has a `type` that will determine whether it's auctioning listings or banners.
* Each auction has a `slots` field, this determines the maximum number of winners of the auction.

To complete the above snippet you will need to add more fields, check out the [sponsored listings example](/en/api-reference/examples/sponsored-listings/set-of-products) or [sponsored banners example](/en/api-reference/examples/sponsored-banners/banners) for more information.

## Response

<Warning>
  **Do not cache this response** or it's results. Auctions need to be unique per page view, this is what makes the system work.

  If the auction results are cached, the same results could be shown to multiple users or to the same user multiple times.
</Warning>

If there are no [request errors](https://topsort.mintlify.app/api-reference/errors), the auctions endpoint will return the results for each auction.

A successful response does not mean that each auction succeeded or has winners. You will need to check the results to determine this.

### Response with winners

Suppose that both auctions in the earlier request result in winners, the response could look something like this:

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": "2",
          "resolvedBidId": "WyJlX1hKYm5OIiwiMTNiNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJzb21lLXNsb3QiLCIxM2I1NTgyOC04ZWFkLTQyOTktODMyNy1jZWJiMDAyYTBmYTgiLCJiYW5uZXJzIiwiZGVmYXVsdCIsIiJd=="
        }
      ],
      "error": false
    }
  ]
}
```

Things to note about this response:

* Auction results are under a top level `results` property.
* The order of the results corresponds to the order of the auctions.
* Each result has an array of winners. This array can be empty and it will never be more than the `slots` of the auction.
* It's possible for auctions to fail/succeed independently. The `error` flag indicates whether an auction succeeded.

### Empty Winners Array

If `winners` is empty (`[]`), common causes include:

* **Budget exhausted:** Campaigns have spent their daily/total budget
* **No active campaigns:** No campaigns are targeting the auction context
* **Bid too low:** Campaign bids are below auction floor prices
* **Product mismatch:** Campaign products don't match auction criteria

The exact fields on the winners depend on the type of the auction, but they will always have:

* `rank` a 1-based number corresponding to its position in `winners`.
* `resolvedBidId` identifying the bid that made this winner win. This ID is used to relate the bid to events.

### Response without winners

It's not guaranteed that an auction will result in winners. If there are no active campaigns that match it's criteria, there won't be any bids to place.

If our earlier auction request did not have any winners for either auction, it's response will look something like this:

```json theme={null}
{
  "results": [
    {
      "winners": [],
      "error": false
    },
    {
      "winners": [],
      "error": false
    }
  ]
}
```

Note that this response still contains results for both auctions.

## Further reading

Check out the other pages in this section to see complete examples for different use cases.

<LastUpdated date="2026-01-06" />