Entry statuses, explained

Canonical reference for every status a customs entry can hold in Commers, mapped to the workflow phase it represents and the action that moves it forward.

This doc is the single source of truth for:

• What each DB status means (the customs_clearance.shipments.status column)
• Which broker / CBP / Autopilot action triggers the next transition
• How the Dashboard filter buckets and the "Needs review" KPI tile map to these statuses

For the visual workflow this maps onto, see the visual workflow — open it in any browser to see the 9-step end-to-end flow (Pre-shipment → Document review → Entry filing → Post-entry).

For the state-machine code itself, see Autopilot.

---

The 8 statuses

Listed in lifecycle order. Every entry walks this path; some terminate early at released if the broker doesn't need to settle duty separately, or detour through hold / exam if CBP escalates.

Status vs. Stage (the pipeline)

The 8 statuses above are the state-machine — the durable value in shipments.status. On top of that, every list + detail response also carries a pipeline stage: a broker-facing reading of where the entry is in the 9-step workflow and what's left to do. It is derived, never stored, by the pure deriveShipmentStage, and it is the single source of truth behind both the Shipments table (the Stage / Next action columns) and the drawer stepper — so the two can never disagree.

The 9 canonical stage names (STAGE_NAMES) — the same words in the table, the KPI cards, and the drawer stepper:

PO & Shipment · ISF · Documents · HTS Classification · Duty Calc · PGA / UFLPA · ACE Filing · CBP · Post-Entry

Two axes are kept deliberately separate:

• Position (step / stage + the 9-dot states[]) reads the furthest step reached, exactly like a "you are here" stepper. A step is "done" only when the underlying work actually happened (lines classified, duty computed, screening cleared, entry filed). A soft concern does not move the entry backward.
• Health (ontrack / attention / blocked) + the one-line action. This is where a concern surfaces.

Hard blockers genuinely gate forward movement, so they un-do the step they sit behind (the entry parks there; the dot never shows a false green tick):

The HTS confidence gate (HTS_REVIEW_THRESHOLD = 70)

Any line classified below 70% confidence un-does the HTS Classification step, so the entry parks at HTS Classification with a red "Blocked — HTS at N% (< 70%), broker review required" — it can never read as "ready to transmit" on an unreviewed low-confidence code. The block:

• bites only while the entry is still in review (draft / ai_review); once a broker approves it to file, it's their call and the entry moves on;
• lands the broker in the drawer's HTS Classification section — exactly where each line's confidence and any invoice-mismatch warnings are shown.

Two thresholds, don't conflate them: the 70% floor here is the review gate (hard-blocks for a human to look). The 92% floor in Autopilot is the higher auto-file bar (Autopilot only transmits at or above it). A sub-70% entry was never going to auto-file anyway; this gate just makes the manual review queue honest about why it's parked.

The owner axis (StageOwner) — whose move is it?

Alongside position and health, deriveShipmentStage names who the next move belongs to: broker (the default — it's your workbench), cbp (filed / under exam — the government has it), supplier (UFLPA high-risk — you're waiting on their traceability docs), or importer (an empty draft — waiting on their commercial documents). Chasing a supplier or importer is still your move (send the reminder); only owner: 'cbp' counts as genuinely waiting on others, because there is no useful action to take against CBP's clock.

The Needs-You action feed (GET /today/actions)

The Today home renders ONE ranked list across three sources — entries needing work, CF-28/29 notices, and in-force rate-change proposals — built by getActionFeed: deterministic, zero LLM calls, ≤3 SQL statements. Each item carries the plain-language action, the owner above, an honest deadline (only real due_by / effective_date dates — "Overdue 37d", "Due in 3d", "In force — unreviewed"; no fabricated urgency), and value at risk. Ranking: blocked first → nearest deadline → highest value. The feed is split yourMove vs waiting on the owner rule above. This is the notification surface — Today is the inbox, Shipments is the workbench.

State transitions

                                              (broker dismisses hit)
              ┌──────────────────────────────────────────────┐
              ▼                                              │
        ┌─────────┐                                      ┌───┴───┐
        │  draft  │──extract+classify+screen──┐          │ hold  │◄──┐
        └─────────┘                           ▼          └───────┘   │  (UFLPA / entity)
                                       ┌─────────────┐               │
                                       │  ai_review  │───────────────┘
                                       └──────┬──────┘
                              (approve / auto-approve)
                                              ▼
                                         ┌─────────┐    transmit ABI    ┌─────────┐
                                         │  ready  │───────────────────►│  filed  │
                                         └─────────┘                    └────┬────┘
                                                                             │
                                              ┌──────────────────────────────┤
                                              ▼               ▼              ▼
                                        ┌──────────┐    ┌───────┐      ┌──────────┐
                                        │  exam    │    │ hold  │      │ released │
                                        └────┬─────┘    └───────┘      └─────┬────┘
                                             │                               │ pay duty
                                             ▼                               ▼ within 10d
                                        ┌──────────┐                   ┌─────────┐
                                        │ released │──────────────────►│ cleared │
                                        └──────────┘                   └─────────┘

Mapping to the Dashboard

The Dashboard filter exposes one bucket per status plus two meta-filters:

The hold + exam and ai_review (low confidence) combo is the only deliberate lumping — those three are the entries a broker triages first thing each morning, so they cluster as "Needs review" both in the KPI tile and in the Filter popover preset.

What this status model does NOT yet capture

These are workflow steps from the visual workflow that don't currently have a dedicated status because they live in adjacent modules or aren't yet built:

• ISF Filing (Step 2) — Importer Security Filing, 24h-before-departure. Not modelled today. Late ISF = $5,000 CBP penalty per violation. Will live in the customs-clearance module as a separate filing alongside the entry, not as a status of the entry itself.
• Duty Payment (Step 8) — sits inside the released → cleared transition today. We don't separately track "duty paid" vs "duty pending past 10 days" — that distinction is needed to surface the capital-float risk to the broker. Q3 2026 roadmap.
• Post-Entry Audit (Step 9) — CF-28 / CF-29 inquiries. Lives in the post-entry-audit module (13 active cases today, see sidebar). Not surfaced on the Dashboard yet. Would be a new KPI tile: "Cleared entries within audit window".

Roadmap

• Q3 2026 — Rename ai_review → awaiting_broker to disambiguate from "AI is currently reviewing".
• Q3 2026 — Add duty_pending status between released and cleared to make capital-float visible.
• Q4 2026 — Add an ISF entity (not a status) — separate filing tracked alongside the entry.
• Q4 2026 — Surface cleared + audit-window-overlap as a Dashboard KPI tile linking into post-entry audit.