Document Processing Pipeline
How documents flow through StarShipper from upload to delivery, and how the document types they are read against are configured
Showing every variant, each marked with the profiles it applies to.
Overview
When you upload a document or forward an email to StarShipper, it goes through an automated pipeline that extracts data, validates it, and delivers it to your connected systems. A single-page invoice is usually done in well under a minute. A long scanned document is read page by page and takes proportionally longer, so a hundred-page file is a matter of minutes.
Tip: Documents with clear formatting and standard layouts are processed faster and with higher accuracy. Scanned documents may take longer due to OCR processing.
The 4-Step Pipeline
The journey a document takes, whichever way it arrives
1. Upload / Receive~1 second
Documents enter the system by direct upload in the dashboard or by forwarding emails to your inbox address. The same formats are accepted either way, and every upload surface reads the same list:
2. Data Extraction2-20 seconds
StarShipper analyzes the document to identify its type (e.g., Bill of Lading, Commercial Invoice) and extracts all relevant fields. The extraction method depends on the file type:
XML, JSON, Excel, CSV: A parser reads the file directly and copies the values across, so there is no interpretation involved. If the file does not parse into usable data, the document falls back to AI extraction rather than failing.
PDF, Images: AI Vision analyzes the document and extracts fields. A confidence score indicates how clearly the AI could interpret the data.
Document Type Detection: If you've configured a specific document type for your inbox, validation checks against that schema. Otherwise, it auto-detects from 25 supported shipping document types.
3. Status DeterminationInstant
The result decides the status, which decides what happens next. A document with nothing flagged carries on by itself. Anything with a missing required field, a field the extractor was unsure about, or low overall confidence waits for you.
4. Automatic Delivery~1-5 seconds
A document at "Ready" is eligible for automatic delivery to whichever destinations you have connected. The send waits for the rest of the upload to arrive, so a destination receives one complete shipment rather than a partial record followed by corrections. Delivery is also held back when the documents on a shipment contradict each other, which leaves the document at "Ready" for you to look at.
Document types and their fields
A living schema that grows from your real documents, not a template you define upfront
Every document StarShipper reads is identified as a type — commercial invoice, bill of lading, packing list, and so on. Each type carries its own set of extraction fields, which define what data gets pulled out of it.
You do not need to set those fields up in advance. They appear automatically the first time a document of that type is processed, and new ones are discovered as more documents come through. Settings → Doc Types shows every field StarShipper has ever extracted for a type, how many documents contained it, and whether it is required.
Fields auto-populate
The first time an extraction finds a paymentTerms on a commercial invoice, that field appears in the table on its own. New fields carry a "NEW" badge for seven days so you notice them.
Required fields
Mark a field required and a document that is missing it is held for review with a validation warning instead of being auto-approved — useful for whatever your compliance process depends on, like HS codes on invoices or consignee details on bills of lading.
Hidden fields
Hide a field you do not care about and it is still extracted — the data is not lost — it just stops cluttering the document detail view and your field mappings.
The Docs count
How many documents have contained that field. A high count means it is reliably extracted; a low one usually means it only appears on certain vendors' paperwork. It is the number to judge a field by before marking it required.
Industry profiles and which types you see
The business type you pick when setting up your organisation decides more than the document type list. It also sets which sections appear in your navigation and which integrations you are offered, and it is the single input to both. There is no per-feature toggle on top of it.
A business that runs a forwarding arm and an agency arm holds two organisations and moves between them with the organisation switcher, so each one stays a single coherent workspace.
Customs Broker
Shipments, Orders, Documents and Finance in the navigation, plus the customs screens. All core document types are enabled. The niche certificates, such as fumigation and phytosanitary, start hidden until one turns up.
Freight Forwarder
The same navigation and the same document type defaults as a customs broker. The two profiles differ in the work rather than the setup, and the customs screens are available to both.
Shipping Agency
Bookings, Bills of Lading, Documents and Finance rather than Shipments and Orders. Purchase orders and customs declarations are off by default, since agencies do not usually handle them, and the forwarder-side integrations are not offered.
What "disabled" actually means: a disabled type is not deleted, only greyed out so it does not clutter the page. If StarShipper detects one in a real upload it re-enables the type automatically — you will never lose data because a type was switched off. Toggle any type yourself with the eye icon on its row; your choice overrides the industry default, and changing your profile later preserves anything you have deliberately toggled or customised.
Customised types, and types you create
Where a type's configuration came from, readable at a glance
System default
The built-in schema. No badge, no coloured border. These cover the standard document types and are maintained by StarShipper as fields and types are added.
Customisedamber border
A system type you have changed — marked fields required, hidden fields, or toggled the type. "Reset to Default" reverts every one of those changes and returns it to the system schema. Documents already extracted keep their data either way.
Customgreen border
A type you created. You give it a slug, a display name and an initial field list — prefix a field with * to make it required. StarShipper generates a tailored extraction prompt from those definitions, so a custom type extracts as well as a built-in one, plus whatever else it finds in the document.
When to create one: for documents StarShipper does not recognise out of the box — warehouse receipts, delivery orders, survey reports, anything specific to your workflow. If a document keeps coming back as "Unclassified", a custom type for it will improve extraction markedly. If it keeps being classified as something close but not right, customising that existing type is usually the better move than adding a new one.
Field mappings
Extracted field names are StarShipper's. The system you send them to has its own. Pick an integration at the top of Settings → Doc Types and a "Maps to" column appears in every field table: if your webhook expects house_bill where StarShipper extracts hblNumber, set the mapping and the translation happens on the way out.
Mappings are per integration and per document type, so the same field can go to two systems under two different names. How each destination is scoped →
Troubleshooting document types
A document type I need is not showing
It is almost certainly disabled by your industry profile. Disabled types sit greyed out in their normal position in the list — click the eye icon to enable one. Or just upload a document of that type; it will be enabled for you.
A type has no fields yet
Fields appear after the first document of that type is processed. If they still do not, the document was probably classified as something else — open the document detail to see which type was detected.
I customised a type and want to undo all of it
"Reset to Default" — the amber reset icon on the row — reverts required flags, hidden fields and visibility in one go. Your extracted documents are untouched.
My custom type is not matching documents
Classification reads field signatures and keywords, so a custom type needs field names distinctive enough to be recognised in the documents themselves.
What Happens When Things Need Review?
Not all documents process perfectly on the first try. Here's what happens:
Needs Review (a missing or flagged field, or confidence under 70%)
The document appears in your review queue. You can view the extracted data, make corrections if needed, and then manually approve it for delivery.
Failed (extraction error, or confidence under 50% with no missing fields)
The AI couldn't reliably extract data. You can try re-extracting the document, or upload a clearer version. Common causes include poor scan quality or unusual document formats.
Re-extraction: You can always re-extract a document to try again. This is useful after the AI has been updated or if the initial extraction had issues. Learn about re-extraction →
Typical Processing Times
| File Type | Method | Typical Time | Notes |
|---|---|---|---|
| XML | Direct | 1-2 seconds | Values copied from the file; AI fallback if it will not parse |
| JSON | Direct | 1-2 seconds | Values copied from the file; AI fallback if it will not parse |
| Excel (XLSX, CSV) | Direct | 2-5 seconds | Values copied from the file; AI fallback if it will not parse |
| PDF (text-based) | AI Vision | 5-15 seconds | AI extraction with confidence score |
| PDF (scanned/image) | AI Vision | 10-30 seconds | OCR + AI extraction |
| Images (JPG/PNG) | AI Vision | 10-30 seconds | AI extraction with confidence score |
Direct extraction (XML, JSON, Excel, CSV) copies values out of the source file, so there is nothing to be confident or unconfident about. A file that will not parse into usable data goes to AI extraction instead, so a structured format is not a guarantee of a direct read. AI Vision extraction (PDF, images) uses Claude Vision to read the document and returns a confidence score per field, which is what drives the status.
Related Articles
Document Statuses Explained
Understanding the 6 document statuses and what they mean
Integrations Overview
Where delivered data can go, and how each destination is scoped
Re-Extract & Resend
How to reprocess documents and resend to your systems
CargoWise Integration
Push document data to CargoWise via eAdaptor