Use the auction-based sponsored listings process by calling the /auctions endpoint after identifying products for display. This initiates auctions among eligible products, returning winners for display on various pages.

Integrate sponsored listings by identifying pages and slots, then call the /auctions endpoint for eligible products. Run auctions for various listings and ads, like brands, hotels, or concerts.

No session information required.
Run up to 5 auctions of 2 types in one request.
One failed auction doesn't affect others.
Required variables: type, slots, productId

Variable	Type	Description
type	string	Specifies type of auction: listing or banner
slots	integer	Specifies the maximum number of auction winners that should be returned
productId	array of strings	An array of strings, each describing a product ID that should participate in the auction. (Can include up to 10,000 items)

Request

Example API V2 JSON request:

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": [
          "p_PJbnN",
          "p_ojng4",
          "p_8VKDt",
          "p_Mfk15"
        ]
      },
      "geoTargeting": {
        "location": "New York"
      }
    },
    {
      "type": "banners",
      "slots": 1,
      "aspectRatio": "4:1",
      "category": {
        "id": "c_yogurt"
      }
    }
  ]
}

Response

The response includes auction results, ordered by bid. Empty if no qualifying bids or errors occur. A boolean variable, error, indicates auction success.

Example API V2 JSON response:

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "product",
          "winnerId": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "winnerType": "product",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "product",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
          "asset": [
            {
              "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
            }
          ]
        }
      ],
      "error": false
    }
  ]
}