# Goods Receipt Matching

## Overview

Goods Receipt Matching records what quantity from a purchase order has actually been received from the supplier. A `GoodsReceipt` references one purchase order and one or more purchase order lines, captures received quantities and receipt dates, and updates each line's received progress. The receipt document is the procurement-side confirmation that supplier fulfillment occurred.

This feature deliberately separates **commercial receipt confirmation** from **warehouse stock execution**. Purchase owns the receipt document and the matching rules against the purchase order; inventory remains the owner of the resulting stock movement, putaway, lot or serial recording, and on-hand updates. That split makes receipts usable both for stock items and for service or non-stock procurement scenarios. The named handoff contract from purchase to inventory is `InboundReceiptHandoff`, whose minimum payload is purchase order reference, purchase order line reference, goods receipt reference, received quantity, unit of measure, and receipt date.

## Business Purpose

- Confirm supplier fulfillment against the original purchase commitment
- Support partial deliveries and backorders without losing order-level visibility
- Enforce over-receipt and under-receipt tolerance rules on purchase order lines
- Provide the receipt basis required for 3-way supplier bill matching
- Trigger downstream inbound stock or service-acceptance processes without moving warehouse logic into purchase
- Preserve an auditable history of what was received, when, and against which supplier commitment

## Process Flow

```mermaid
flowchart TD
    A[Purchase Order in ORDERED status] --> B[Create Goods Receipt]
    B --> C[Select open order lines]
    C --> D[Enter received quantities and dates]
    D --> E{Within tolerance?}
    E -->|No| F[Block or require override]
    E -->|Yes| G[Post Goods Receipt]
    G --> H[Update PO line received quantities]
    G --> I[Emit inbound receipt handoff to inventory]
    H --> J{All quantities received?}
    J -->|No| K[PO remains PARTIALLY RECEIVED]
    J -->|Yes| L[PO becomes RECEIVED]
    G --> M[Receipt eligible for supplier bill matching]
```

## Scenario Patterns

- **Full delivery**: The supplier delivers every ordered line in one shipment and a single posted goods receipt completes the receiving side of the order
- **Partial shipment with backorder**: Only half the quantity arrives. The receipt posts successfully, open quantity remains on the PO, and another receipt can be recorded later
- **Overdelivery within tolerance**: A supplier sends 102 units against an order for 100 where a 2 percent over-receipt tolerance is allowed, so the receipt is accepted
- **Overdelivery beyond tolerance**: A supplier sends materially more than ordered, and the receipt is blocked or requires an explicit procurement exception
- **Split line receiving**: One line on the order is fully received while another remains open, and the receipt captures both outcomes in the same document
- **Service acceptance**: A non-stock service line is marked received or accepted without creating warehouse-level stock, but the receipt still unlocks downstream bill matching
- **Receipt date tracking**: The supplier shipment arrives late, and the posted receipt captures the actual date for lead-time and supplier-performance analysis
- **Receipt correction before posting**: A receiver notices a quantity entry mistake while the receipt is still draft and corrects it before it updates PO fulfillment
- **Future receipt reversal**: A posted receipt is later found to be incorrect. A future reversal workflow will preserve the original posted receipt, emit a compensating correction, and keep the audit trail intact rather than mutating history

## Test Cases

- Creating a goods receipt against an `ORDERED` purchase order with open quantity should succeed
- A goods receipt line must reference a valid purchase order line and a received quantity greater than zero
- A cancelled or closed purchase order must not accept new goods receipts
- Posting a goods receipt must increase the referenced purchase order line's cumulative received quantity
- Partial receipts must leave the remaining open quantity available for future receipts
- Receiving more than the ordered quantity plus configured tolerance should fail or require an explicit override
- Receiving against an inactive item or inactive supplier should be prevented if the order is no longer valid for execution
- A goods receipt posted for a stock item should emit or call the downstream inventory handoff contract exactly once
- The `InboundReceiptHandoff` payload must include purchase order reference, purchase order line reference, goods receipt reference, received quantity, UoM, and receipt date at minimum
- A goods receipt posted for a non-stock or service line must not require warehouse stock execution
- Only posted goods receipts should count toward 3-way supplier bill matching
- Receipt posting must be isolated by company and must not update purchase orders belonging to another company
- If a receipt is reversed or corrected through a future workflow, the purchase order received quantity must remain auditable rather than silently overwritten
- Purchase order status should move to a partial or full receipt state based on aggregate posted receipt quantities
- Only authorized receiving or procurement users should be able to post goods receipts
- A goods receipt should preserve the supplier, order, and line references needed for audit and traceability

## Reference Links

- [Odoo vendor bills and three-way matching](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/manage_deals/manage.html#vendor-bills)
- [Oracle Fusion Cloud Procurement documentation](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
- [SAP receipt confirmation documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD/65de2977205c403bbc107264b8eccf4b/552eb9c732c14df6a2926efce6d890ad.html)
