Orders, Task Groups, Segments, and Stops

A shipment on chrt is an order. Orders are split into one or more task groups — each task group is a leg of the shipment that one party (a courier company, an airline, or an onboard courier) executes end-to-end. Inside each task group is an ordered list of tasks, where each task is one action at one location: a pickup, a delivery, a hand-off to an airline, a customs clearance, and so on. The user-visible label varies by surface — drafts and the forwarder UI call task groups segments and tasks stops — but the underlying model is the same.

Order

An order is the shipper-facing record of a shipment. It owns the customer, the cargo, the time windows, and the overall lifecycle. One order can contain multiple task groups when the shipment crosses more than one party — for example, a pickup-courier task group, a flight task group, and a delivery-courier task group on an international move.

Shippers and forwarders see the full order. Couriers see only the task group(s) assigned to them.

Order states

Status	Meaning
`draft`	Being built in the draft builder. Not visible to assigned parties yet.
`staged`	Submitted. Assignments and details are locked in but no work has started.
`in_progress`	At least one task group is in progress; live tracking is on.
`completed`	Every non-skipped task group has completed.
`exception`	Something blocked completion (cancelled, failed delivery, dispute).

Task group

A task group is one continuous unit of work on an order. It’s the courier-facing concept: a courier company is assigned to a task group, sees only that task group, and bills against it. Three kinds exist:

Task group type	Used for
`chrt_ground_provider`	A ground leg run by a courier (pickup, deliver, tender, recover).
`cargo_on_flight`	An air leg — cargo travels on a commercial flight, tracked via FlightAware.
`onboard_courier`	A hand-carry shipment where one person accompanies the cargo through pickup, flight(s), and delivery.

A simple LA-to-San-Diego order has one ground task group. An LA-to-Houston international hand-off has three: ground to LAX, cargo on the SAN→IAH flight, ground from IAH to the consignee.

In the draft builder, task groups are labelled segments.

Task group states

Status	Meaning
`draft`	Created on a draft order, not yet submitted.
`staged`	Submitted and waiting to start.
`in_progress`	Driver has started; events and location updates are flowing.
`completed`	All non-skipped tasks completed.
`skipped`	Task group was bypassed (rarely used; e.g. cancelled mid-route).
`exception`	Something went wrong and the task group did not complete normally.

Task

A task is one action at one place: pick this cargo up at this address, deliver it at that one, tender it to the airline at LAX, recover it at DEN. Each task carries a location, a time window, a cargo reference, and an action verb drawn from one of the three task-action enums:

Ground actions — pickup, deliver, tender_to_airline, recover_from_airline, consolidate, hold, other.
Flight actions — cargo_received_by_airline, cargo_loaded_onto_flight, flight_departed, flight_arrived, cargo_offloaded_from_flight, cargo_cleared_customs, cargo_ready_for_recovery.
OBC actions — the courier-and-cargo lifecycle from courier_departed_for_pickup_location through courier_arrived_at_delivery_location.

In the draft builder and on the order timeline, tasks are labelled stops.

Task states

Status	Meaning
`draft`	Created on a draft order.
`staged`	Submitted, awaiting completion.
`completed`	Done — either by driver action, geofence trigger, or flight integration.
`skipped`	Marked as not needed (e.g. a recipient refusing a partial).
`exception`	Blocked or failed.

Flight tasks frequently auto-complete from the FlightAware feed — no human input required.

Cargo

Cargo is what’s being moved. An order has one or more cargo records, and each task references the cargo it’s acting on. Cargo has a quantity, weight, optional dimensions, an optional declared value, and a cargo type. See Cargo types for the full enum and how it affects routing and pricing.

How the pieces fit together

Order
├── Task Group 1 (e.g. ground pickup leg, assigned to Courier A)
│   ├── Task: pickup at origin
│   └── Task: tender to airline at LAX
├── Task Group 2 (flight leg, auto-tracked)
│   ├── Task: cargo received by airline
│   ├── Task: flight departed
│   ├── Task: flight arrived
│   └── Task: cargo cleared customs
└── Task Group 3 (ground delivery leg, assigned to Courier B)
    ├── Task: recover from airline at IAH
    └── Task: deliver to consignee

A courier assigned to Task Group 1 sees Task Group 1’s two tasks. They don’t see Task Group 2 or 3 unless explicitly given access. The shipper and the forwarder see the whole order.

UI vs model vocabulary

Model term	Draft builder label	Order page label
Order	Order	Order
Task group	Segment	Task group (or “leg”)
Task	Stop	Task / event
Cargo	Cargo	Cargo

Use whichever term matches the surface you’re documenting; this page is the canonical mapping.

Cargo types — what cargo types exist and how they drive routing and pricing.
Billing primitives — rate sheets attach to task groups, not orders.
Tracking — how live location and ETA flow through this model.
Creating shipments — building a draft order end to end.
Multi-leg orders — composing orders with multiple segments.