Profitability API

All endpoints require authentication and reporting view permission. Cost rates are derived from the Productive integration’s budget report (org-wide average cost per hour).

Profitability Summary

GET /api/profitability

Returns profitability data broken down by project and aggregated by client.

Query parameters:

Param	Type	Description
`date_from`	string	Start date (YYYY-MM-DD, default: first day of current month)
`date_to`	string	End date (YYYY-MM-DD, default: last day of current month)
`squad`	string	Filter by squad name
`client_id`	string	Filter by client company ID

Response:

{
  "summary": {
    "total_revenue",
    "total_cost",
    "gross_margin",
    "margin_percent",
    "avg_cost_per_hour"
  },
  "projects": [...],
  "clients": [...],
  "date_from",
  "date_to"
}

Revenue is calculated from invoices with status sent or paid, linked via budgets to projects. Cost is calculated as approved time entry hours multiplied by the org-wide average cost per hour from Productive.

Each project includes:

Field	Type	Description
`project_id`	string	Project ID
`project_name`	string	Project name
`client_id`	string	Company ID
`client_name`	string	Company name
`squad`	string	Squad name
`revenue`	number	Total invoiced revenue
`cost`	number	Estimated cost (hours x avg rate)
`gross_margin`	number	Revenue minus cost
`margin_percent`	number	Margin as percentage of revenue
`has_incomplete_data`	boolean	True if revenue or hours are zero

Each client aggregate includes client_id, client_name, revenue, cost, gross_margin, and margin_percent.

Profitability Trend

GET /api/profitability/trend

Returns a 12-month rolling trend of monthly revenue, cost, and margin.

Query parameters:

Param	Type	Description
`squad`	string	Filter by squad name
`client_id`	string	Filter by client company ID

Response: { months }

Each month includes:

Field	Type	Description
`month`	string	Period key (YYYY-MM)
`label`	string	Human-readable label (e.g. “Apr 26”)
`revenue`	number	Monthly revenue
`cost`	number	Monthly cost
`gross_margin`	number	Revenue minus cost
`margin_percent`	number	Margin percentage