@procurementexpress.com/mcp 1.0.0 → 2.0.0

package/.claude/skills/pex-companies/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: pex:companies
+description: >
+  ProcurementExpress company management, employee listing, user invitations, and approver
+  queries. Use when listing companies, switching the active company, viewing company details
+  and settings, managing employees and user invitations, or querying approvers. Routes to MCP
+  tools: list_companies, get_company, get_company_details, set_active_company, list_approvers,
+  list_all_approvers, list_employees, invite_user, get_invite_limit, list_pending_invites,
+  cancel_invite, resend_invite. Triggers on: company, switch company, employees, invite user,
+  approvers, company settings, custom fields, payment terms.
+---
+
+# ProcurementExpress Companies
+
+## Prerequisites
+
+Authenticate first (pex-auth skill). Most tools require an active company set via `set_active_company`.
+
+## Tools Reference
+
+### set_active_company
+Set the working company for all subsequent API calls. **Must be called before most operations.**
+- **Params:** `company_id` (required, string)
+- **Returns:** Confirmation text
+- This is a client-side operation (no API call)
+
+### list_companies
+List all companies the authenticated user belongs to.
+- **Params:** None
+- **Returns:** `CompanyDetail[]`
+
+### get_company
+Get company details by ID including settings, custom fields, and supported currencies.
+- **Params:** `id` (required, integer)
+- **Returns:** `CompanyDetail`
+
+### get_company_details
+Get details for the currently active company.
+- **Params:** None
+- **Returns:** `CompanyDetail`
+
+### list_employees
+List all active employees of the current company with their roles.
+- **Params:** None
+- **Requires:** companyadmin role
+- **Returns:** `Employee[]` — each has: id, email, name, roles[]
+
+### list_approvers
+List approvers for the current company. Returns empty if company uses approval flows.
+- **Params:** `department_id` (optional, integer) — filter by department
+- **Returns:** `Approver[]` — each has: id, email, name, approval_limit
+
+### list_all_approvers
+List all approvers regardless of auto-approval routing.
+- **Params:** None
+- **Returns:** `Approver[]`
+
+### invite_user
+Invite a user to the company.
+- **Params:**
+  - `email` (required, email format)
+  - `name` (required, string)
+  - `roles` (required, array) — valid values: `"companyadmin"`, `"approver"`, `"finance"`, `"teammember"`
+  - `approval_limit` (optional, number, default: 0)
+  - `department_ids` (optional, integer array)
+- **Requires:** Available invite slots (check with `get_invite_limit`)
+- **Returns:** Invitation result
+
+### get_invite_limit
+Check remaining invite slots for the company plan.
+- **Params:** None
+- **Returns:** `{ invite_limit_left, active_users, allowed_users }`
+
+### list_pending_invites
+List pending user invitations.
+- **Params:** None
+- **Requires:** companyadmin role
+- **Returns:** Array of pending invites (each has a `token` for cancel/resend)
+
+### cancel_invite
+Cancel a pending invitation.
+- **Params:** `token` (required, string) — from pending invite
+- **Requires:** companyadmin role
+
+### resend_invite
+Resend a pending invitation email.
+- **Params:** `token` (required, string) — from pending invite
+- **Requires:** companyadmin role
+
+## CompanyDetail Response Fields
+
+Key fields in `CompanyDetail`:
+- `id`, `name`, `is_locked`, `in_trial`, `trial_expired`, `remaining_trial_days`
+- `company_setting` — 40+ config fields including:
+  - `currency_id` — default currency
+  - `date_format` — date format used across all date fields in the API
+  - `gross_or_net` — whether amounts are gross or net
+  - `show_po_item_number`, `show_delivery_status`, `show_payment_status`
+  - `po_number_prefix`, `next_po_number`
+  - `invoice_enabled`, `invoice_approval_flow_enabled`
+  - `approval_flow_enabled` — whether approval flows are active
+- `custom_fields[]` — company custom fields with type, options, placement flags
+- `supported_currencies[]` — currencies enabled for this company
+- `payment_terms[]` — payment terms with due_days, day_of_month, term_type
+
+## User Roles
+
+| Role | Permissions |
+|------|------------|
+| `companyadmin` | Full admin access, manage users, settings |
+| `approver` | Approve/reject POs and invoices |
+| `finance` | Financial operations, override approvals, archive |
+| `teammember` | Create and view POs |

