Skip to content
Topsort Documentation
guides

End to end API example

Before diving in, it’s important to realize that this article describes just one situation. The Topsort platform is designed to support different use-cases and marketplace-vendor relationships.

In this tutorial you’ll play the role of marketplace owner. On your marketplace a variety of vendors sell different products.

Many of these vendors are interested in boosting their sales and promoting some of their products.

After a discussion with your team you decide there are two ways products can be promoted in your marketplace. You want to allow:

  • A maximum of 2 promoted products at the top of the search results.
  • A maximum of 4 promoted products in a highlighted section on the homepage.

To make this a fully functioning system, a number of components are required:

  1. A catalog of vendors, categories and products.
  2. A way for vendors to create and manage campaigns and make products available for promotion.
  3. Auctions to decide which products get to be promoted in the marketplace.

Finally, to calculate campaign performance it’s necessary to collect events like clicks and purchases (in a privacy-friendly manner of course).

The catalog

There are several ways for the catalog to be constructed. Topsort can:

  1. Pull data from product feeds.
  2. Automatically import products when they pass through the proxy.
  3. Receive product data from the APIs.

In this article we’ll use the API.

Every product always belongs to at least one vendor. By using the product upsert endpoint, we can populate vendors, products and categories in one go.

Example request

const apikey = "TSC_mykey";
const catalog = {
  products: [
    {
      active: true,
      categories: ["soft-drinks"],
      id: "example-product-coca-cola",
      imageURL:
      "https://intl.cokestore.com/media/catalog/product/1/6/16181_squeeze-ko-can-maria-2.png",
      name: "Coca Cola can",
      price: "9.99",
      vendors: ["coca-cola"],
    },
  ],
};

try {
  const response = await fetch("https://api.topsort.com/public/v1/catalog-search-service/catalogs/products", {
    method: "PUT",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(catalog),
  })

  if (!response.ok) return { stderr: response.status };
  return { stdout: response.status };
} catch (error) {
  console.error(error);
}
output
 
   

Campaigns


Next up, we need to create a campaign. The campaign will additionally hold the bids (products) that are available for promotion.
In this example we use the product we created in the previous request using the autoBidder.

 
Example request
  
 
 
const apikey = "TSE_mykey";
const campaign = {
  bids: [
    {
      target: {
        type: "product",
        id: "example-product-coca-cola"
      },
      "trigger": {
        type: "product",
        value: {
          matchType: "exact"
        }
      },
      amount: 1000
    }
  ],
  "budget": {
    type: "daily",
    amount: 10000
  },
  campaignType: "autobidding",
  isActive: true,
  status: "approved",
  adFormat: "listing",
  name: "An example campaign"
};

try {
  const response = await fetch("https://api.topsort.com/public/v1/campaign-service/campaigns", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(campaign),
    }
  )

  if (!response.ok) return { stderr: response.status };
  return { stdout: response.status };
} catch (error) {
  console.error(error);
}

 
 
 
    
 
  
 
 
output
 
 
   

Auctions


The marketplace needs to run an auction every time it wants to include promoted products in a request.


In this situation it will need to run auctions when the homepage is requested or when users search for products.


When an auction is run, Topsort will look at the triggered bids from the available campaigns and determine the ones that win.


Auctions are fully customizable.


For example, a search results auction request could look like this:

 
Example request
  
 
 
const apikey = "TSE_mykey";
const auction = {
  "auctions": [
    {
      "products": {
        "ids": [
          "example-product-coca-cola",
          "example-product-sprite",
          "example-product-fanta",
        ]
      },
      "slots": 1,
      "type": "listings"
    }
  ]
};

try {
  const response = await fetch("https://api.topsort.com/v2/auctions", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(auction),
  })

  if (!response.ok) return { stderr: response.status };
  return await response.json();
} catch (error) {
  console.error(error);
}
 
 
 
    
 
  
 
 
output
 
 
   

One important element is the resolvedBidId. This is an ID that Topsort provides and it identifies the winning bid.


When sending analytics events to Topsort, you will need to include this ID in order to attribute these events to the right campaigns.


Analytics


Now that an auction has been run, it’s important to keep track of the results. If a user ends up purchasing a promoted product, that sale needs to be attributed to the right campaign. This will allow vendors to track campaign performance.


There are three kinds of events that are tracked: Impressions, Clicks and Purchases.


Topsort provides several libraries for different platforms to make it easy to track these events.


    

  • Web: analytics.js
    • 

  • Android: analytics.kotlin
    • 

  • iOS: topsort.swift
    • 



As before, the API can also be used directly. This is also where the resolvedBidId comes in.


In the following example, a request is sent that contains a single impression, click and purchase that are all attributed to the first bid of our search results auction.

 
Example request
  
 
 
const apikey = "TSE_mykey";
const events = {
  "clicks": [
    {
      "id": "d0cf3f56-a719-4e02-9c88-625f965ae6e7",
      "occurredAt": "2024-07-23T11:49:04+00:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e2",
      "resolvedBidId": "ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw"
    }
  ],
  "impressions": [
    {
      "id": "6efafd0c-df0c-4872-a0e1-a18e07752e50",
      "occurredAt": "2024-07-23T11:48:04+00:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e2",
      "resolvedBidId": "ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw"
    }
  ],
  "purchases": [
    {
      "id": "44449170-63c8-43ba-a10e-1c9f776a0ecd",
      "items": [
        {
          "productId": "example-product-coca-cola",
          "quantity": 1,
          "unitPrice": 6.99
        }
      ],
      "occurredAt": "2024-07-23T11:50:04+00:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e2"
    }
  ]
};

try {
  const response = await fetch("https://api.topsort.com/v2/events", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(events),
  })

  if (!response.ok) return { stderr: response.status };
  return { stdout: response.status };
} catch (error) {
  console.error(error);
}

 
 
 
    
 
  
 
 
output
 
 
   

Summary


And with the sending of that event, we have gone concluded this guide. We discussed the basics of a Topsort integration, namely:


    

  • Importing a catalog.
    • 

  • Creating a campaign.
    • 

  • Running an auction.
    • 

  • Sending events to Topsort.
    • 



If you have any questions or comments, feel free to contact us.