Single Tasks

A single task is a standalone delivery operation with no parent. It represents one discrete action — such as a pickup or a delivery — and follows its own status lifecycle independently. Most simple deliveries in Deliverty Hub are created as single tasks.

Single tasks have a type of PICKUP, DELIVERY, CASH_COLLECTION, or CASH_DROP. They do not have a parent task and are not linked to other tasks.

What Is a Job?

A job is a special type of task (type: JOB) that acts as a parent container for one or more child tasks. It does not represent a physical delivery itself — instead, it groups related operations into a single coordinated unit.

For example, a single customer order might require:

1. A PICKUP at the merchant warehouse
2. A DELIVERY to the customer address
3. A CASH_COLLECTION from the customer (COD)
4. A CASH_DROP back at the merchant office

All four of these would be child tasks under a single parent job.

Job Structure

The relationship between a job and its children is a simple parent-child hierarchy:

Status Propagation

One of the most important behaviors of jobs is status propagation. When child tasks change status, the parent job's status is automatically updated to reflect the aggregate state of its children. This is handled by the task.job.status.propagated event internally.

The propagation rules are:

Child Status Condition	Propagated Job Status
All children are NEW	NEW
At least one child is ASSIGNED or beyond, but not all completed	Job status reflects the furthest active child
At least one child is IN_TRANSIT	IN_TRANSIT
All children are COMPLETED	COMPLETED
All children are CANCELLED	CANCELLED

When to Use Jobs

Jobs are ideal for delivery scenarios that involve multiple coordinated stops or operations:

Multi-Stop Deliveries

When a single agent needs to pick up from one location and deliver to multiple recipients, a job groups all the individual delivery tasks together. The agent sees the entire route as a single assignment with ordered stops.

Pickup and Delivery Pairs

The most common job pattern is a pickup followed by a delivery. Instead of creating two unrelated tasks, grouping them under a job ensures they are treated as a single unit — assigned to the same agent, tracked together, and completed as one operation.

Cash-on-Delivery with Cash Drop

When a delivery involves collecting cash from the customer and then returning that cash to a merchant or office, the full flow (PICKUP, DELIVERY, CASH_COLLECTION, CASH_DROP) is best managed as a job so the financial operations stay linked.

Grouped Operations

Any scenario where multiple tasks need to be tracked, assigned, and reported on as a single logical operation benefits from using a job as the grouping container.

Comparison Table

Aspect	Single Task	Job (Parent + Children)
Structure	Standalone, no parent	Parent JOB with 1+ child tasks
Type	PICKUP, DELIVERY, CASH_COLLECTION, or CASH_DROP	Parent is JOB; children are other types
Status tracking	Independent lifecycle	Children have own status; parent status is propagated
Assignment	Assigned individually	Children can be assigned to the same or different agents
Use case	Simple point-to-point delivery	Multi-stop, pickup+delivery, COD flows
Nesting	N/A	One level only (job → children)