PSA/ee/docs/plans/2026-01-05-contract-purchase-order-support/PRD.md

PRD — Contract Purchase Order Support (Invoice + Limit Advisory)

• Slug: contract-purchase-order-support
• Date: 2026-01-05
• Status: Draft

Summary

Add purchase order (PO) support to contract billing in two ways:

1. When an invoice is created from a PO-enabled client contract assignment, the invoice stores a snapshot of the PO number and surfaces it in the UI + default PDF header.
2. When a PO has an authorized spend amount, the system computes advisory overage warnings (do not block) and provides batch-invoicing upfront handling (allow vs skip) only when an overage is possible.

Problem

MSPs frequently must include customer PO numbers on invoices to avoid AP rejections. Today, Alga stores PO context on the client contract assignment (client_contracts) but invoices do not reliably surface or export it, and PO authorized-spend limits are not enforced/advised during billing.

Goals

• Invoice records created from contract billing include an invoice-level po_number snapshot (immutably tied to that invoice).
• PO number appears on:
  • Invoice metadata in-app
  • Default invoice PDF header (when present)
  • Accounting export/sync “reference” surfaces (QBO + Xero + CSV adapters where applicable)
• PO authorized spend (po_amount) is treated as an advisory total spend cap:
  • Warn (do not block) when a newly generated invoice would exceed remaining PO amount.
  • “Consume” PO amount only for finalized invoices; “unconsume” automatically when invoice is unfinalized (and if an invoice is cancelled/voided).
• Batch invoicing prompts upfront for overage handling when (and only when) at least one invoice could overrun a PO limit:
  • Allow overages
  • Skip invoices that would overrun

Non-goals

• Supporting more than one PO per invoice.
• Full PO lifecycle management (creation, multi-PO allocation, splitting charges across POs).
• Blocking invoice generation due to PO limit overage.
• Retroactively changing historical invoices when contract PO values are edited later.

Users and Primary Flows

• Billing admin / finance ops
  1. Configure contract assignment PO fields (po_required, po_number, optional po_amount).
  2. Generate invoice(s) (single or batch).
  3. Review invoice details and PDF; PO is visible.
  4. Export invoices to QBO/Xero; PO reference is available externally.

UX / UI Notes

• Invoice detail view:
  • Display PO number when present.
  • Display PO “authorized” amount (from contract assignment) and “consumed/remaining” summary when po_amount is present.
  • If invoice would exceed remaining PO amount, show a warning banner with overage amount; provide an explicit “Proceed anyway” confirmation.
• Batch invoicing:
  • If none of the invoices being generated can overrun a PO limit, proceed without any extra prompts.
  • If one or more invoices could overrun, present a single prompt up front:
    • Allow overages (generate all)
    • Skip overages (generate only invoices that fit)
  • Summarize results (generated count, skipped count + reasons).

Requirements

Functional Requirements

• Invoice PO snapshot
  • Add invoices.po_number populated at invoice creation time from the associated client_contracts.po_number.
  • Add invoices.client_contract_id populated for invoices created from contract billing (single-assignment invoice scope; independent of whether the client has other active assignments).
  • Invoices created without contract context (pure manual, etc.) may leave these fields null.
• PO-required behavior
  • If client_contracts.po_required = true, invoice generation remains blocked when po_number is missing.
• PO limit advisory (authorized total spend)
  • Finalized mapping (based on current UI + invoice modification logic):
    • Treat invoice as finalized when finalized_at is set OR status is one of sent, paid, overdue, prepayment, partially_applied.
    • Do not count draft, pending, or cancelled toward consumption.
  • If client_contracts.po_amount is set, compute:
    • consumed: sum of invoices.total_amount for invoices tied to the same client_contract_id where invoice is finalized per the mapping above.
    • remaining: po_amount - consumed.
    • overage: max(0, invoice.total_amount - remaining).
  • Warn (do not block) if overage > 0.
• PDF header
  • Default invoice template includes PO number in the header when present.
• Accounting exports
  • Include PO number on exported invoices in the external system’s “reference/memo” surface(s):
    • QBO API export: include in PrivateNote (or other supported memo field).
    • QBO CSV export: include in Memo.
    • Xero API export: include in reference while preserving the invoice identifier (format TBD).
    • Xero CSV export: include in Reference while preserving existing matching identifiers (format TBD).

Non-functional Requirements

• No new external dependencies.
• Overage checks should be query-efficient (indexes on new invoice columns; avoid N+1 in batch mode).

Data / API / Integrations

• DB migration(s)
  • Add invoices.po_number (text, nullable).
  • Add invoices.client_contract_id (uuid, nullable; FK optional depending on schema conventions).
  • Add indexes to support lookups by client_contract_id and status.
• Invoice view models / API responses should include the new invoice-level PO fields for UI + exports.
• Accounting export adapters should load invoice po_number and include it in outbound payloads.

Security / Permissions

• No new permissions beyond existing invoice read/generate/export permissions.
• Ensure client portal visibility rules remain unchanged (only show PO number where the invoice is visible).

Observability

• Not in scope beyond existing logs/errors.

Rollout / Migration

• Ship a migration adding invoice columns and backfill as “best effort” if feasible (optional).
• Ensure invoice generation still works when PO columns are absent (if runtime schema checks are used elsewhere).

Open Questions

• Formatting rules for external-system references (length limits, delimiter choice, and preserving matching keys).

Acceptance Criteria (Definition of Done)

• Creating an invoice from a PO-enabled contract assignment stores invoices.po_number and shows it in invoice UI + default PDF header.
• When po_amount is set, invoice preview/generation shows an overage warning when applicable and allows an explicit override.
• Batch invoicing prompts for overage handling only when an overage is possible, and can skip overage invoices when requested.
• QBO + Xero exports include PO reference content in their respective memo/reference field(s) without breaking existing matching/mapping.