Skip to main content
The proxy is a middle layer between the marketplace backend and the results server (Algolia’s server, for example). It acts as a bridge between the marketplace, the search engine and Topsort. This allows the proxy to ingest auction winners retrieved from Topsort into the response provided by the search engine, and return the final merged response to the marketplace. The proxy is compatible with most tech stacks, and it has been tested with platforms like VTEX, Algolia, and Salesforce.

​
How to Use the Proxy

To start using the proxy, you only need to change the hostname in your existing API call, from your catalog or search engine to our proxy. For example, change from: 
https://api.site.com/catalog/query?taxonomy=clothes
to: 
https://site.proxy.topsort.com/catalog/query?taxonomy=clothes
And we take it from there. We send the request to Topsort’s auction engine and to the catalog or search engine. If any of the products returned by the catalog or search engine is promoted, we will indicate it in the merged response we’ll build, which will be returned to the marketplace. Currently, the proxy supports application/json responses. Support for XML and GraphQL is planned.

​
How Promoted Products Are Added

Consider the following request, which fetches products from the ‘office’ taxonomy: 
GET https://api.site.com/catalog/query?taxonomy=office
The response from the catalog or search server without Topsort’s proxy integration: 
{
  "products": [
    { "id": "1", "name": "High-Speed Color Laser Printer" },
    { "id": "2", "name": "Adjustable Height Standing Desk" },
    { "id": "3", "name": "Ergonomic Swivel Office Chair" },
    { "id": "4", "name": "Wireless Keyboard and Mouse Combo" },
    { "id": "5", "name": "Magnetic Whiteboard with Marker Set" }
  ]
}
After merging promoted products into the response: 
{
  "products": [
    {
      "id": "3",
      "name": "Ergonomic Swivel Office Chair",
      "rank": 1,
      "resolvedBidId": "..."
    },
    {
      "id": "6",
      "name": "Multi-drawer Filing Cabinet",
      "rank": 2,
      "resolvedBidId": "..."
    },
    { "id": "1", "name": "High-Speed Color Laser Printer" },
    { "id": "2", "name": "Adjustable Height Standing Desk" },
    { "id": "4", "name": "Wireless Keyboard and Mouse Combo" }
  ],
  "topsort": {
    "winners": [
      { "rank": 1, "type": "product", "id": "3", "resolvedBidId": "..." },
      { "rank": 2, "type": "product", "id": "6", "resolvedBidId": "..." }
    ]
  }
}

​
Understanding the New Fields

  • rank: The position of the promoted product in the auction.
  • resolvedBidId: A unique ID used to track the product in analytics.
A new object named topsort is added at the root level only when promoted products are included.

​
How to Track Events

If you use Topsort’s analytics.js library or Events API, use the product id and resolvedBidId fields to track user interactions: 
<div class="product" data-ts-product="3" data-ts-resolved-bid="resolvedBidId">
  ...
</div>

​
Proxy Features

  • Response Caching: Reduces latency by caching successful responses from the catalog or search engine.
  • Staging Mode: Allows testing before going live.
  • Catalog Sync Support: Sends information to keep Topsort’s catalog up to date.
  • Built-in Logging: Collects data on products, auctions, and performance.