`get_payee_reports_by_year`

Read-only

Calls GET /api/payee-reports/{year} as the signed-in person · REST reference

What Pawsitive Future paid each clinic in a calendar year

The payee side of year-end reporting: every clinic paid, or recovered from, in the calendar year on the Pacific clock, with its net payments, the Form 1099 threshold flag and — for a sole proprietor — the date California's DE 542 became owed. Compared with the Form 1099 totals Stripe Connect files. Read from the ledger; each payee's entity type, legal name and whether its TIN is on file are read from Stripe at request time and stored nowhere. Platform staff only.

Arguments

Argument	Type		Description
`year`path	string	required	Four digits, from 2000 to the current year.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_payee_reports_by_year",
    "arguments": {
      "year": "string"
    }
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The report.

json

{
  "de542ThresholdCents": 1,
  "form1099ThresholdCents": 1,
  "generatedAt": "2026-01-15T12:00:00Z",
  "payees": [
    {
      "de542DueBy": "2026-01-15",
      "de542ReachedOn": "2026-01-15",
      "entityType": "individual",
      "legalName": "string",
      "meets1099Threshold": true,
      "netPaidCents": 1,
      "orgId": "11111111-1111-4111-8111-111111111111",
      "orgName": "string",
      "paymentsCents": 1,
      "payoutCount": 1,
      "recoveredCents": 1,
      "stripeAccountId": "string",
      "tinProvided": true
    }
  ],
  "timezone": "string",
  "totals": {
    "meeting1099Threshold": 1,
    "netPaidCents": 1,
    "payees": 1
  },
  "unattributedCents": 1,
  "year": 1
}

Fields

Field	Type	Description
`de542ThresholdCents`	integer
`form1099ThresholdCents`	integer	$600 for payments before 2026; $2,000 for payments made in 2026 and later.
`generatedAt`	string (date-time)
`payees`	array of object	By clinic name.
`payees[].de542DueBy`	string (date) \| null	20 days after `de542ReachedOn`.
`payees[].de542ReachedOn`	string (date) \| null	Sole proprietors only: the Pacific date of the payout that brought the year's payments to $600 — when California's DE 542 became owed. Null for a company or below $600.
`payees[].entityType`	"individual" \| "company" \| "unknown"	Stripe's `business_type` for the connected account, read at request time.
`payees[].legalName`	string \| null	The name Stripe reports the payee under — the company's legal name, or the sole proprietor's own. Null when Stripe did not say.
`payees[].meets1099Threshold`	boolean	netPaidCents is at least the year's Form 1099 threshold.
`payees[].netPaidCents`	integer	paymentsCents less recoveredCents. Below zero when a recovery exceeded the year's payments.
`payees[].orgId`	string (uuid)
`payees[].orgName`	string \| null
`payees[].paymentsCents`	integer	PAYOUT transactions whose Stripe transfer is SENT, dated by settlement. Offset payouts (settling credit against a clawback) are not payments.
`payees[].payoutCount`	integer
`payees[].recoveredCents`	integer	Confirmed clawback recovery legs that took cash back from the clinic — REVERSAL, BANK_DEBIT (confirmed and not returned), OUT_OF_BAND, CLINIC_PAYMENT — dated by when the money moved. The OFFSET leg is not counted: its payout never was.
`payees[].stripeAccountId`	string \| null
`payees[].tinProvided`	boolean \| null	Whether Stripe holds the payee's full SSN or EIN. Null when Stripe did not say. The TIN itself is never read.
`timezone`	string	The clock a payment's year is read on — America/Los_Angeles.
`totals`	object
`totals.meeting1099Threshold`	integer
`totals.netPaidCents`	integer
`totals.payees`	integer
`unattributedCents`	integer	Payout cents whose clinic the ledger does not name. Nonzero means a payee is under-reported here.
`year`	integer

When it fails

A failed call returns isError: true with the API's message as text.

400: The year is out of range (details.field year).
403: Authenticated, but the caller holds none of the required permissions.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "get_payee_reports_by_year",
  "description": "GET /api/payee-reports/{year} — The payee side of year-end reporting: every clinic paid, or recovered from, in the calendar year on the Pacific clock, with its net payments, the Form 1099 threshold flag and — for a sole proprietor — the date California's DE 542 became owed. Compared with the Form 1099 totals Stripe Connect files. Read from the ledger; each payee's entity type, legal name and whether its TIN is on file are read from Stripe at request time and stored nowhere. Platform staff only.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "year": {
        "type": "string",
        "description": "Four digits, from 2000 to the current year."
      }
    },
    "required": [
      "year"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}