Pawsitive Future Pawsitive FutureDeveloper docs

post_vouchers_batches_by_id_assign

Changes data · you confirm first

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

Assign an existing batch to an organization

How a distributor is handed stock PFF minted for it — the holder is always a distributor or the platform org, never a clinic. Also re-points the batch's PRE-ISSUE vouchers, so their holder (assignedToOrgId) follows the batch. A batch whose vouchers are already out in the world is NOT wholesale reassigned: the DAL moves only the pre-issue ones and reports how many it had to leave bound, so a non-zero vouchersLeftBound means the batch is no longer homogeneous. That is a success, not an error — check the field rather than the status code. Gated by the platform-staff middleware, not by a dedicated assign permission.

Arguments

ArgumentTypeDescription
idpathstring (uuid)requiredInventory batch id.
bodyJSONobjectrequiredThe request body, as a JSON object. Its fields are listed below.

Fields of body

FieldTypeDescription
orgIdstring (uuid)requiredOrganization to assign the batch to. Missing or blank answers 400, and so does anything but a DISTRIBUTOR or the platform organization — a service provider never holds a batch. A missing or deleted organization answers 404.

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": "post_vouchers_batches_by_id_assign",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "body": {
        "orgId": "11111111-1111-4111-8111-111111111111"
      }
    }
  }
}
Confirmation
The client shows the person the exact request and waits. Nothing runs until they tick Make this change. See Reading and changing.

Result

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

The batch was assigned; the counts say how completely.

json
{
  "batchId": "11111111-1111-4111-8111-111111111111",
  "vouchersLeftBound": 1,
  "vouchersReassigned": 1,
  "assignedTo": "11111111-1111-4111-8111-111111111111"
}

Fields

FieldTypeDescription
assignedTostring (uuid) | nullThe org the batch now belongs to, read back from the DAL.
batchIdstring (uuid)
vouchersLeftBoundintegerVouchers already past pre-issue and therefore left pointing at their previous org. Non-zero means the batch is now split across two orgs.
vouchersReassignedintegerPre-issue vouchers moved to the new org.

When it fails

A failed call returns isError: true with the API's message as text. A change the person declines, or lets time out, also comes back this way and nothing changes.

400

The request was malformed or failed a guard.

403

Authenticated, but the caller holds none of the required permissions.

404

No such resource — or none this caller may see.

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": "post_vouchers_batches_by_id_assign",
  "description": "POST /api/vouchers/batches/{id}/assign — How a distributor is handed stock PFF minted for it — the holder is always a distributor or the platform org, never a clinic. Also re-points the batch's PRE-ISSUE vouchers, so their holder (`assignedToOrgId`) follows the batch. A batch whose vouchers are already out in the world is NOT wholesale reassigned: the DAL moves only the pre-issue ones and reports how many it had to leave bound, so a non-zero `vouchersLeftBound` means the batch is no longer homogeneous. That is a success, not an error — check the field rather than the status code. Gated by the platform-staff middleware, not by a dedicated assign permission.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Inventory batch id."
      },
      "body": {
        "type": "string",
        "description": "The JSON request body: { orgId*: string (Organization to assign the batch to.) }"
      }
    },
    "required": [
      "id",
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}