Delivery Note Extraction API: Developer Implementation Guide

A delivery note extraction API converts delivery notes, dispatch notes, packing slips, and proof-of-delivery forms into structured JSON, CSV, or XLSX. For most teams, that means extracting delivery dates, document numbers, item tables, recipient details, carrier references, and signatures in a format your systems can actually consume. If the output cannot move directly into receiving, ERP or WMS sync, or invoice reconciliation, it is not solving the real problem.

That is the difference between OCR and extraction. A generic OCR layer gives you text. A delivery note data extraction API should give you fielded operational data: header fields, line items, references, normalized dates, and exception-ready outputs that can be validated and routed. You should not have to rebuild tables from raw text, guess whether a reference belongs to the shipment or the supplier, or hand-map every document layout before the data becomes usable.

That requirement is not theoretical. A 2025 MHL News report on document-processing hurdles in logistics back offices said 82% of respondents reported that manual document processing remains a significant hurdle for the sector, and 49% cited the absence of standardized document formats as a significant challenge. For developers, that points to the real implementation work: building flexible schemas, preserving line-item structure, and validating extracted values instead of relying on brittle fixed-template parsing.

So when you assess a delivery note extraction API, the key question is not whether it can read a document. It is whether it can return structured shipment data that still holds up when document variants change, fields move between header and footer, line items spill across pages, or receiving and invoice-matching rules need additional checks. The rest of this guide focuses on those implementation choices: document variants, schema design, validation patterns, and the downstream logic that turns extracted delivery-note data into something your operations stack can trust.

Map Document Variants and Field Groups Before You Build

If you are evaluating a delivery note extraction API, start by treating delivery notes, dispatch notes, packing slips, and proof of delivery (POD) forms as one document family with controlled variation, not as four unrelated workflows and not as one identical template. They all describe a shipment or receipt event, so they often share core references, parties, and item data. But they do not serve the same operational purpose. A dispatch note may emphasize what left the warehouse. A packing slip may focus on carton contents. A POD may add signatures, timestamps, shortages, or damage annotations. If you model them as identical, your schema will be too thin for exception handling and too rigid for real supplier variation.

A better approach is to define a shared base schema, then add variant-specific fields where they are actually needed. For a quick refresher on the fields a delivery note usually includes, think in terms of operational data groups rather than page zones or one supplier's visual layout.

• Header metadata: document type, delivery note number, dispatch note number, packing slip number, POD number, delivery date, shipment date, supplier or shipper name, supplier identifier, warehouse or branch code.
• Recipient details: consignee name, recipient site, delivery address, store code, receiving location, contact name.
• Shipment references: purchase order number, sales order number, shipment ID, consignment number, route ID, trailer number, carrier references, tracking number.
• Item-table fields: SKU or item code, supplier item code, description, batch or lot number, serial number, unit of measure, quantities shipped, quantities received, backordered quantity, damaged quantity.
• Proof-of-receipt fields: receiver name, signature present, delivery timestamp, driver name, POD status, shortage noted, damage noted, receiver comments.

This grouping is what keeps a packing slip extraction API or dispatch note extraction API usable across multiple suppliers. Your downstream systems rarely care that one vendor prints the consignee block on the left and another hides it under a barcode. They care whether you can consistently map the shipment reference, the recipient site, and the received quantities into receiving, reconciliation, and exception queues.

A shared workflow is realistic when the documents still answer the same core questions: what was shipped, to whom, when, and in what quantities. In practice, that usually means you can keep one extraction family when the item table is structurally similar, the reference fields are comparable, and the receiving team applies the same business logic after extraction. That is common across delivery notes, dispatch notes, and many packing slips.

You should split into separate classification or extraction branches when the divergence affects meaning, not just layout. Common examples include POD forms with signatures and incident notes but no usable line-item table, carrier manifests that list package events instead of delivered goods, or supplier-specific documents where quantities shipped and quantities received are represented differently enough to change your downstream rules. If one variant needs receipt confirmation and another is purely pre-delivery paperwork, forcing both through the same schema usually creates null-heavy output and brittle mappings.

The practical test is simple: design fields around decisions your receiving or finance workflow must make next. If the output will feed goods receipt, ERP or WMS updates, or invoice reconciliation, then fields like recipient site, carrier references, quantities shipped, quantities received, and POD markers deserve explicit treatment even if they appear inconsistently on source documents. Build for the operational event you need to capture, not for the first PDF layout you happened to sample.

Use Prompt Design and Output Structure to Keep Line Items Usable

The fastest way to get a proof of concept working is to send a natural-language prompt such as "extract the delivery note details and line items." The safest way to build a production workflow is usually different. If your API supports both a plain-language prompt and a structured object or dict with fields plus a general prompt, use the structured form when column names must be exact. That gives you tighter control over field naming, output order, and repeatability, which matters when downstream code expects stable keys instead of loosely interpreted labels.

