Overview

Introduction
Statuses Overview
Statuses in detail

Introduction

Every package in 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 the visibility, are directly related to or restricted by its status.

A package doesn’t necessarily go through all available statuses. Some statuses may be skipped during transitions.

Statuses Overview

This is a short overview of all available statuses. Continue with the next section for more detailed explanations and available status transitions.

Status	Short Description
Created	Package created
Awaiting pickup	Package scheduled for pickup
In transit	Package picked up by driver and in transit to hub
At hub	Package delivered to hub or created directly 'At hub'
Scheduled for delivery	Package scheduled for drop-off
Out for delivery	Package picked up by driver and in transit to destination
Delivered	Package dropped off at destination
Ready for collection	Package collection from Hub was requested by customer
Collected	Package collected from Hub by customer
At customs	Package processed at customs
Cancelled	Package delivery cancelled
Failed	Package couldn't be picked up or dropped off

Statuses in detail

If you are developing integration with MotionTools, note that the status names shown on the Dashboard may slightly differ from the names used in the API. To receive notifications for every status change, you can subscribe to the corresponding webhook event.

Created

created

A package was created with a customer’s Place as origin.

Available transitions	Transition name on API	Trigger
Created → Awaiting pickup	`announce`	Package was scheduled for pickup
Created → At hub	`relocate`	A Dispatcher/Admin relocated the package to a hub
Created → Failed	`miss`	A pickup or drop-off attempt failed right after creation (edge case)
Created → Cancelled	`cancel`	Admin cancelled the package

Awaiting pickup

awaiting_pickup

A package was scheduled for pickup

Available transitions	Transition name on API	Trigger
Awaiting pickup → In transit	`pickup`	A driver picked up the package
Awaiting pickup → Out for delivery	`pickup`	A driver picked up the package
Awaiting pickup → At hub	`tour_cancelled` `tour_force_ended` `remove_from_tour`	The tour was cancelled/force-ended or the package was removed from the tour after it had already reached a hub
Awaiting pickup → Created	`tour_cancelled` `tour_force_ended` `remove_from_tour`	The tour was cancelled/force-ended or the package was removed from the tour before pickup happened (package returns to initial state)
Awaiting pickup → Failed	`miss`	A pickup attempt failed (e.g., driver couldn’t pick up the package)

In transit

in_transit

A package was picked up by a driver and is in transit to a hub now.

Available transitions	Transition name on API	Trigger
In transit → Awaiting pickup	`dropoff`	The driver dropped off the package at the origin again (e.g., pickup was reverted)
In transit → At hub	`dropoff` `tour_force_ended`	The driver dropped off the package at the hub (or the tour was force-ended after reaching the hub)
In transit → Delivered	`tour_force_ended`	The tour was force-ended and the package was marked as delivered
In transit → Failed	`miss` `tour_cancelled`	A pickup/drop-off attempt failed or the tour was cancelled while the package was in transit

At hub

at_hub

A package was delivered to a hub or was created directly 'At hub' by mentioning an admin’s Place.

Available transitions	Transition name on API	Trigger
At hub → At hub	`relocate` `tour_cancelled` `tour_force_ended`	The package was relocated to another hub, or a tour was cancelled/force-ended while the package remained at a hub
At hub → Awaiting pickup	`announce`	Package was scheduled for pickup from the hub
At hub → Scheduled for delivery	`announce`	Package was scheduled for drop-off
At hub → Ready for collection	`request_collection`	A customer requested to collect the package from the hub
At hub → Failed	`miss`	A hub handover/pickup attempt failed
At hub → Cancelled	`cancel`	A package delivery was cancelled
At hub → Delivered	`force_delivery`	A Dispatcher/Admin force-delivered the package (marked delivered manually)

Scheduled for delivery

scheduled_for_delivery

A package was scheduled for drop-off.

Available transitions	Transition name on API	Trigger
Scheduled for delivery → Out for delivery	`pickup`	A driver picked up the package at the hub to start the delivery tour
Scheduled for delivery → Ready for collection	`request_collection`	A customer requested hub collection instead of delivery
Scheduled for delivery → At hub	`tour_cancelled removed_from_tour`	The delivery tour was cancelled or the package was removed from the tour (package stays at the hub)
Scheduled for delivery → Delivered	`tour_force_ended`	The delivery tour was force-ended and the package was marked as delivered
Scheduled for delivery → Failed	`miss`	A delivery attempt failed (e.g., driver couldn’t hand over the package)

Out for delivery

out_for_delivery

A package was picked up by a driver and is in transit to the destination now.

Available transitions	Transition name on API	Trigger
Out for delivery → Delivered	`dropoff` `tour_force_ended`	The driver dropped off the package at the destination (or the tour was force-ended after drop-off)
Out for delivery → Failed	`miss` `tour_cancelled`	A delivery attempt failed or the tour was cancelled while delivering

Delivered

delivered

A package was dropped off at the destination.

Available transitions	Transition name on API	Trigger
Delivered → Delivered	`tour_cancelled` `tour_force_ended`	The tour was cancelled/force-ended after delivery (package remains delivered)

Ready for collection

ready_for_collection

A package collection from a Hub was requested by a customer.

Available transitions	Transition name on API	Trigger
Ready for collection → Ready for collection	`removed_from_tour`	A collection-related tour assignment was removed (package remains ready for collection)
Ready for collection → At hub	`relocate`	The package was relocated to another hub
Ready for collection → Collected	`collect`	The customer collected the package from the hub
Ready for collection → Cancelled	`cancel`	The collection request was cancelled
Ready for collection → Failed	`miss`	A collection attempt failed (e.g., package couldn’t be handed over)

Collected

collected

A package was collected from a Hub by a customer

Available transitions	Transition name on API	Trigger
Collected → Failed	`miss`	A post-collection issue was reported and the collection failed (edge case)

At customs

at_customs

A package was announced to customs, and the clearance process started. You can find the customs-specific statuses in the Status model of Packages in customs article.

Available transitions	Transition name on API	Trigger
At customs → At customs	`relocate`	The package was relocated while remaining in customs processing
At customs → At hub	`customs_approved`	Customs clearance was approved (package released back to hub)
At customs → Failed	`miss`	Customs clearance failed or the package couldn’t be processed at customs

Cancelled

cancelled

A package delivery was cancelled.

Available transitions	Transition name on API	Trigger
Cancelled → Cancelled	`tour_cancelled` `tour_force_ended`	A related tour was cancelled/force-ended after the package was already cancelled

Failed

failed

A package couldn't be picked up or dropped off.

Available transitions	Transition name on API	Trigger
Failed → Failed	`miss` `tour_cancelled` `tour_force_ended`	A retry failed again, or the related tour was cancelled/force-ended while the package was already failed
Failed → Cancelled	`cancel`	A Dispatcher/Admin cancelled the package after it had failed
Failed → Delivered	`force_delivery`	A Dispatcher/Admin force-delivered the package (marked delivered manually)
Failed → Created	`recover`	A Dispatcher/Admin recovered the package back to its initial state
Failed → At hub	`recover`	A Dispatcher/Admin recovered the package back to a hub state

Create pickup and drop-off tours for packages

Operations analytics

Package collection from hub

Release Notes May 2025

Recover Packages