Pawsitive Future Pawsitive FutureDeveloper docs

patch_vouchers_batches_by_id

Changes data · you confirm first

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

Resize a voucher batch through its holder's allocation

Sets the batch to quantity vouchers, in one DAL transaction. GROWING mints the difference under exactly the guards a new batch is minted under — the holder may hold a batch, its allocation covers the growth, the voucher pool covers it — and debits the holder. A grow prints nothing: a grown PHYSICAL batch's new vouchers are NOT_PRINTED until the batch is printed (POST /api/vouchers/batches/{id}/print, which sends exactly the vouchers no printer has). SHRINKING voids the newest vouchers that are still unissued (CREATED or ASSIGNED) and credits their value back to the holder; it is refused with 409 when too few are unissued, and the message names the lowest quantity the batch can go to. A slot already dead — a voucher voided or expired and never replaced — needs no voucher voided, but its value is credited when the target drops past it. Refused with 409 for a batch REQUEST (REQUESTED/DENIED — those are decided, not resized) or for growing a batch whose vouchers have expired. The same quantity the batch already has is a no-op. Requires execute:CreateVoucherBatchCommand: growing a batch is minting.

Arguments

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

Fields of body

FieldTypeDescription
quantityintegerrequiredThe new number of vouchers. 0 releases the whole batch (see DELETE).
reasonstringRecorded as the void reason on vouchers a shrink releases.

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": "patch_vouchers_batches_by_id",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "body": {
        "quantity": 1,
        "reason": "string"
      }
    }
  }
}
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 resized (or already had that quantity).

json
{
  "allocationCredited": 1,
  "allocationDebited": 1,
  "batchId": "11111111-1111-4111-8111-111111111111",
  "previousQuantity": 1,
  "quantity": 1,
  "vouchersMinted": 1,
  "vouchersReleased": 1,
  "assignedTo": "11111111-1111-4111-8111-111111111111"
}

Fields

FieldTypeDescription
allocationCreditedintegerCENTS returned to the holder's allocation by a shrink.
allocationDebitedintegerCENTS drawn from the holder's allocation by a grow.
assignedTostring (uuid) | null
batchIdstring (uuid)
previousQuantityinteger
quantityinteger
vouchersMintedintegerVouchers a grow minted (CREATED). 0 for a shrink.
vouchersReleasedintegerVouchers a shrink voided. 0 for a grow.

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.

409

The resource is not in a state that allows this operation.

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": "patch_vouchers_batches_by_id",
  "description": "PATCH /api/vouchers/batches/{id} — Sets the batch to `quantity` vouchers, in one DAL transaction. GROWING mints the difference under exactly the guards a new batch is minted under — the holder may hold a batch, its allocation covers the growth, the voucher pool covers it — and debits the holder. A grow prints nothing: a grown PHYSICAL batch's new vouchers are NOT_PRINTED until the batch is printed (`POST /api/vouchers/batches/{id}/print`, which sends exactly the vouchers no printer has). SHRINKING voids the newest vouchers that are still unissued (CREATED or ASSIGNED) and credits their value back to the holder; it is refused with 409 when too few are unissued, and the message names the lowest quantity the batch can go to. A slot already dead — a voucher voided or expired and never replaced — needs no voucher voided, but its value is credited when the target drops past it. Refused with 409 for a batch REQUEST (REQUESTED/DENIED — those are decided, not resized) or for growing a batch whose vouchers have expired. The same `quantity` the batch already has is a no-op. Requires `execute:CreateVoucherBatchCommand`: growing a batch is minting.\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": "Batch id."
      },
      "body": {
        "type": "string",
        "description": "The JSON request body: { quantity*: integer (The new number of vouchers.); reason: string (Recorded as the void reason on vouchers a shrink releases.) }"
      }
    },
    "required": [
      "id",
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}