GET /api/finance/profitability — Profit by Department

The /api/finance/profitability endpoint returns a per-department breakdown of income, expense, net profit, and profit margin for a given date range. It is the right choice for questions about which departments drive revenue, how much each department contributes to net profit, and where margins are strongest or weakest. Results are sorted most-profitable-first by net income, so the top revenue-generating departments appear at the top of the list. Use departments to narrow the response to a subset of departments when you only need to compare a few cost centers or revenue units side by side.

Request

string

required

Start of the date range in YYYY-MM-DD format. Inclusive — transactions on this exact date are included.

string

required

End of the date range in YYYY-MM-DD format. Inclusive — transactions on this exact date are included.

string

Optional comma-separated list of department names to include in the response (e.g. Sales,Engineering). Whitespace around commas is trimmed automatically. When omitted, all departments are returned.

Response

The response is an array of ProfitByDept objects, one per department, sorted by net descending — the most profitable department appears first.

string

The department name (e.g. Sales, Engineering, Marketing).

number

Total income recorded by this department in the date range.

number

Total expense recorded by this department in the date range.

number

Net profit for this department, calculated as income - expense. A negative value indicates the department spent more than it earned — expected for cost-center departments.

number | null

Net profit margin, calculated as net / income. Returns null for departments with zero income (cost centers). A value of 0.741 means 74.1% of revenue was retained as profit after expenses.

Cost-center departments — Marketing, Operations, and Finance — book no revenue in the seeded dataset, so their margin is always null. This is correct and expected behavior: dividing by zero income is undefined, and returning null clearly distinguishes “no revenue” from a 0% margin (which would imply break-even). The chart UI displays null margin as “n/a” rather than 0%.

Examples

Profitability for all departments

curl "http://localhost:3000/api/finance/profitability?from=2025-01-01&to=2025-12-31"

[
  { "department": "Sales", "income": 850000, "expense": 220000, "net": 630000, "margin": 0.741 },
  { "department": "Engineering", "income": 400000, "expense": 310000, "net": 90000, "margin": 0.225 },
  { "department": "Marketing", "income": 0, "expense": 180000, "net": -180000, "margin": null },
  { "department": "Operations", "income": 0, "expense": 140000, "net": -140000, "margin": null },
  { "department": "Finance", "income": 0, "expense": 95000, "net": -95000, "margin": null }
]

Filter to revenue-generating departments only

curl "http://localhost:3000/api/finance/profitability?from=2025-01-01&to=2025-12-31&departments=Sales,Engineering"

[
  { "department": "Sales", "income": 850000, "expense": 220000, "net": 630000, "margin": 0.741 },
  { "department": "Engineering", "income": 400000, "expense": 310000, "net": 90000, "margin": 0.225 }
]

Error Response

If either from or to is missing, the endpoint returns a 400 Bad Request:

{
  "error": {
    "formErrors": [],
    "fieldErrors": {
      "from": ["Required"],
      "to": ["Required"]
    }
  }
}

​Request

​Response

​Examples

​Profitability for all departments

​Filter to revenue-generating departments only

​Error Response

Request

Response

Examples

Profitability for all departments

Filter to revenue-generating departments only

Error Response