For a delivery note extraction API, separate document-level fields from row-level fields before you write the prompt. Your header layer might include delivery note number, shipment reference, supplier name, delivery date, warehouse or site, carrier, and PO number. Your row layer might include line number, SKU or item code, description, delivered quantity, unit of measure, unit price if present, batch or lot number, and any status notes such as short shipped or damaged. That split keeps line-item extraction usable for receiving workflows, inventory updates, and later invoice matching, instead of forcing your team to parse a text blob after the fact.

The documented output structure choices are automatic, per_invoice, and per_line_item. For delivery note line item extraction API use cases, per_line_item is usually the safer choice whenever tables are detailed, inconsistent across suppliers, or likely to span pages. It gives you one row per extracted line with the header fields repeated on each row, which makes filtering, regrouping, and validation much easier. Per_invoice can work if you only need header data or a very small summary of delivered goods. Automatic is useful for experimentation, but it is less predictable when your application logic depends on a specific JSON schema.

You can sometimes keep line items inside a nested JSON field on a single delivery-note-level row, and that can be fine for a lighter delivery note OCR to JSON workflow or an internal prototype. But it becomes harder to work with when you need reliable row-level extraction, detailed field instructions, or consistent handling of messy tables. If your next step is to compare delivered quantities against receiving records, push rows into an ERP or WMS, or isolate exceptions line by line, the docs' recommendation to use per_line_item is the better default.

There is one regrouping rule worth treating as mandatory: do not rely on the default Source File column alone to reconstruct the document. Files get renamed, split, merged, or reprocessed. Keep a persistent identifier in the extracted output, ideally a delivery note number, shipment reference, dispatch number, or other stable document key. Then repeat that identifier on every line-item row. That is what lets your application safely rebuild a header-plus-lines structure after sorting, deduping, batching, or joining rows with purchase order and receiving data.

Prompt design matters as much as the schema. A good starting schema for a receiving workflow often includes:

• Delivery Note Number
• Shipment Reference
• Supplier Name
• Delivery Date
• PO Number
• SKU
• Line Description
• Quantity Shipped
• Quantity Received
• Unit of Measure
• Exception Note

Then add the edge-case rules that make the output usable in production:

• Tell the model to capture SKU or item code separately from description when both appear in the same cell.
• Tell it how to handle partial deliveries, for example by extracting delivered quantity separately from ordered quantity, backordered quantity, or remaining quantity if those values appear.
• Tell it to preserve units of measure as their own field, rather than burying them inside quantity text.
• Tell it how to format quantities, dates, and references, such as decimal precision, leading zeros, or normalized date format.
• Tell it what to do with missing values so your application can distinguish blank, not present, and zero.
• Tell it how to handle nonstandard tables, such as continuation rows, wrapped descriptions, handwritten annotations, or totals mixed into the item table.

That is the practical difference between a demo prompt and a production prompt. In a live workflow, you want one row per line item, the delivery note number repeated on each row, SKU pulled from the item code column or a labeled description token, quantity and unit of measure stored separately, and missing values left blank rather than guessed. If you are using Invoice Data Extraction, that approach fits the platform well because it supports natural-language prompts, structured field definitions, custom field naming, per-line-item extraction, and downloadable JSON, CSV, or XLSX outputs through the same extraction workflow.

Finally, remember that JSON output values arrive as strings, including nested JSON fields. That means prompt-level formatting is not optional. If you want quantities to be parseable, say how decimals should look. If you want dates normalized, state the target format. If you want booleans or status flags, define the allowed values. Then parse and cast types in your application code instead of assuming the API will deliver native numeric or date types in JSON. That discipline is what keeps delivery note line-item extraction usable after the demo, when the real workload starts.

Validate Delivery Note Data Against Purchase Orders and Supplier Invoices

A delivery note becomes operationally useful when you treat it as a verification input, not just an OCR result. The real job is to compare what the supplier says was shipped against what you expected to receive and what you were later billed for. That means validating extracted delivery-note data against purchase orders, expected receipts, and supplier invoices at both the header level and the line-item level.

At the header level, your matching rules usually start with supplier name, delivery note number, purchase order reference, shipment or consignment reference, delivery date, and receiving location. At the line-item level, you need item codes, supplier part numbers, descriptions, ordered quantity, delivered quantity, unit of measure, and sometimes batch or lot references. If you want those comparisons to work reliably later, your extraction prompt and schema need to capture the identifiers and quantities your rules actually depend on. Teams that skip this step often end up with a clean-looking JSON payload that is missing the one field required to reconcile the document.

