Pawsitive Future Pawsitive FutureDeveloper docs

get_vouchers_batches

Read-only

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

Inventory batches, org-scoped unless the caller is platform staff

Backs the Vouchers page's Inventory tab. Declared before /{id} so the literal path is not captured as a voucher id. Answers the { data, count } envelope, unlike its sibling GET /api/vouchers which answers a bare array. Scoping is derived from the caller's own token, never from a query parameter: platform staff see every org's batches, and everyone else the batches of every organization in which they hold an inventory feature, bounded at the DAL. A caller holding an inventory feature in no organization is refused 403 before any DAL call. An unknown status is refused 400 before any DAL call; every failure of the read itself is answered 503 with a fixed message.

Arguments

ArgumentTypeDescription
statusquery"AVAILABLE" | "CREATED" | "DENIED" | "DEPLETED" | "DISTRIBUTED" | "EXPIRED" | … (12 values)One of the DAL's inventory-batch statuses. Any other value is refused 400, naming the accepted ones, and nothing is read.
itemTypequerystring
limitqueryintegerApplied only when it parses to a finite integer greater than zero; anything else is dropped and the DAL's own default page size applies.

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

Result

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

The batches of every organization in which the caller holds an inventory feature (hospital.inventory.manage, distributor.inventory.manage or hospital.vouchers.request) — bounded at the DAL from the caller's own token — or every organization's for platform staff.

json
{
  "count": 1,
  "data": [
    {
      "availableQuantity": 1,
      "batchNumber": "string",
      "committedQuantity": 1,
      "deleted": true,
      "id": "string",
      "inspectionDate": 1,
      "itemName": "string",
      "itemType": "string",
      "manufactureDate": 1,
      "quantity": 1,
      "receivedDate": 1,
      "reservedQuantity": 1,
      "status": "AVAILABLE",
      "totalPotentialValueCents": 1
    }
  ]
}

Fields

FieldTypeDescription
countintegerThe DAL's totalCount for the filter, falling back to the length of data. It is therefore a MATCH count, not a page count, and normally exceeds data.length when a limit is applied.
dataarray of object
data[].assignedTostring | null
data[].availableQuantitynumber
data[].batchNumberstring
data[].batchTypestring | null
data[].certificationsobject | null
data[].committedQuantitynumber
data[].complianceFlagsobject | null
data[].createdBystring | null
data[].deletedboolean
data[].deletedAtnumber | null
data[].deletedBystring | null
data[].distributionCapnumber | null
data[].distributionHistoryobject | null
data[].expirationDatenumber | null
data[].idstring
data[].inspectionDatenumber
data[].inspectionResultsobject | null
data[].itemDescriptionstring | null
data[].itemNamestring
data[].itemTypestring
data[].locationstring | null
data[].lotNumberstring | null
data[].manufactureDatenumber
data[].metadataobject | null
data[].printerJobIdstring | null
data[].processedAtnumber | null
data[].qualityGradestring | null
data[].quantitynumber
data[].receivedAtnumber | null
data[].receivedDatenumber
data[].reservedQuantitynumber
data[].shippedAtnumber | null
data[].shippingInfoobject | null
data[].status"AVAILABLE" | "CREATED" | "DENIED" | "DEPLETED" | "DISTRIBUTED" | "EXPIRED" | … (12 values)
data[].storageConditionsstring | null
data[].supplierstring | null
data[].supplierOrderNumberstring | null
data[].totalPotentialValueCentsinteger | nullquantity × unitCostCents, in integer CENTS. Null on the same batches as unitCostCents.
data[].typestring | null
data[].unitCostCentsinteger | nullCost of one unit in integer CENTS. Null on a batch whose cost the graph holds only in dollars.
data[].unitOfMeasurestring
data[].updatedAtnumber | null
data[].voucherCountsobjectThe batch's vouchers by lifecycle state, counted in the graph. live (every state but VOIDED, EXPIRED and VOIDED_REPRINTED) against quantity is whether the batch still holds what its holder was promised; unissued (CREATED/ASSIGNED) is what a shrink may release.
data[].voucherCounts.expiredinteger
data[].voucherCounts.issuedintegerISSUED through QUEUED_FOR_CHECKOUT.
data[].voucherCounts.liveinteger
data[].voucherCounts.paidinteger
data[].voucherCounts.reprintedintegerVOIDED_REPRINTED — each replaced by a voucher counted in live.
data[].voucherCounts.unissuedinteger
data[].voucherCounts.voidedinteger

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

The caller holds no inventory feature in any organization.

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",
  "description": "GET /api/vouchers/batches — Backs the Vouchers page's Inventory tab. Declared before `/{id}` so the literal path is not captured as a voucher id. Answers the `{ data, count }` envelope, unlike its sibling `GET /api/vouchers` which answers a bare array. Scoping is derived from the caller's own token, never from a query parameter: platform staff see every org's batches, and everyone else the batches of every organization in which they hold an inventory feature, bounded at the DAL. A caller holding an inventory feature in no organization is refused 403 before any DAL call. An unknown `status` is refused 400 before any DAL call; every failure of the read itself is answered 503 with a fixed message.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "description": "One of the DAL's inventory-batch statuses. Any other value is refused 400, naming the accepted ones, and nothing is read."
      },
      "itemType": {
        "type": "string"
      },
      "limit": {
        "type": "string",
        "description": "Applied only when it parses to a finite integer greater than zero; anything else is dropped and the DAL's own default page size applies."
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}