Trips
A Trip is the document that actually moves goods — it sits at the end of TradeStack's order-to-delivery flow, carrying approved Delivery Orders through to dispatch on a vehicle.
This guide reflects the authoritative Trips HTML training artifact and converts it into the native Docusaurus manual format used in TradeStack docs.
1. Introduction & overview
A Trip is the document that actually moves goods — it sits at the very end of TradeStack's order-to-delivery chain, carrying already-approved Delivery Orders (via generated Shipments) out to customers on a vehicle.
Delivery Order → Shipment (generated automatically once the trip is approved) → Trip
Unlike a Sales Order, a Trip has no permanent "context" flag fixed at creation — every Trip is the same document type. What it does have is a Route chosen once at creation, and an unusual status transition that starts an asynchronous background workflow rather than doing everything synchronously.
This manual covers the Trip document itself in full depth — its fields, assignment steps, statuses, and permissions. Loading Requests, Vehicle Switches, and Offload & Reconciliation are adjacent flows and are only covered briefly in the relevant section below.
2. Prerequisites
| Requirement | Details |
|---|---|
| Active organisation and branch | Your session must have a current organisation and branch. A Trip's business_partner and last_known_location are derived from the branch's own partner location, not chosen by you. |
| Permissions | At minimum VIEW_TRIP to browse; ADD_TRIP to create a trip and manage crew; CHANGE_TRIP for vehicle assignment and most everyday status changes; APPROVE_TRIP to approve or reject at the Ready stage; START_OR_END_TRIP to move into In Progress, Complete, or Failed. |
| Route | An active Route record must already exist for your organisation — it's the field required to create a Trip at all. |
| Vehicle | Not required to create a Trip, but required before almost every status change beyond Draft/Ready. |
| Delivery Orders | Any Delivery Order you intend to add to the trip must already be APPROVED and not yet attached to a Shipment. |
3. Accessing Trips
- From the main navigation, open Trips.
- The Trips list loads, showing trips scoped to your active organisation and branch.
- Use the list's search and filter controls to narrow by route, status, or vehicle.
Trips list showing trip records grouped by route, status, and vehicle filters.
4. Creating a Trip
From the list, click + Trip to open the creation form.
The trip detail view used as the entry point for creating and managing a new trip record.
| Field | Required? | Description |
|---|---|---|
route / Route | Required | The route this trip follows. Only active routes in your organisation are selectable. |
scheduled_departure_time / Scheduled Departure | Required | Planned departure. Cannot be set in the past. Defaults to now if left blank. |
scheduled_return_time / Scheduled Return | Optional | Planned return. If supplied, it must be after departure and not in the past. |
document_manager / Trip Manager | Required | User responsible for the trip. Restricted to users with “Can manage deliveries” enabled. |
business_partner | Auto | Hidden from the form; set to the branch's own partner location. |
last_known_location | Auto | Hidden from the form; set to the branch's own location. |
vehicle | Not on this form | Assigned in a dedicated next step after save. |
A Trip starts with nothing on it. Unlike a Sales Order, it is created with no cargo and no vehicle; saving takes you straight into the vehicle-assignment screen. Crew and orders are added afterward, in either order.
This creates the trip in DRAFT status and redirects you into the vehicle assignment screen.
5. Assigning a vehicle
Immediately after creating a Trip, you are taken to the vehicle assignment screen.
The vehicle assignment screen and surrounding trip detail context used before a trip is released into the field.
- Vehicle can only be assigned or reassigned while the trip is DRAFT, READY, or APPROVED.
- The vehicle must be in one of Available, Reserved, Loading, or In Transit status.
- You cannot reassign the vehicle while the trip has an active non-terminal loading request.
- A vehicle already on another trip in progress is treated as a conflict and is blocked.
- The Route becomes read-only once you reach this screen.
There is a separate Vehicle Switch mechanism for swapping a trip's vehicle once loading is underway or mid-trip. See the adjacent flows section.
6. Assigning crew
There is no single "driver" field on a Trip — crew is handled through a dedicated assignment record, and a trip can have multiple active crew members.
Two ways crew gets attached
- Automatic — when you assign a vehicle, that vehicle's default crew is copied onto the trip automatically.
- Manual — use the Assign Crew screen to pick users whose profile status is On Duty, Off Duty, Approved, or Delivering.
The crew assignment area shown when the trip is ready to move into loading and dispatch.
- Assigning someone already active on the trip is a no-op.
- Unassigning is a soft deactivation, not a delete.
- Crew can be added or removed at any Trip status.
- Permission for crew assignment uses the same
ADD_TRIPpermission as creating the trip.
Swapping the vehicle automatically deactivates crew tied to the outgoing vehicle. Crew changes driven by a vehicle swap are staged and handled through the Vehicle Switch flow. Also, there is no hard check preventing the same crew member from being actively assigned to two different trips at once; only the vehicle is checked for double-booking.
7. Adding orders to a Trip
A Trip's cargo comes from Delivery Orders. Two things must be true before a Delivery Order can be attached to a trip:
- it must already be APPROVED
- it must not already have a Shipment
You can:
- add by quantity from Delivery Order lines
- pick whole orders directly for the trip
The order selection and confirmation workflow used to attach approved delivery orders to the trip.
What happens next depends on the trip's current status:
- If the trip is still DRAFT or READY, orders are simply held until approval.
- If the trip is already APPROVED or IN_PROGRESS, adding an order immediately triggers shipment generation.
A Trip does track aggregate weight and volume totals, but nothing compares those totals against the vehicle's actual capacity. Capacity checks live in the separate Loading Request flow.
8. Trip statuses and the full workflow
A Trip can be in one of thirteen statuses.
| Status | Meaning |
|---|---|
| DRAFT | Being built — route and schedule set, no vehicle or cargo required yet. |
| READY | Submitted and awaiting approval. |
| APPROVED | Signed off. Vehicle, crew and orders can now be finalised. |
| REJECTED | Declined at Ready stage; can only be cancelled from here. |
| RETURNED | Sent back for rework. Can be resubmitted or cancelled. |
| LOADED | Vehicle has been physically loaded. |
| IN_PROGRESS | Vehicle has departed and the trip is actively running. |
| FAILED | The trip attempt did not complete successfully. Can be resubmitted or reconciled. |
| COMPLETE | Trip finished successfully. Can be reconciled or archived. |
| RECONCILED | Post-completion stock/mileage reconciliation has been closed out. |
| ARCHIVED | Terminal closed-out state. |
| CANCELLED | Terminal. Reached from Draft, Rejected, or Returned. |
| TEMPLATE | Present in the status list but not part of the live trip lifecycle. |
8.1 Full status graph
DRAFT → READY, CANCELLED
READY → APPROVED, REJECTED, RETURNED
REJECTED → CANCELLED
RETURNED → READY, CANCELLED
APPROVED → FAILED, LOADED, IN_PROGRESS
LOADED → IN_PROGRESS, FAILED
FAILED → READY, RECONCILED
IN_PROGRESS → COMPLETE, FAILED
COMPLETE → ARCHIVED, RECONCILED
RECONCILED → ARCHIVED
ARCHIVED → terminal
CANCELLED → terminal
TEMPLATE → terminal (not wired to any transition)
Once a trip reaches Ready, Approved, Loaded, or Failed, Cancel is no longer available. This is a deliberate design choice. A trip that failed can only be resubmitted or reconciled, not cancelled.
Moving a trip to Returned, Rejected, Failed, or Cancelled requires a notes field to be filled in.
Every transition except into Cancelled or Archived requires a vehicle to already be assigned.
8.2 Mileage requirements
Starting, ending, or failing a trip always requires an odometer reading and its unit of measure. The reading cannot be lower than the vehicle's last recorded mileage.
8.3 Approving a Trip starts a background workflow
The moment a trip is approved, the system publishes an internal event that starts an asynchronous background workflow. That workflow builds the trip's Shipments from attached Delivery Orders, generates the trip's loading request, and sends notifications.
Two consequences are worth knowing:
- If a trip is approved with Delivery Orders attached but the Shipments tab still looks empty, that is normal while the workflow finishes.
- If that background workflow fails, the trip's own status is not rolled back — it stays approved with no shipments. The symptom is a Shipments tab that never leaves generating / queued.
Adding a Delivery Order to a trip already approved or in progress retriggers generation for that order.
8.4 What blocks completing a trip
Before Complete Trip is allowed, all of the following must be true:
- Every shipment on the trip must be in a terminal state.
- Every completed shipment must have a complete Goods Issue Note.
- Every completed shipment with an actual return must have a complete return Goods Receive Note.
- Every completed shipment with trackable lines must have a complete trackable-asset Goods Receive Note.
8.5 Actions available at each status
| Action | From | Preconditions | Result |
|---|---|---|---|
| Submit | DRAFT | ADD_TRIP or CHANGE_TRIP | READY |
| Approve | READY | At least one active order; APPROVE_TRIP | APPROVED |
| Reject | READY | APPROVE_TRIP; notes required | REJECTED |
| Return | READY | CHANGE_TRIP; notes required | RETURNED |
| Cancel | DRAFT, REJECTED, RETURNED | Notes required | CANCELLED |
| Mark Loaded | APPROVED | Vehicle required; crew quorum may apply; CHANGE_TRIP | LOADED |
| Start Trip | APPROVED or LOADED | Vehicle required; mileage + UoM required; crew quorum may apply; START_OR_END_TRIP | IN_PROGRESS |
| Complete Trip | IN_PROGRESS | Mileage + UoM required; shipment checks; crew quorum may apply; START_OR_END_TRIP | COMPLETE |
| Fail Trip | APPROVED, LOADED, IN_PROGRESS | Notes required; mileage + UoM where relevant; START_OR_END_TRIP | FAILED |
| Reconcile | COMPLETE or FAILED | Opens reconciliation; CHANGE_TRIP | RECONCILED |
| Archive | COMPLETE or RECONCILED | CHANGE_TRIP | ARCHIVED |
9. Multi-step approval (crew-based)
Two transitions can require multi-step approval on a Trip:
- Mark Loaded
- Complete Trip
This is not the same style of approval as a Sales Order. A Trip uses a crew quorum: every crew member ever assigned to the trip must approve once each before the transition proceeds.
- If a trip has zero crew assigned, the approval count is zero and the transition proceeds immediately.
- Only someone in the trip's crew list can approve, and only once each.
- A qualified but incomplete approval shows a waiting message.
- A duplicate approval attempt shows "You've already approved this document."
Crew qualification is checked against every crew member ever assigned to the trip — not only currently active assignments. This is a genuine subtlety and worth flagging to trainers.
10. Permissions reference
| Permission | Gates |
|---|---|
VIEW_TRIP | Viewing the Trips list and detail screens. |
ADD_TRIP | Creating a trip; assigning or unassigning crew; Submit (Draft → Ready). |
CHANGE_TRIP | Vehicle assignment; Submit and Return; Mark Loaded, Reconcile, and Archive. |
APPROVE_TRIP | Approving or rejecting a trip at Ready. |
START_OR_END_TRIP | Moving a trip into In Progress, Complete, or Failed. |
VIEW_STOCK_COUNT | Viewing trip reconciliation; backed by the Stock Count feature. |
A Trip permission model differs from a Sales Order. It checks permissions based on the target status rather than a single fixed gate. If a permission error appears, first identify which status the user was moving to.
Two API endpoints in the codebase can transition a Trip's status. Which one a client calls determines which permission check applies. If behaviour appears inconsistent, confirm the endpoint in play.
11. Adjacent flows — loading, vehicle switch, and reconciliation
11.1 Loading Request / Loading Sheet
A Trip's detail page has a Loading Request tab showing either a draft Loading Request to work on or a list of already-approved ones.
This tab is a window into the Loading Request feature, not a separate workflow of its own. See the dedicated Loading Request manual for the full step-by-step process of physically loading a vehicle.
The Trip detail view showing the loading request state and actions used while preparing the vehicle for dispatch.
11.2 Vehicle Switch
A Vehicle Switch is a small document for swapping a trip's vehicle mid-flight. It bundles a stock transfer with crew reassignment and only changes the trip's vehicle once the switch reaches Complete. Only one open Vehicle Switch is allowed per trip at a time.
The change-vehicle wizard used to reassign the trip to a replacement vehicle without starting the trip from scratch.
11.3 Offload & reconciliation
Offload is a mid-trip session for logging stock taken off the vehicle while the trip is still In Progress. Reconciliation is the end-of-trip stock count, only available once the trip is Complete or Failed. Reconciliation is backed by the platform's general Stock Count feature.
The close-out and reconciliation state used to confirm the trip has finished and the stock is accounted for.
12. Common errors and troubleshooting
| Message / symptom | Cause | What to do |
|---|---|---|
| "Departure time cannot be in the past..." | Scheduled departure is in the past. | Choose today or a future date/time. |
| "Return time cannot be..." | Scheduled return is invalid. | Choose a return time later than departure or leave it blank. |
| "Vehicle can only be assigned..." | Trying to assign a vehicle on a trip already Loaded or In Progress. | Use the Vehicle Switch flow instead. |
| "Only vehicles in AVAILABLE, RESERVED, LOADING or IN_TRANSIT status..." | Selected vehicle is ineligible. | Choose a different vehicle or wait. |
| "This trip has a loading request..." | Active loading request is blocking reassignment. | Wait or switch vehicles from the loading request itself. |
| "Vehicle is already assigned to an active trip." | Vehicle double-booking conflict. | Choose a different vehicle. |
| "Trip {id} has no orders assigned and cannot be approved." | Trip approved with zero active orders. | Add at least one order before approving. |
| "A trip must have a vehicle assigned before transitioning." | Transition attempted without a vehicle. | Assign a vehicle first. |
| "Notes are required..." | Return, Reject, Fail, or Cancel without notes. | Provide a short reason and resubmit. |
| "Mileage and UoM required when starting, ending or failing trip" | Missing odometer info. | Enter both values before continuing. |
| "The mileage entered is lower than the vehicle's last recorded mileage..." | Odometer reading regressed. | Enter the correct reading. |
| "Cannot dispatch {n}. Maximum allowed is {m}." | Requested quantity exceeds what remains undispatched. | Lower the quantity. |
| "Trip {id} has shipments that are not in a terminal state." | Tried to complete a trip before shipments were resolved. | Resolve the shipments first. |
| "Only crew assigned to this trip can approve it..." | Non-crew user or duplicate approval attempt. | Only approved crew members may act, once each. |
| HTTP 403 permission denied | Wrong permission for the target transition. | Check the permission mapping above. |
13. Best practices
- Assign the vehicle immediately after creating the trip.
- Do not rely on Cancel being available later.
- Give the Shipments tab a moment after approval; background generation may take a few seconds.
- Always enter accurate mileage.
- Do not complete a trip with unresolved shipments.
- Remember crew approval is quorum-based, not role-based.
14. Quick reference
DRAFT → READY → APPROVED → LOADED → IN_PROGRESS → COMPLETE → RECONCILED → ARCHIVED
↘ CANCELLED
↘ REJECTED → CANCELLED
↘ RETURNED ⇄ READY
APPROVED/LOADED/IN_PROGRESS ↘ FAILED ⇄ READY, → RECONCILED
| Step | Action | Watch out for |
|---|---|---|
| 1 | Create the trip | Route required; departure/return dates cannot be in the past. |
| 2 | Assign a vehicle | Only from Draft/Ready/Approved; must be eligible. |
| 3 | Assign crew | Automatic from the vehicle default crew or manual; no status gate. |
| 4 | Add orders | Delivery Order must be Approved and have no Shipment yet. |
| 5 | Submit / Approve | Approve requires at least one active order. |
| 6 | Mark Loaded / Start Trip | Vehicle required; mileage + UoM required; crew quorum may apply. |
| 7 | Complete Trip | All shipments must be terminal and notes complete. |
| 8 | Reconcile & Archive | Reconcile from Complete or Failed; Archive from Complete or Reconciled. |
Glossary
- Route — the fixed path a trip follows, chosen at creation.
- Trip Manager — user responsible for the trip; required at creation.
- TripOrder — temporary record linking a Delivery Order line to a trip before approval/shipment generation.
- Shipment / TripLine — actual cargo record generated from attached orders once approved.
- Loading Request — separate document governing physical vehicle loading.
- Vehicle Switch — dedicated mini-document for swapping a trip's vehicle mid-flight.
- Offload — mid-trip stock removal from the vehicle while In Progress.
- Reconciliation — end-of-trip stock count moving Complete/Failed trips to Reconciled.
- Crew quorum approval — every currently or ever-assigned crew member must approve, once each.
Summary
The Trips flow is a route-based delivery lifecycle: create the trip, assign the vehicle and crew, attach approved Delivery Orders, submit and approve, load the vehicle, start the trip, complete the run, then reconcile and archive it as needed.
The most important implementation details are:
- the asynchronous approval workflow
- the requirement for a vehicle on nearly every status change
- the strict mileage validation rules
- the crew quorum approval model
- the fact that Cancel is limited to early lifecycle states