Skip to main content

Overview & prerequisites

How to read this guide

This Integration Guide is a step-by-step walkthrough spread over several pages. If you are integrating with topi for the first time, we recommend reading it in order.

Welcome to the topi seller Integration Guide. This guide covers the backend integration with the topi Seller API: syncing your catalog, getting rental prices, creating offers, receiving and fulfilling orders, and handling webhooks.

topi supports three sales channels: eCommerce, telesales, and in-store point of sale. The Seller API can be used in all of them, and this guide applies to any channel.

If you sell online and want ready-made UI, see topi Elements, our JavaScript library that renders rental prices and a checkout button on your storefront so you do not have to build that frontend yourself.

How the integration fits together​

Your integration has two parts: a one-time setup, and a flow that runs on every transaction.

Phase 1 - Set up once

  1. Authenticate with the Seller API.
  2. Sync your catalog so topi can compute rental prices for your products.
  3. Set up shipping methods so offers can carry a shipping price.
  4. Set up webhooks so your systems receive real-time updates.

Phase 2 - On every transaction

  1. Get rental prices and check whether a basket can be checked out with topi.
  2. Create an offer and send the customer to the topi Hosted Checkout.
  3. topi runs a risk review. On approval, the offer becomes an order.
  4. Receive and fulfil the order, then create shipments.

Phase 3 - Reconcile & test

  1. Record the order in your systems, with topi as the payment method.
  2. Test end-to-end in the sandbox before going live.

What you need before you start​

  • API credentials. A client_id and client_secret, provided by your topi point of contact. See Authentication.
  • A product catalog. The list of products you sell, which topi uses to compute rental prices. This is typically exported from your commerce backend or ERP as CSV or JSON. See Syncing your catalog.
  • Your shipping methods. The delivery options you offer (for example DHL Standard or UPS Express), which you register with topi so offers can carry a shipping price. Needed if you ship physical goods. See Setting up shipping methods.
  • A server endpoint for webhooks. A URL topi can send HTTP requests to for real-time updates on offers and orders. Your endpoint must respond with a 2XX status to acknowledge receipt. See Setting up Webhooks.

You can integrate with topi even without an ecommerce store. As long as you have a commerce backend (for example an ERP such as SAP or Microsoft Dynamics), you can use the Seller API directly. If you do not maintain your own catalog, topi can provide a central catalog to get you started: reach out to your topi point of contact.