The example on this page shows how to run auctions for products originating from search results.

There are two ways to run these type of auctions:

  • Using the searchQuery parameter, where only bids that target products with matching keywords will have a chance to win such auctions.
  • Using a set of products and additionaly use the searchQuery parameter to expand the list of bids by adding products with matching keywords to the ones in the set of products.

​
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: using searchQuery

{
  "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.

​
Request: combining products and searchQuery

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": [
          "p_ojng4",
          "p_8VKDt",
          "p_Mfk15"
        ]
      }
      "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.

Products entering this auctions will be "p_ojng4", "p_8VKDt", "p_Mfk15" and those with a keyword matching the searchQuery.

​
Response

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

Notable comments:

  • 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.
  • The winner in rank 1 "p_Mfk15" comes from the set of product and rank 2 "p_PJbnN" comes from matching keywords since its id was not specified in the auction request.

Running auctions using the searchQuery parameter enhances Topsort to improve the Keywords Matching algorithm.

Using this type of auctions does not allow to use quality scores.

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

CategoriesCombining winners and organic results