Invoice Approval Workflow

The Invoice Manager (/invoices/) is the central place to enter, route, approve, and pay vendor invoices for the association. It complements the Expense Manager (which handles reimbursement of out-of-pocket spending by members and staff): use Expenses when a person paid first and needs to be paid back, and use Invoices when a vendor sent us a bill that the association still owes.

Every vendor invoice moves through a fixed sequence of states (the "workflow"). Each state transition records who acted, when, and any comment they left, so the audit trail is automatic.

This page covers the workflow end-to-end for submitters (anyone entering an invoice), managers (first-step approvers), and finance (second-step approvers and payment processors). The last two sections document the intended organisational routing rules (which approver handles which kind of invoice) and the known gaps between that policy and what the software enforces today.

Access is controlled by Django permissions assigned to your user account (usually via an invitation permission template). Staff and superuser accounts bypass these checks and can perform every action.

Important for approvers: the manager and finance approval permissions only enable the approve / reject buttons. To open an invoice submitted by someone else you also need can_view_all_invoices (or staff/superuser status). Without it, the invoice will not appear on your list or open from a direct link. If your approver account cannot see invoices waiting for review, ask an admin to add the view permission.

Submitters can always see and edit their own invoices while they are in Draft or after a rejection.

An invoice always sits in exactly one state. Allowed transitions are:

DRAFT -> SUBMITTED -> MANAGER_APPROVED -> FINANCE_APPROVED -> READY_FOR_PAYMENT -> PAID -> CLOSED
              |                  |
              v                  v
       MANAGER_REJECTED   FINANCE_REJECTED
              |                  |
              v                  v
            DRAFT              DRAFT

State guide:

• Draft - being entered by the submitter; no one else acts on it yet.
• Submitted - waiting for the manager to review.
• Manager Approved - cleared by the manager; waiting for finance.
• Manager Rejected - manager sent it back; the submitter must return it to draft, fix it, and resubmit.
• Finance Approved - cleared by finance; ready to be queued for payment.
• Finance Rejected - finance sent it back after the manager already approved; the submitter returns it to draft.
• Ready for Payment - finance has queued the invoice for the next payment run.
• Paid - the payment has been issued to the vendor.
• Closed - terminal state; the invoice is fully reconciled and archived.

Each transition writes an InvoiceStatusLog entry capturing the user, timestamp, and any comment, and updates the shared WorkflowInstance audit trail. You can review the full history on the invoice detail page.

Creating an invoice

1. Go to /invoices/ and click New Invoice.
2. Pick the Vendor (use the search combobox; if the supplier is missing, an admin must add it on the Vendors page or via the CSV importer).
3. Set the Classification. This defaults from the vendor when possible (e.g., a known umpire supplier defaults to "Umpire Fees"); change it if the bill covers something else.
4. Pick a Division if the invoice belongs to one (Jr Mens, Senior, etc.). Leave blank for association-wide / HQ invoices.
5. Enter one line item per GL code on the bill. Quantity x Unit Amount is totalled automatically.
6. Add the supplier's PDF (or photo) as an Attachment. Approvers will expect to see the original bill.
7. Save - the invoice is still in Draft. You can keep editing it.
8. When the entry is complete and matches the supplier PDF, click Submit for Approval. The invoice moves to Submitted and is now visible to managers.

If your invoice is rejected

You will see the invoice back at the top of your list with status Manager Rejected or Finance Rejected, plus the rejection comment in the status log. From the invoice detail page:

1. Click Return to Draft.
2. Edit the fields, line items, or attachments to address the comment.
3. Click Submit for Approval again to restart the workflow.

Tips

• Get the Classification and Division right - this is what tells approvers which commissioner or VP owns the bill (see the routing section below).
• Always attach the supplier's original invoice. Approvers cannot verify totals from memory.
• Use the notes field for context the approver will need (e.g., "covers diamond rentals for the May 12 tournament").

Managers are the first-step approvers. Your job is to confirm the invoice is legitimate, correctly classified, and within the budget of the division or function it belongs to.

Finding invoices that need you

There is no per-user "assigned to me" inbox yet (see Gaps section). Today you find work by filtering the invoice list:

1. Go to /invoices/.
2. Filter Status = Submitted.
3. Optionally filter by Division or Classification to see only the invoices the routing policy says you own.

What to check before approving

• The attached supplier PDF matches the entered vendor, totals, and line items.
• The classification is correct (umpires vs. fields vs. uniforms etc.).
• The division is correct, or the invoice is genuinely HQ-wide.
• Line-item GL codes look reasonable for the classification.
• The amount fits the relevant budget you steward.

Available actions

• Approve (Manager) - sends the invoice to Finance.
• Reject (Manager) - sends it back. Add a comment explaining what the submitter needs to fix; the comment is recorded on the status log.

A rejected invoice goes to Manager Rejected; the submitter is responsible for returning it to Draft and resubmitting.

