> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartbills.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Expense Reports

> Complete reference for expense report management in the Smartbills Python SDK, create, submit, approve, reject, reimburse, and export reports.

## Expense Reports

The expense reports API in Python spans three services:

* **`client.expense_reports`**: core report lifecycle (create, submit, approve, reject, reimburse)
* **`client.expense_report_expenses`**: manage expenses within a report
* **`client.expense_report_payments`**: reimbursement and payment operations

All methods are async and must be called with `await`.

## ExpenseReportService

### Listing reports

```python theme={null}
# List all reports for the business
result = await client.expense_reports.list()
for report in result.data:
    print(f"{report.id}: {report.name} ({report.status})")

# With filters
from smartbills.models.expense_reports import ExpenseReportListRequest
result = await client.expense_reports.list(
    ExpenseReportListRequest(page=1, limit=20)
)

# List for a specific employee
result = await client.expense_reports.list_for_employee(employee_id=42)

# List reports for a specific employee by ID
report = await client.expense_reports.get_by_id_for_employee(
    employee_id=42,
    report_id=100,
    params={"sortBy": "amount", "sortOrder": "desc"},
)

# Get current user's reports
my_reports = await client.expense_reports.get_mine(params={"status": "draft"})

# Get reports pending your approval
pending = await client.expense_reports.get_pending_approvals()
```

### Getting a single report

```python theme={null}
report = await client.expense_reports.get_by_id(report_id=123)
print(report.name, report.status)
```

### Creating a report

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportCreateRequest

report = await client.expense_reports.create(
    ExpenseReportCreateRequest(
        name="Q1 Travel Expenses",
        description="Business travel January-March",
    )
)
```

### Updating a report

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportUpdateRequest

updated = await client.expense_reports.update(
    report_id=123,
    request=ExpenseReportUpdateRequest(
        name="Q1 Travel Expenses (Updated)",
    ),
)
```

### Deleting a report

```python theme={null}
await client.expense_reports.delete(report_id=123)
```

## Report lifecycle

Reports follow a workflow: **Draft** -> **Submitted** -> **Approved** -> **Reimbursed**.

### Submit for approval

```python theme={null}
submitted = await client.expense_reports.submit(report_id=123)
print(submitted.status)  # 'submitted'
```

### Approve

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportApproveRequest

approved = await client.expense_reports.approve(
    report_id=123,
    request=ExpenseReportApproveRequest(comment="Looks good."),
)
```

### Reject

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportRejectRequest

rejected = await client.expense_reports.reject(
    report_id=123,
    request=ExpenseReportRejectRequest(reason="Missing receipts."),
)
```

### Request changes

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportRequestChangesRequest

returned = await client.expense_reports.request_changes(
    report_id=123,
    request=ExpenseReportRequestChangesRequest(
        comment="Please attach the conference receipt."
    ),
)
```

### Recall a submitted report

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportRecallRequest

recalled = await client.expense_reports.recall(
    report_id=123,
    request=ExpenseReportRecallRequest(reason="Need to add more expenses."),
)
```

### Reimburse

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportReimburseRequest

reimbursed = await client.expense_reports.reimburse(
    report_id=123,
    request=ExpenseReportReimburseRequest(payment_method="bank_transfer"),
)
```

### Plan reimbursement

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportPlanReimbursementRequest

planned = await client.expense_reports.plan_reimbursement(
    report_id=123,
    request=ExpenseReportPlanReimbursementRequest(
        scheduled_date="2025-04-15",
        payment_method="bank_transfer",
    ),
)
```

## Comments and audit trail

### Get comments

```python theme={null}
comments = await client.expense_reports.get_comments(report_id=123)
for comment in comments:
    print(f"{comment.author}: {comment.content}")
```

### Add a comment

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportCommentCreateRequest

comment = await client.expense_reports.add_comment(
    report_id=123,
    request=ExpenseReportCommentCreateRequest(
        content="Please review the hotel charges."
    ),
)
```

### Get timeline

```python theme={null}
timeline = await client.expense_reports.get_timeline(report_id=123)
for entry in timeline:
    print(f"{entry.type}: {entry.description}")
```

### Get audit log

```python theme={null}
audit_log = await client.expense_reports.get_audit_log(report_id=123)
for entry in audit_log:
    print(f"{entry.action} by user {entry.user_id} at {entry.timestamp}")
```

## Ledger account assignment

```python theme={null}
from smartbills.models.expense_reports import ExpenseReportAssignLedgerAccountRequest

