Packages
The physical items being transported — every delivery task carries one or more packages.
What Is a Package?
A package represents a physical item or parcel that is being transported as part of a delivery task. Each task can contain one or more packages, and each package has its own description, dimensions, weight, and handling instructions.
Packages are attached to tasks and inherit the task's organization scope. They are the actual goods the agent picks up, transports, and delivers.
Package Fields
| Field | Type | Required | Description |
|---|---|---|---|
description |
String | Yes | A brief description of the package contents (e.g., "Electronics order #4521") |
weight |
Decimal | No | Weight of the package in kilograms |
width |
Decimal | No | Width of the package in centimeters |
height |
Decimal | No | Height of the package in centimeters |
length |
Decimal | No | Length of the package in centimeters |
barcode |
String | No | Barcode or tracking number for the package |
isFragile |
Boolean | No | Whether the package requires careful handling (defaults to false) |
quantity |
Integer | No | Number of identical items in this package entry (defaults to 1) |
task |
Task | Yes | The parent task this package belongs to |
Adding Packages to Tasks
Packages are added when creating or editing a task. The task creation form includes a packages section where you can:
- Add multiple packages: Each task can have as many packages as needed. Click "Add Package" to add another entry.
- Describe each package: Enter a description that helps the agent identify what they are picking up and delivering.
- Specify dimensions: Enter width, height, and length in centimeters. This is optional but useful for logistics planning and capacity estimation.
- Enter weight: Specify the weight in kilograms. This can influence which agent or vehicle type is best suited for the delivery.
- Scan or enter barcodes: If the package has a barcode or tracking number, enter it for reference and verification during pickup/delivery.
- Mark as fragile: Toggle the fragile flag to alert the agent that the package requires careful handling.
When tasks are created via the API or through a channel integration (e.g., from an e-commerce platform), packages are included in the request payload as an array. Each package object contains the fields described above. The API validates that at least a description is provided for each package.
Fragile Handling
When a package is marked as fragile (isFragile: true), the platform provides visual indicators to alert everyone in the delivery chain:
- Dashboard: The task detail view shows a "Fragile" badge next to the package, ensuring dispatchers are aware of the handling requirement.
- Mobile app: The agent sees a fragile indicator on the task and package detail screens, reminding them to handle the item with care.
- Notifications: Task assignment notifications to agents may include a note about fragile contents.
The fragile flag is an informational indicator only — it does not enforce any automated behavior such as restricting assignment to specific agents or vehicle types. It is the responsibility of dispatchers and agents to ensure fragile packages receive appropriate care.
Dimensions and Weight
While dimensions and weight are optional fields, providing them offers several benefits:
- Capacity planning: Dispatchers can estimate how many packages an agent can carry based on total volume and weight.
- External courier routing: Some external courier APIs require package dimensions and weight to calculate shipping rates and create shipment orders.
- Reporting: Package size and weight data feeds into analytics for understanding delivery logistics patterns.
- Cost estimation: Future pricing features may use dimensions and weight to calculate delivery fees.
Units of Measurement
| Measurement | Unit | Example |
|---|---|---|
| Weight | Kilograms (kg) | 2.5 = 2.5 kg |
| Width | Centimeters (cm) | 30 = 30 cm |
| Height | Centimeters (cm) | 20 = 20 cm |
| Length | Centimeters (cm) | 40 = 40 cm |
Barcodes and Tracking
Each package can have an associated barcode or tracking number. This is particularly useful for:
- Verification at pickup: Agents can verify they have the correct package by scanning or checking the barcode against the task details.
- Verification at delivery: The barcode can be used to confirm the correct package is being delivered to the right recipient.
- External reference: For tasks created via channel integrations, the barcode often corresponds to the external system's order or shipment number, maintaining traceability across systems.
Multiple Packages per Task
A single task can contain multiple packages. This is common in scenarios such as:
- An e-commerce order with multiple items packed in separate boxes
- A bulk pickup from a warehouse where each box is tracked individually
- A delivery that includes both the main item and accessories or documentation
All packages within a task share the same pickup location, drop-off location, and assigned agent. If packages need to go to different destinations, they should be split into separate tasks (or grouped under a job).