Skip to content
Hoursmith Docs
APIReferenceReports

Revenue report

Revenue report. Invoiced, paid, outstanding and draft revenue per currency with a monthly series. Months and from/to use the invoice ISSUE date: paid is attributed to the issue month, not the payment date (use /reports/cash-flow for cash basis). Invoices replaced by a correction are excluded from invoiced totals. Owner, Admin or Manager only: a Member token gets 403. Plan: Studio or Agency (reports); otherwise 402. Read-only; requires a token with read scope. Unknown or repeated (non-list) query parameters, impossible dates and inverted ranges return 422 with `fields`. Money is an exact decimal string paired with its currency; amounts in different currencies are never added together and nothing is converted. Responses are private (Cache-Control: private, no-store; Vary: Authorization).

GET
/reports/revenue

Authorization

BearerAuth
AuthorizationBearer <token>

Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.

In: header

Query Parameters

from?string

Inclusive start (invoice issue date), YYYY-MM-DD.

to?string

Inclusive end (invoice issue date), YYYY-MM-DD. Must not be before from (422).

clientId?array<>

Filter by client. Repeat the parameter for several (max 25). Unknown ids return 404.

currency?string

Only invoices in this currency.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/reports/revenue"
{  "data": {    "range": {      "from": "2019-08-24",      "to": "2019-08-24"    },    "basis": "issue_date",    "defaultCurrency": "str",    "filters": {      "clientIds": [        "c055e856-96a7-4f69-80a6-b75690833d98"      ],      "currency": "string"    },    "currencies": [      {        "currency": "str",        "invoiced": "string",        "paid": "string",        "outstanding": "string",        "draft": "string",        "invoiceCount": 0,        "cancelledCount": 0,        "months": [          {            "month": "string",            "invoiced": "string",            "paid": "string"          }        ]      }    ]  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
Was this page helpful?

Project budget and financials

Budget consumption and billing status for one project. Every role that can see the project gets tracked time and the hours budget; Owner/Admin/Manager responses add the amount budget and unbilled/billed/fixed-fee amounts in the client currency (omitted for Members). For HOURLY projects, unbilledHours and unbilledAmount are billable, uninvoiced, stopped time (a running timer is left out), each entry rounded up to the quarter hour; billedAmount is SENT and PAID invoice lines in the project's current currency (lines billed in another currency are listed in billedOtherCurrencies, never added); the amount budget's used also counts DRAFT invoice lines. Archived projects are included. No plan beyond API access. Read-only; requires a token with read scope. Unknown or repeated (non-list) query parameters, impossible dates and inverted ranges return 422 with `fields`. Money is an exact decimal string paired with its currency; amounts in different currencies are never added together and nothing is converted. Responses are private (Cache-Control: private, no-store; Vary: Authorization).

Project profitability

Per-project hours and value: tracked, uninvoiced and invoiced value in the client currency, plus fixed-fee value and remaining balance (CURRENT balances, not date-filtered). Archived projects, and projects of archived clients, are listed while they have time in range or are named by projectId or clientId. members (per-person billability) is returned only on the Agency plan (advancedReporting); otherwise a warning says it was omitted. Members see only their own hours on projects they belong to and no money; a userId other than their own is a 404. Any role. Plan: Studio or Agency (reports); otherwise 402. Read-only; requires a token with read scope. Unknown or repeated (non-list) query parameters, impossible dates and inverted ranges return 422 with `fields`. Money is an exact decimal string paired with its currency; amounts in different currencies are never added together and nothing is converted. Responses are private (Cache-Control: private, no-store; Vary: Authorization).