invoices.recovery

List the customer accounts holding an unpaid invoice balance

Read-onlyRead budget

REST

Shipping

POST /api/v1/invoices/recovery

MCP tool

Live

invoices.recovery

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

Operating contract

EVERY OPEN BALANCE GROUPED INTO THE ACCOUNTS YOU WOULD ACTUALLY PHONE, worst first. invoices.aging is the total; invoices.list is the bills; this is the worklist — one row per customer, with everything they owe, how far past due the worst of it is, and whether there is any way to reach them at all.

reachable: false MEANS DO NOT PLAN A TEXT. It is a customer with no email and either no phone or one that has opted out of messaging. Chasing them is a phone call or a letter, and pretending otherwise wastes the shop's afternoon.

chaser_touched is how many of their invoices the Invoice Chaser has already texted about. A person about to chase an account that an automation nudged this morning is about to be the second message today.

MIGRATED INVOICES ARE THE POINT OF THIS SCREEN. A shop that switched from another system arrives holding a book of receivables the old software was chasing; imported_count is how many of theirs came across, and recovered is what has actually been collected against migrated invoices since the switch.

held IS THE HONEST FOOTNOTE. Some imported invoices arrive with a paid figure nothing can vouch for — chasing somebody for money they already paid is worse than not chasing them — so those are held OUT of the worklist by default and counted separately. include_unverified: true folds them in, and then every figure carries that caveat.

truncated: true means a read hit its ceiling and the totals are a floor rather than a total. Say 'at least' when it is set.

TRUNCATION: at most limit accounts come back, biggest balance first, and omitted is how many more have an open balance.

Who may call it

Permission: invoices.accessThe caller must hold Invoices 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: readCounted against the read budget — the widest of the four.

Partial answers

omitted 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

When `omitted` is not 0 there are more accounts with an open balance than were returned. Raise `limit`; the totals above already count every one of them.

Input

Field	Type	Description
include_unverified	boolean	True folds in imported invoices whose paid figure cannot be vouched for. Every figure then carries that caveat.
limit	integer1–100	How many accounts to return, 1-100, worst first. Defaults to 25. Default: `25`

Output

Field	Type	Description
currency	string	—
as_of	string	—
include_unverified	boolean	—
truncated	boolean	—
totals	object	—
totals.customers	number	—
totals.invoices	number	—
totals.balance	number	—
totals.past_due	number	—
totals.imported_invoices	number	—
totals.imported_balance	number	—
items	object[]	—
items[].customer_id	string	—
items[].name	string	—
items[].company	string \| null	—
items[].email	string \| null	—
items[].phone	string \| null	—
items[].reachable	boolean	—
items[].sms_opted_out	boolean	—
items[].balance	number	—
items[].past_due	number	—
items[].bucket	string	—
items[].max_days_past_due	number	—
items[].invoices	number	—
items[].imported_count	number	—
items[].chaser_touched	number	—
items[].recovered	number	—
held	object	—
held.customers	number	—
held.invoices	number	—
held.balance	number	—
recovered	object \| null	—
recovered.amount	number	—
recovered.payments	number	—
recovered.since	string	—
recovered.partial	boolean	—
omitted	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/invoices/recovery \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":25}'

TypeScript (fetch)

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

// 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/invoices/recovery",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "limit": 25
},
    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": "invoices.recovery",
    "arguments": {
      "limit": 25
    }
  }
}

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 invoices.access.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many read 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#