Pawsitive Future Pawsitive FutureDeveloper docs

post_allocations_by_orgid_revoke

Changes data · you confirm first

Calls POST /api/allocations/{orgId}/revoke as the signed-in person · REST reference

Take back part of an organization's unspent voucher budget

Debits CENTS from the organization's ORG_ALLOCATION account, returning them to what the pool may grant. Only the UNSPENT allocation can be revoked — what batches already committed stays committed. The reason is recorded on the ledger transaction. TWO GATES, NOT ONE. The platform-staff middleware is the outer one; the caller's own bearer token is then forwarded so the DAL evaluates the real actor against execute:RevokeOrgAllocationCommand. A platform staffer without that command is refused by the DAL with 403. A non-positive amount, more than the unspent allocation, an organization with no allocation account, a reason under 10 characters or a non-UUID orgId answer 400. An organization that does not exist answers 404. A revoke that lost a race with another write to the same allocation answers 409 — retry it. A DAL that does not answer is 503.

Arguments

ArgumentTypeDescription
orgIdpathstring (uuid)requiredOrganization whose allocation to reduce.
bodyJSONobjectrequiredThe request body, as a JSON object. Its fields are listed below.

Fields of body

FieldTypeDescription
amountintegerrequiredCENTS to take back. A positive integer, at most the organization's unspent allocation.
currencystringCurrency of the allocation account. Defaulted by the DAL, not here.
reasonstringrequiredWhy, recorded on the ledger transaction. At least 10 characters.

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_allocations_by_orgid_revoke",
    "arguments": {
      "orgId": "11111111-1111-4111-8111-111111111111",
      "body": {
        "amount": 1,
        "reason": "string",
        "currency": "USD"
      }
    }
  }
}
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 allocation was reduced, verbatim as the DAL reports it.

json
{
  "accountId": "11111111-1111-4111-8111-111111111111",
  "amount": 1,
  "currency": "string",
  "newBalance": 1,
  "orgId": "11111111-1111-4111-8111-111111111111",
  "transactionId": "11111111-1111-4111-8111-111111111111"
}

Fields

FieldTypeDescription
accountIdstring (uuid)The ORG_ALLOCATION account debited.
amountintegerAmount revoked by THIS call, in CENTS.
currencystring
newBalanceintegerThe org's allocation balance after the revoke, in CENTS.
orgIdstring (uuid)
transactionIdstring (uuid)Ledger transaction recording the revoke.

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": "post_allocations_by_orgid_revoke",
  "description": "POST /api/allocations/{orgId}/revoke — Debits CENTS from the organization's ORG_ALLOCATION account, returning them to what the pool may grant. Only the UNSPENT allocation can be revoked — what batches already committed stays committed. The reason is recorded on the ledger transaction. TWO GATES, NOT ONE. The platform-staff middleware is the outer one; the caller's own bearer token is then forwarded so the DAL evaluates the real actor against `execute:RevokeOrgAllocationCommand`. A platform staffer without that command is refused by the DAL with 403. A non-positive amount, more than the unspent allocation, an organization with no allocation account, a reason under 10 characters or a non-UUID `orgId` answer 400. An organization that does not exist answers 404. A revoke that lost a race with another write to the same allocation answers 409 — retry it. A DAL that does not answer is 503.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orgId": {
        "type": "string",
        "description": "Organization whose allocation to reduce."
      },
      "body": {
        "type": "string",
        "description": "The JSON request body: { amount*: integer (CENTS to take back.); currency: string (Currency of the allocation account.); reason*: string (Why, recorded on the ledger transaction.) }"
      }
    },
    "required": [
      "orgId",
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}