# GetPurchaseOrder

## Overview

GetPurchaseOrder retrieves a single purchase order with its lines, frozen commercial snapshots, and fulfillment progress.

## Business Rules

- Accepts lookup by `{ id }` or by `{ companyId, externalSupplierOrderReference }`
- Returns purchase orders in any status so cancelled and closed documents remain auditable
- Response includes line-level remaining quantity to receive and remaining quantity to bill
- Response includes payment-term snapshot and matched price-rule references when present
- Returns null when no purchase order matches the lookup

## Process Flow

```mermaid
flowchart TD
    A[Receive lookup input] --> B{Lookup by id or external reference?}
    B -->|id| C[Select PurchaseOrder by id]
    B -->|external reference| D[Select PurchaseOrder by company + external reference]
    C --> E{Order found?}
    D --> E
    E -->|Yes| F[Load lines, snapshots, and fulfillment totals]
    E -->|No| G[Return null]
    F --> H[Return purchase order]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: No purchase order matches the given lookup; caller receives null

## Test Cases

- returns purchase order when found by id
- returns purchase order when found by company and external supplier order reference
- returns lines and fulfillment totals with the order
- returns null when purchase order is not found
