Documentation
Reports
reports.tax
REST
ShippingPOST /api/v1/reports/taxMCP tool
Livereports.taxExposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Reports domain.
Operating contract
Sales and tax by month over the window, with the totals a shop takes to a remittance.
THIS IS NOT TAX ADVICE AND IT IS NOT A FILED RETURN. It is what this shop's own invoices recorded. A shop remitting from it is responsible for the numbers, and anything unusual on it belongs in front of their accountant rather than being explained away.
basis MATTERS AND THE TWO DISAGREE. accrual counts tax on invoices raised in the period; cash counts it on payments received. A shop that bills in March and gets paid in April has that tax in a different month under each, and using the wrong one produces a remittance that is wrong by exactly the timing difference.
drift IS THE FINDING. Those are invoices whose recorded tax does not match the shop's configured rate — usually a rate that changed, or a line somebody overrode. drift_variance is the total size of the disagreement, and it is the number that makes an accountant's afternoon.
tax_refunded and sales_refunded are reversals recorded in that month, and they are reported separately rather than netted, because a remittance form asks for them separately.
excluded counts voided and draft invoices left out entirely, which is what a shop expects and is stated so nobody has to wonder.
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
Input
| Field | Type | Description |
|---|---|---|
| range | string | The window: 7d, 30d, 90d, 12mo, ytd or all. Defaults to 12mo. Default:"12mo"One of: 7d, 30d, 90d, 12mo, ytd, all |
| basis | string | accrual counts tax on invoices raised; cash counts it on payments received. They disagree by the timing. Default:"accrual"One of: accrual, cash |
Output
| Field | Type | Description |
|---|---|---|
| range | string | — |
| basis | string | — |
| currency | string | — |
| configured_rate_pct | number | — |
| truncated | boolean | — |
| has_data | boolean | — |
| totals | object | — |
| totals.taxable_sales | number | — |
| totals.exempt_sales | number | — |
| totals.net_sales | number | — |
| totals.tax_collected | number | — |
| totals.tax_refunded | number | — |
| totals.sales_refunded | number | — |
| totals.entries | number | — |
| months | object[] | — |
| months[].key | string | — |
| months[].label | string | — |
| months[].taxable_sales | number | — |
| months[].exempt_sales | number | — |
| months[].net_sales | number | — |
| months[].tax_collected | number | — |
| months[].tax_refunded | number | — |
| drift_count | number | — |
| drift_variance | number | — |
| excluded | object | — |
| excluded.voided | number | — |
| excluded.draft | 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.
export SERVICEVIN_API_KEY=svk_live_…
curl -X POST https://www.servicevin.com/api/v1/reports/tax \
-H "Authorization: Bearer $SERVICEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"range":"12mo","basis":"accrual"}'const res = await fetch("https://www.servicevin.com/api/v1/reports/tax", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"range": "12mo",
"basis": "accrual"
}),
});
// 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;import os, requests
res = requests.post(
"https://www.servicevin.com/api/v1/reports/tax",
headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
json={
"range": "12mo",
"basis": "accrual"
},
timeout=30,
)
payload = res.json()
if not res.ok:
raise RuntimeError(payload["error"]["code"])
data = payload["data"]{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "reports.tax",
"arguments": {
"range": "12mo",
"basis": "accrual"
}
}
}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. |