By using our API to plan deliveries you can enable your customers to schedule a delivery while finalizing a purchase on your website. This reduces the number of times you have to interact with your customers and offers a nice and integrated experience.
Overview
- Setup in Urbantz
- API Documentation
- Process
1. Setup in Urbantz
Planning deliveries by API requires the existence of a Flow of type Planning. You can find detailed information in this article.
2. API Documentation
Our API documentation is available here and includes four sections called "Get timeslots" and "Reserve a timeslot", "Confirm a reservation" and "Cancel a reservation" that are relevant for scheduling by API. Please refer to the API documentation for technical aspects.
3. Process
The below illustration shows the general process of scheduling by API.
Your service can, for example as part of the checkout, send a request for timeslot ("Get timeslot") availability to Urbantz. This request needs to contain certain parameters as specified in our API documentation. Urbantz will return a list of available timeslots with a set of information amongst which a timeslotiD & configuration, hub, start and stop properties that need to be used later on to book a timeslot, as well as information on the capacity that is already used.
Booking a timeslot ("Reserve a timeslot") is the next step. At this stage, capacity will be reserved but no task will be created. Urbantz will return amongst others a "booking ID" (timeslotReservationId) corresponding to the chosen slot which will need to be used to initiate the task creation.
ℹ️ Bookings are not displayed in Urbantz, information is only available using API requests.
Once your customer finalized the purchase on your website you can proceed to a regular task announcement ("Confirm a reservation") with the "booking ID" being a piece of additional information that needs to be provided. The booking will be transformed into an actual task, and the usual methods for changing task properties apply from here on (discard, update...).
❗️ If the purchase process is dropped by your customer, timeslots need to actively be released ("Cancel a reservation") using the booking ID, otherwise, capacity will be blocked. There is no automatic release process.
ℹ️ If wanted, a reservation can be forced to overload a slot, for example, if several customers try reserving the same slot but there is only capacity for one. This parameter is by default false, change it to true if operationally speaking you have the capacity overload slots.
See also our API documentation about Timeslot booking here article.