Sponsored listings in search results

The example on this page shows how to run auctions for products matching search terms.

Only bids that target products with matching keywords will have a chance to win such auctions.

Use cases

Running these kind of auctions on search pages will allow your vendors to promote products inside the search results.

Example API call

Request

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "searchQuery": "Running shoes"
    }
  ]
}

The request above will create a single listings auction:

• It will have a maximum of two winners due to the slots field.
• The searchQuery field determines what keywords bid targets must have.

Only bids that target products with the Running shoes keyword can take part in this auction.

Response

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "type": "product",
          "id": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "type": "product",
          "id": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    },
  ]
}

Notable here:

• The type of the winners is product, because we’re running a listings auction.
• There are two winners, the maximum that is allowed by the slots field in the request.

Next steps

The winners will need to be combined with product data to a create a result that can be shown to the end-user.

Check this page for an example.