Overview
Every Service on MotionTools progresses through different statuses during its lifecycle. It’s critical to understand the meaning of each status, as available actions and features, as well as visibility, are directly related to or restricted by the status.
A Service in the form of a booking from customer or a tour for drivers doesn’t necessarily go through all available statuses. Some statuses may be skipped during transitions. For example, if a operator hasn’t enabled payments, a booking will never enter the Processing Payment status.
If you are developing integration with MotionTools, note that the status names shown on the Dashboard may differ from the names used in the API. To receive notifications for every status change, you can subscribe to the corresponding webhook event.
- On Hold
- Scheduled
- Dispatched
- Partially dispatched
- Claimed
- Pickable
- En Route
- Done
- Processing payment
- Paid
- Cancelled
On hold
to_be_dispatched
An On Hold status indicates that a booking isn’t visible to drivers. This status allows Admins and Organization Managers to prepare a booking for a driver. For example, decide whether they should merge it with another booking or hand it over “as is”.
On Hold is also the initial status of all bookings if the Manual Dispatching feature is enabled for a service of a booking.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| On Hold → Scheduled | schedule |
A booking is released from On Hold |
| On Hold → Dispatched | dispatch |
All stops of a booking were merged into tours |
| On Hold → Cancelled | partially_dispatch |
Some stops of a booking were merged into tours |
| On Hold → Cancelled | cancel |
A booking was cancelled |
Scheduled
scheduled
A Scheduled status indicates that a booking has been scheduled for a future date and time and is currently available for drivers to claim.
This is also the initial status of all bookings if the Manual Dispatching feature is disabled for a service of a booking. Note that newly created bookings of type Instant will immediately transition to either Looking for Drivers or Pickable status, while bookings of type Scheduled will remain in the Scheduled status.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Scheduled → On Hold | revoke |
A booking was put back On Hold |
| Scheduled → Claimed | claim |
A driver accepted a booking or a booking was force-assigned |
| Scheduled → Pickable | ready_to_pick |
No drivers accepted a booking until the specified time and the Pickable booking feature is enabled for the service of a booking |
| Scheduled → Cancelled | cancelled |
A booking was cancelled |
Dispatched
dispatched
A Dispatched status indicates that all stops of a booking were distributed between one or multiple tours. The booking will transition straight to Done as soon as all stops are completed unless any stops fail. A booking won’t transition through the En Route status.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Dispatched → Done | complete_stops |
All stops of a booking were completed via corresponding tours |
| Dispatched → Scheduled | undispatch_stops |
All stops of a booking were undispatched, and the Manual Dispatching feature is disabled for the service of a booking |
| Dispatched → On Hold | undispatch_stops |
All stops of a booking were undispatched, and the Manual Dispatching feature is enabled for the service of a booking |
| Dispatched → On Hold | complete_stops |
A booking was operationally completed, but all stops failed |
| Dispatched → Partially Dispatched | undispatch_stops |
Only some stops of a booking were undispatched |
| Dispatched → Partially Dispatched | complete_stops |
A booking was operationally complete, but some stops failed |
| Dispatched → Cancelled | cancel |
A booking was cancelled |
Partially dispatched
partially_dispatched
A Partially Dispatched status indicates that only some of its stops were distributed between tours or that a booking has failed stops.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Partially Dispatched → Dispatched | dispatch |
The remaining stops were distributed between tours |
| Partially Dispatched → Scheduled | undispatch_stops |
All stops of a booking were undispatched, and the Manual Dispatching feature is disabled for the service of a booking |
| Partially Dispatched → On Hold | undispatch_stops |
All stops of a booking were undispatched, and the Manual Dispatching feature is enabled for the service of a booking |
| Partially Dispatched → Cancelled | cancel |
A booking was cancelled |
Claimed
claimed
A Claimed status indicates that a driver has accepted a booking scheduled for a future date and time. The driver is now responsible for starting the booking at the scheduled time.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Claimed → En Route | start |
A driver started a claimed booking |
| Claimed → Scheduled | unclaim |
A driver rejected the previously claimed booking |
| Claimed → Scheduled | release |
A booking was rejected on behalf of a driver because it wasn’t started on time |
| Claimed → On Hold | revoke |
A booking was put back On Hold |
| Claimed → Cancelled | cancel |
A booking was cancelled |
Pickable
pickable
A Pickable status indicates that an Instant booking is visible to all eligible drivers within the service area of the booking. Any eligible driver can now start the booking.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Pickable → En Route | pick |
A driver started a booking, or they were force-assigned |
| Pickable → On Hold | revoke |
A booking was put back On Hold |
| Pickable → Cancelled | cancel |
A booking was cancelled |
En Route
en_route
An En Route status indicates that a driver is carrying out a booking now. A booking in this status can also be referred to as an Active Booking.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| En Route → Done | complete_stops |
A booking was operationally completed without any failed stops |
| En Route → Partially dispatched | complete_stops |
A booking was operationally completed, but some stops failed |
| En Route → On Hold | complete_stops |
A booking was operationally completed, but all stops failed |
| En Route → Scheduled | ditch |
A booking was rejected by a driver |
| En Route → Paid | force_end |
A booking was force-ended |
| En Route → Cancelled | cancel |
A booking was cancelled |
Done
done
A Done status indicates that a booking has been operationally completed, i.e., all stops of the booking were completed by a driver.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Done → Processing payment | process_payment |
The platform started processing payment after a booking is completed operationally |
| Done → Paid | paid |
If a tenant doesn’t have payments enabled, a booking transitions to Paid after it’s completed operationally |
Processing payment
processing_payment
A Processing Payment status indicates that we are waiting for the payment to be received. Depending on the payment method selected for the booking, this process can be finalized automatically or may require manual confirmation by an Admin. For instance, invoice payments always require manual confirmation, whereas credit card payments will be resolved automatically unless a card charge fails.
| Available transition | Transition name on API | Trigger |
|---|---|---|
| Processing payment → Paid | paid |
A payment was confirmed automatically, or an Admin marked a booking as paid manually |
| Processing payment → Cancelled | cancel |
A booking was cancelled |
Paid
paid
This is the final status of a booking. Note that a booking will transition to this status even if payments are disabled for a tenant.
Cancelled
cancelled
This is the final status of a booking if a booking is cancelled by an Admin, Organization Manager, or Customer.
