Status Overview

Every task in Deliverty Hub has a status field that represents its current position in the delivery lifecycle. There are 7 possible statuses, of which 2 are terminal (no further transitions allowed).

Status	Enum Value	Terminal	Description
NEW	new	No	Task has been created and is awaiting processing. This is the initial status for all tasks.
AWAITING_ASSIGNMENT	awaiting_assignment	No	Task has been validated and the system is searching for an available courier to assign.
ASSIGNED	assigned	No	A courier has been assigned to the task but has not yet accepted it.
ACCEPTED	accepted	No	The assigned courier has accepted the task and is preparing for pickup.
IN_TRANSIT	in_transit	No	The courier has picked up the package and is en route to the drop-off location.
COMPLETED	completed	Yes	The delivery has been successfully completed. The package was delivered to the customer.
CANCELLED	cancelled	Yes	The task has been cancelled. This can be initiated by the channel, admin, or system.

Status Flow

The standard (happy path) flow for a delivery task is:

At any non-terminal stage, a task can also transition to:

Allowed Transitions

The following table shows every valid status transition. Any transition not listed here will be rejected by the API with a 409 Conflict error.

From Status	Allowed Transitions
NEW	AWAITING_ASSIGNMENT CANCELLED
AWAITING_ASSIGNMENT	ASSIGNED CANCELLED
ASSIGNED	ACCEPTED AWAITING_ASSIGNMENT CANCELLED
ACCEPTED	IN_TRANSIT CANCELLED
IN_TRANSIT	COMPLETED CANCELLED
COMPLETED	None (terminal)
CANCELLED	None (terminal)

Detailed Status Descriptions

NEW

The initial status assigned to a task immediately upon creation via the API. The task has been persisted and validated, but no action has been taken yet. The channel can still update or cancel the task at this point.

• Set by: System (on task creation)
• API actions available: Update, Cancel
• Notifications: Customer receives in-app and email notification; admins receive in-app and email notification

AWAITING_ASSIGNMENT

The task has been picked up by the dispatch system and is actively searching for a suitable courier based on availability, proximity, and workload. This status may persist for some time during peak hours.

• Set by: System (automatic dispatch)
• API actions available: Cancel
• Notifications: None (internal state)

ASSIGNED

A courier has been selected and assigned to the task. The courier receives a notification and must accept or reject within the configured acceptance window.

• Set by: System (dispatch algorithm) or Admin (manual assignment)
• API actions available: Cancel
• Notifications: Assigned courier receives in-app and push notification; admins receive in-app notification

ACCEPTED

The assigned courier has confirmed they will handle the delivery. The courier is expected to proceed to the pickup location.

• Set by: Courier (via mobile app)
• API actions available: Cancel
• Notifications: Customer receives in-app and email notification; admins receive in-app notification

IN_TRANSIT

The courier has picked up the package and is actively traveling to the drop-off location. Real-time location tracking is available during this phase.

• Set by: Courier (via mobile app, after pickup confirmation)
• API actions available: Cancel
• Notifications: Customer receives in-app, email, and SMS notification; admins receive in-app notification

COMPLETED

The delivery has been successfully completed. The courier confirmed drop-off, and optionally collected proof of delivery (signature, photo). This is a terminal status — no further transitions are possible.

• Set by: Courier (via mobile app, with delivery confirmation)
• API actions available: Read only
• Notifications: Customer receives in-app, email, and SMS; courier receives in-app and push; admins receive in-app and email

CANCELLED

The task has been cancelled before completion. The reason field contains an explanation. This is a terminal status — no further transitions are possible.

• Set by: Channel (via API), Admin (via dashboard), or System (timeout/policy)
• API actions available: Read only
• Notifications: Customer receives in-app and email; courier (if assigned) receives in-app and push; admins receive in-app and email

Using Statuses in the API

Filtering by status

Use the status query parameter when listing tasks:

GET /api/v1/tasks?status=in_transit

Status in responses

The status field is always returned as the lowercase enum value:

{
  "id": 1042,
  "status": "in_transit",
  "type": "DELIVERY",
  ...
}

Webhook events

Status changes trigger task.status.changed webhook events containing both the old and new status values. See Event Reference for details.