Finance is the second-step approver and also drives the payment workflow once an invoice is fully approved.

Finance approval

1. Filter the invoice list to Status = Manager Approved.
2. Review for finance concerns: tax handling, currency, GL coding, duplicate payment risk, cash position.
3. Choose Approve (Finance) or Reject (Finance). A finance rejection sends the invoice back to the submitter (not the manager), since the submitter is the only one who can edit the underlying data.

Payment processing

After finance approval, the invoice sits in Finance Approved. Finance then drives it through the rest of the lifecycle:

1. Mark Ready for Payment - queues the invoice for the next payment run. Use this when the cheque run or e-transfer batch is being prepared.
2. Mark as Paid - records that the payment has actually been issued. The paid-at timestamp is captured automatically.
3. Close - terminal step once the invoice is fully reconciled (e.g., against the bank statement). Closed invoices remain visible for reporting but cannot be changed.

The software does not yet enforce who should review which invoice. The rules below are policy: approvers should use them to decide which submitted invoices to pick up, and submitters should use them to set Classification and Division so the right person can find the work.

How submitters help routing today: set Classification (Umpire Fees, Equipment, Field Rental, Insurance, etc.) and Division (Jr Mens, Senior, blank for HQ). Approvers filter the invoice list by these two fields to pull their own queue.

How finance step works: Finance approval is performed by whoever holds the can_finance_approve_invoices permission (typically the Treasurer). The finance step is not routed by classification - all approved invoices flow through the same finance reviewer.

The list above is a starting point and is intentionally not exhaustive; new classifications or unusual bills should be raised with the VP Admin so the routing table can be expanded.

The routing policy above is currently manual. The software does not yet know about commissioners or VPs, and several quality-of-life features for approvers are still on the roadmap. This section makes the gaps explicit so users know what to expect today and so future work can be prioritised.

Not enforced in the application:

• There is no model for the organisational roles (Division Commissioner, VP Baseball, VP Admin). Any user with the manager-approve permission can currently approve any invoice in any division.
• Invoice Classifications are a catalogue only - they do not point at a specific approver, so the system cannot auto-route fields/umpires to the VP Baseball.
• Divisions do not have a commissioner foreign key, so the system cannot auto-route Jr Mens coaching expenses to the Jr Mens Commissioner.
• There is no "Pending my approval" inbox - approvers find work by filtering the full invoice list.
• There are no approval / rejection email notifications. Submitters discover rejections by checking the list; approvers discover new submissions the same way.
• There is no self-approval guard. A user who is both a submitter and holds the manager permission could technically approve their own invoice (the Expense Manager already blocks this).
• The seed permission templates (setup_permission_templates) do not yet ship Invoice Submitter / Manager / Finance bundles - admins must create custom templates or assign permissions manually.
• Audit fields capture when the manager and finance steps happened but not who performed them as a foreign key - the user is recoverable from the status log but not from the invoice header.
• The requirement that approvers also hold can_view_all_invoices is not surfaced in the UI; admins should bundle the two permissions together.

Planned follow-up work (tracked as a separate spec) is expected to add:

• Org-role models (Commissioner / VP Baseball / VP Admin) with linked users and backups.
• Routing on Classification and/or Division so the system can pre-assign each new invoice to the right approver.
• A "Pending my approval" inbox queryset and dashboard tile.
• Submission / approval / rejection email notifications.
• Self-approval guard parity with the Expense workflow.
• Audit FKs for manager_approved_by and finance_approved_by.
• Seeded permission templates so new admins can grant the right role in one click.

If you see other gaps in the workflow as you use the system, please flag them to the VP Admin so they can be added here and into the follow-up spec.

I have the approval permission but the invoice will not open.

You also need invoices.can_view_all_invoices (or staff status) to see invoices submitted by other people. Ask an admin to add the view permission.

I cannot find the invoice that needs my approval.

Go to /invoices/ and set Status = Submitted (for managers) or Status = Manager Approved (for finance). Add Division or Classification filters to narrow down to the bills the routing policy says you own.

I rejected an invoice by mistake.

Tell the submitter. From the rejected state they click Return to Draft, and from Draft they can immediately Submit for Approval again. Add a comment so the audit log explains the round-trip.

Where do the attached supplier PDFs go?

They are stored as InvoiceAttachment records linked to the invoice and displayed on the invoice detail page. Maximum 10 MB per file.

How do I see only my own invoices?

Submitters automatically see only their own invoices on the list page unless they also have the view-all permission, in which case the list shows everything. Filter by Submitter to restrict to your own.

Why is there a finance step on top of the manager step?

The manager step confirms the bill is real and correctly classified for its area. The finance step adds a second check focused on tax, GL coding, duplicate-payment risk, and cash position before the invoice gets queued for actual payment.

What happens after Paid?

A user with can_close_invoices can close the invoice once it has been reconciled (e.g., matched against the bank statement). Closed invoices are read-only and remain in the system for reporting.