This is the alternative method for integrating your catalog instead of passing the product feed. The benefit of using the catalog API is to support a large inventory system and making sure the products are always in sync regarding availability and related product information. If you would like a speedy integration or your marketplace does not have a large volume of inventory fluctuation, we recommend using the Product Feed to pass the catalog.

Before representatives from your company and your vendors are able to create ad campaigns, you must provide your catalog information to Topsort. In order to do this you need to create an API that follows Topsort's Catalog service reference API definition.

📘

If you are using Topsort's Magento 2 Extension, we've got you covered! The extension already provides the API for you.

Catalog API Overview

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 vendors 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.

Catalog API Reference Documentation

The Catalog API Reference definition is available here. A general overview of the definition can be found below.

📘

What do I need to implement?

• GET / (health check): returns 200 if the API service is available.
• POST /products: retrieves an array of matching products by IDs.
• GET /products/search: retrieves an array of matching products by search string, separated into pages.
• GET /categories: retrieves an array with all categories, separated into pages.
• GET /vendors: retrieves an array with all vendors, separated into pages.
• (optional) GET /brands: this endpoint is used to allow advanced use cases for Banner Ads. Talk to your Account Manager to understand whether you need to implement this endpoint.

❗️

Required

To complete the integration you must provide Topsort with the base URL of your catalog API implementation. E.g., if your categories endpoint is https://acme.com/api/categories, the base URL will be https://acme.com/api.

👍

We're here for support

If you need help implementing this service, please contact us. We can provide you with the needed scaffolding for your language or framework.