Sponsored listings from a set of products

How to run an auction for a set of products

In this example we will use the API to run an auction for a set of products.

Only bids that target the products in this set will have a chance to win this auction. Bids that target other products will not participate.

This allows you full control over which products get shown where, while still enabling your vendors to promote products.

Use cases

We don’t prescribe how you create your set of products, you can use any algorithm you desire. All we need is a list of product IDs.

For example, use your own algorithm to generate:

• Cross-sells.
• Related products.
• Checkout upsells.

Collect the resulting IDs and pass them to an auction.

Your vendors will then be able to bid for opportunities to appear in valuable positions in the marketplace.

Example API call

Request

Let’s assume we use some kind of algorithm to create a set of product IDs. We can then pass them to an auction request:

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"]
      }
    }
  ]
}

The request above will create a single listings auction:

• It will have a maximum of two winners due to the slots field.
• The products.ids is the set of products. These need to exist in your catalog.

As said before, only bids that target these products will participate in the auction.

The auction endpoint supports up to 10000 product IDs per auction, but we recommend sending no more than the 500 most relevant.

Adding custom quality scores

You may sometimes want to incorporate custom quality scores for each product. The quality score is a number between 0 and 1 that encodes the relevance of the participating products. The use of quality scores helps mitigate risks and losses due to non-relevant products winning auctions.

To include custom quality scores in the request, modify the products field as shown below:

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"],
        "qualityScores": [0.5, 0.4, 0.7, 0.6]
      }
    }
  ]
}

In this example:

• Product p_PJbnN has a quality score of 0.5.
• Product p_ojng4 has a quality score of 0.4.
• Product p_8VKDt has a quality score of 0.7.
• Product p_Mfk15 has a quality score of 0.6.

Important: The number of quality scores must match the number product IDs. If they do not match, the request will fail.

Caveat: You cannot include quality scores and a search query. While running an auction with a search query and a set of products is allowed, the request cannot include custom quality scores.

Filtering by product attributes

You may want to restrict the auction further, to products with specific attributes. Add a filter field to do so:

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"]
      },
      "filter": {
        "operator": "and",
        "attributes": ["brand:nike", "color:black"]
      }
    }
  ]
}

In this example:

• The operator is and, so an ad only participates if its product has both the brand:nike and the color:black attributes. Use or instead to keep ads matching any of the attributes.
• The attributes are key:value strings. You can provide up to 5 of them.

The filter is applied on top of products.ids, never instead of it. A bid needs to target one of the four products and match the attributes to have a chance of winning. Non-matching ads are removed before ranking, so they never win and are never charged.

Attribute filtering requires additional integration and configuration. Contact your Topsort representative to enable it.

See Filtering auctions by attributes for the full rules and limits.

Response

Do not cache this response or its 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.

If bids targeting the products exist, they could win this auction. The resulting response would look something like this:

{
  "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.
• Both winning id correspond to a product ID in the request.
• 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 create a result that can be shown to the end-user.

Check this page for an example.