Get Revenue Analytics (v1)

Method & Path

GET /api/v1/client/workspace/:workspaceId/financial/analytics

Description

Get revenue analytics with detailed breakdown of revenue, expenses, and net profit for the specified period.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with financial permissions.

Headers

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

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
period	string	No	Time period (daily, weekly, monthly, yearly, custom). Default: monthly
startDate	string	No	Start date for custom period (YYYY-MM-DD format). Required when period is custom
endDate	string	No	End date for custom period (YYYY-MM-DD format). Required when period is custom

Response 200 OK

{
  "period": "monthly",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "dataPoints": [
    {
      "date": "2025-01-01",
      "revenue": 2000.00,
      "expenses": 500.00,
      "net": 1500.00
    },
    {
      "date": "2025-01-08",
      "revenue": 2500.00,
      "expenses": 800.00,
      "net": 1700.00
    },
    {
      "date": "2025-01-15",
      "revenue": 2000.00,
      "expenses": 600.00,
      "net": 1400.00
    },
    {
      "date": "2025-01-22",
      "revenue": 2000.00,
      "expenses": 700.00,
      "net": 1300.00
    },
    {
      "date": "2025-01-29",
      "revenue": 1500.00,
      "expenses": 400.00,
      "net": 1100.00
    }
  ],
  "totals": {
    "revenue": 10000.00,
    "expenses": 3000.00,
    "net": 7000.00
  }
}

Response Fields

• period (string): The time period used for the analytics
• startDate (string): Start date of the period (YYYY-MM-DD format)
• endDate (string): End date of the period (YYYY-MM-DD format)
• dataPoints (array): Array of data points with revenue, expenses, and net profit
  • date (string): Date in YYYY-MM-DD format
  • revenue (number): Revenue amount for that date
  • expenses (number): Expense amount for that date
  • net (number): Net profit (revenue - expenses) for that date
• totals (object): Total amounts for the entire period
  • revenue (number): Total revenue
  • expenses (number): Total expenses
  • net (number): Total net profit

Common Errors

400 Bad Request:

• Invalid workspace ID format
• Invalid period value
• Missing startDate or endDate when period is custom
• Invalid date format (must be YYYY-MM-DD)
• startDate is after endDate

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have permission to view financial analytics

404 Not Found: Workspace not found

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

Notes

• Date calculations use the workspace's configured timezone
• Data points are aggregated based on the selected period:
  • daily: One data point per day
  • weekly: One data point per week (starting from Sunday)
  • monthly: One data point per month
  • yearly: One data point per year
  • custom: Data points based on the date range
• Net profit is calculated as revenue minus expenses for each data point
• Totals represent the sum across all data points in the period
• Workspace subscription status is checked before processing the request