`get_finance_clawbacks`

Read-only

Calls GET /api/finance/clawbacks as the signed-in person · REST reference

The payout clawback review queue (platform staff)

Every clinic's payout clawbacks, newest first, filed by the clinic or by Pawsitive Future: the reason, the amount against what the voucher's payout credited, the payout it concerns, and how often Pawsitive Future has absorbed the clinic's fees before. Reads only. { data, count }, where count is the rows in data.

Arguments

Argument	Type		Description
`status`query	"REQUESTED" \| "APPROVED" \| "DENIED" \| "EXECUTING" \| "RECOVERED" \| "PARTIALLY_RECOVERED" \| … (7 values)
`limit`query	integer

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_finance_clawbacks",
    "arguments": {}
  }
}

Result

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

The queue

json

{
  "count": 1,
  "data": [
    {
      "amount": 1,
      "approvedAt": 1,
      "approvedBy": "11111111-1111-4111-8111-111111111111",
      "creditedAmount": 1,
      "currency": "string",
      "deniedAt": 1,
      "deniedBy": "11111111-1111-4111-8111-111111111111",
      "feeCents": 1,
      "feeLiability": {},
      "feeWaiverConsumed": true,
      "filedBy": "SERVICE_PROVIDER",
      "id": "11111111-1111-4111-8111-111111111111",
      "initiatedBy": "11111111-1111-4111-8111-111111111111",
      "initiatorOrgId": "11111111-1111-4111-8111-111111111111"
    }
  ]
}

Fields

