Category

To add sponsored listings on category pages, request a category auction instead of sending individual product IDs. Topsort will conduct auctions for products within the requested category/categories and provide the winners.

Advertisers can display products in related categories such as "laptop backpack" ads in "laptop bags," "messenger bags," or "eco-friendly" categories. Topsort can easily accommodate auctions for single, multiple, or disjunction categories.

1. Single Category
2. Multiple Categories (products in all categories)
3. Disjunctions (products in at least one category)

For example, requesting an auction with the "laptop bags" category ID will return participating products in that category.

To request auctions for products in multiple categories simultaneously, such as "laptop bags" and "eco-friendly products," send the category IDs and select the 'ids' parameter in the Auction API.

For disjunctions, such as "laptop bags" and "messenger bags," Topsort will return products belonging to either category.

Alternatively, send an array of product IDs displayed on the category page in an auction request, and Topsort will return the winning product IDs. Remember to include category pages in the auction or event implementation request.

📘

Keep in mind that you can request up to 5 auctions in a single request

For multiple categories, you need to provide an array of the category_ids

Request Example - Single Category

To enter the auction for a single category, specify the category ID of the products you want.

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

Response for a Single Category Auction Request

Here's an example of the response for a call with the auction request for one category using the API V2 in JSON format.

These winning products belong to the category specified in the auction request.

{
  "results": [
    {
      "winners": [   // winner details
      ],
      "error": false
    }
  ]
}

Request Example - Category Disjunctions

Example request for sponsored listings on category pages requires bid products to belong to at least one category in each provided disjunction, e.g., medium & red, large & red..

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "disjunctions": [
          [
            "c_large",
            "c_medium"
          ],
          [
            "c_red",
            "c_blue"
          ]
        ]
      }
    }
  ]
}

Response Example - Category Disjunctions

Example response for a single auction request using API V2 in JSON format includes winning products from at least one category in each disjunction.

{
  "results": [
    {
      "winners": [   // winner details
      ],
      "error": false
    }
  ]
}