package/.claude/skills/pex-departments/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pex:departments
+description: >
+  ProcurementExpress department management. Use when listing, viewing, creating, or updating
+  departments (organizational units). Routes to MCP tools: list_departments, get_department,
+  create_department, update_department. Triggers on: department, division, organizational unit,
+  department users, department budgets.
+---
+
+# ProcurementExpress Departments
+
+## Prerequisites
+
+Authenticate (pex-auth) and set active company (pex-companies) first.
+
+## Tools Reference
+
+### list_departments
+List departments. By default returns only departments the current user has access to.
+- **Params:**
+  - `archived` (optional, boolean, default: false)
+  - `company_specific` (optional, boolean) — true to list ALL company departments regardless of user access
+- **Returns:** `Department[]`
+
+### get_department
+Get a specific department by ID.
+- **Params:** `id` (required, integer)
+- **Returns:** `Department`
+
+### create_department
+Create a new department.
+- **Params:**
+  - `name` (required, string)
+  - `contact_person` (optional, string)
+  - `phone_number` (optional, string)
+  - `email` (optional, string)
+  - `address` (optional, string)
+  - `tax_number` (optional, string)
+  - `budget_ids` (optional, integer array) — budgets to associate
+  - `user_ids` (optional, integer array) — users to assign
+- **Returns:** `Department`
+
+### update_department
+Update an existing department.
+- **Params:** `id` (required) + any create_department params + `archived` (optional, boolean)
+- **Returns:** `Department`
+
+## Department Response Fields
+
+- `id`, `name`, `company_id`, `archived`
+- `contact_person`, `tax_number`, `phone_number`, `address`, `email`
+- `supplier_ids[]` — associated supplier IDs
+- `budget_ids[]` — associated budget IDs
+- `created_at`, `updated_at`
+
+## Relationships
+
+- Departments contain users and budgets
+- Departments can restrict which suppliers are available
+- POs and invoices can be filtered by department
+- Approvers can be filtered by department (pex-companies `list_approvers`)

package/.claude/skills/pex-invoices/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: pex:invoices
+description: >
+  ProcurementExpress invoice management. Covers creating, updating, accepting, approving,
+  rejecting, cancelling, archiving invoices, and adding comments. Handles the full invoice
+  lifecycle from receipt through approval to settlement. Routes to MCP tools: list_invoices,
+  get_invoice, create_invoice, update_invoice, accept_invoice, approve_invoice, reject_invoice,
+  cancel_invoice, archive_invoice, dearchive_invoice, rerun_invoice_approval_flow,
+  add_invoice_comment. Triggers on: invoice, bill, invoice approval, invoice status,
+  awaiting review, outstanding invoice, ready to pay, invoice comment, invoice line items.
+---
+
+# ProcurementExpress Invoices
+
+## Prerequisites
+
+Authenticate (pex-auth) and set active company (pex-companies) first.
+Invoices must be enabled for the company (`company_setting.invoice_enabled`).
+
+## Core Tools
+
+### list_invoices
+List invoices with pagination and filters.
+- **Params:**
+  - `page` (optional, integer, default: 1)
+  - `per_page` (optional, integer) — allowed: 10, 20, 50, 100
+  - `search` (optional) — matches invoice number, supplier name
+  - `invoice_statuses_filter` (optional) — `"awaiting_review"`, `"outstanding"`, `"ready_to_pay"`, `"settled"`, `"cancelled"`
+  - `supplier_id`, `requester_id`, `approver_id`, `department_id` (all optional, integer)
+  - `archived` (optional, boolean, default: false)
+  - `invoice_date_filter` (optional) — `"last 7days"`, `"last 30days"`, `"last 60days"`, `"last 90days"`, `"last 180days"`, `"last 1year"`, `"current_month"`, `"current_year"`, `"last_month"`, `"last_year"`
+  - `sage_exported` (optional, boolean) — filter by Sage export status
+  - `sort` (optional), `direction` (optional, `"asc"` or `"desc"`)
+- **Returns:** `{ invoices: Invoice[], meta: PaginationMeta }`
+
+### get_invoice
+Get invoice details including line items, linked POs, comments, and payment history.
+- **Params:** `id` (required, integer)
+- **Returns:** `Invoice`
+
+### create_invoice
+Create a new invoice. If company has "create invoice in awaiting review" enabled, starts in awaiting_review status.
+- **Params:**
+  - `invoice_number` (optional, string)
+  - `issue_date`, `uploaded_date`, `received_date`, `due_date` (optional, string — company date_format)
+  - `gross_amount` (optional, number)
+  - `currency_id` (optional, integer)
+  - `supplier_id` (optional, integer)
+  - `standalone_invoice` (optional, boolean) — true if not linked to any PO
+  - `payment_term_id` (optional, integer) — payment terms from company settings
+  - `selected_purchase_order_ids` (optional, integer array) — PO IDs to link
+  - `line_items` (optional, array) — see [references/line-items.md](references/line-items.md)
+  - `custom_field_values_attributes` (optional, array) — invoice-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:** `Invoice`
+
+### update_invoice
+Update an existing invoice.
+- **Params:** `id` (required) + any create params
+- For line items: include `id` to update, `_destroy: true` to remove
+- **Returns:** `Invoice`
+
+## Approval Lifecycle Tools
+
+### accept_invoice
+Accept an invoice in awaiting_review status (moves to outstanding).
+- **Params:** `id` (required, integer)
+
+### approve_invoice
+Approve an invoice (requires invoice approval permission).
+- **Params:** `id` (required, integer)
+
+### reject_invoice
+Reject an invoice (requires invoice approval permission).
+- **Params:** `id` (required, integer)
+
+### cancel_invoice
+Cancel an invoice (requires cancel permission).
+- **Params:** `id` (required, integer)
+
+### archive_invoice
+Archive an invoice (requires archive permission).
+- **Params:** `id` (required, integer)
+
+### dearchive_invoice
+Restore an archived invoice.
+- **Params:** `id` (required, integer)
+
+### rerun_invoice_approval_flow
+Rerun the approval flow when rules have changed.
+- **Params:** `id` (required, integer)
+
+## Comment Tool
+
+### add_invoice_comment
+Add a comment to an invoice.
+- **Params:** `invoice_id` (required, integer), `comment` (required, string)
+
+## Invoice Status Flow
+
+```
+awaiting_review → (accept_invoice) → outstanding → (approve_invoice) → ready_to_pay → (payment) → settled
+                                    → (reject_invoice) → rejected
+                                    → (cancel_invoice) → cancelled
+```
+
+If `invoice_approval_flow_enabled`, the approval flow determines the approval path automatically.
+
+## Invoice Response Fields
+
+Key fields in `Invoice`:
+- `id`, `invoice_number`, `status`, `gross_amount`, `net_amount`
+- `issue_date`, `uploaded_date`, `received_date`, `due_date`, `validation_date`
+- `supplier_id`, `supplier_name`, `currency`
+- `standalone_invoice` — whether linked to POs
+- `confidence_score`, `digital_invoice` — AI extraction confidence
+- `invoice_line_items[]` — line items (see [references/line-items.md](references/line-items.md))
+- `purchase_order_summaries[]` — linked PO summaries
+- `supplier_invoice_uploads[]` — attached invoice files
+- `invoice_histories[]` — status change history
+- `invoice_comments[]` — comments with creator info
+- `payments[]` — payment records
+- Actions: `can_accept`, `can_approve`, `can_reject`, `can_cancel`, `can_archive`, `can_dearchive`
+- `payment_terms_list[]` — available payment terms

