Purchase Orders - Overview

A Purchase Order (PO) represents a formal request from your organization to a supplier for goods to be delivered to a warehouse. Each PO has a header record (PurchaseOrderList) and one or more line items (PurchaseOrderDetails).

---

Data Model

PurchaseOrderList (header)
│
├── id                   integer   Internal identifier
├── PO List Number       string    Document number (user-defined)
├── PO List Document Status  enum  Current status of the order
├── PO List Order Date   date      Earliest order date across all line items
├── PO List Servicenow Id  string  External reference (ServiceNow integration)
│
├── SupplierMaster ──────────────── Supplier for this PO
│   ├── Supplier Id
│   ├── Supplier Name
│   └── Supplier Number
│
└── PurchaseOrderDetails[] (line items)
    ├── id
    ├── Item Number / Sub Item Number
    ├── Warehouse Number / Name
    ├── Ship From Number / Name
    ├── PO Details Quantity
    ├── PO Details Price
    ├── PO Details Document Status
    ├── PO Details Tracking         BOL / tracking number
    ├── PO Details Order Date
    ├── PO Details Ship Date
    ├── PO Details ETA Date
    ├── PO Details First Promise Date
    ├── PO Details Request Date
    ├── PO Details Actual Ship Date
    ├── PO Details Actual Delivery Date
    ├── PO Details Unique Id
    └── PO Details Servicenow Id

---

Document Statuses

Both the PO header and individual line items carry a document status.

Status	Description
Open	Order placed, awaiting shipment
Shipped	Goods have shipped from the supplier
Partially Shipped	Some line items have shipped
Partially Received	Some line items have been received
Received	All goods received
Cancelled	Order cancelled
Suggested	System-generated suggested order, pending review

---

Business Rules

• Warehouse consistency: All line items on a single PO must target the same warehouse. Attempting to mix warehouses returns OrderList.MultipleWarehouses.
• Date ordering: Order Date ≤ Ship Date ≤ ETA Date. Violations return PurchaseOrderDetails.OrderDateAfterShip.
• Minimum line items: A PO must contain at least one line item. Empty details arrays return OrderList.NoItems.
• Duplicate detection: The combination of Item Number + Sub Item Number must be unique within a PO. Duplicates return OrderDetails.DuplicateRows.
• Cascade delete: Deleting a PO removes all its line items. Deleting the last line item on a PO also removes the parent PO header.
• Referential integrity: A PO or line item that is referenced by other records cannot be deleted (PurchaseOrderList.StillInUse / PurchaseOrderDetails.StillInUse).

---

Privilege Requirements

Operation	Required Privilege
Read (GET)	Procurement / View
Create (POST)	Procurement / Edit
Update (PUT)	Procurement / Edit
Delete (DELETE)	Procurement / Edit

---

Integration Behaviour

During data integration runs, procurement tables are locked. Any POST, PUT, or DELETE submitted while tables are locked is queued and executed in the background after the integration completes. The API returns an HTTP 200 with a Warning notification:

{
  "message": "Changes will be visible after the integration is done.",
  "notification_type": "Warning"
}

---

Endpoints

Method	Path	Description
GET	/api/purchase-order	List all POs
GET	/api/purchase-order/{id}	Get PO with details
POST	/api/purchase-order	Create PO
PUT	/api/purchase-order/{id}	Update PO
DELETE	/api/purchase-order/{id}	Delete PO