The examples on this page show how to run auctions for products belonging to specific categories.

Only bids that target products belonging to the given categories will have a chance to win these auctions. Bids targeting products that belong to other categories will not participate.

​
Use cases

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

Non traditional categories:

Our catalog system does not make any assumption about what a category is.

If your marketplace deals with vacation homes for example, categories could be geographic locations instead of product groups.

​
Specifying categories

The /auctions endpoint supports several ways to specify categories.

When you create an auction, you must pick one of the following methods:

MethodRelevant fieldDescription
Single categorycategory.idBid targets must belong to the category. The id of category is the same value used when upsert product.
All categoriescategory.idsBid targets must belong to all of the categories.
Disjunctionscategory.disjunctionsBid targets must belong to one of the categories of each disjunction.

Let’s look at some examples.

​
Example API calls

​
Request: Single category

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "laptop_bags"
      }
    }
  ]
}

The request above will create a single listings auction that:

  • Has a maximum of two winners due to the slots field.
  • Only allows bids that target products in a single category. The category ID is specified in the category.id field.

In this case, only bids that target products in the laptop_bags category can take part in the auction.

​
Request: All categories

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "ids": ["summer_hats", "sale"]
      }
    }
  ]
}

The request above will create a single listings auction that:

  • Has a maximum of two winners due to the slots field.
  • Only allows bids that target products that belong to all categories. The category IDs are specified in the category.ids field.

This field is plural. It’s called ids, not id.

Only bids that target products that belong to both the summer_hats and the sale categories can take part in this auction.

​
Request: Disjunctions (“at least one category”)

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "disjunctions": [
          [
            "large",
            "medium"
          ],
          [
            "red",
            "blue"
          ]
        ]
      }
    }
  ]
}

The request above will create a single listings auction that:

  • Has a maximum of two winners due to the slots field.
  • Only allows bids that target products that belong to one of the categories for each disjunction. The disjunctions are specified as string arrays in the category.disjunctions field.

Only bids that target products that are in large or medium, and, red or blue categories can participate in this auction.

This means, products with the following combinations of categories:

  • large and red.
  • large and blue.
  • medium and red.
  • medium and blue.

​
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 the bids targeting products in the appropriate categories exist, a response to any of the above requests could 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.
  • 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.

Set of productsSearch