`get_vouchers_batches_by_id_vouchers`

Read-only

Calls GET /api/vouchers/batches/{id}/vouchers as the signed-in person · REST reference

One batch's vouchers, a page at a time, searchable by code or id

Every voucher minted into the batch, in every state — VOIDED, EXPIRED and VOIDED_REPRINTED included, each replaced one naming its replacement (replacedByVoucherId) and each replacement the voucher it replaced (replacesVoucherId). Walked over the batch's IN_BATCH edge, the one its voucherCounts count, newest first. Scoped exactly as GET /api/vouchers is: the DAL bounds it, from the caller's own token, to the vouchers the caller's orgs hold or took — every org's for platform staff. The batch itself is not read, so an unknown batch and one outside the caller's orgs both answer an empty page rather than a 404 that would confirm the id. Answers { data, count } like GET /api/vouchers/batches; count is the number of matches, not the length of the page.

Arguments

Argument	Type		Description
`id`path	string (uuid)	required	Inventory batch id.
`search`query	string		Case-insensitive substring of the voucher's code or id. Trimmed; blank is no filter. Applied before paging, so `count` counts the matches.
`limit`query	integer
`offset`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_vouchers_batches_by_id_vouchers",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Result

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

One page of the batch's vouchers the caller may read, as the DAL's ListVouchers selection returns them.

json

{
  "count": 1,
  "data": [
    {
      "claimAmount": 1,
      "clawbackStatus": "REQUESTED",
      "code": "string",
      "currency": "string",
      "expiresAt": 1,
      "id": "11111111-1111-4111-8111-111111111111",
      "openClawbackStatus": "REQUESTED",
      "printStatus": "NOT_PRINTED",
      "state": "ACTIVE",
      "value": 1,
      "assignedToOrgId": "11111111-1111-4111-8111-111111111111",
      "batchId": "11111111-1111-4111-8111-111111111111",
      "claimedByOrgId": "11111111-1111-4111-8111-111111111111",
      "creditedAmount": 1
    }
  ]
}

Fields

Field	Type	Description
`count`	integer	Vouchers matching the search in the batch — every page's, not this one's.
`data`	array of object
`data[].assignedToOrgId`	string (uuid) \| null	The org holding the voucher to distribute it — a distributor or the platform.
`data[].batchId`	string (uuid) \| null
`data[].claimAmount`	integer \| null	The value of the voucher's claim in CENTS — the only money a voucher is shown as worth, derived by the backend (`claimAmount`, backend/src/domain/claimInvoice.ts), not a DAL field. Null until the claim is submitted, and while a CLAIMED voucher's invoice waits on the AI or a reviewer; a CLAIMED voucher's validated covered amount, capped as approval caps it; from APPROVED on, what approval credited (`creditedAmount`). Never the face value (`value`).
`data[].claimedByOrgId`	string (uuid) \| null	The clinic that took the voucher at verify; null while no clinic has.
`data[].clawbackStatus`	"REQUESTED" \| "APPROVED" \| "EXECUTING" \| "RECOVERED" \| "PARTIALLY_RECOVERED" \| "WRITTEN_OFF" \| … (7 values)	The status of the latest payout clawback against a voucher, resolved ones included — what the voucher's (or its payout's) clawback chip says. Null when there is none. DENIED is never reported, nor a REQUESTED clawback Pawsitive Future filed: until it is approved it is Pawsitive Future's own deliberation.
`data[].code`	string
`data[].creditedAmount`	integer \| null	CENTS approval credited the claiming clinic; null before approval.
`data[].currency`	string
`data[].expiresAt`	integer	Epoch MILLISECONDS.
`data[].id`	string (uuid)
`data[].issuedToEmail`	string \| null	The beneficiary's address — the reason every voucher read is org-scoped.
`data[].maxPayout`	integer \| null	The voucher's catalog cap in CENTS; null when it has none and its face value caps it.
`data[].openClawbackStatus`	"REQUESTED" \| "APPROVED" \| "EXECUTING" \| "PARTIALLY_RECOVERED" \| "WRITTEN_OFF" \| null	The status of the voucher's open payout clawback, newest first: one being decided or collected, or one closed without all of its cash whose payouts pause has not been lifted. Null when none is — and for any voucher that is not PAID. A REQUESTED clawback Pawsitive Future filed is not reported: until it is approved it is Pawsitive Future's own deliberation.
`data[].printStatus`	"NOT_PRINTED" \| "PRINT_FAILED" \| "SUBMITTED"	Whether a printer has this voucher, apart from its lifecycle state. SUBMITTED: a printer accepted a job carrying it; PRINT_FAILED: the last print carrying it failed; NOT_PRINTED: no print has covered it.
`data[].procedure`	string \| null
`data[].receiptValidatedAmount`	integer \| null	The covered amount the invoice was validated at, in CENTS, before any cap. Null to a reader who does not read the claiming clinic's invoice.
`data[].receiptValidationStatus`	string \| null	The invoice check — PENDING, VALID or PENDING_MANUAL_REVIEW; null before an invoice.
`data[].replacedByVoucherId`	string (uuid) \| null
`data[].replacesVoucherId`	string (uuid) \| null
`data[].serviceType`	string \| null
`data[].state`	"ACTIVE" \| "APPROVED" \| "ASSIGNED" \| "AVAILABLE" \| "CLAIMED" \| "CREATED" \| … (17 values)	A voucher's lifecycle state, as the DAL's `VoucherState` enum names it.
`data[].value`	integer	Face value in CENTS.
`data[].workOrderId`	string \| null

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_vouchers_batches_by_id_vouchers",
  "description": "GET /api/vouchers/batches/{id}/vouchers — Every voucher minted into the batch, in every state — VOIDED, EXPIRED and VOIDED_REPRINTED included, each replaced one naming its replacement (`replacedByVoucherId`) and each replacement the voucher it replaced (`replacesVoucherId`). Walked over the batch's IN_BATCH edge, the one its `voucherCounts` count, newest first. Scoped exactly as `GET /api/vouchers` is: the DAL bounds it, from the caller's own token, to the vouchers the caller's orgs hold or took — every org's for platform staff. The batch itself is not read, so an unknown batch and one outside the caller's orgs both answer an empty page rather than a 404 that would confirm the id. Answers `{ data, count }` like `GET /api/vouchers/batches`; `count` is the number of matches, not the length of the page.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Inventory batch id."
      },
      "search": {
        "type": "string",
        "description": "Case-insensitive substring of the voucher's code or id. Trimmed; blank is no filter. Applied before paging, so `count` counts the matches."
      },
      "limit": {
        "type": "string"
      },
      "offset": {
        "type": "string"
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}