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 reportclient.expense_report_payments: reimbursement and payment operations
await.
ExpenseReportService
Listing reports
# 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
report = await client.expense_reports.get_by_id(report_id=123)
print(report.name, report.status)
Creating a report
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
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
await client.expense_reports.delete(report_id=123)
Report lifecycle
Reports follow a workflow: Draft -> Submitted -> Approved -> Reimbursed.Submit for approval
submitted = await client.expense_reports.submit(report_id=123)
print(submitted.status) # 'submitted'
Approve
from smartbills.models.expense_reports import ExpenseReportApproveRequest
approved = await client.expense_reports.approve(
report_id=123,
request=ExpenseReportApproveRequest(comment="Looks good."),
)
Reject
from smartbills.models.expense_reports import ExpenseReportRejectRequest
rejected = await client.expense_reports.reject(
report_id=123,
request=ExpenseReportRejectRequest(reason="Missing receipts."),
)
Request changes
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
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
from smartbills.models.expense_reports import ExpenseReportReimburseRequest
reimbursed = await client.expense_reports.reimburse(
report_id=123,
request=ExpenseReportReimburseRequest(payment_method="bank_transfer"),
)
Plan reimbursement
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
comments = await client.expense_reports.get_comments(report_id=123)
for comment in comments:
print(f"{comment.author}: {comment.content}")
Add a comment
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
timeline = await client.expense_reports.get_timeline(report_id=123)
for entry in timeline:
print(f"{entry.type}: {entry.description}")
Get audit log
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
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
# 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
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
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
Theclient.expense_report_expenses service provides dedicated methods for managing expenses within reports.
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
Theclient.expense_report_payments service handles reimbursement payments.
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",
),
)