| name | pex:purchase-orders |
| description | ProcurementExpress purchase order (PO) management — the core procurement workflow. Covers creating, updating, approving, rejecting, cancelling, archiving, and deleting POs. Also handles delivery tracking, PDF generation, forwarding POs to suppliers, and adding comments. Routes to MCP tools: list_purchase_orders, get_purchase_order, create_purchase_order, update_purchase_order, approve_purchase_order, reject_purchase_order, override_and_approve_purchase_order, cancel_purchase_order, archive_purchase_order, delete_purchase_order, generate_purchase_order_pdf, get_pending_request_count, receive_purchase_order_items, cancel_receiving_items, complete_purchase_order_delivery, add_purchase_order_comment, forward_purchase_order, list_send_to_supplier_templates. Triggers on: purchase order, PO, create PO, approve PO, reject PO, PO delivery, PO PDF, forward PO, PO comment, pending approvals, line items, PO status.
|
ProcurementExpress Purchase Orders
Prerequisites
Authenticate (pex-auth) and set active company (pex-companies) first.
Core Tools
list_purchase_orders
List POs with pagination, search, and filters. Always returns paginated results.
- Params:
page (optional, integer, default: 1)search (optional) — matches PO number, supplier name, notes, line item descriptionsstatus (optional) — "draft", "pending", "approved", "rejected", "cancelled", "paid"delivery_status (optional) — "not_delivered", "partially_delivered", "complete_delivered"payment_status (optional) — "unpaid", "partially_paid", "paid", "invoice_received"supplier_id, requester_id, budget_id, filter_dept_id, approver_id (all optional, integer)archived (optional, boolean, default: false)date_filter (optional) — "current_month", "current_year", "last_month", "last_year"from, to (optional) — custom date range (company date_format)updated_after (optional) — ISO datetime for incremental syncsort (optional), direction (optional, "asc" or "desc")requests (optional, boolean) — include pending approval requestsbell (optional, boolean) — with requests=true, show only bell notification items
- Returns:
{ purchase_orders: PurchaseOrder[], meta: PaginationMeta }
get_purchase_order
Get PO details including line items, comments, approvals, and status flags.
- Params:
id (required, string) — accepts numeric ID, approval-key, or slug
- Returns:
PurchaseOrder
create_purchase_order
Create a new PO. At least one line item is required. See references/line-items.md.
- Params:
commit (required) — "Send" (submit for approval) or "Draft" (save as draft)creator_id (required, integer) — get from get_current_userline_items (required, array, min 1) — see references/line-items.mddepartment_id (optional, integer)supplier_id (optional, integer) — existing suppliersupplier_name (optional) — display name for existing suppliernew_supplier_name (optional) — create a new supplier inlinecurrency_id (optional, integer) — defaults to company/user currencyiso_code (optional) — alternative to currency_id (e.g. "USD")notes (optional)submitted_on (optional) — date in company date_formaton_behalf_of (optional, integer) — create on behalf of another user (companyadmin only)approver_list (optional, integer array) — override default approverscustom_field_values_attributes (optional, array) — PO-level custom field values:
id (optional, integer — for updates), value (required, string), custom_field_id (required, integer)- Get available custom fields from
get_company_details (pex-companies) → custom_fields[]
- Returns:
PurchaseOrder
update_purchase_order
Update an existing PO. Use commit: "Send" to submit a draft for approval.
- Params:
id (required, string) + any create params (all optional)
- For line items: include
id to update existing, _destroy: true to remove
- Returns:
PurchaseOrder
Approval Tools
approve_purchase_order
- Params:
id (required, string), token (required, string — accept token from approver_requests)
- Get the token from
get_purchase_order response → approver_requests[].accept_token
reject_purchase_order
- Params:
id (required, string), token (required, string — reject token from approver_requests)
- Get the token from
get_purchase_order response → approver_requests[].reject_token
override_and_approve_purchase_order
Override and approve without a token. Requires finance role.
- Params:
id (required, string)
get_pending_request_count
Get count of pending approval requests for the current user.
- Params: None
- Returns: Text with pending count
Lifecycle Tools
cancel_purchase_order
- Params:
id (required, string). Requires cancel permission.
archive_purchase_order
Toggle archive status. Requires finance role. Call again to dearchive.
- Params:
id (required, string)
delete_purchase_order
Permanently delete. Requires destroy permission.
- Params:
id (required, string)
Delivery Tools
receive_purchase_order_items
Mark line items as received (partial or full delivery).
- Params:
id (required, string) — PO IDitems (required, array) — [{ id: lineItemId, quantity: receivedQty }, ...]delivered_on (required, string) — delivery date in company date_formatnotes (optional)
cancel_receiving_items
Cancel all received deliveries, reverting to not_delivered status.
- Params:
id (required, string)
complete_purchase_order_delivery
Mark PO as fully delivered.
- Params:
id (required, string)
Communication Tools
add_purchase_order_comment
- Params:
purchase_order_id (required, integer), comment (required, string)
- Returns:
PurchaseOrderComment with formatted dates and creator info
forward_purchase_order
Forward PO to supplier(s) via email with PDF attached.
- Params:
purchase_order_id (required, integer)emails (required, string) — comma-separated recipient emailscc (optional) — CC email (defaults to PO creator's email)note (optional) — email body textemail_subject (optional)uploads (optional, integer array) — upload IDs to attach
list_send_to_supplier_templates
List email templates for forwarding POs.
- Returns:
SendToSupplierTemplate[] — id, label, text, is_default, template_name
generate_purchase_order_pdf
Generate a PDF and get download link.
- Params:
id (required, string)
- Returns:
{ pdf_link: string }
PO Response Fields
Key fields in PurchaseOrder:
id, po_number, slug, status, notes, total_gross_amount, total_net_amountsupplier_name, supplier_id, department_name, department_idcurrency_id, creator_id, submitted_on, archiveddelivery_status, payment_statuspurchase_order_items[] — line items (see references/line-items.md)purchase_order_comments[] — comments with creator infoapprover_requests[] — approval status with accept/reject tokensapprovers_with_flows[] — approval flow step detailscompliance_checks[] — compliance status with violationscustom_field_values[] — custom field datauploads[] — attached files
Common Workflows
See references/workflows.md for step-by-step guides.