package/.claude/skills/pex-invoices/references/line-items.md

@@ -0,0 +1,55 @@
+# Invoice Line Item Schema
+
+## Creating/Updating Line Items
+
+Each line item in the `line_items` array accepts:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | integer | For updates | Existing line item ID |
+| `description` | string | No | Item description |
+| `unit_price` | number | No | Unit price |
+| `quantity` | number | No | Quantity |
+| `vat` | number | No | VAT/tax percentage |
+| `net_amount` | number | No | Net amount |
+| `sequence_no` | integer | No | Display order |
+| `tax_rate_id` | integer | No | Tax rate ID (from pex-settings) |
+| `chart_of_account_id` | integer | No | GL code (from pex-settings) |
+| `qbo_customer_id` | integer | No | QuickBooks customer |
+| `quickbooks_class_id` | integer | No | QuickBooks class |
+| `qbo_line_description` | string | No | QuickBooks line description override |
+| `purchase_order_id` | integer | No | Link to a specific PO |
+| `purchase_order_item_id` | integer | No | Link to a specific PO line item |
+| `billable_status` | string | No | Billable status for QuickBooks |
+| `_destroy` | boolean | No | Set true to delete (updates only) |
+| `custom_field_values_attributes` | array | No | Line-item-level custom field values: `[{id?, value, custom_field_id}]` |
+
+## Line Item Response Fields
+
+Each `InvoiceLineItem` in the response contains:
+
+- `id`, `sequence_no`, `description`, `unit_price`, `quantity`
+- `vat`, `gross_amount`, `net_amount` — calculated amounts
+- `tax_rate_id`, `tax_exception` — tax details
+- `chart_of_account` — GL code details (id, name, display_name)
+- `qbo_customer` — QuickBooks customer details
+- `quickbooks_class` — QuickBooks class details
+- `invoice_id`, `purchase_order_id`, `purchase_order_item_id` — relationships
+
+## Linking to Purchase Orders
+
+Invoice line items can be linked to PO line items for three-way matching:
+- Set `purchase_order_id` to link to a PO
+- Set `purchase_order_item_id` to link to a specific PO line item
+- Also set `selected_purchase_order_ids` on the invoice itself
+
+This enables matching invoice amounts against PO amounts for variance detection.
+
+## Reference Data
+
+For IDs used in line items, use pex-settings tools:
+- `list_tax_rates` → `tax_rate_id`
+- `list_chart_of_accounts` → `chart_of_account_id`
+- `list_qbo_customers` → `qbo_customer_id`
+- `list_qbo_classes` → `quickbooks_class_id`
+- Custom field IDs from `get_company_details` (pex-companies) → `custom_fields[]`

