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.

​
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 a create a result that can be shown to the end-user.

Check this page for an example.

Running auctionsCategories