Dispatch FAQ

Webhooks Deliverect sends you: each one carries an X-Server-Authorization-HMAC-SHA256 header, an HMAC-SHA256 signature of the request body. Check it before processing.

Calls you make to Deliverect: use a Bearer token from /oauth/token with the client credentials you were given.

A successful validation doesn't guarantee a booking. The usual reasons:

• The order failed in the POS. Deliverect doesn't create delivery jobs for failed orders.
• Another partner won. The location has several dispatch partners and a rule such as "always use the cheapest partner" picked another one. Don't treat a validation as a booking, and don't show the job to couriers until create_job arrives.
• Your answer didn't fit the location's dispatch settings. For example, a scheduled order whose pickup time falls outside the location's maximum pickup window.
• It was only an availability check. The ordering platform called Deliverect's pre-validation (/fulfillment/validate) and the customer never placed the order.

Send trackingUrl in your Update Delivery Job calls, starting with the first one. Support for returning it directly in the create_job response, so it reaches the ordering channel with the 81 "delivery created" update, is being added. Until then, send it as early as possible.

Deliverect cancels: when the merchant or the channel cancels the order, Deliverect calls your cancel_job webhook. Respond 200 if the job is cancelled, or 400 if it can't be cancelled any more (for example, the courier has already picked it up). Deliverect logs your response but doesn't act on it, so keep your side consistent.

You cancel: call POST /fulfillment/cancel with:

• deliveryJobId;
• a reasonTag: COURIER_NO_LONGER_AVAILABLE, COURIER_TRANSPORT_FAILURE, FOOD_ITEMS_ARE_NOT_READY, DROP_OFF_LOCATION_NOT_FOUND, CUSTOMER_UNRESPONSIVE or PACKAGE_SIZE_TOO_LARGE;
• deliveryFeeCharged, if a fee still applies;
• extraDescription

street can already include apartment or building details (merged into one line). Use the latitude/longitude provided, and read deliveryRemarks and phoneAccessCode for access instructions.