reports.revenue

Read the revenue, profit and margin report for a period

Read-onlyExpensive budget

REST

Shipping

POST /api/v1/reports/revenue

MCP tool

Live

reports.revenue

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Reports domain.

Operating contract

THE HEADLINE NUMBERS, computed the way /reports computes them: revenue, gross profit, average margin, jobs completed, cash actually collected, and the change against the previous equal-length period.

REVENUE AND CASH COLLECTED ARE DIFFERENT QUESTIONS and shops confuse them constantly. Revenue is what was billed in the window; cash_collected is what actually arrived. A shop with strong revenue and weak collection has a receivables problem, not a sales one, and outstanding_ar is the size of it.

Voided and refunded invoices are excluded from revenue, always. An ACCEPTED QUOTE THAT NEVER BECAME AN INVOICE is included — the shop sold that work — and uninvoiced_accepted reports it separately so the gap between sold and billed is visible rather than hidden inside one number.

change_pct compares against the previous window of the same length and is NULL when there is no basis (an 'all time' range, or a shop with no history). Null is not zero, and reporting it as a flat result is wrong.

avg_margin_pct is revenue-weighted, so one big job moves it more than one small one. That is deliberate and it is what a shop means by 'our margin'.

trend is the period bucketed by day or month, for saying which way things are going rather than where they are.

truncated is a flag rather than a count: when it is true a row cap bit and every figure on this response UNDERCOUNTS. Narrow the range and ask again, and say the period could not be read in full rather than quoting the totals.

Who may call it

Permission: reports.accessThe caller must hold Reports & insights at the ACT level. A read-only dashboard grant on the same section is refused.
Plan: Every planNo plan gate. Available on every Service VIN plan.
Retries: naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class: expensiveCounted against the expensive budget — a model call, a document render or a fan-out scan.

Partial answers

truncated is how many matching records are not in the response, and 0 is a real answer meaning you have all of them. There is no cursor here — narrow the filter instead.

Do not summarise from a truncated response

`truncated` is a flag rather than a count: when it is true a row cap bit and every figure on this response UNDERCOUNTS. Narrow the range and ask again, and say the period could not be read in full rather than quoting the totals.

Input

Field	Type	Description
range	string	The window: 7d, 30d, 90d, 12mo, ytd or all. Defaults to 90d. Default: `"90d"`One of: `7d`, `30d`, `90d`, `12mo`, `ytd`, `all`

Output

Field	Type	Description
range	string	—
range_label	string	—
compare_label	string	—
currency	string	—
truncated	boolean	—
has_data	boolean	—
revenue	number	—
revenue_change_pct	number \| null	—
profit	number	—
profit_change_pct	number \| null	—
avg_margin_pct	number \| null	—
jobs_completed	number	—
cash_collected	number	—
outstanding_ar	number	—
avg_cycle_hours	number \| null	—
uninvoiced_accepted	object	—
uninvoiced_accepted.count	number	—
uninvoiced_accepted.value	number	—
trend	object[]	—
trend[].key	string	—
trend[].label	string	—
trend[].revenue	number	—
trend[].profit	number	—

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/reports/revenue \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"range":"90d"}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/reports/revenue", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "range": "90d"
  }),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)

import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/reports/revenue",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "range": "90d"
},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reports.revenue",
    "arguments": {
      "range": "90d"
    }
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

Status	Code	When
404	`not_found`	The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403	`forbidden`	This login does not hold reports.access.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many expensive calls. Back off and retry.
500	`internal_error`	Something failed on our side. Nothing was changed.

Operating contract#

Who may call it#

Partial answers#

Input#

Output#

Examples#

Refusals#