package/.claude/skills/pex-payments/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pex:payments
+description: >
+  ProcurementExpress payment management. Use when creating or viewing payments to settle
+  invoices and purchase orders. Routes to MCP tools: get_payment, create_payment,
+  create_po_payment. Triggers on: payment, pay invoice, pay purchase order, settle,
+  bank transfer, payment record, payment type.
+---
+
+# ProcurementExpress Payments
+
+## Prerequisites
+
+Authenticate (pex-auth) and set active company (pex-companies) first.
+The payments feature may be feature-flagged — contact sales if `create_payment` returns an error.
+
+## Tools Reference
+
+### get_payment
+Get payment details by ID including linked invoices and POs.
+- **Params:** `id` (required, integer)
+- **Returns:** `Payment`
+
+### create_payment
+Create a payment to settle invoices and/or purchase orders.
+- **Params:**
+  - `supplier_id` (required, integer)
+  - `ptype` (required, enum) — payment type, one of:
+    - `"bank_transfer"`, `"card"`, `"credit_card"`, `"check"`, `"cash"`, `"one_time_card"`, `"letter_of_credit"`, `"other"`
+  - `date` (required, string) — must match company `date_format` setting
+  - `currency_id` (required, integer)
+  - `amount` (required, number) — total payment amount
+  - `reference` (optional, string) — payment reference number
+  - `payment_mode` (optional, string)
+  - `status` (optional, string)
+  - `invoices` (optional, array) — invoices to settle:
+    - `invoice_id` (required, integer)
+    - `gross_amount` (required, number) — amount applied to this invoice
+  - `purchase_orders` (optional, array) — POs to settle:
+    - `purchase_order_id` (required, integer)
+    - `budget_id` (optional, integer)
+    - `gross_amount` (required, number) — amount applied to this PO
+  - `comments` (optional, array) — payment comments:
+    - `comment` (required, string)
+- **Returns:** `Payment`
+
+### create_po_payment
+Create a payment for a specific purchase order with optional item-level breakdown.
+- **Params:**
+  - `purchase_order_id` (required, integer)
+  - `amount` (optional, number) — total payment (if not using item-level)
+  - `note` (optional, string)
+  - `item_payments` (optional, array) — item-level payments:
+    - `purchase_order_item_id` (required, integer) — PO line item ID
+    - `amount` (required, number) — amount for this item
+- **Returns:** Payment result
+
+## Payment Response Fields
+
+- `id`, `reference`, `status`, `ptype`, `date`, `amount`
+- `currency` — currency details
+- `supplier` — supplier summary
+- `user` — creator details
+- `invoices[]` — linked invoice summaries
+- `npayment_comments[]` — payment comments (id, comment, creator_id, system_generated)
+
+## Workflow: Settle an Invoice
+
+```
+1. get_invoice (pex-invoices) → get invoice details, supplier_id, gross_amount
+2. create_payment → with supplier_id, amount, ptype, invoices array
+```
+
+## Workflow: Pay a Purchase Order
+
+```
+Option A: create_po_payment → simple PO payment with optional item breakdown
+Option B: create_payment → with purchase_orders array (can combine with invoices)
+```

package/.claude/skills/pex-purchase-orders/SKILL.md

