> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.chrt.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.chrt.com/_mcp/server.

# Orders, Task Groups, Segments, and Stops

> How chrt models a shipment — the order, the task groups (segments) it's composed of, the tasks (stops) inside each task group, and the cargo that flows through them.

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](/docs/concepts/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.

## Related guides

* [Cargo types](/docs/concepts/cargo-types) — what cargo types exist and how
  they drive routing and pricing.
* [Billing primitives](/docs/concepts/billing-primitives) — rate sheets attach
  to task groups, not orders.
* [Tracking](/docs/concepts/tracking) — how live location and ETA flow through
  this model.
* [Creating shipments](/shippers/creating-shipments) — building a draft order
  end to end.
* [Multi-leg orders](/forwarders/multi-leg-orders) — composing orders with
  multiple segments.