Expense Approvals

Overview

Employees often incur expenses for business purposes, such as travel, software licenses, meals, or project supplies. Before these expenses are reimbursed or recorded in the organization's financial reports, they must be reviewed and verified.

Expense Approvals provides the dedicated workspace where managers, project leaders, and finance personnel can review submitted expenses, analyze receipts, check project or category allocations, and make a final decision to approve or reject the claim.

Why Expense Approvals Exists

Submitting an expense doesn't automatically mean it is valid or ready for reimbursement. Expense Approvals exists to:

• Enforce Business Policy: Ensure that submitted expenses comply with organizational rules and limits.
• Maintain Budget Control: Verify that project budgets or departmental cost centers can absorb the expense.
• Prevent Fraud: Review AI-analyzed receipts to ensure the claimed amount matches the physical proof.
• Provide Audit Trails: Maintain a permanent history of who approved an expense and when, ensuring accountability.

Who Uses Expense Approvals

This page is primarily used by:

• Direct Managers: To review their direct reports' regular expenses.
• Project Managers: To approve expenses specifically billed against their projects.
• Finance Teams: For secondary or final verification before sending to payroll or accounting for reimbursement.
• Administrators: To monitor bottlenecks or SLA (Service Level Agreement) breaches in the approval flow.

How to Access Expense Approvals

1. Open your Personal Workspace via the main navigation menu.
2. Select Expense Approvals (look for the receipt icon).

[!NOTE] Expense Approvals operates on a strict permission model. You must have the org.expense.approve permission to access this page. If you do not have this permission, the menu item will be completely hidden.

How Expense Management Fits Together

Understanding the entire ecosystem helps clarify the approver's role:

My Expenses vs Expense Approvals

It is easy to confuse these two pages if you are both a submitter and a manager.

Feature	Purpose	Audience
My Expenses (/org/expenses/my)	Where you create, view, and track the status of your own personal expenses.	All Employees
Expense Approvals (/org/expense-approvals)	Where you review and approve expenses submitted by other people.	Managers & Approvers

Understanding the Expense Approvals Screen

The page is designed for efficiency, split into two main sections:

1. The Approval Queue (Left Sidebar): A list of all expenses currently awaiting your decision.
2. The Detail View (Right Panel): The full details, receipt preview, and action buttons for the currently selected expense.

The Approval Queue

Each card in the queue provides an immediate summary:

• Requestor & Category: Who submitted it and what it's for.
• Project: Which project this expense belongs to (or "General" if unassigned).
• Amount & Currency: The exact requested value.
• Date & Status: When it was submitted and its current workflow state.
• SLA Progress: A visual progress bar showing how much time remains before an auto-action (like an auto-reject or escalation) occurs, turning red as the deadline approaches.

Searching and Filtering Expenses

If you have a large number of pending requests, use the collapsible toolbar at the top of the queue:

Control	Purpose	Example
Search	Instantly find expenses by the applicant's name.	Type "Priya" to see only her submissions.
Group By	Visually clusters the queue into categories.	Group by "Project" to review all "Q4 Marketing" expenses together.
Category Filter	Narrows the list down to a specific expense type.	Show only "Travel" expenses.
Tabs	Toggles between queues.	Switch from "Pending My Approval" to "My Pending Claims" to see where your own submissions are stuck.

Understanding an Expense (Detail View)

When you select an expense from the queue, the right panel loads the full context needed to make a decision.

Expense Details Explained

You should verify the following fields:

• Submitter Information: The employee claiming the expense.
• Amount & Currency: The total value. Ensure the currency matches expectations, especially for international travel.
• Expense Category: Ensure the correct category was chosen, as this dictates which budget head is consumed.
• Project: If applicable, verify that the expense genuinely belongs to the assigned project.
• Business Purpose (Notes): A text description explaining why the expense was necessary.
• Current Status: e.g., PENDING_APPROVAL.

Receipts and Attachments

A dedicated viewer occupies the left half of the detail screen.

• Image Previews: If the receipt is an image (JPG, PNG), you can use the built-in zoom controls (+, -, or mouse scroll) and pan around the image without leaving the page.
• PDF Previews: Supported documents render directly in the viewer.
• Missing Receipts: If the category requires a receipt but none is attached, you should likely reject the expense.

AI Receipt Analysis

Optima Orbit utilizes AI to automatically extract data from uploaded receipts. As an approver, this helps you catch discrepancies instantly.

