Create a package via API

ℹ️  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.

 

Overview

 

Concepts

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

Saved place

Glossary entry: Saved place

For a package, we use a saved place to define its original location — i.e. the warehouse from which the package will be shipped, or the address from where the package needs to be picked up. At least one saved place is required in order to be able to create a package. Saved places can be managed both via our API and the Dashboard.

Package properties

Service area

Glossary entry: Service area

A service area essentially represents a well-defined zone where your business operates. Besides representing an area on the map, for packages a service area also controls the following:

The final price to be paid for delivering a package is calculated using the pricing information attached to the service area of the package origin and the properties of the respective package.

Given all the above, it goes without saying that in order to create package first you need to create a service area via the Dashboard.

Scheduling configuration

Glossary entry: Scheduling configuration

Essentially configures the “open hours” of your business. A scheduling configuration is attached to one or more service areas and you can define multiple scheduling configurations. Like with service areas, scheduling configurations are created via the Dashboard.

Payment information

MotionTools doesn’t process payments for operations with packages, however we do offer various exporting and integration options to ensure that external accounting systems can process all the completed deliveries. Learn more about Webhooks: Webhooks quickstart.

In terms of supported payment methods, packages only support the invoice payment method for the time being.

Optional: Metadata

Glossary entry: Metadata

Metadata represents a set of custom key-value entries that can be added to various MotionTools data structures, including packages.

Metadata enables you to enrich packages with your own data, such as your internal package id, or customer id for the equivalent in your system to the package created in MotionTools.

 

💡 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:
  • 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:

 

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:

Was this article helpful?
0 out of 0 found this helpful

Articles in this section