reports.marketing

Read the report of what each lead source cost and returned

Read-onlyExpensive budget

REST

Shipping

POST /api/v1/reports/marketing

MCP tool

Live

reports.marketing

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

Operating contract

What each channel brought in over the window, and — where the shop recorded spend against it — what that cost per lead and per booked job.

THIS IS THE HONEST SIDE OF AD REPORTING. marketing.ad_spend reports what the ad platform says it delivered; this reports what actually ARRIVED as a lead here. When those two disagree, this one is measuring the shop's business and the other is measuring the platform's attribution.

cost_per_lead and roas are null wherever the shop recorded no spend for that channel. Null means 'we do not know what this cost', not 'it was free', and reporting an unattributed channel as infinitely efficient is the classic version of this mistake.

The unknown source is leads that recorded no attribution at all. It is usually the largest row and it is the most useful finding on the report: it is the share of the pipeline nobody can credit, and it is what makes every cost-per-lead figure above an approximation.

Spend is what somebody TYPED IN as having been paid. Nothing here verifies it against a bank or an ad account.

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	—
currency	string	—
truncated	boolean	—
total_spend	number	—
has_recorded_spend	boolean	—
sources	object[]	—
sources[].key	string	—
sources[].label	string	—
sources[].leads	number	—
sources[].booked	number	—
sources[].revenue	number	—
sources[].spend	number \| null	—
sources[].cost_per_lead	number \| null	—
sources[].cost_per_booked	number \| null	—
sources[].roas	number \| null	—
sources[].unattributed	boolean	—

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/marketing \
  -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/marketing", {
  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/marketing",
    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.marketing",
    "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#