`post_vouchers_by_id_expire`

Changes data · you confirm first

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

Expire a voucher ahead of its date

Moves the voucher to EXPIRED, gated exactly as POST /api/vouchers/{id}/void is. The state machine allows EXPIRED only while no clinic has taken it — from CREATED, ASSIGNED or ISSUED — and refuses it from every other state with 409, a voucher in process included. A voucher in a batch is REPLACED in that batch in the same write: the DAL mints one CREATED voucher like it and links the two (replacedByVoucherId on the expired one, returned here), unless the batch's own expiry has already passed.

Arguments

Argument	Type		Description
`id`path	string (uuid)	required	Voucher id.

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_by_id_expire",
    "arguments": {
      "id": "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 expired voucher, as the DAL's TransitionVoucher selection returns it; its replacedByVoucherId names the replacement when the DAL minted one.

json

{
  "code": "string",
  "currency": "string",
  "expiresAt": 1,
  "id": "11111111-1111-4111-8111-111111111111",
  "state": "ACTIVE",
  "value": 1,
  "assignedToOrgId": "11111111-1111-4111-8111-111111111111",
  "batchId": "11111111-1111-4111-8111-111111111111",
  "issuedAt": 1,
  "issuedToEmail": "string",
  "issuedToPhone": "string",
  "maxPayout": 1,
  "procedure": "string",
  "replacedByVoucherId": "11111111-1111-4111-8111-111111111111"
}

Fields

Field	Type	Description
`assignedToOrgId`	string (uuid) \| null
`batchId`	string (uuid) \| null
`code`	string
`currency`	string
`expiresAt`	integer	Epoch MILLISECONDS.
`id`	string (uuid)
`issuedAt`	integer \| null	Epoch MILLISECONDS.
`issuedToEmail`	string \| null
`issuedToPhone`	string \| null
`maxPayout`	integer \| null	Catalog face-value cap in CENTS.
`procedure`	string \| null
`replacedByVoucherId`	string (uuid) \| null	The voucher the DAL minted to replace this one in its batch, if any.
`serviceType`	string \| null
`species`	string \| null
`state`	"ACTIVE" \| "APPROVED" \| "ASSIGNED" \| "AVAILABLE" \| "CLAIMED" \| "CREATED" \| … (17 values)	A voucher's lifecycle state, as the DAL's `VoucherState` enum names it.
`value`	integer	Face value in CENTS.
`voidReason`	string \| null

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.

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_vouchers_by_id_expire",
  "description": "POST /api/vouchers/{id}/expire — Moves the voucher to EXPIRED, gated exactly as `POST /api/vouchers/{id}/void` is. The state machine allows EXPIRED only while no clinic has taken it — from CREATED, ASSIGNED or ISSUED — and refuses it from every other state with 409, a voucher in process included. A voucher in a batch is REPLACED in that batch in the same write: the DAL mints one CREATED voucher like it and links the two (`replacedByVoucherId` on the expired one, returned here), unless the batch's own expiry has already passed.\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": "Voucher id."
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}