- A supplier invoice can be perfectly genuine and still be wrong for payment.
- The purchase order may contain ten units.
- Accounts payable cannot answer that situation by checking whether an invoice exists.
- That was the client problem we addressed on a B2B procurement platform built with Medusa.
The client problem
A supplier invoice can be perfectly genuine and still be wrong for payment.
The purchase order may contain ten units. The property may have received eight. Two may have been returned or claimed. The supplier may invoice a revised price, add shipping, apply a discount or send a replacement PDF after the first document was reviewed.
Accounts payable cannot answer that situation by checking whether an invoice exists. Nor can it rely on the invoice total alone.
That was the client problem we addressed on a B2B procurement platform built with Medusa. Before a purchase-order payment could progress, the platform needed to compare three concrete truths: what the buyer ordered, what the receiving workflow says arrived and what the reviewed supplier invoice asks the organisation to pay.
We built that comparison into the commerce workflow and turned every discrepancy into a reviewable business reason.
The objective was not accounting theatre. It was to prevent payment from moving forward on an unexplained mismatch.
Why “invoice received” is not a payment decision
An invoice PDF proves that a supplier sent a document. It does not prove that the requested amount matches the transaction.
Several legitimate events can create differences:
- the supplier shipped fewer units than ordered;
- receiving recorded damaged or missing goods;
- a line was returned;
- an accepted price changed before fulfilment;
- shipping, tax or discount differs from the order expectation;
- the invoice describes a product differently from the catalogue;
- a corrected invoice replaced an earlier file.
Some differences should block payment. Some need a buyer to map or explain them. Some are expected consequences of the purchase lifecycle.
A useful invoice capability must distinguish those cases. “Matched” and “not matched” are outcomes, not enough of an explanation.
Compare the three business records explicitly
The reconciliation begins with three sources.
The order captures the commercial commitment: lines, quantities, prices, discounts, tax, shipping and totals.
The receipt-of-goods state captures what the organisation says physically arrived. It can reflect final received quantities and later claims or returns.
The reviewed invoice source captures what the supplier is requesting, after extraction and any authorised human mapping.
The comparison utility builds one structured view across those sources. It does not treat the PDF as an image to approve by intuition. It asks whether the quantities, prices and totals have a coherent relationship to the actual purchase and receiving history.
This is sometimes called a three-way match. In our implementation, the useful definition is the exact one: order, received-goods state and reviewed invoice evidence. We do not rely on the label to imply every rule of a particular accounting product.
Use final received quantity, not the original expectation
The ordered quantity is not always the payable quantity.
If ten units were ordered and only eight were finally received, the invoice comparison must reason from the receipt state. Claims and returns can change what the organisation considers accepted goods. Paying against the original ten simply because the order still displays ten would disconnect accounts payable from operations.
The platform’s validation tests cover final received quantity and the effects of claims and returns. That gives the comparison a commerce-aware basis rather than a static copy of the initial order.
For the buyer, this removes a common manual investigation. The system can explain that an invoice line exceeds the accepted received quantity instead of forcing someone to compare screens and delivery notes by hand.
For finance, the payment gate follows the current business record of what was received.
Preserve the price that belongs to the transaction
Prices can evolve after an order is placed.
A supplier may update the catalogue. A price list may change. A negotiated quote may have established a specific amount. The invoice comparison cannot simply ask the current product catalogue what the item costs today.
The validation path is version-aware. It compares invoice prices with the commercial source associated with the purchase rather than treating live catalogue price as historical truth.
This is a broader commerce rule: every financial review needs the price context captured by the transaction. Current product data is useful for new buying decisions; it should not silently rewrite an old commitment.
The same logic applies to discounts, tax and shipping. Each amount must be evaluated in the context of the order and the reviewed invoice so the grand total can be explained from its components.
Turn mismatches into buyer-readable reasons
“Invoice mismatch” creates work without helping anyone resolve it.
The comparison produces specific blocking reasons. A reviewer can distinguish a quantity difference from a price difference, an unknown line, a missing document or a grand-total inconsistency.
That matters because each discrepancy has a different owner and remedy.
- A quantity problem may need receiving to correct or confirm the goods record.
- A price problem may require supplier review or an authorised price adjustment.
- An unknown line may need manual mapping.
- A total inconsistency may indicate that the interpreted lines do not reproduce the supplier’s document.
The platform turns an accounting exception into a bounded task. The buyer sees what needs attention rather than being asked to approve a document they cannot explain.
Keep AI extraction subordinate to the review
Invoice extraction is a useful application of AI because supplier documents vary widely. The model can identify candidate invoice numbers, lines, quantities, prices and totals from the file.
But extraction is not payment authority.
The extracted data becomes one input to a deterministic comparison. Product identity is checked against order and receipt records. Unknown or ambiguous lines can be routed to human mapping. Arithmetic safeguards verify that corrected or mapped lines still reproduce the extracted invoice total.
This division of responsibility is deliberate.
AI handles document variability. The commerce system owns product, quantity, price and payment rules. A human owns genuinely ambiguous mappings. No single model response can move the payment lifecycle by sounding plausible.
Let humans map uncertain lines without breaking the maths
Supplier descriptions rarely match catalogue titles perfectly.
An invoice may use an internal supplier code, abbreviate a product name or combine charges in a way that automatic SKU matching cannot resolve. Rejecting every such invoice would waste the value of automation; accepting the model’s best guess would create financial risk.
The review flow allows an authorised user to map an extracted invoice item to the relevant received or ordered item. The corrected comparison is then recalculated.
The important safeguard is arithmetic consistency. Manual mapping cannot make an invoice valid if the resulting lines no longer reproduce the amount represented by the supplier document. Missing extracted quantity is not quietly converted to zero, and ambiguous combinations remain in manual or blocked review.
Human authority adds context. It does not bypass the financial equation.
Keep source files and replacements connected
Invoice review is also an evidence problem.
A supplier can send a replacement document after the buyer has already inspected the first. Email ingestion can receive several attachments. Extraction and manual mapping evolve as the reviewer works.
The platform keeps source identity, extracted data, mappings and review status together. Replacement records preserve the relationship between prior and active evidence. Review transitions identify which source was accepted, rejected, waived or replaced.
This means the final validation can answer: which invoice file was reviewed, how its lines were interpreted and which version became active?
Without that relationship, a corrected PDF can quietly overwrite the evidence behind an earlier decision. With versioned sources, the system can move forward while retaining the story of the review.
Guard against a stale browser decision
Two people—or one person with two tabs—can review an invoice while its comparison changes.
If the browser submits “approve” against an old view after a replacement file or mapping has changed the numbers, the action should not apply to the newer comparison by accident.
Comparison submissions therefore carry a version. The server can reject a decision that refers to stale comparison data and ask the reviewer to inspect the current result.
This is a narrow but valuable concurrency contract. It protects the meaning of the approval: the person decides on the comparison they actually saw.
The same pattern applies anywhere a financial action depends on a generated view. Bind the decision to the version of the facts presented to the user.
Payment progression requires both document and validation
A purchase-order payment should not progress simply because an invoice number was entered.
The buyer-side validation path requires the invoice PDF to exist and the validation result to be persisted. The validation workflow verifies the submitted comparison, stores the decision and emits the next business event.
This creates a visible hand-off between invoice review and payment lifecycle.
The invoice module does not pretend that document processing is money movement. It establishes that the organisation reviewed a particular source against the order and received goods. The payment provider or downstream accounting integration can then respond to that business state according to its own responsibility.
Keeping those stages explicit is especially important for account-term purchasing, where validation, confirmation and capture are not the same event.
Why this capability belongs close to commerce
It is possible to export orders to an external AP tool and perform the entire comparison there.
For this client, the Medusa platform already held critical context: order lines, purchased prices, seller identity, receipt-of-goods state, claims, returns and purchase-order payment status. Moving only a partial order snapshot elsewhere would require another system to reconstruct the purchase lifecycle before it could judge an invoice.
We therefore implemented the reconciliation capability around the commerce records and exposed clear integration states for downstream accounting.
Medusa remained responsible for the transaction. The invoice module owned sources, extraction, mappings, comparison and review. The purchase-order payment lifecycle consumed the validated outcome.
This is the value of an extensible commerce engine: a client-specific financial control can be added where the relevant business facts already meet.
A practical invoice-validation checklist
Before automating invoice review, define these contracts.
- What was commercially ordered? Preserve transaction prices, discounts, tax and shipping context.
- What was finally received? Include claims and returns in the accepted quantity.
- Which supplier document is active? Version source files and replacements.
- What may AI extract? Treat the output as proposed document data, not authority.
- How are products matched? Use deterministic identity first and human mapping for ambiguity.
- What arithmetic must remain true? Recalculate lines, subtotal and grand total after every correction.
- How are mismatches explained? Return precise business reasons and owners.
- How is a decision bound to its facts? Version the comparison shown to the reviewer.
- What gates payment progression? Require the document and persisted validation state.
- What moves downstream? Emit a clear business event rather than conflating review with settlement.
These decisions turn invoice automation into financial control rather than faster document handling.
The outcome: explain before paying
The platform does not ask finance to trust a PDF, an AI extraction or a matching invoice number.
It presents the relationship between the order, received goods and reviewed invoice. When those truths disagree, it explains the difference. When human judgement is needed, it constrains the correction with product identity and arithmetic. When a replacement arrives, it preserves which source became active.
Medusa supplied the purchase and order lifecycle. We added the invoice evidence and comparison capability the client’s account-term workflow required.
That is how WeAreSouk approaches financial commerce architecture: automate the repetitive interpretation, preserve human authority over ambiguity and make payment progression depend on an explainable business state.
If your AP team still reconciles supplier invoices by moving between order screens, receiving spreadsheets and email attachments, we can map those sources and build a reviewable validation journey around your Medusa orders.