Purchase requests · Cluster ERP Wiki

This page describes the purchase_requests sub-module in src/cluster_erp/modules/procurement/purchase_requests/. A purchase request (PurchaseRequest) collects materials to be bought, with estimated prices, before an order or an RFQ exists. Requests are created by users or from MRP run items; MRP is described on material requirements planning.

Scope and source¶

Defined in: models.py (PurchaseRequest, PurchaseRequestItem), services.py (PurchaseRequestService), routes.py, metadata.py, and item_metadata.py of the sub-module.
Count: 2 tables, 12 routes (@router. decorators in routes.py), 3 ActionMeta entries.

Request fields¶

Name	Meaning	Source
`pr_no`	Business key from the yearly sequence `purchase_request`	`src/cluster_erp/modules/procurement/purchase_requests/models.py:30`, `src/cluster_erp/modules/procurement/purchase_requests/services.py:208`
`project_id`	Project the request serves	`src/cluster_erp/modules/procurement/purchase_requests/models.py:36`
`requested_by`, `required_by_date`	Requester (the acting user) and need date	`src/cluster_erp/modules/procurement/purchase_requests/models.py:40-44`
`status`	Default `draft`	`src/cluster_erp/modules/procurement/purchase_requests/models.py:48-54`
`priority`	Default `normal`	`src/cluster_erp/modules/procurement/purchase_requests/models.py:55-60`
`total_estimated_cost`, `currency`	Sum of item estimates, `Numeric(19, 4)`	`src/cluster_erp/modules/procurement/purchase_requests/models.py:61-65`
`approved_by`, `approved_at`, `cancel_reason`, `notes`	Approval and cancellation record	`src/cluster_erp/modules/procurement/purchase_requests/models.py:69-81`
`source_type`, `source_id`	Origin of the request, for example an MRP run	`src/cluster_erp/modules/procurement/purchase_requests/models.py:85-89`

Item fields¶

Name	Meaning	Source
`product_id`, `product_model_id`, `product_version_id`	Product breakdown	`src/cluster_erp/modules/procurement/purchase_requests/models.py:111-127`
`qty`, `unit_id`	Quantity `Numeric(14, 4)` and unit	`src/cluster_erp/modules/procurement/purchase_requests/models.py:128-132`
`estimated_unit_price`, `estimated_total`	Estimate `Numeric(18, 4)` and line total `Numeric(19, 4)`	`src/cluster_erp/modules/procurement/purchase_requests/models.py:136-143`
`required_by_date`, `suggested_vendor_id`, `is_critical`	Need date, vendor proposal, critical flag	`src/cluster_erp/modules/procurement/purchase_requests/models.py:144-157`
`mrp_item_id`	The MRP run item the line came from	`src/cluster_erp/modules/procurement/purchase_requests/models.py:158`

Statuses and actions¶

The service allows these transitions (src/cluster_erp/modules/procurement/purchase_requests/services.py:76-83):

stateDiagram-v2
 [*] --> draft
 draft --> pending_approval: submit_approval
 pending_approval --> approved: approve
 pending_approval --> draft
 approved --> po_issued: order from request
 po_issued --> closed
 draft --> cancelled: cancel
 pending_approval --> cancelled: cancel
 approved --> cancelled: cancel

In prose: a request starts as draft. submit_approval moves it to pending_approval, approve to approved, and creating an order from it to po_issued (src/cluster_erp/modules/procurement/purchase_requests/services.py:493-531, src/cluster_erp/modules/procurement/purchase_orders/services.py:409-410). cancel is open from draft, pending_approval, and approved. The table allows po_issued to closed, but a grep for "closed" in the sub-module finds only the table and a metadata filter value; no route sets it.

