Skip to main content

Get Expense Statistics (v1)

Method & Path​

GET /api/v1/admin/expenses/stats

Description​

Retrieve expense statistics including totals for today, this week, this month, and all time, as well as breakdown by category.

Authentication​

Required: Admin authentication with dashboard.view permission.

Headers​

Authorization: Bearer <admin_token>
Content-Type: application/json

Query Parameters​

ParameterTypeRequiredDescription
startDatedateNoStart date for custom date range filter (ISO 8601 format)
endDatedateNoEnd date for custom date range filter (ISO 8601 format)

Response 200 OK​

{
  "today": {
    "amount": 500.00,
    "count": 3
  },
  "thisWeek": {
    "amount": 2500.00,
    "count": 12
  },
  "thisMonth": {
    "amount": 10000.00,
    "count": 45
  },
  "total": {
    "amount": 150000.00,
    "count": 650
  },
  "byCategory": {
    "services": 5000.00,
    "salaries": 80000.00,
    "rent": 18000.00,
    "utilities": 2500.00,
    "marketing": 15000.00,
    "other": 29500.00
  }
}

Response Fields​

Period Statistics​

Each period (today, thisWeek, thisMonth, total) contains:

  • amount (number): Total expense amount in USD for the period
  • count (number): Total number of expenses in the period

byCategory​

Breakdown of total expenses by category:

  • services (number): Total expenses in the "services" category
  • salaries (number): Total expenses in the "salaries" category
  • rent (number): Total expenses in the "rent" category
  • utilities (number): Total expenses in the "utilities" category
  • marketing (number): Total expenses in the "marketing" category
  • other (number): Total expenses in the "other" category

Common Errors​

400 Bad Request: Invalid date format in query parameters

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Admin does not have dashboard.view permission

500 Internal Server Error: Server error occurred while processing the request

Notes​

  • Period calculations use UTC timezone
  • today includes expenses from the start of the current day (00:00:00 UTC)
  • thisWeek includes expenses from the start of the current week (Sunday 00:00:00 UTC)
  • thisMonth includes expenses from the start of the current month (1st day 00:00:00 UTC)
  • total includes all expenses in the system (or within the date range if provided)
  • If startDate or endDate is provided, all statistics will be calculated only for expenses within that date range