Create a package via API

Overview

Creating a new package via the MotionTools API is rather straightforward — just a handful of parameters need to be specified — API Docs. Read more about the Packages product on our dedicated article.

• Concepts
• Prerequisites
• Creating a package
• Payload breakdown
• Fin

Concepts

Before we create a package though, you should be familiar with the following concepts.

If you want a faster way to get started, you have the option to simply log into the MotionTools dashboard, create a package using the Package Webbooker and check the Developer Tools of your browser to see a valid sample payload. To access the Package Webbooker, you can log in with a Customer account, then click the Packages item in the dashboard header (or add /packages to the dashboard homepage URL).

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

Prerequisites

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

• Saved place: At least 1 — the package we’re about to create has to have an origin.
• Package properties: Whether they’re the final properties you plan to use, or just sample values is less important.
• Service area, Scheduling configuration: These two are intricately tied to each other and both need to be configured in advance via the dashboard. See our dedicated articles on how to set them up:
  • Manage service areas
  • Manage scheduling configurations
• Customer: when creating bookings as an admin (or using an API Token), a valid customer_id is required. Bookings created by an account that has the Customer role do not need the customer_id specified.
• 🔐 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

Creating a package

An example payload to create a package as an admin for a customer 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 package is highly dependent on the package properties, saved places, service areas and scheduling configurations specific to your account and your account only.

Sample request payload

// Headers
// 
// Authentication: Bearer <API Token> 
// Accept-Language: en-US 

{
    "customer_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
    "package": { 
      "pickup_place_id": "36e97f6e-1964-7451-aedf-bbb43cbbbba6", 
      "destination": { 
        "lat": 53.551085, 
        "lng": 10.3824, 
        "first_name": "Foo", 
        "last_name": "Bar", 
        "phone_number": 4915252345, 
        "email": "foo@example.com", 
        "street": "Van-der-Smissen-Straße", 
        "number": 3, 
        "location_name": "MotionTools HQ", 
        "city": "Hamburg",
        "zip_code": 22767, 
        "country": "Germany" 
      }, 
      "pickup_at": "2019-08-24T14:15:22Z", 
      "requested_properties": { 
        "size": "large", 
        "refrigeration": "deep_freeze", 
        "insurance": "top_notch" 
      }, 
      "payment_method": "invoice", 
      "metadata": { 
        "internal_package_id":"42-ff-olfoo-132", 
        "internal_customer_id":"84b1169fe9d328d22d075d3cca2c3846" 
      } 
    } 
}

Payload breakdown

Customer id

    "customer_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 

id of the customer account in MotionTools that will “own” the package. Packages can also be created by customer accounts, not just by admins. When this is the case, the customer_id parameter can be omitted.

Package properties

{ 
    ... 
    "package": { 
      ... 
      "requested_properties": { 
        "size": "large", 
        "refrigeration": "deep_freeze", 
        "insurance": "top_notch" 
      }, 
      ... 
    } 
}

Properties of this individual package. The above represents just an example, but they could be something configured by you: weight, spatial dimensions (LxWxH), container type (bag, box), etc.

Package origin

{ 
    ... 
    "package": { 
      "pickup_place_id": "36e97f6e-1964-7451-aedf-bbb43cbbbba6", 
      ... 
    } 
}

id of a Saved place in MotionTools. This will be counted as the origin of the package.

Furthermore, the package will belong to the service area that contains its origin, i.e. the referenced saved place. This essentially means that besides the package properties, the origin of the package also affects pricing.

Destination

{ 
    ... 
    "package": { 
      ... 
      "destination": { 
        "lat": 53.551085, 
        "lng": 10.3824, 
        "first_name": "Foo", 
        "last_name": "Bar", 
        "phone_number": 4915252345, 
        "email": "foo@example.com", 
        "street": "Van-der-Smissen-Straße", 
        "number": 3, 
        "location_name": "MotionTools HQ", 
        "city": "Hamburg", 
        "zip_code": 22767, 
        "country": "Germany" 
      }, 
      ... 
    } 
}

Information about the recipient of the package. The lat/lng values are optional — if they are missing, their values will be automatically detected by MotionTools through geocoding.

Pickup time

{ 
    ... 
    "package": { 
      ... 
      "pickup_at": "2019-08-24T14:15:22Z", 
      ... 
    } 
}

The expected pickup time of the package.

Bear in mind that the value passed here will be validated against the scheduling configuration associated with the service area the package will belong to (i.e. service area that contains the package origin). This means that setting the pickup time to a value that’s outside the operating schedule within the service area will result in an error upon package creation.

Obtaining the scheduling configuration relevant for the package origin can be done via our dedicated endpoint built specifically for this purpose.

Metadata

{ 
    ... 
    "package": { 
      ... 
      "metadata": { 
      "internal_package_id":"42-ff-olfoo-132", 
      "internal_customer_id":"84b1169fe9d328d22d075d3cca2c3846" 
      } 
      ... 
    } 
}

Key-value pairs set by you upon package creation and fully editable afterwards.

Tip: Metadata is also searchable, thus allowing you to easily find the MotionTools package for a particular identifier from your system, that you then stored as metadata on a package. See available filters for the ListPackages endpoint in our docs for details.

Example filter

GET https://api.motiontools.io/api/hailing/packages?filters[metadata]["internal_
package_id"]="42-ff-olfoo-132"

Please also make sure to url-encode the request URL, otherwise it might not work as expected.

Payment method

{ 
    ... 
    "package": { 
      ... 
      "payment_method": "invoice", 
      ... 
    } 
}

Defines how payment will be handled for the given package. For now only invoice is supported.

Fin 🎉

That’s it! Now you have created your first package on in MotionTools, congratulations!  🙌 🎆

Next, we encourage you to explore our comprehensive API docs to learn how to:

• Dispatch packages into tours (Concept, Create a pick-up tour, Create a drop-off tour)
• View package journey
• Generate labels
• and more!