End-to-End API Example

This example demonstrates a full flow using Topsort’s APIs for a sponsored product campaign with category targeting. Replace API keys and IDs with your actual credentials and values.

Steps:

1. Sync catalog
2. Create a campaign
3. Send auction requests
4. Track events
5. Get report

Note

• For managing products, campaigns, and reports, use an Advanced API Key (TSC_…).
• For auctions and events, use a Marketplace API Key (TSE_…).

1. Sync Catalog

   A sample product example-product-coca-cola, from category soft-drinks is used in this example. Remember to use your Advanced API Key.

   const apikey = "TSC_...";
   
   const body = {
     "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(body),
     })
     if (!response.ok) {
       console.error("unexpected status: " + response.status);
     } else {
       console.log("success status: " + response.status);
     }
   } catch (error) {
     console.error(error);
   }

2. Create Campaign

   In this example, a campaign is created to promote the product example-product-coca-cola, having a keyword trigger (soft drink). Remember to use your Advanced API Key.

   const apikey = "TSC_...";
   
   const body = {
     "bids": [
       {
         "target": {
           "type": "product",
           "id": "example-product-coca-cola"
         },
         "triggers": [
           {
             "type": "keyword",
             "value": {
               "matchType": "exact",
               "words": [
                 "soft drink"
               ]
             }
           }
         ]
       }
     ],
     "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?vendor_id=demo-vendor", {
       method: "POST",
       mode: "cors",
       headers: {
         Authorization: `Bearer ${apikey}`,
         "Content-Type": "application/json; charset=utf-8",
       },
       body: JSON.stringify(body),
     })
     if (!response.ok) {
       console.error("unexpected status: " + response.status);
     } else {
       console.log("success status: " + response.status);
     }
   } catch (error) {
     console.error(error);
   }

3. Send Auction Request

   In this example, an auction request is created to return winners triggered by the search term “soft drink”. Remember to use your Marketplace API Key.

   const apikey = "TSE_...";
   
   const body = {
     "auctions": [
       {
         "searchQuery": "soft drink",
         "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(body),
     })
     if (!response.ok) {
       console.error("unexpected status: " + response.status);
     } else {
       console.log("success status: " + response.status);
     }
   } catch (error) {
     console.error(error);
   }

4. Tracking Events

   In this example, a click on a promoted product is tracked using our API. The resolvedBidId of the winner returned by the auctions call needs to be sent in the body of the request, to guarantee correct attribution of sales. Remember to use your Marketplace API Key.

   const apikey = "TSE_...";
   
   const body = {
     "clicks": [
       {
         "id": "d0cf3f56-a719-4e02-9c88-625f965ae6e7",
         "occurredAt": "2024-07-23T11:49:04+00:00",
         "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e2",
         "resolvedBidId": "ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw"
       }
     ]
   };
   
   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(body),
     })
   
     if (!response.ok) {
       console.error("unexpected status: " + response.status);
     } else {
       console.log("success status: " + response.status);
     }
   } catch (error) {
     console.error(error);
   }

5. Tracking Events

   In this example, a click on a promoted product is tracked using our API. The resolvedBidId of the winner returned by the auctions call needs to be sent in the body of the request, to guarantee correct attribution of sales. Remember to use your Marketplace API Key.

   const apikey = "TSE_...";
   
   const body = {
     "clicks": [
       {
         "id": "d0cf3f56-a719-4e02-9c88-625f965ae6e7",
         "occurredAt": "2024-07-23T11:49:04+00:00",
         "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e2",
         "resolvedBidId": "ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw"
       }
     ]
   };
   
   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(body),
     })
   
     if (!response.ok) {
       console.error("unexpected status: " + response.status);
     } else {
       console.log("success status: " + response.status);
     }
   } catch (error) {
     console.error(error);
   }