Status Model of Packages

This article provides a comprehensive overview of all package statuses throughout the delivery lifecycle, explaining what each status means and how packages transition between them.

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

INFO

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