Core Resources
The topi Seller API exposes endpoints for 4 core resources: offer, order, catalog, and shipping.
In this page, we'll go through each of these resources at a high level. For low-level details, see API Reference.
Offer
Offer status changes will trigger topi webhooks with the relevant payload to your configured URL. Learn how to setup webhooks.
What is an offer?
When a customer clicks on the "Rent with topi" button on any part of your ecommerce shop, you should make a backend POST request to the createOffer endpoint with your cart's products and other details. This creates an offer.
You can think of an offer as a frozen copy of your shop's cart on topi for a customer to checkout with. The business definition of offer is a legally binding agreement to provide products if accepted. Acceptance is typically unilaterally done by the buyer but can be subject to seller-set criteria.
On successful offer creation, topi will respond with a generated topi Hosted Checkout link in the payload, which you can use to redirect the customer. It should resemble this:
https://dashboard.topi.eu/offer/{offer_id}?token={token}
The Offer object
An offer object consists of:
- Items a customer wants to procure (rent or buy) through topi
- Contract terms: each item in the offer will have a selected contract terms attached to it (which will include for how long the item is rented). Each offer line has more than one contract term available, but only one set of selected ones
topi offers have a sales_channel attribute that is used internally by topi for determining certain sales-channel specific behaviours. If you are integrating with an ecom store, you should always set this value to ecommerce in your request payloads. For telesales integrators, use telesales, and for point-of-sale integrators, use in_store_pos.
Offer states
The offer.status keeps track of the status of an offer. Certain status changes will cause topi webhooks to be fired (learn more in Setting up Webhooks).
| Status | Description |
|---|---|
| accepted | The customer has accepted the offer and has passed topi's risk review. An offer in this state is ready to be processed by the seller. |
| created | A freshly created offer. |
| declined | The offer is declined due to customer-specific risk concerns. |
| expired | The offer has expired, as the customer has not accepted it in the allocated time. Expiry is automatically set by topi and varies by sales_channel. It is 24 hours for ecommerce and 7 days for telesales and in_store_pos. |
| pending_review | The customer has completed the checkout process and confirmed their order, but is currently under topi's risk review. |
| rejected (deprecated) | The offer is rejected by topi. In an earlier release of the API, we marked an offer as rejected before the fully automated risk checks were in place. This is not the case anymore and no new offers will reach this state. |
| voided | The offer is marked as invalid, either by topi or the seller. |
Offer status updates
Order
Order status changes also trigger topi webhooks with the relevant payload to your configured URL. Learn how to setup webhooks.
What is an Order?
topi conducts an automatic risk check of each customer, handling the complexity of fraud prevention on your behalf, before placing an order in both your system and ours.
When the customer accepts a topi offer and has successfully been risk reviewed by topi, topi will create an order on the basis of the offer.
topi will send a order.created webhook with relevant order information in the payload, which you can then use to update your ecom backend.
Order states
| Status | Description |
|---|---|
| acknowledged | The order has been sent to the seller and is acknowledged by the seller, thereby, validating it towards topi. The retailer also confirms that the order can be fulfilled. |
| canceled | The customer has canceled the order. Therefore topi cancels the order and all asset contracts are voided. Any cancellation from the customer at this point is accepted with goodwill by topi, as in theory, there is a legal obligation to comply with the concluded contract. |
| created | An offer has been created. The offer has reached the status of accepted by topi and the customer agrees to the terms and concludes the contract. E-commerce: items are added to the basket on the seller’s website and “buy or rent through topi” is selected |
| completed | All parts of the order have been fulfilled and all asset contracts are active. |
| confirmed | The seller confirms the order is ready for processing. The seller activates the asset contract. |
| partially_fulfilled | Only some parts of the order could be fulfilled. Others are still waiting for fulfillment. |
| rejected | The seller rejects the order. This can happen from the created or acknowledged state, typically if the order cannot be fulfilled or is invalid. |
Order status updates
Order cancellation
There are 2 ways an order can be cancelled after it has been placed:
- The customer emails topi to cancel the order
- The seller uses the Order API endpoint to cancel the order
Currently, a customer can either cancel an order in the shop or notify the retailer’s customer support. Use the rejectOrder order API endpoint to change the status of an existing order to order.rejected or notify the topi customer support via support@topi.eu
If a customer cancels the order with topi, we send a webhook to your configured URL so that you can update the order's status on your ecom backend.
In general, when an order is canceled, it cannot be changed anymore. If a customer requests topi to cancel the order after the shipment process has been completed, it needs to be handled as a return of the product.