pexpurchase-orders

name

pex:purchase-orders

description

ProcurementExpress purchase order (PO) management via CLI — 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 comments. CLI commands: pex purchase-order (alias: pex po) list|show|create|update|approve|reject| override|cancel|archive|delete|pdf|forward|receive|cancel-receiving|complete-delivery| pending-requests|pending-count|mark-as-paid. Also: pex comment add-purchase-order, pex compliance check|justify|memo|audit-trail, pex upload po|comment|status. Triggers on: purchase order, PO, create PO, approve PO, reject PO, PO delivery, PO PDF, forward PO, PO comment, pending approvals, pending requests, line items, PO status, mark as paid, compliance, audit trail, upload attachment.

ProcurementExpress Purchase Orders

Prerequisites

Authenticate and set active company first (pex:setup skill).

IMPORTANT: "Requests" vs "Purchase Orders"

These terms have different meanings — use the correct command:

• "Pending requests" / "requests" = POs waiting for the current user to approve. These are items in the user's approver queue. → Use pex po pending-requests or pex po pending-count → Example user phrases: "how many pending requests are there?", "show my requests", "what do I need to approve?"

• "Pending purchase orders" = POs with status == "pending" (general list filter). These may have been submitted by anyone and are awaiting approval from someone. → Use pex po list --status=pending → Example user phrases: "how many pending purchase orders do I have?", "list pending POs", "show purchase orders with pending status"

• "Purchase orders" (without qualifier) = POs that are approved, paid, or delivered. → Use pex po list with appropriate --status filter (approved, paid, etc.) → Example user phrases: "show my purchase orders", "list approved POs"

Pending Requests (Approver Workflow)

For approvers checking and acting on POs assigned to them:

# Check how many POs are waiting for your approval
pex po pending-count

# List POs pending your approval (paginated)
pex po pending-requests              # alias: pex po pending
pex po pending-requests --page=2

# Review a specific PO
pex po show 12345  # → check approver_requests[].accept_token / reject_token

# Take action
pex po approve 12345 --token=<accept_token>
pex po reject 12345 --token=<reject_token>
pex po override 12345  # finance role, no token needed
pex po cancel 12345

List & Show

# List purchase orders (approved/paid/delivered — post-approval)
pex po list --status=approved --page=1
pex po list --status=paid
pex po list --status=pending   # POs with pending status (NOT the approver queue)

# Other filters
pex po list --search="laptop" --supplier-id=10
pex po list --date-filter=current_month --sort=total_gross_amount --direction=desc
pex po list --delivery-status=not_delivered --payment-status=unpaid
pex po list --department-id=5 --requester-id=12 --approver-id=8
pex po list --archived --from="2024-01-01" --to="2024-12-31"
pex po list --requests --bell  # pending approval notifications
pex po list --updated-after="2024-01-01T00:00:00Z"  # incremental sync

# Show details (accepts numeric ID, approval-key, or slug)
pex po show 12345

Create

At least one line item is required. Pass line items as JSON.

pex po create \
  --commit=Send \
  --creator-id=1 \
  --supplier-id=10 \
  --department-id=5 \
  --notes="Q1 office supplies" \
  --line-items='[
    {"description":"Laptops","quantity":5,"unit_price":1200,"budget_id":3},
    {"description":"Monitors","quantity":5,"unit_price":400,"tax_rate_id":2}
  ]'

• --commit: Send (submit for approval) or Draft (save as draft)
• --creator-id: required — get from pex auth whoami
• --supplier-id or --supplier-name or --new-supplier-name
• --currency-id or --iso-code (e.g., USD)
• --approver-list: comma-separated user IDs to override default approvers
• --on-behalf-of: user ID (companyadmin only)
• --custom-fields: JSON array of [{"value":"x","custom_field_id":1}]

Line Item Fields

Each line item object supports:

• description (required), quantity (required), unit_price (required)
• budget_id, vat, tax_rate_id, item_number, sequence_no
• department_id, product_id, chart_of_account_id
• qbo_customer_id, quickbooks_class_id
• custom_field_values_attributes: [{"value":"x","custom_field_id":1}]

Update

pex po update 12345 --notes="Updated notes" --commit=Send
pex po update 12345 --line-items='[
  {"id":100,"quantity":10},
  {"id":101,"_destroy":true},
  {"description":"New item","quantity":1,"unit_price":50}
]'

For line items: include id to update existing, _destroy: true to remove, omit id for new.

Approval

# First get the PO to find approval tokens
pex po show 12345  # → approver_requests[].accept_token / reject_token

pex po approve 12345 --token=<accept_token>
pex po reject 12345 --token=<reject_token>
pex po override 12345  # finance role, no token needed

Lifecycle

pex po cancel 12345
pex po archive 12345       # toggle archive (call again to dearchive)
pex po delete 12345        # permanent delete
pex po mark-as-paid 12345  # mark PO as paid

Compliance

Run compliance checks, justify violations, generate memos, and view audit trails.

pex compliance check 12345                  # run compliance check on a PO
pex compliance justify 12345 \
  --violation-id=1 \
  --justification="Emergency procurement approved by CFO"
pex compliance memo 12345                   # generate compliance memo
pex compliance audit-trail 12345            # view audit trail

File Uploads

Attach files to purchase orders or PO comments.

pex upload po 12345 --file=./invoice.pdf            # upload to PO
pex upload comment 12345 --comment-id=67 \
  --file=./receipt.png                               # upload to PO comment
pex upload status 99                                 # check upload status

Delivery

pex po receive 12345 \
  --items='[{"id":100,"quantity":5},{"id":101,"quantity":3}]' \
  --delivered-on="2024-03-15" \
  --notes="Partial delivery"

pex po cancel-receiving 12345    # revert all deliveries
pex po complete-delivery 12345   # mark fully delivered

Communication

# PDF
pex po pdf 12345  # returns { pdf_link: "..." }

# Forward to supplier
pex po forward 12345 --emails="[e-mail]" --note="Please confirm" --subject="PO #12345"

# Comment
pex comment add-purchase-order 12345 --comment="Approved by finance"

Key Response Fields

• id, status, notes, total_gross_amount, total_net_amount
• supplier_name, department_name, creator_name
• delivery_status, payment_status, archived
• purchase_order_items[] — line items with amounts, quantities, custom fields
• approver_requests[] — approval status with accept_token / reject_token
• purchase_order_comments[] — comments with creator info
• can_cancel, can_archive, can_override, can_edit — action flags