Action	Label	Condition	Endpoint	Permission	Source
`submit_approval`	Submit for Approval	`status` is `draft`	`POST /purchase-requests/{id}/submit-approval`	`purchase_request.update`	`src/cluster_erp/modules/procurement/purchase_requests/metadata.py:111-130`, `src/cluster_erp/modules/procurement/purchase_requests/routes.py:150`
`approve`	Approve	`status` is `pending_approval`	`POST /purchase-requests/{id}/approve`	`purchase_request.approve`	`src/cluster_erp/modules/procurement/purchase_requests/metadata.py:131-150`, `src/cluster_erp/modules/procurement/purchase_requests/routes.py:165`
`cancel`	Cancel	`status` is `draft`, `pending_approval`, or `approved`	`POST /purchase-requests/{id}/cancel`	`purchase_request.update`	`src/cluster_erp/modules/procurement/purchase_requests/metadata.py:151-184`, `src/cluster_erp/modules/procurement/purchase_requests/routes.py:180`

Request routes¶

Method and path	Permission	Source
`GET /purchase-requests/`, `GET /purchase-requests/{pr_id}`	`purchase_request.read`	`src/cluster_erp/modules/procurement/purchase_requests/routes.py:49`, `src/cluster_erp/modules/procurement/purchase_requests/routes.py:99`
`POST /purchase-requests/`	`purchase_request.create`	`src/cluster_erp/modules/procurement/purchase_requests/routes.py:87`
`PUT /purchase-requests/{pr_id}`	`purchase_request.update`	`src/cluster_erp/modules/procurement/purchase_requests/routes.py:113`
`DELETE /purchase-requests/{pr_id}`, `POST /purchase-requests/bulk-delete`	`purchase_request.delete`, `purchase_request.bulk_delete`	`src/cluster_erp/modules/procurement/purchase_requests/routes.py:126`, `src/cluster_erp/modules/procurement/purchase_requests/routes.py:138`
`POST /purchase-requests/{pr_id}/items`, `PUT` and `DELETE /purchase-requests/{pr_id}/items/{item_id}`	`purchase_request.update`	`src/cluster_erp/modules/procurement/purchase_requests/routes.py:196-230`

Constraints and validation¶

Each item's product breakdown is checked with ensure_product_breakdown (src/cluster_erp/modules/procurement/purchase_requests/services.py:233, src/cluster_erp/modules/procurement/purchase_requests/services.py:378).
The line estimate is quantity times unit price, rounded with ROUND_HALF_EVEN; the header total is the sum (src/cluster_erp/modules/procurement/purchase_requests/services.py:48-60, src/cluster_erp/modules/procurement/purchase_requests/services.py:120-122).
If any item's product is an active critical material, the request priority becomes high (src/cluster_erp/modules/procurement/purchase_requests/services.py:124-138, src/cluster_erp/modules/procurement/purchase_requests/services.py:270-273).
The header and items can change only in draft or pending_approval (src/cluster_erp/modules/procurement/purchase_requests/services.py:297, src/cluster_erp/modules/procurement/purchase_requests/services.py:372, src/cluster_erp/modules/procurement/purchase_requests/services.py:421, src/cluster_erp/modules/procurement/purchase_requests/services.py:460).
Only a draft request can be deleted; delete sets deleted_at (src/cluster_erp/modules/procurement/purchase_requests/services.py:324-336).
An order can be created from a request only when it is approved; deleted items are skipped (src/cluster_erp/modules/procurement/purchase_orders/services.py:369-381).
Events: PrCreated on create, PrApproved on approve, PrCancelled on cancel (src/cluster_erp/modules/procurement/purchase_requests/services.py:278-285, src/cluster_erp/modules/procurement/purchase_requests/services.py:522-529, src/cluster_erp/modules/procurement/purchase_requests/services.py:547).

Terms introduced¶

Term	Code identifier	Definition	Turkish term	Source
purchase request	`PurchaseRequest`	A request for materials to be bought, with estimated cost, before ordering.	Satın alma talebi	`src/cluster_erp/modules/procurement/purchase_requests/models.py:23`

Verified against commit 92f8051 on 2026-11-13.