Receiving and fulfilling orders
When a customer's offer is accepted after the risk review, topi creates an order and sends you an order.created webhook. From this point, topi is effectively buying the devices from you and you fulfil the order. This page covers what you do with an order once you receive it.
For the full list of order statuses, see Core Resources: Order.
The fulfilment flow
1. Receive the order
When the order.created webhook arrives, record the order in your systems. Match it to your original offer using seller_offer_reference, which is carried through from offer to order. The webhook payload includes the order id, its assets (the individual items to fulfil), and the shipping address. See Recording orders in your systems for how to record the order against the right customer.
2. Acknowledge the order
Call acknowledgeOrder (POST /v1/orders/{id}/acknowledge) to confirm to topi that you received the order. This moves the order to acknowledged.
3. Accept the order
Call acceptOrder (POST /v1/orders/{id}/accept) to confirm the order can be fulfilled. This moves the order to confirmed and activates the rental contracts. You can accept from either created or acknowledged.
4. Ship the items
As you dispatch items, report each shipment with createShipment. topi tracks fulfilment as you go: once some but not all items are shipped, the order is partially_fulfilled; once everything is shipped, it becomes completed. See Creating a shipment for serial numbers, partial shipments, and tracking URLs.
Rejecting an order
If you cannot fulfil an order, call rejectOrder (POST /v1/orders/{id}/reject). This moves the order to rejected. You can reject from created or acknowledged, but not after the order is confirmed.
Rejection vs cancellation
These are two different things, driven by two different parties:
- Rejection is initiated by you, the seller, through the
rejectOrderendpoint, when you cannot fulfil the order. There is no separate seller "cancel" endpoint. - Cancellation is initiated by topi or the customer (for example, the customer asks topi to cancel). You are notified with an
order.canceledwebhook; you do not call an endpoint for this.
In general, once an order is canceled or rejected it cannot be changed. If a customer asks to cancel after shipment has completed, it is handled as a return of the product rather than a cancellation.