# Procurement operator guide

Step-by-step instructions for staff using the procurement module: purchase requests, sourcing, purchase orders, receiving, invoicing, payments, vendors, and exports. This guide is written for **operators** (programme staff, procurement officers, finance approvers).

**In-app copy:** open **Help and guides** in the workspace sidebar at [`/workspace-docs#docs-module-procurement`](/workspace-docs#docs-module-procurement).

For system architecture and data relationships, see [Grants, budgets, finance, and procurement](../system/04-grants-budgets-procurement.md). For supplier self-service, see [Vendor hub and supplier portal](../system/05-vendor-hub-and-portal.md).

---

## Who this is for

| Role | Typical tasks |
|------|----------------|
| **Programme / field staff** | Raise purchase requests against grant budget lines |
| **Procurement officers** | RFQs, vendor management, PCS comparison, award |
| **Finance / approvers** | Approve PRs and POs, match invoices, post grant actuals, payment runs |
| **Organisation admins** | Procurement policy, approval workflows, RBAC |

---

## Module requirements

Your organisation must have the right **modules enabled** (Settings → Policy modules). Procurement screens are gated as follows:

| Capability | Modules required |
|------------|------------------|
| Purchase requests (PR) | **Grants** + **Finance** |
| Procurement hub, POs, RFQs, vendors, receipts, tasks, exports, payment runs, framework agreements, vendor contracts | **Grants** + **Procurement** |

If a module is missing, the hub shows a warning and related menu items are hidden.

### Sidebar navigation

When modules are enabled, the workspace sidebar under **Procurement** includes:

- **Procurement** (hub) — `/procurement`
- **Purchase requests** — `/procurement/purchase-requests`
- **Purchase orders** — `/procurement/purchase-orders`
- **RFQs** — `/procurement/rfqs`
- **Vendors** — `/procurement/vendors`
- **Receipts** — `/procurement/receipts`
- **Tasks** — `/procurement/tasks`

Framework agreements, vendor contracts, payment runs, and exports are reached from vendor pages, PO pages, the hub actions, or direct URLs (see [Appendix: URL quick reference](#appendix-url-quick-reference)).

---

## Before you start

Complete this checklist before raising your first purchase request.

### 1. Grant and budget line

Every PR and PO must link to a **grant** and usually a **grant budget line** with remaining balance.

1. Open the grant from **Grants** → select grant → **Budget** tab.
2. Confirm a budget line exists for the category you need (e.g. supplies, travel).
3. Check **Remaining** on the line — commitments from approved PRs/POs reduce available budget.

If no budget lines appear on the PR form, ask your programme or finance team to add lines on the grant budget.

### 2. Approval workflows

Submit for approval requires active workflows:

1. Go to **Settings → Approvals**.
2. Ensure workflows exist for **purchase request** and **purchase order** subjects.
3. Assign approvers to workflow steps (or use role-based assignees).

Without a workflow, **Submit for approval** fails with a message directing you to Settings.

### 3. Procurement policy

Admins configure organisation rules at **Settings → Procurement policy** (`/settings/procurement-policy`):

| Section | What it controls |
|---------|------------------|
| **Sourcing thresholds** | Direct purchase max, competitive minimum, RFQ required minimum, minimum quotes for award, policy currency |
| **Bid evaluation** | Mandatory criteria (legal registration, tax compliance, blacklist), scoring weights (price, quality, delivery, experience, social impact), auto-reject threshold |
| **Goods receipt** | Quantity variance tolerance (default and by category), price variance, photo evidence requirement |
| **Three-way match** | Auto-approve conditions, escalation rules (SLA hours for low/high severity exceptions) |

The system enforces thresholds when you choose sourcing routes and when evaluating RFQ awards.

### 4. Access (RBAC)

Functional roles can grant procurement capabilities in **Settings → RBAC**:

| Matrix row | Typical permissions |
|------------|---------------------|
| Purchase request | Create, read, update, delete, approve |
| Purchase order | Create, read, update, delete, approve |
| Bids / RFQ | Create, read, update, delete, approve |
| GRN (goods receipt) | Create, read, update, delete, approve |
| Vendors | Create, read, update, delete |
| Payment runs | Create, read, update, approve |

Data scopes can limit users to specific grants. If you cannot see a grant on a PR form, check your role assignments.

### 5. Vendor hub (optional)

Share your organisation’s supplier portal URL with vendors (shown on the procurement hub). Suppliers register, log in, and submit RFQ bids there. See [Vendor hub and supplier portal](../system/05-vendor-hub-and-portal.md).

---

## Procurement hub

**URL:** `/procurement`

The hub is your dashboard:

- **KPI cards** — open PRs, open POs, total tasks, items awaiting payment
- **Budget at risk** — budget lines nearing exhaustion (links to grants)
- **Spend by grant** — PO totals grouped by grant
- **Reorder suggestions** — inventory items below reorder level (quick link to create PR)
- **Vendor portal** — active vendors, pending registrations, portal URL

**Actions** (top of page):

- **New purchase request** (Finance module)
- **Tasks** — open your procurement task list
- **Exports** — register, audit pack, payment batch
- **Procurement policy** (admins with settings access)

Use the card grid to jump to PRs, POs, RFQs, vendors, receipts, tasks, or exports.

---

## End-to-end flows

### Overview diagram

```mermaid
flowchart TD
  subgraph direct [Direct purchase]
    PR1[Purchase request] --> ApprovePR1[PR approved]
    ApprovePR1 --> PO1[Purchase order]
    PO1 --> ApprovePO1[PO approved]
  end
  subgraph competitive [Competitive / RFQ]
    PR2[PR competitive route] --> RFQ[RFQ published]
    RFQ --> Bids[Vendor bids]
    Bids --> PCS[PCS comparison]
    PCS --> Award[Bid awarded]
    Award --> PO2[PO from award]
  end
  subgraph receive [Receive and pay]
    PO1 --> GR[Goods receipt]
    PO2 --> GR
    GR --> SI[Supplier invoice]
    SI --> Match[Three-way match]
    Match --> Actual[Post grant actual]
    Actual --> Pay[Record payment or payment run]
  end
```

### Sourcing routes on purchase requests

When creating a PR, choose a **sourcing route**:

| Route | When to use |
|-------|-------------|
| **Direct purchase** | Low value, single supplier, within direct-purchase threshold |
| **Competitive (RFQ/RFP)** | Multiple quotes required; typically spawns or links to an RFQ |
| **Sole source** | Only one qualified supplier; document justification |
| **Emergency** | Urgent need; policy may require extra approval |
| **Framework agreement** | Call-off from an existing framework with a pre-qualified vendor |

Policy thresholds (e.g. direct max USD 500, RFQ required above USD 5,000) are enforced by the system based on estimated totals.

### Budget commitments

When a PR or PO is **approved**, the system posts a **commitment** against the grant budget line (visible on the grant Budget tab as encumbered amount). When a PO is created from an approved PR, the PR commitment is released and replaced by the PO commitment.

---

## Happy-path walkthrough: direct purchase

Example: buy supply kits for **USD 250** on grant line **SUPPLIES**.

1. **Create PR** — `/procurement/purchase-requests/new`
   - Grant: your active grant
   - Budget line: SUPPLIES
   - Payment currency: USD (same as grant)
   - Sourcing route: Direct purchase
   - One line: quantity 1, unit price 250
   - Submit for approval

2. **Approve PR** — Approvals inbox (`/approvals/inbox`) or auto-approve if configured

3. **Create PO** — from PR show page or `/procurement/purchase-orders/new`
   - Link to approved PR
   - Vendor name, same lines and amounts
   - Submit PO for approval

4. **Approve PO**

5. **Logistics** — `/procurement/purchase-orders/{uuid}/logistics`
   - Record **goods receipt** (kind: goods or service; quantity received)
   - Register **supplier invoice** (vendor invoice number, date, total 250)
   - Run **three-way match** → status should become **matched**
   - **Post grant actual** → creates grant ledger entry
   - **Record payment** when paid (or add to payment run)

6. **Verify** — Grant → Spending tab shows posted actual; budget line remaining decreases.

---

## Purchase requests

**List:** `/procurement/purchase-requests`  
**Create:** `/procurement/purchase-requests/new`  
**Legacy URLs:** `/procurement/{uuid}` and `/procurement/edit/{uuid}` also resolve to show/edit.

### Create a purchase request

1. **Choose the grant**  
   Select the grant at the top. The form loads budget lines and grant currency. You cannot add lines until a grant is selected.

2. **Payment currency and FX**  
   Under “Payment currency & FX”, choose the currency you will pay in. If it differs from the grant currency, enter the rate as **1 payment unit = X grant units** (e.g. 1 TRY = 0.022 USD). Line prices are entered in payment currency; a grant-currency reference total is shown for budget checking.

3. **Request header**  
   - **Title** (required)  
   - Optional vendor name, needed-by date, delivery location  
   - **Budget line** per line or at header level  
   - **Sourcing route** (required)  
   - **Approval workflow** (required when workflows exist)

4. **Line items**  
   Click **Add line** for each item:
   - Description and quantity (required)
   - Unit of measure (e.g. ea, month)
   - Optional specifications, duration and duration unit
   - Unit price in payment currency  
   - **Line total** = quantity × duration × unit price  
   - Optional **BOQ** (bill of quantities) rows are detail only — they do not change the total

5. **Check totals**  
   Grand total is in payment currency. When currencies differ, a grant-equivalent row shows estimated budget impact.

6. **Submit**  
   Click **Submit purchase request**. Fix validation errors (values are preserved). After submit, status moves to pending approval.

### After submit

- Track from PR list or **Approvals inbox**
- **PDF** — `/procurement/purchase-requests/{uuid}/pdf`
- **Edit** — only **draft** PRs without an in-progress workflow (`/procurement/purchase-requests/edit/{uuid}`)

### Document requests

On the PR show page you can request supporting documents from colleagues or vendors:

- **Create document request** — specify what is needed
- **Cancel** pending requests
- **Download** when fulfilled

### On approval

Approved PRs encumber the grant budget line. You can then create a PO or (for competitive route) an RFQ from the PR.

---

## RFQs (request for quotation)

**List:** `/procurement/rfqs`  
**Create:** `/procurement/rfqs/new`  
**From PR:** use the **Create RFQ** action on an approved competitive PR show page (do not navigate to the POST URL directly).

### Create and publish

1. Create RFQ standalone or **from an approved purchase request** (copies scope/lines).
2. Set title, description, closing date, linked grant if applicable.
3. Move status to **published** so suppliers see it on the vendor portal.

### Supplier bids

- Active vendors log in to the **vendor hub** and submit bids before `closes_on`.
- Staff view bids on the RFQ show page.

### Clarifications

- Suppliers may ask questions via the public RFQ quote page (vendor hub).
- Staff **answer clarifications** on the RFQ show page (`POST` clarifications/answer).

### Bid evaluation

For each bid:

1. Open **Evaluate** on the bid row.
2. Score against policy weights (price, quality, delivery, experience, social impact).
3. Mandatory criteria must pass (legal registration, tax compliance, no blacklist).
4. Bids below the auto-reject threshold are rejected.

### PCS (price comparison schedule)

For formal comparison:

1. **Start PCS** on the RFQ.
2. Assign **panel members** and enter comparison matrix scores.
3. **Update PCS** until finalized.
4. Download **PCS PDF** (`/procurement/rfqs/{uuid}/pcs.pdf`).

### Award

1. Enter **award justification** (narrative for auditors).
2. **Award recommended bid** or **Award** a specific bid.
3. Download **award memo PDF** if needed.
4. **Create purchase order from awarded bid** — pre-fills vendor and lines.

RFQ status flow: **draft** → **published** → **closed** (optional) → **awarded**.

---

## Purchase orders

**List:** `/procurement/purchase-orders`  
**Create:** `/procurement/purchase-orders/new`

### Ways to create a PO

| Source | How |
|--------|-----|
| Approved PR | PO create form — select PR |
| Awarded RFQ | RFQ show → Create purchase order |
| Framework call-off | Framework agreement show → Call-off |
| Manual | New PO — pick grant, budget line, vendor, lines |

### Submit and approve

1. Complete vendor, lines, currency, grant budget line.
2. **Submit for approval** — starts PO workflow.
3. Approvers act from **Approvals inbox**.

On PO approval, budget commitment transfers from PR (if linked) to PO.

### PO show page

- View reference, status, lines, totals
- **PDF** export
- **Logistics** link — receiving and invoicing
- **Create vendor contract** shortcut (optional)

---

## Logistics: receive, invoice, match, pay

**URL:** `/procurement/purchase-orders/{uuid}/logistics`

This is the main screen for fulfilment after PO approval.

### 1. Goods receipt (GRN)

1. Click **Record goods receipt**.
2. Choose **kind**: `goods` (physical) or `service`.
3. Enter **received on** date and line quantities received.
4. Policy may require photo evidence for goods.

Quantity variance beyond tolerance (Settings → Procurement policy) may flag match exceptions later.

### 2. Supplier invoice

1. Click **Register supplier invoice**.
2. Enter vendor invoice number, invoice date, currency, total amount.
3. Optional retention amount if contract holds retention.

### 3. Three-way match

The system compares **PO**, **goods receipt**, and **supplier invoice**:

| Outcome | Meaning | Next step |
|---------|---------|-----------|
| **matched** | Within tolerance | Post grant actual |
| **exception** | Variance or missing data | Review on logistics page; may escalate per policy SLA |

Run match from the invoice row. Escalated exceptions appear in **Tasks**.

### 4. Post grant actual

Available when invoice status is **matched** and not yet posted.

Posts a **grant transaction (actual)** against the PO’s budget line — this is the formal spend on the grant ledger.

### 5. Record payment

After posting actuals, record partial or full payment:

- Payment date, amount, reference
- Tracks `amount_paid` vs total minus retention

Alternatively, batch payments via **payment runs** (below).

### 6. Release retention

When retention period ends, **Release retention** on the invoice with release notes.

---

## Receipts index

**List:** `/procurement/receipts`  
**Detail:** `/procurement/receipts/{goods_receipt}`  
**PDF:** `/procurement/goods-receipts/{goods_receipt}/pdf`

Browse all goods receipts across POs. Use for warehouse/field teams confirming what was received.

---

## Vendors

**List:** `/procurement/vendors`  
**Detail:** `/procurement/vendors/{vendor}`

### Register and activate

| Method | Flow |
|--------|------|
| **Supplier portal** | Vendor self-registers → appears in **Portal queue** (`/procurement/vendors/portal-queue`) → staff review and **Activate** |
| **Staff-created** | Create vendor record manually on vendor list/show |

Inactive vendors cannot log in to the portal.

### Vendor show page

- Edit legal name, contact, tax ID, default currency
- **Activate / Deactivate**
- **Prequalification** records (categories, expiry)
- **Bank accounts** — required for payment runs (IBAN, currency, primary flag)
- **Download registration document** (PDF uploaded at portal registration)
- Links to **framework agreements** for this vendor

---

## Framework agreements

**List:** `/procurement/framework-agreements`  
**Create:** `/procurement/framework-agreements/new` (or from vendor page with `?vendor={uuid}`)

Long-term agreements with pre-negotiated terms and catalog lines.

1. Create agreement: reference, title, vendor, currency, validity dates, status.
2. Add **framework lines** (items, unit prices, max quantities).
3. **Call-off** from agreement show page → generates a PO against selected lines.

Use PR sourcing route **Framework agreement** when the purchase is under an existing framework.

---

## Vendor contracts

**List:** `/procurement/vendor-contracts`  
**Create:** `/procurement/vendor-contracts/new` (optional `?purchase_order={uuid}` from PO show)

Store executed contract documents:

1. Title, vendor, linked PO (optional), dates, status.
2. Upload contract file.
3. Update status: draft → active → completed / terminated.

---

## My procurement tasks

**URL:** `/procurement/tasks`

Personal work queue grouped by type:

| Section | What appears |
|---------|----------------|
| **Draft purchase requests** | Your PRs still in draft |
| **Approved POs awaiting receipt** | POs with no goods receipt yet |
| **Invoice match exceptions** | Three-way match failed |
| **Escalated match exceptions** | Past SLA — needs manager attention |
| **Matched — awaiting grant actual** | Matched invoices not posted to grant |
| **Awaiting payment** | Posted actuals with outstanding payable balance |
| **Retention ready for release** | Retention held; release period may have passed |

Click any item to open the PR, PO logistics page, or related record.

---

## Payment runs

**List:** `/procurement/payment-runs`

Batch outbound payments to vendors:

1. **Create payment run** — choose format (CSV, SEPA XML, ACH CSV, NEFT CSV) and currency.
2. System includes payable supplier invoices with vendor bank details.
3. **Submit** run for approval if workflow applies.
4. **Export** payment file for bank upload.
5. **Reconcile** after bank confirms — mark lines paid.

Open a run from the list to see lines, totals, and actions.

---

## Exports and audit

**URL:** `/procurement/exports`

### Procurement register

Filter by grant, date range, sourcing route, vendor, type (PR / PO / all).

- Download **CSV** or **PDF** register for donor or internal reporting.

### Payment batch export

Quick CSV of invoices awaiting payment (shortcut to finance handoff).

### Audit pack

ZIP (or CSV index) bundling for a date/grant/vendor range:

- Approval instances
- PR/PO PDFs
- RFQ PCS and bid attachments
- Goods receipt and invoice documents

Use for donor audits or year-end procurement files.

---

## Approvals integration

When the **Approvals** module is enabled:

```mermaid
sequenceDiagram
  participant Staff
  participant PR as Purchase request
  participant Inbox as Approvals inbox
  participant Approver

  Staff->>PR: Submit for approval
  PR->>Inbox: Approval instance created
  Approver->>Inbox: Open assigned step
  Approver->>PR: Approve or reject
  PR->>PR: Status approved or rejected
```

- **Purchase requests** and **purchase orders** each use their own workflow definitions.
- Approvers need **approve** privilege on the relevant RBAC row (or org-admin bypass).
- Rejected documents return to draft or rejected status depending on workflow configuration.

---

## Troubleshooting

### No budget lines on the PR form

- Grant has no budget lines → add on grant **Budget** tab.
- Grant not visible → RBAC data scope or grant read permission.
- All lines fully encumbered → choose another line or request budget amendment.

### Submit for approval disabled or fails

- PR/PO must be **draft**.
- No active workflow → Settings → Approvals.
- Already in approval → wait for current instance to finish.

### Policy blocks sourcing or award

- Estimated total exceeds **direct purchase** max → use competitive route or RFQ.
- RFQ award with fewer than **minimum quotes** → publish longer or invite more vendors.
- Check **Settings → Procurement policy** thresholds.

### Three-way match exception

- Compare PO line qty/price vs receipt qty vs invoice total.
- Check quantity tolerance in policy.
- Fix receipt or invoice, re-run match.
- Escalated items appear in **Tasks**; high-severity SLA in policy.

### Budget at risk on hub

- Line **used %** high — review open PRs/POs on that line before new requests.
- Open grant budget tab for commitment and actual columns per line.

### Vendor cannot bid

- Vendor must be **active**.
- RFQ must be **published** and before closing date.
- Supplier uses correct organisation vendor hub URL.

---

## Appendix: URL quick reference

| Task | Path |
|------|------|
| Procurement hub | `/procurement` |
| Purchase requests list | `/procurement/purchase-requests` |
| New purchase request | `/procurement/purchase-requests/new` |
| PR show | `/procurement/purchase-requests/{uuid}` |
| PR PDF | `/procurement/purchase-requests/{uuid}/pdf` |
| Purchase orders list | `/procurement/purchase-orders` |
| New PO | `/procurement/purchase-orders/new` |
| PO show | `/procurement/purchase-orders/{uuid}` |
| PO logistics | `/procurement/purchase-orders/{uuid}/logistics` |
| RFQs list | `/procurement/rfqs` |
| New RFQ | `/procurement/rfqs/new` |
| RFQ show | `/procurement/rfqs/{uuid}` |
| Vendors | `/procurement/vendors` |
| Vendor portal queue | `/procurement/vendors/portal-queue` |
| Receipts | `/procurement/receipts` |
| Tasks | `/procurement/tasks` |
| Exports | `/procurement/exports` |
| Payment runs | `/procurement/payment-runs` |
| Framework agreements | `/procurement/framework-agreements` |
| Vendor contracts | `/procurement/vendor-contracts` |
| Procurement policy (settings) | `/settings/procurement-policy` |
| Approvals inbox | `/approvals/inbox` |

All `{uuid}` values are public UUIDs shown in the browser URL bar, not internal numeric IDs.

---

## Appendix: Status reference

### Purchase request

| Status | Meaning |
|--------|---------|
| `draft` | Editable; not yet submitted |
| `pending_approval` | In approval workflow |
| `approved` | Approved; budget committed; can convert to PO/RFQ |
| `rejected` | Approval rejected |
| `cancelled` | Cancelled by user |

### Purchase order

| Status | Meaning |
|--------|---------|
| `draft` | Editable |
| `pending_approval` | In approval workflow |
| `approved` | Approved; ready for receipt and invoicing |
| `rejected` | Approval rejected |
| `cancelled` | Cancelled |

### RFQ

| Status | Meaning |
|--------|---------|
| `draft` | Not visible to suppliers |
| `published` | Open for bids on vendor portal |
| `closed` | Bidding closed; evaluation in progress |
| `awarded` | Winning bid selected; PO can be created |

### RFQ bid

| Status | Meaning |
|--------|---------|
| `submitted` | Received from vendor |
| `in_progress` | Under evaluation |
| `approved` | Passed evaluation |
| `rejected` | Failed evaluation or mandatory criteria |

### Supplier invoice

| Status | Meaning |
|--------|---------|
| `draft` / `issued` | Registered; match not run or pending |
| `matched` | Three-way match passed |
| `exception` | Match failed — review required |

After **post grant actual**, invoice links to a grant transaction. Payment fields track settlement and retention.

### Payment run

| Status | Typical meaning |
|--------|-----------------|
| `draft` | Created; not submitted |
| `submitted` | Awaiting approval or export |
| `exported` | File generated for bank |
| `reconciled` | Payments confirmed |

### Framework agreement

| Status | Meaning |
|--------|---------|
| `active` | Call-offs allowed |
| `suspended` | Temporarily frozen |
| `expired` | Past end date |

### Vendor contract

| Status | Meaning |
|--------|---------|
| `draft` | Not yet executed |
| `active` | In force |
| `completed` | Fulfilled |
| `terminated` | Ended early |

---

## Related documentation

- [Grants, budgets, finance, and procurement](../system/04-grants-budgets-procurement.md) — architecture and data flow
- [Vendor hub and supplier portal](../system/05-vendor-hub-and-portal.md) — supplier registration and bidding
- [Authentication and authorization](../system/03-authentication-and-authorization.md) — RBAC overview
- [Multi-tenancy and modules](../system/02-multi-tenancy-and-modules.md) — enabling Finance and Procurement modules