Field	Type	Description
`count`	integer
`data`	array of object
`data[].amount`	integer	CENTS asked back — at most `creditedAmount`.
`data[].approvedAt`	integer \| null
`data[].approvedBy`	string (uuid) \| null
`data[].creditedAmount`	integer	CENTS the voucher's approval credited — what its payout paid.
`data[].currency`	string
`data[].deniedAt`	integer \| null
`data[].deniedBy`	string (uuid) \| null
`data[].feeCents`	integer	CENTS of recovery fee assessed; 0 until a fee is realized.
`data[].feeLiability`	object \| null	Proposed when Pawsitive Future files the clawback, set by an approval; null on a clinic's filing until it is approved, and on a denial.
`data[].feeWaiverConsumed`	boolean	Whether Pawsitive Future absorbs this approved clawback's processing cost.
`data[].filedBy`	"SERVICE_PROVIDER" \| "PAWSITIVE_FUTURE"	Who filed a clawback — the service provider that was paid, or Pawsitive Future staff.
`data[].id`	string (uuid)	The clawback's ledger transaction.
`data[].initiatedBy`	string (uuid) \| null	The user who filed it.
`data[].initiatorOrgId`	string (uuid) \| null	The service provider that filed it; null when Pawsitive Future did.
`data[].memo`	string \| null
`data[].orgId`	string (uuid)	The service provider the payout went to.
`data[].orgName`	string \| null
`data[].paidAt`	integer \| null	Epoch milliseconds the voucher was paid out.
`data[].payoutStripeTransferId`	string \| null	That payout's Stripe transfer (`tr_…`), when it recorded one.
`data[].payoutTransactionId`	string (uuid) \| null	The org's PAYOUT settlement created at the voucher's `paidAt`; null when none matches.
`data[].reasonCode`	"PFF_DISCRETIONARY" \| "PROCEDURE_NOT_COMPLETED" \| "BENEFICIARY_DISPUTE" \| "DUPLICATE_OR_ERRONEOUS_PAYOUT" \| "DONATION_REVERSED" \| "OTHER"	Why a clawback was filed. A service provider files PROCEDURE_NOT_COMPLETED, BENEFICIARY_DISPUTE or OTHER about a payout it received; the rest are Pawsitive Future's findings. OTHER needs a memo of at least 20 characters.
`data[].requestedAt`	integer	Epoch milliseconds.
`data[].status`	"REQUESTED" \| "APPROVED" \| "DENIED" \| "EXECUTING" \| "RECOVERED" \| "PARTIALLY_RECOVERED" \| … (7 values)	A payout clawback's lifecycle, kept apart from its ledger transaction's status. Filing and deciding reach REQUESTED, APPROVED and DENIED; the rest follow execution. RECOVERED is "cash confirmed": Pawsitive Future has confirmed the full amount is back in hand, never merely a booked reversal.
`data[].transferReversalState`	object \| null
`data[].voucherCode`	string
`data[].voucherId`	string (uuid)
`data[].voucherValueReversed`	boolean \| null	Decided at approval, beside the money: whether the voucher stops counting as help delivered once the clawback resolves. Null until approved, and on a denial.
`data[].voucherValueReversedByDefault`	boolean \| null	What an approval records as `voucherValueReversed` when the approver does not say — set by the reason: true for PROCEDURE_NOT_COMPLETED, BENEFICIARY_DISPUTE and DUPLICATE_OR_ERRONEOUS_PAYOUT, false for DONATION_REVERSED. Null for PFF_DISCRETIONARY and OTHER, which have no default: an approval must say.
`data[].cashConfirmationSource`	string \| null	The kinds of recovery the confirmed cash came by, comma-joined.
`data[].cashConfirmedAt`	integer \| null	When the full amount was confirmed back — what RECOVERED means.
`data[].noticeMessageId`	string \| null
`data[].noticeSentAt`	integer \| null	When the service provider was sent the written notice. Null after an approval means the notice did not send: nothing is recovered, payouts are paused, and POST /api/finance/clawbacks/{id}/execute retries it.
`data[].offsetPendingAmount`	integer	CENTS its offset payouts have moved that no OFFSET leg has recorded yet — settled, the transfer not confirmed. A failed one stays counted until the reconcile records it or it is released (POST /api/finance/clawbacks/{id}/offsets/{payoutTransactionId}/release).
`data[].originalStripeTransferId`	string \| null	The payout transfer (`tr_…`) the reversal reverses.
`data[].outstandingAmount`	integer	CENTS still owed while it is being collected (APPROVED, EXECUTING); 0 once closed.
`data[].pausesPayouts`	boolean	Whether this clawback pauses its service provider's payouts: APPROVED or EXECUTING, or PARTIALLY_RECOVERED / WRITTEN_OFF until payouts are resumed.
`data[].payoutsResumedAt`	integer \| null
`data[].payoutsResumedBy`	string (uuid) \| null
`data[].payoutsResumedReason`	string \| null
`data[].recoveredAmount`	integer	CENTS recovered so far — its confirmed recovery legs.
`data[].stripeReversalId`	string \| null	The transfer reversal (`trr_…`), once booked.
`data[].transferReversalLastError`	string \| null	The last failed reversal attempt's error; null once one succeeds.
`data[].transferReversalUpdatedAt`	integer \| null	Epoch milliseconds the reversal outbox state was last written; null when none was. A PENDING older than two minutes is read as a reversal whose synchronous call died.
`data[].writtenOffAt`	integer \| null
`data[].writtenOffBy`	string (uuid) \| null
`data[].writtenOffMemo`	string \| null
`data[].feesAbsorbedBefore`	integer	How many of the service provider's other approved clawbacks Pawsitive Future absorbed the processing cost of — what the approver weighs for a repeat.

When it fails

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

400: The request was malformed or failed a guard.
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_finance_clawbacks",
  "description": "GET /api/finance/clawbacks — Every clinic's payout clawbacks, newest first, filed by the clinic or by Pawsitive Future: the reason, the amount against what the voucher's payout credited, the payout it concerns, and how often Pawsitive Future has absorbed the clinic's fees before. Reads only. `{ data, count }`, where `count` is the rows in `data`.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string"
      },
      "limit": {
        "type": "string"
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}