Overview

Creating a booking via API using a customer account is straightforward, but some basic concepts of MotionTools are required. That’s why we will start this article by giving you a quick intro into these concepts.

If you want an easy way to simply get started, you have the option to simply log into the MotionTools Dashboard provided to you by your delivery operator and create a booking using the Webbooker, theb check the Developer Tools of your browser to see a valid sample payload.

Concepts

Service area

A service area essentially represents a well-defined zone where your delivery partner operates. Besides representing an area on the map, a service area in MotionTools also controls things such as price currency or the scheduling configuration.

This is configured by the delivery operator and is mostly relevant to you as their customer if you plan to perform deliveries in different service areas supported by the same delivery partner.

Scheduling configuration

Defines the supported scheduling modes - Instant, Scheduled or both, and also stores the “open hours” of your delivery partner.

A scheduling configuration is attached to one or more service areas and you can define multiple scheduling configurations.

Capabilities

Capabilities represent the booking properties supported by your delivery operator, and are specific to your operator's setup.

For instance, for an operator running a delivery business, one capability could be:

Order Size, with values: small, medium, large as possible values.

An operator of an on-demand hailing moving service, might use 2 capabilities:

Car Size - van , small_truck , large_truck
Helpers - 1_helper, 2_helpers

Capabilities play an important role when matching bookings to drivers. If we take the example above with the Car Size capability - if a booking is created and the Car Size - Large Truck capability is requested, then only drivers that have a Large Truck will be matched with the booking.

Capabilities are defined by your delivery operator, and specifying them when creating a booking is optional. Please check with your delivery partner if they need to be mentioned, and if yes, how to map properties from your order object to the capabilities configured for your delivery operator.

Booking stops

Stops represent the fundamental unit of work associated with a booking. Stops have multiple properties, such as contact details, proofs of stop completion, additional information, custom content, and (very important) type (pickup / drop-off), status and location. A booking needs to have at least one stop.

When creating a booking, the service area that a stop belongs to is identified based on the location of the stop. Depending on how your setup is configured, stops need to either be all within a valid service area, only the first one, or just the first & last stop need to be within a service area. See here more about booking validation.

A stop can also be defined by mentioning a Saved place when creating the booking, instead of passing in a lat/ lng pair. For more info, see Hailing booking stops.

Payment info

If payments are enabled, the payment method needs to be specified on booking create. Otherwise, if payments are disabled, the payment method can be left empty.

For the sake of simplicity, we won’t work with payment methods when creating a booking in this article, but supported payment methods are mentioned in our API reference - just expand the request body.

Create a booking

Required properties

Now that we’re familiar with the most important concepts, we’re ready to create our first booking.

To do so, at a minimum we need the following pieces of information:

🔐 Authentication: An API Token is required to authenticate our request against the MotionTools backend. The token is provided via an Authorization header. See more information here:
- MotionTools API Introduction
- Create an API Token

Stops: this is a simple one → we need a few locations that will represent stops in our booking. Anything would do here, just make sure the stops are located inside the a valid service area configured for your delivery operator.

Optional properties

Scheduling: `instant` vs `scheduled`

Decide whether you want the booking to be dispatched immediately, or if needs to be scheduled for later. Bear in mind that whatever you select needs to be allowed by the scheduling configuration associated with the service area the booking will belong to.

You can’t create instant bookings outside open hours, nor can you schedule bookings to be fulfilled outside open hours. Furthermore, you need to check with your delivery operator to see if instant, scheduled, or both are enabled for the service area you plan to ship orders in.

When omitted, defaults to:

now (represents "instant' bookings) when instant bookings are enabled in the service area
next available time in service area when scheduled bookings are enabled

Desired capabilities

Key-value pairs. Please contact your delivery operator for details on what to specify here.

When omitted the smallest capabilities are being used.

Idempotence Key

An optional idempotence key of your choice, representing for example an order ID on your side when integrating with the API.

Using an idempotence key will prevent creating two bookings with the same idempotence key in MotionTools, ensuring that edge case conditions like network failures when sending the create API call response or failing to process the successful create on your end lead to duplicated bookings, as our API will complain about duplicate idempotence keys on subsequent re-create attempts.

Besides the above, you can check the API reference for the #CreateHailingBooking endpoint to see the complete list of all supported parameters and options when creating a booking.

Sample request payload

An example payload to create a booking can be seen below. Keep in mind however that it’s unlikely for the payload below to work on your setup, given that creating a booking is highly dependent on the capabilities, services & scheduling configuration specific to your account and your account only.

// Headers // // Authentication: Bearer  // Accept-Language: en-US// Payload {   "booking": {     "customer_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",     "requested_capabilities": {         "vehicle_type": "bike_cargo",        "assistance": "one_helper"     },     "scheduled_at": "now",     "stops": [       {         "city": "Hamburg",         "country": "Germany",         "lat": 53.633621999999995,         "lng": 9.9974128,         "street": "Hamburg Airport",         "type": "pickup",         "zip_code": "22335"       },       {         "city": "Bezirk Altona",         "country": "Germany",         "lat": 53.5434024,         "lng": 9.9404465,         "street": "MotionTools",         "type": "dropoff",         "zip_code": "22767"       }     ]   } }

Sample create hailing booking payload

Let’s explore the contents.

"requested_capabilities": {      "vehicle_type": "bike_cargo",       "assistance": "one_helper" }

As the name suggests, these are the capabilities of the new booking. In your case, the key/values contents of the requested_capabilities object might differ, and will

match the capabilities configured for your setup.

"scheduled_at": "now"

This represents the scheduling configuration. now indicates that this is an instant booking, not a scheduled one. If this were a scheduled booking, the contents of the scheduled_at field would have been an ISO8601 formatted timestamp, e.g. 2022-03-20T02:31:00+02:00 or equivalent.

"stops": [       {         "city": "Hamburg",         "country": "Germany",         "lat": 53.633621999999995,         "lng": 9.9974128,         "street": "Hamburg Airport",         "type": "pickup",         "zip_code": "22335"       },       {         "city": "Bezirk Altona",         "country": "Germany",         "lat": 53.5434024,         "lng": 9.9404465,         "street": "Van-der-Smissen-Straße",         "type": "dropoff",         "zip_code": "22767"       }     ],

The above represents the two stops of the booking. Notable details are the values of the type field in each stop, as well as the lat / lng. The other fields, such as city, country, street, etc are not mandatory to be present. Furthermore, a stop supports more details on creation time, however all said details are optional.

For a complete specification, check the API reference.

Besides the payload itself, don’t forget to also add the necessary headers: