Purchase API

The Purchase module manages procurement — from Request for Quotation (RFQ) through Purchase Order approval, goods receipt, and vendor bill payment. It integrates with Inventory (stock receipts) and Accounting (vendor bills).

---

Endpoints

Method	Path	Description
GET	/api/purchase/rfqs	List RFQs (paginated)
POST	/api/purchase/rfqs	Create an RFQ
GET	/api/purchase/rfqs/:id	Get an RFQ
PATCH	/api/purchase/rfqs/:id	Update an RFQ
DELETE	/api/purchase/rfqs/:id	Delete a draft RFQ
POST	/api/purchase/rfqs/:id/confirm	Confirm RFQ to Purchase Order
POST	/api/purchase/rfqs/:id/send	Send RFQ to vendor
GET	/api/purchase/orders	List confirmed Purchase Orders
POST	/api/purchase/orders/:id/receive	Record goods receipt
POST	/api/purchase/orders/:id/bill	Create vendor bill
GET	/api/purchase/vendors	List vendors
POST	/api/purchase/vendors	Add a vendor
GET	/api/purchase/vendors/:id/pricelists	Vendor-specific pricelists

---

Request for Quotation (RFQ)

List RFQs

GET /api/purchase/rfqs?status=draft&vendorId=018e...&page=1&limit=20

Query Parameters

Parameter	Type	Description
status	draft | sent | confirmed | cancelled	RFQ status
vendorId	string	Filter by vendor contact ID
from	ISO 8601	Created from date

Response

{
  "data": [
    {
      "id": "018e2222-abcd-7000-8000-000000000001",
      "reference": "PO/2026/0011",
      "status": "sent",
      "vendor": { "id": "...", "name": "TechSupply Co", "email": "[email protected]" },
      "buyer": { "id": "...", "name": "John Buyer" },
      "expectedArrival": "2026-04-05T00:00:00Z",
      "lineItems": [
        {
          "productId": "018e...comp1",
          "productName": "Circuit Board",
          "quantity": 200,
          "unitPrice": 2500,
          "total": 500000
        }
      ],
      "total": 500000,
      "currency": "usd",
      "createdAt": "2026-03-18T09:00:00Z"
    }
  ],
  "meta": { "total": 18, "page": 1, "limit": 20, "totalPages": 1 }
}

Create an RFQ

POST /api/purchase/rfqs
Content-Type: application/json

{
  "vendorId": "018e1234-abcd-7000-8000-000000000099",
  "expectedArrival": "2026-04-10T00:00:00Z",
  "lineItems": [
    {
      "productId": "018e...comp1",
      "quantity": 200,
      "unitPrice": 2500
    }
  ],
  "currency": "usd",
  "notes": "Please confirm lead time."
}

Confirm to Purchase Order

POST /api/purchase/rfqs/018e2222-abcd-7000-8000-000000000001/confirm

Locks pricing, assigns PO number, and creates a scheduled warehouse receipt.

---

Goods Receipt

Record the physical receipt of goods against a confirmed Purchase Order.

POST /api/purchase/orders/018e2222-abcd-7000-8000-000000000001/receive
Content-Type: application/json

{
  "receiptDate": "2026-04-05T08:00:00Z",
  "lines": [
    {
      "productId": "018e...comp1",
      "receivedQty": 195,
      "notes": "5 units damaged on delivery"
    }
  ]
}

Response:

{
  "receiptId": "018e...receipt",
  "transferReference": "WH/IN/00055",
  "receivedLines": [
    { "productId": "018e...comp1", "receivedQty": 195 }
  ],
  "backorderQty": 5
}

---

Vendor Bill

Create a vendor bill from a Purchase Order (equivalent to receiving a supplier invoice).

POST /api/purchase/orders/018e2222-abcd-7000-8000-000000000001/bill
Content-Type: application/json

{
  "vendorInvoiceNumber": "TINV-2026-00882",
  "invoiceDate": "2026-04-05T00:00:00Z",
  "dueDate": "2026-05-05T00:00:00Z"
}

Returns a new vendor bill object linked to the PO.

---

Vendors

List Vendors

GET /api/purchase/vendors?search=tech&page=1&limit=20

Vendors are contacts with vendor: true. Returns the same contact schema with vendor-specific fields:

{
  "data": [
    {
      "id": "018e1234-abcd-7000-8000-000000000099",
      "name": "TechSupply Co",
      "email": "[email protected]",
      "paymentTerms": "net30",
      "currency": "usd",
      "leadTimeDays": 14,
      "minOrderQty": 50
    }
  ],
  "meta": { "total": 12, "page": 1, "limit": 20, "totalPages": 1 }
}

Add a Vendor

POST /api/purchase/vendors
Content-Type: application/json

{
  "name": "GlobalParts Ltd",
  "email": "[email protected]",
  "paymentTerms": "net60",
  "currency": "usd",
  "leadTimeDays": 21
}

---

Status Codes

Code	Scenario
200	Get or list succeeded
201	RFQ, receipt, or vendor bill created
204	Draft RFQ deleted
400	Received quantity exceeds ordered quantity
404	RFQ or PO not found
409	PO already received or billed