If AI analysis is available for the expense, you can click the AI Analysis button to view a comparison modal.

[!TIP] Discrepancy Detection: The system will automatically warn you if the user's manual entry (e.g., amount, date, or merchant) differs from what the AI detected on the physical receipt. For example, if the employee typed "$50" but the receipt clearly shows "$45", a warning will appear.

Approving an Expense

Once you have verified the details and the receipt, you can process the expense.

1. Select the expense from the left queue.
2. Review the data and receipt in the right panel.
3. Check for any AI discrepancies.
4. Click the Approve button.
5. Add a Comment (Mandatory): You must enter a comment explaining your decision (e.g., "Approved, receipt verified").
6. Confirm the action.

Rejecting an Expense

If the expense violates policy, lacks a receipt, or is categorized incorrectly, you must reject it.

1. Select the expense.
2. Click the Reject button (or "Return" if configured in your workflow).
3. Add a Reason (Mandatory): You must explain exactly why it is being rejected so the employee knows how to fix it (e.g., "Please attach the correct hotel receipt, this is just a taxi bill").
4. Confirm the action.

The expense will immediately disappear from your pending queue and return to the submitter's view.

What Happens After a Decision?

Downstream Effects of Approval

1. Status Change: The expense status updates to APPROVED (or moves to the next approver if multi-level approval is active).
2. Financial Queue: Fully approved expenses move into the Payment Eligible queue (/org/expenses/payment-eligible).
3. Analytics: The expense value now contributes to the "Approved Amount" KPIs in the Expense Analytics dashboards.
4. Notifications: The submitter receives an automated notification (via Email or WhatsApp, depending on Org settings).

[!WARNING] Approval Does Not Mean Paid! Approving an expense merely confirms that it is valid. It does not initiate a bank transfer. Finance teams manage actual reimbursements through the Payment Eligible queue.

Downstream Effects of Rejection

1. Status Change: The status updates to REJECTED or RETURNED.
2. Notifications: The submitter is notified along with your mandatory rejection reason.
3. Resubmission: Depending on the specific workflow configuration, the employee may edit their original claim to fix the issue and resubmit it, starting the approval cycle over.

Workflow and Timelines

The top right corner of the page features a Workflow Timeline.

This timeline visualizes the exact journey of the specific expense you are viewing. It shows:

• When it was submitted.
• Who approved it previously (if it requires multiple approvals).
• Where it currently sits (e.g., waiting on you).
• Any comments left by previous approvers.

Why Is This Expense Assigned to Me?

Expenses appear in your queue based on Approval Workflows configured by your administrator. You might see an expense because:

• You are the direct manager of the person who submitted it (Reporting Hierarchy).
• You are the Project Manager for the specific project the expense is billed against.
• You belong to a specific Persona (e.g., "Finance Team") assigned to Step 2 of the workflow.

Troubleshooting

Problem	Possible Reason	What to Do
I can't see the Expense Approvals menu.	You lack the org.expense.approve permission.	Ask your Org Owner to map this permission to your Role.
An employee says they submitted an expense, but my queue is empty.	The workflow routes it to someone else (e.g., a Project Manager instead of you).	Check the Workflow configuration or ask the employee to view their submission timeline.
The "Approve" button gives an error.	You didn't write a comment.	Comments are strictly mandatory for all actions.
SLA is showing "Breached".	The expense sat in your queue longer than the allowed limit.	Process it immediately. Note that depending on rules, it may soon auto-approve or auto-reject.

Technical Reference

For administrators and QA personnel, here are the technical implementation details for this module:

• Route: /org/expense-approvals
• Component: src/routes/org/ExpenseApprovalsPage.tsx
• Required Permission: org.expense.approve
• Core Services: approvalService.ts, expenseService.ts
• API Flow:
  • GET /org/approvals/pending (Fetches queue, filtered frontend by EXPENSE module codes)
  • GET /org/expenses/{id} (Fetches detail record)
  • GET /org/approvals/{id}/timeline (Fetches visual workflow steps)
  • POST /org/approvals/{id}/process (Submits {action, comments})
• Data Models: Expense, ApprovalInstance, StepTransition (src/types/expense.ts, src/types/approval.ts)
• Simulation: A "Verify Mode" allows testing complex workflow transitions (POST /org/approvals/{id}/simulate) without committing state.

Related Features

• My Expenses
• Expense Analytics (coming soon)
• User Role Mapping

Claims waiting on your decision, with their amounts.