# Report-level
await client.expense_reports.assign_ledger_account(
    report_id=123,
    request=ExpenseReportAssignLedgerAccountRequest(ledger_account_id=500),
)

# Per-expense within a report
await client.expense_reports.assign_expense_ledger_account(
    report_id=123,
    expense_id=456,
    request=ExpenseReportAssignLedgerAccountRequest(ledger_account_id=501),
)
```

## Summary and export

```python theme={null}
# Get summary statistics
summary = await client.expense_reports.get_summary()

# Export reports
from smartbills.models.expense_reports import ExpenseReportExportRequest

data = await client.expense_reports.export(
    ExpenseReportExportRequest(format="xlsx")
)
with open("reports.xlsx", "wb") as f:
    f.write(data)
```

## Managing expenses within reports

```python theme={null}
from smartbills.models.expense_reports import (
    AddExpenseToReportRequest,
    AddExpensesToReportBatchRequest,
    EditExpenseInReportRequest,
)

# Add an expense
await client.expense_reports.add_expense(
    report_id=123,
    request=AddExpenseToReportRequest(expense_id=456),
)

# Add multiple expenses
await client.expense_reports.add_expenses_batch(
    report_id=123,
    request=AddExpensesToReportBatchRequest(expense_ids=[456, 457, 458]),
)

# Edit an expense within the report
await client.expense_reports.edit_expense(
    report_id=123,
    expense_id=456,
    request=EditExpenseInReportRequest(category_id=15),
)

# Remove an expense
await client.expense_reports.remove_expense(report_id=123, expense_id=456)
```

## Bulk operations

```python theme={null}
from smartbills.models.expense_reports import (
    BulkDeleteExpenseReportsRequest,
    BulkSubmitExpenseReportsRequest,
    BulkRecallExpenseReportsRequest,
    BulkAssignReportCategoryRequest,
    BulkRemoveReportExpensesRequest,
)

# Bulk delete
await client.expense_reports.bulk_delete(
    BulkDeleteExpenseReportsRequest(report_ids=[1, 2, 3])
)

# Bulk submit
await client.expense_reports.bulk_submit(
    BulkSubmitExpenseReportsRequest(report_ids=[4, 5, 6])
)

# Bulk recall
await client.expense_reports.bulk_recall(
    BulkRecallExpenseReportsRequest(report_ids=[7, 8])
)

# Bulk approve
from smartbills.models.expense_reports import BulkApproveApprobationsRequest
await client.expense_reports.bulk_approve(
    BulkApproveApprobationsRequest(report_ids=[9, 10])
)

# Bulk reject
from smartbills.models.expense_reports import BulkRejectApprobationsRequest
await client.expense_reports.bulk_reject(
    BulkRejectApprobationsRequest(report_ids=[11, 12])
)

# Bulk assign category to expenses in a report
await client.expense_reports.bulk_assign_category(
    report_id=123,
    request=BulkAssignReportCategoryRequest(
        expense_ids=[1, 2, 3],
        category_id=20,
    ),
)

# Bulk remove expenses from a report
await client.expense_reports.bulk_remove_expenses(
    report_id=123,
    request=BulkRemoveReportExpensesRequest(expense_ids=[10, 11]),
)
```

***

## ExpenseReportExpenseService

The `client.expense_report_expenses` service provides dedicated methods for managing expenses within reports.

```python theme={null}
from smartbills.models.expense_reports import AddExpenseToReportRequest

# Add expense
await client.expense_report_expenses.add(
    report_id=123,
    request=AddExpenseToReportRequest(expense_id=456),
)

# Remove expense
await client.expense_report_expenses.remove(report_id=123, expense_id=456)
```

***

## ExpenseReportPaymentService

The `client.expense_report_payments` service handles reimbursement payments.

```python theme={null}
from smartbills.models.expense_reports import (
    ExpenseReportReimburseRequest,
    ExpenseReportPlanReimbursementRequest,
)

# Full reimbursement
await client.expense_report_payments.reimburse(report_id=123)

# Partial reimbursement
await client.expense_report_payments.partial_reimburse(
    report_id=123,
    request={"amount": 150.00},
)

# Plan future reimbursement
await client.expense_report_payments.plan_reimbursement(
    report_id=123,
    request=ExpenseReportPlanReimbursementRequest(
        scheduled_date="2025-05-01",
    ),
)
```