Thank you for your interest in Topsort! This document will guide you through the process of integration with Topsort.

Architecture for Catalog API Integration

There's essentially 2 interfaces you need to familiarize yourself with: the Catalog API, which you will be implementing; and the Topsort API, which will be called from your backend. The Catalog API is used to retrieve product information so your vendorvendor - An organization running campaigns to promote products on the e-commerce site.s can add their products to ad campaigns in Topsort. The Topsort API is the interface through which you will run auctions in Topsort and notify events to Topsort for billing and analytics purposes.

Topsort Integration DiagramTopsort Integration Diagram

Topsort Integration Diagram

Integrating with Topsort requires 3 main components:

  1. Product Catalog
  2. Auctions Endpoint (/auctions)
  3. Events Endpoint (/events)

1. Product Catalog

We need access to catalog information in order to start running ad auctions. There are 2 ways in which you can share this with Topsort:

2. Auctions Endpoint

After setting the catalog, /auctions runs for specific categories and finds a winner out of all the vendors who bid and participated in the auction. Read more here.

3. Events Endpoint

/events is used to report impressions, clicks, and purchases to us. Topsort uses this information to calculate campaign statistics like CTR, CPC, ROAS, etc. Read more here.

Topsort's Integration is as follows:

  1. You can either pass Topsort the Product Feed or implement with the Catalog API as described in the Topsort Reference Catalog API.
  2. You integrate your marketplace with the Topsort API, specifically the /auctions and /events endpoints.
  3. Topsort runs the User Acceptance Tests (UAT) over your implementation regarding Catalog and Topsort API.
  4. We migrate the 2-side integration to your production environment, often we collocate to ensure high performance.
  5. Once we start receiving production data, we run some data integrity and end-to-end tests to make sure everything is ready.