In practice, your receiving controls should look for a small set of high-value mismatch patterns:

• Partial deliveries: The delivery note matches the purchase order, but only some lines or quantities arrived.
• Substitutions: The supplier shipped a different SKU, pack size, or description than the ordered item.
• Short shipments: The document shows fewer units than the purchase order or expected receipt.
• Duplicate references: The same delivery note number, shipment reference, or supplier reference appears more than once.
• Quantity mismatches: Ordered, delivered, received, and invoiced quantities do not align.
• Date mismatches: Delivery date, goods-received date, invoice date, or expected receipt date fall outside your tolerances.

Those checks should drive workflow, not sit in a report. A matched delivery note can support goods-received posting, release downstream receiving steps, or confirm that an invoice should move into two-way or three-way review. A mismatched one should create an exception with enough context for a buyer, warehouse lead, or AP analyst to act on it. If you are also matching extracted delivery-note data to supplier invoices, the delivery note gives you the evidence for whether the invoice reflects what was actually shipped and received. Likewise, building a matching-ready purchase order extraction API workflow makes the upstream comparison much more dependable because the purchase order and delivery note are already normalized into compatible fields.

This is why schema design matters as much as model accuracy. If your downstream logic needs to match on PO number plus supplier SKU plus delivered quantity, ask for those fields explicitly. If your warehouse tolerates substitutions only when the original line reference is preserved, capture both the shipped item identifier and the ordered reference. If invoice matching depends on unit of measure conversions, do not settle for a generic quantity field. Design the extraction output around the validation decisions you need to make later.

Keep traceability in scope when you choose an API for this workflow. A good implementation should return structured outputs, preserve source-file and page references for review, and surface failed pages or AI uncertainty notes when the model had to make assumptions. Those signals should feed your exception queue, not be ignored, because page-level failures and ambiguity directly affect how much confidence you should place in any downstream match.

Design for Low-Quality Inputs, Handwriting, and Receiving Exceptions

Most delivery-note projects fail on document quality, not on JSON formatting. Your extraction flow has to survive low-resolution scans, phone photos from receiving docks, skewed images, cropped pages, rubber stamps over tables, multi-page line-item continuations, handwritten shortage notes, and supplier-specific layouts that move the same field to different places. If you only test against clean export PDFs, you will approve a workflow that breaks the first time a warehouse supervisor uploads a signed paper copy.

Build around the failure modes you already know will happen:

• Low-quality scans and mobile photos: Expect blur, shadows, tilted framing, and partial crops. Test whether core fields still extract when page edges are missing or the camera angle is off.
• Handwritten annotations: Drivers and receivers often add quantities received, damage notes, trailer references, or short-ship comments by hand. Treat those as operational data, not noise.
• Rubber stamps and overlays: Received stamps, date stamps, and internal routing marks can obscure supplier references, line totals, or delivery dates.
• Multi-page tables: A usable workflow must preserve line-item continuity when one shipment table rolls onto a second or third page.
• Inconsistent layouts: Some suppliers put PO numbers in the header, some in a references block, some only near the line table. Carrier proofs of delivery may not resemble packing slips at all.

This is where prompt and schema control matter more than raw OCR alone. You need extraction rules that tell the model what to prioritize, what to ignore, and how to behave when the document is messy. Good instructions are usually explicit: extract receiver signature status, capture handwritten exception notes into a separate field, ignore email cover sheets, skip barcode-only separator pages, and return page references for fields that may need review. That is also where it helps to choose a platform that explicitly supports scanned PDFs, JPGs, PNGs, lower-quality scans, mobile photos, and prompt-level page-handling instructions instead of assuming a clean digital-input workflow.

Proof-of-delivery documents also need a different extraction emphasis from standard packing slips. For a proof of delivery OCR API, the highest-value fields are often signatures, receipt date and time, receiver name, site confirmation, and handwritten exception notes such as damaged, partial, refused, or short received. A packing slip workflow may focus on SKU, quantity shipped, and order references. A proof-of-delivery workflow may need to treat signature presence, delivery completion evidence, and exception text as the primary output. If you force both document types through one generic schema, you usually end up with bloated fields on one side and missing operational signals on the other.

A practical pattern is to maintain a representative sample set before you lock the workflow. Include:

• Clean supplier PDFs
• Poor scans from shared printers
• Mobile photos from warehouse receiving
• Signed proof-of-delivery pages
• Documents with handwritten shortage or damage notes
• Multi-page shipments with table continuations
• Examples from multiple suppliers and carriers
• At least a few bad cases with cropped pages, stamps, and unreadable regions

