A shipment is one movement of cargo, from the moment it is booked to the moment it is delivered. It is the operational heart of the system: quotations feed into it, invoices and vendor costs come out of it, and the workflow attached to it is what actually moves the job along.
Three kinds of shipment
The shipment type decides which fields you see:
| Type | For | Distinctive fields |
|---|---|---|
| FCL | Full container load | Container IDs, master bill of lading number, house shipper and consignee, house ACID, shipping line, direct or master, vessel and voyage |
| LCL | Groupage | Packages, container IDs, release type, number of originals, B/L release point, house B/L document, vessel and voyage |
| Air | Air freight | Packages, air waybill number, master air waybill number, direct or master, flight, airline, road number |
Pick the type at creation. It is not a label — it determines the whole shape of the record.
The core record
Identity and routing
| Field | Notes |
|---|---|
| Shipment number | The reference everyone quotes. |
| Shipping type | Import or export. |
| Origin and Departure | Where the cargo starts and where it leaves from — not always the same place. |
| Destination and Discharge | Where it ends up and where it comes off the vessel or aircraft. |
| Transshipments | Intermediate calls. |
| Incoterms | The commercial terms of delivery. |
| Subject | A short description of the job. |
Dates — the pairs matter:
| Estimated | Actual |
|---|---|
| Estimated departure | Actual departure |
| Estimated arrival | Actual arrival |
| Pickup date | Actual pickup date |
Plus cutoff date, release date and storage date. Keep the actuals updated — estimates are what you promised, actuals are what happened, and every conversation about a delay depends on being able to see both.
Dates that are validated against each other
Six orderings are enforced, and a save is rejected if any is broken:
| Rule | Message |
|---|---|
| Actual departure ≤ actual arrival | Actual departure (ATD) must be before or equal to actual arrival (ATA) |
| Cutoff ≤ actual departure | Cutoff date must be before or equal to actual departure (ATD) |
| Cutoff ≤ actual arrival | Cutoff date must be before or equal to actual arrival (ATA) |
| Pickup ≤ cutoff | Pickup date must be before or equal to cutoff date |
| Pickup ≤ actual departure | Pickup date must be before or equal to actual departure (ATD) |
| Pickup ≤ actual arrival | Pickup date must be before or equal to actual arrival (ATA) |
In short: pickup ≤ cutoff ≤ departure ≤ arrival.
These catch the commonest data error in operations: a date typed with the wrong month or year. If a save is refused and the dates look right, check the year — a January arrival against a December departure is usually last December.
Reference number formats
ACID
An ACID number must be exactly 19 digits. Anything else is rejected as "Invalid ACID number format".
Beyond the format check, ACID numbers are verified against Nafeza, the customs single-window system, and must be unique — "ACID number … already exists". Two consequences:
- Validation depends on an external service. "No ACID validation response received from Nafza" means Nafeza did not answer — a connectivity problem, not a wrong number. Retry rather than re-keying.
- "ACID validation failed" followed by a message is Nafeza's own answer. The number is well-formed but customs rejected it, and the message is theirs.
Master air waybill
A MAWB must be either 8 digits, or a 3-digit airline prefix followed by 7 or 8 digits, with an optional dash: 12345678, 123-4567890, 1234567890.
Two further checks:
- The 3-digit prefix must match a known airline. "Airline not found" means the airline is not in the catalog — add it there rather than working around the number. See Ports, agents, warehouses and carriers.
- The last digit must be 6 or lower. This reflects the IATA check digit, which is the remainder of a division by seven and so can only be 0–6. A number rejected for this is nearly always mistyped somewhere earlier, not in its final digit.
MAWB numbers must also be unique.
Documents that block progress
Some document slots are required, and their absence is refused with "Predefined document … is required", naming the one that is missing. This is the mechanism that stops a shipment progressing without its bill of lading or packing list — the requirement is configured per process rather than being a general rule, so which documents block depends on the workflow. See Running a transition.
Parties
| Party | Who |
|---|---|
| Shipper | Who is sending it. |
| Consignee | Who is receiving it. |
| Notifier | Who is told on arrival. |
| Forwarder | The forwarding party. |
| Agent | The counterpart handling the other end, plus any additional agents. |
| Company / Customer profile | Your customer, and which of their arrangements this falls under. |
Each party holds a full address block — name, address, city, state, postal code, country, VAT ID, ISO code — so documents can be produced without chasing details.
FCL shipments additionally carry a house shipper and house consignee, distinct from the master-level parties.
People on your side
Four operator fields split the work: general operator, trucking operator, clearance operator, plus trucking vendor and clearance vendor for the suppliers doing it. Filling these in is what makes "who is handling this?" answerable without asking around.
Status
| Status | Meaning |
|---|---|
| Draft | Being set up. |
| Pending | Ready but not started. |
| In progress | Live. |
| On hold | Paused. |
| Completed | Operationally finished. |
| Delivered | Cargo delivered. |
| Returned | Cargo came back. |
| Cancelled | Called off. |
| Failed | Did not complete. |
There is also a separate hold flag, distinct from the on hold status. The flag is a marker you can set on a shipment that is otherwise progressing normally — typically a commercial hold pending payment or documentation — without rewriting its operational status.
Bill of lading and release
| Field | Values / notes |
|---|---|
| Bill of lading type | Telex or Original. |
| Number of originals | Telex (0) or Originals (3). |
| Payment term | Prepaid (P) or Collect (C). |
| Contract party | Which side holds the carrier contract — your company, the client, or the agent. |
| Contract number | The carrier contract reference. |
| Hide consignee data | Default, Hide or Show — controls whether consignee details are suppressed on generated documents. |
Hide consignee data exists for back-to-back business where the consignee must not be visible to the other party. Default follows the configured behaviour; the explicit values override it for this shipment. If a customer has ever asked you not to reveal their buyer, this is the field.
Cargo
Cargo detail — packages, dimensions, containers — is covered separately in Cargo, packages and containers.
Notes and documents
Notes are timestamped entries attributed to the operator who wrote them: a running log of what happened on this job.
Documents come in two forms:
- Attached documents — anything you upload.
- Predefined documents — a set keyed by document type, so the bill of lading, packing list and certificate each have a known slot rather than being one of a dozen files with unhelpful names.
Use the predefined slots wherever one exists. It is what lets other people, and the system, find a document without opening every attachment.
Raising a quotation from a shipment
Work does not always start with a quotation. Where a shipment exists first, a quotation can be created from it — but five conditions must hold, and each produces its own message:
| Condition | Refusal |
|---|---|
| The shipment has no quotation yet | Shipment already has a quotation with ID: … |
| An incoterm is set | Shipment must have an incoterm (incoTerms) to create a quotation |
| The payment term is Prepaid | Quotation can only be created for shipments with Prepaid payment term |
| There is cargo — at least one package (LCL, air) or at least one container (FCL) | … must have at least one package to create a quotation / FCL shipment must have at least one container… |
| An operator is set | Operator is required to create a quotation |
The Prepaid restriction surprises people. A collect shipment cannot have a quotation raised from it, because on collect terms the charge is settled at the far end and there is nothing here to quote. If a collect shipment genuinely needs quoting, the payment term is what should be examined first — not the quotation.
The cargo condition is why the order matters: enter the packages or containers before attempting the quotation, or it is refused for having nothing to price.
Links to the rest of the system
- Quotation — the shipment can be linked to the quotation it came from, carrying its terms and conditions through.
- Warehouse and storage date — where cargo is being held, which is what storage charges are calculated from.
- Vessel, voyage, master shipment, containers — see Master shipments, containers and voyages.
- ACID — the customs declaration identifier, with a separate house ACID on FCL.
Moving a shipment along
You do not change a shipment's step by editing it. Progress happens through transitions defined by its workflow — see Workflows and Running a transition.
Shipments from XML
Some shipments arrive from an external system rather than being keyed in, and are flagged as such. Where an inbound message could not be applied cleanly, the record carries update results listing what succeeded and what failed, with validation errors marked as error or warning. Check these on any shipment that arrived automatically and looks incomplete — the answer is usually there rather than in the data itself.
Last updated 9 September 2026