@@ -0,0 +1,167 @@
+---
+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 descriptions
+  - `status` (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 sync
+  - `sort` (optional), `direction` (optional, `"asc"` or `"desc"`)
+  - `requests` (optional, boolean) — include pending approval requests
+  - `bell` (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](references/line-items.md).
+- **Params:**
+  - `commit` (required) — `"Send"` (submit for approval) or `"Draft"` (save as draft)
+  - `creator_id` (required, integer) — get from `get_current_user`
+  - `line_items` (required, array, min 1) — see [references/line-items.md](references/line-items.md)
+  - `department_id` (optional, integer)
+  - `supplier_id` (optional, integer) — existing supplier
+  - `supplier_name` (optional) — display name for existing supplier
+  - `new_supplier_name` (optional) — create a new supplier inline
+  - `currency_id` (optional, integer) — defaults to company/user currency
+  - `iso_code` (optional) — alternative to currency_id (e.g. "USD")
+  - `notes` (optional)
+  - `submitted_on` (optional) — date in company date_format
+  - `on_behalf_of` (optional, integer) — create on behalf of another user (companyadmin only)
+  - `approver_list` (optional, integer array) — override default approvers
+  - `custom_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 ID
+  - `items` (required, array) — `[{ id: lineItemId, quantity: receivedQty }, ...]`
+  - `delivered_on` (required, string) — delivery date in company date_format
+  - `notes` (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 emails
+  - `cc` (optional) — CC email (defaults to PO creator's email)
+  - `note` (optional) — email body text
+  - `email_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_amount`
+- `supplier_name`, `supplier_id`, `department_name`, `department_id`
+- `currency_id`, `creator_id`, `submitted_on`, `archived`
+- `delivery_status`, `payment_status`
+- `purchase_order_items[]` — line items (see [references/line-items.md](references/line-items.md))
+- `purchase_order_comments[]` — comments with creator info
+- `approver_requests[]` — approval status with accept/reject tokens
+- `approvers_with_flows[]` — approval flow step details
+- `compliance_checks[]` — compliance status with violations
+- `custom_field_values[]` — custom field data
+- `uploads[]` — attached files
+
+## Common Workflows
+
+See [references/workflows.md](references/workflows.md) for step-by-step guides.

package/.claude/skills/pex-purchase-orders/references/line-items.md

@@ -0,0 +1,53 @@
+# PO Line Item Schema
+
+## Creating/Updating Line Items
+
+Each line item in the `line_items` array accepts:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | integer | For updates | Existing line item ID (omit for new items) |
+| `description` | string | Yes | Item description |
+| `quantity` | number | Yes | Quantity |
+| `unit_price` | number | Yes | Unit price |
+| `budget_id` | integer | No | Budget to charge against |
+| `vat` | number | No | VAT/tax percentage |
+| `tax_rate_id` | integer | No | Tax rate ID (from pex-settings) |
+| `item_number` | string | No | Item number (if company has show_po_item_number enabled) |
+| `sequence_no` | integer | No | Display order |
+| `department_id` | integer | No | Department for this line item |
+| `product_id` | integer | No | Product ID (auto-fills description, SKU, unit_price from catalog) |
+| `chart_of_account_id` | integer | No | GL code (from pex-settings) |
+| `qbo_customer_id` | integer | No | QuickBooks customer |
+| `quickbooks_class_id` | integer | No | QuickBooks class |
+| `qbo_line_description` | string | No | QuickBooks line description override |
+| `archived` | boolean | No | Archive this line item |
+| `_destroy` | boolean | No | Set true to delete this line item (updates only) |
+| `custom_field_values_attributes` | array | No | Line-item-level custom field values: `[{id?, value, custom_field_id}]` |
+
+## Line Item Response Fields
+
+Each `PurchaseOrderItem` in the response contains:
+
+- `id`, `description`, `quantity`, `unit_price`, `item_number`, `sequence_no`
+- `budget_id`, `budget_name` — associated budget
+- `gross_amount`, `net_amount`, `vat` — calculated amounts
+- `tax_rate_id` — applied tax rate
+- `product_id` — linked product
+- `received_quantity` — quantity received so far
+- `chart_of_account` — GL code details (id, name, display_name)
+- `qbo_customer` — QuickBooks customer details
+- `quickbooks_class` — QuickBooks class details
+- `custom_field_values[]` — custom field data for this line item
+- `department_id`, `purchase_order_id`
+
+## Tips
+
+- When using `product_id`, the product's description, SKU, and unit_price will be used as defaults
+- To update existing line items, include their `id`. To add new items, omit `id`
+- To remove a line item during update, include `id` and `_destroy: true`
+- The `budget_id` determines which budget is charged when the PO is approved
+- If the company uses `gross_or_net` setting, amounts are calculated accordingly
+- Custom fields can be set at both PO level and line item level via `custom_field_values_attributes`
+- Get available custom field IDs from `get_company_details` (pex-companies) → `custom_fields[]`
+- For reference data IDs: use pex-settings tools (`list_tax_rates`, `list_chart_of_accounts`, `list_qbo_customers`, `list_qbo_classes`)