Run that sample set repeatedly as you refine prompts and output fields. If one broad schema keeps getting looser to accommodate every variant, split the flow. Classify first, then route into narrower extraction paths such as packing slip, delivery note, proof of delivery, or carrier receipt. That usually produces cleaner downstream data than trying to make one universal document contract handle every receiving scenario.

You should also design explicit exception handling into the integration. Some pages will fail. Some fields will be ambiguous. Some signatures will be present but illegible. Some handwritten notes will clearly indicate a receiving issue without matching any predefined field. Your API workflow should return structured exceptions for those cases, not pretend extraction succeeded cleanly. At minimum, flag failed pages, surface low-confidence or ambiguous fields for review, preserve source file and page references, and keep unmatched notes in a raw exceptions field so receiving or AP teams can decide whether the document should update inventory, trigger a discrepancy workflow, or pause invoice reconciliation.

Choose the Integration Pattern That Fits Your Stack

For most teams, the best starting point is the official SDK path, not a hand-built client. The Python SDK installs with pip install invoicedataextraction-sdk and requires Python 3.9+. The Node SDK installs with npm install @invoicedataextraction/sdk and requires Node.js 18+. In both cases, the happy path is a single extract() call that wraps file upload, extraction submission, polling, and output download.

Move to staged SDK methods or raw REST when the delivery-note workflow is spread across multiple services. That is common when dock uploads land in one queue, a background worker submits extraction later, and another service handles ERP receipt posting or exception review. In that setup, it helps to split upload, submission, polling, and download into separate steps instead of forcing one process to own the whole lifecycle.

If you are not using Python or Node, the REST flow is straightforward but more manual. You create an upload session, request presigned part-upload URLs, upload each part, complete each file upload, submit the extraction task, poll for status no more frequently than every 5 seconds, and then download the output files. Authentication uses a Bearer-token API key. Output is available as XLSX, CSV, or JSON. The download URLs are temporary, so production integrations should treat download as a deliberate workflow step rather than assuming the first URL will still be valid later.

Where you place extraction in the wider system should depend on what the delivery note triggers next. If the document is primarily part of receiving, the extracted output usually lands in a warehouse management system (WMS) or a receiving dashboard to confirm quantities received, shortages, or damaged-item exceptions. If it is part of goods receipt and supplier reconciliation, the same structured result can feed enterprise resource planning (ERP) receiving modules and then support PO matching or invoice checks downstream. If the delivery note sits closer to shipment confirmation and carrier handoff, selected fields may flow into transportation management systems (TMS) instead. Teams that are also automating adjacent logistics documents such as bills of lading often use the same pattern across multiple document types, with one extraction layer feeding several operational systems.

If you use Invoice Data Extraction here, the practical benefit is continuity rather than extra abstraction. The API exposes the same extraction engine as the web product, so teams can test the workflow in the dashboard, then move the same logic into an SDK- or REST-driven integration once the receiving and exception-handling path is clear.

When a Configurable API Beats a Fixed Delivery Note Parser

A fixed delivery note parser can be enough when your document set is narrow, the layouts are stable, the required fields rarely change, and downstream logic is minimal. If one supplier group sends the same format every time and you only need a few header fields plus a basic item table, a narrowly tuned delivery note parser API may be perfectly reasonable.

A delivery note OCR API needs more flexibility when you are dealing with multiple document variants, supplier-specific fields, proof-of-delivery forms, line-item exceptions, or validation rules that depend on more than text capture. The moment you need to control field names, repeat stable identifiers on each row, distinguish shipped from received quantities, or route the output into WMS or ERP logic, a configurable approach becomes more valuable than a fixed layout parser.

Use that as the decision rule. Choose the fixed option when layouts are stable and post-extraction handling is shallow. Choose a configurable API when schema variation is normal, line-item control matters, and extraction has to feed reconciliation or exception handling. That is why many teams evaluating a document extraction API for logistics workflows are really choosing how much control they need over the data contract between incoming documents and downstream operations.

Keep the product claim honest while you make that choice. Invoice Data Extraction should be positioned as a configurable document extraction API that can be adapted to delivery-note workflows through prompts, structured field definitions, line-item capture, and structured JSON, CSV, or XLSX outputs. It should not be presented as a dedicated delivery-note-only model with a separate product surface or a fixed delivery-note endpoint, because the current docs do not support that claim.

Then run a pilot against a representative sample that includes delivery notes, packing slips, dispatch notes, and proof-of-delivery pages. Score the results against the criteria that matter in production:

• Schema fit across document variants
• Line-item accuracy and regrouping reliability
• Exception handling for failed or ambiguous pages
• Validation readiness against purchase orders, receipts, and invoices
• Ease of routing the output into your existing warehouse and finance systems

If the workflow still holds together on real receiving documents, you likely need the configurable route. If it only works cleanly on one narrow document family, the fixed parser may be enough.