Document Statuses Explained
Understanding the 6 document statuses and what triggers each one
Showing every variant, each marked with the profiles it applies to.
Overview
A document in StarShipper carries a status that says where it is in the processing pipeline. The status decides whether the document can be delivered to your integrations without a human looking at it first, or whether it needs your attention.
Key insight: Status answers a single question, which is whether a person needs to check something. Four signals feed it, in this order: whether extraction threw an error, whether a required field is missing, whether the extractor flagged particular fields it was unsure about, and the overall confidence score. The first signal that applies decides the status, and the confidence score is only consulted when the ones above it are clear.
The 6 Document Statuses
What each status means and what puts a document into it
ProcessingTemporary
The document is being read by the AI. A short text-layer PDF takes a few seconds; a long scanned document goes through page-by-page vision OCR and takes considerably longer.
ReadyNothing flagged
The extraction came back with nothing specific to verify. Ready is the single gate for both the review badge and automatic delivery, so a document is treated the same way whether it goes out by itself or you send it by hand.
A document reaches Ready when all of these hold:
- Extraction completed without throwing an error
- No required fields are missing
- The extractor flagged no individual fields for review
- Overall confidence is 70% or above
Needs ReviewAction Required
Extraction worked, and something in the result wants a human glance before the data goes anywhere. You get a notification naming the specific fields.
Triggers (any of these):
- A required field is missing, at any confidence score
- The extractor flagged particular fields as low confidence
- Overall confidence is below 70%
SentDelivered
The document reached at least one destination. On your profile those are CargoWise, Expedient, Xero, Google Sheets, SAP, Third Party Email and Webhook. You can still resend it.
FailedError
Failed means the extraction produced nothing usable. A document that merely missed some fields is Needs Review instead, because the extraction itself worked.
Triggers (any of these):
- Extraction threw an error, such as a timeout, a parsing failure or an unreadable file
- Overall confidence below 50% with no missing required fields to explain it
Awaiting CreditsPaused
Nothing is wrong with the document. Extraction is paused because your organisation has used its monthly document allowance, so the file is held rather than processed. It is not an error and it never counts as a failure.
Triggers:
- The monthly document allowance for your plan is exhausted
Confidence Thresholds
Where the confidence score lands a document, once the checks above it are clear
The score is not the whole answer. A document scoring 100% still goes to Needs Review if a required field is missing or the extractor flagged a field, because those checks run first. The bands above apply only once both are clear. Real customs documents rarely score in the high nineties, which is why the Ready line sits at 70% and the flagged-field checks do the precise work.
Content warnings do not change the status. Findings such as a container check-digit that does not compute, or a code StarShipper does not recognise, are reported against the document for you to read. They leave the status alone. Only a missing required field holds a document back.
What "Ready" Does Not Guarantee
Three reasons a Ready document can sit without being delivered
Reaching Ready makes a document eligible for automatic delivery. Approval and delivery are separate judgements, though, and the second one looks at the whole shipment rather than the single file.
Cross-document checks disagree
When the documents on a shipment contradict each other, for instance a container number on the packing list that the bill of lading does not carry, the document stays Ready and is not auto-approved. Resolve the mismatch, then send it.
The rest of the upload is still arriving
Delivery waits for the batch to settle so a destination receives one complete shipment instead of a partial record followed by corrections. The document is approved immediately; the send follows once the batch is done.
The document is not attached to a shipment
Delivery is built from the shipment record, so an unassigned document has nothing to send. Assign it from the Unassigned tab and it goes out on the next dispatch.
Status Flow
How documents move between statuses
Re-extraction sets a new status
"Re-Extract" runs the AI again and works out a fresh status from the new result. It is the only way back out of Failed, and the only way a Sent document returns to Ready or Needs Review.
Awaiting Credits is a parking state
It leads nowhere on its own. Resuming a held document puts it back into Processing and the pipeline runs properly from there, which is why the result is a real status rather than a guess made at the time it was parked.