cancel_purchase

Before any checkout report, request a stop when the user changes their mind or the merchant total differs.

POST https://api.envoy.money/tools/cancel_purchase

Before any checkout report, request a stop when the user changes their mind or the merchant total differs. Envoy refuses cancel_purchase after any report_checkout_result and explains that the purchase must reconcile. Cancellation is not proof of a refund or card blocking; follow the returned purchase and next action.

Title	Service	Read only	Destructive	Idempotent	External sites
Cancel a purchase	shared	false	true	true	false

Send a Central Auth bearer with agent scope. A key-bound connection also sends Envoy-Installation-Proof over this exact request. JSON bodies are limited to 64 KB; a larger body returns HTTP 413 with INVALID_INPUT.

Input

Field	Required	Type	Description and rules
`purchase`	Yes	`string`	Purchase ID or original idempotency key. minLength 16; maxLength 64; pattern `^(?:pur_[a-f0-9]{32}\|(?:[A-Za-oq-z0-9_-]\|p[A-Za-tv-z0-9_-]\|pu[A-Za-qs-z0-9_-]\|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$`
`reason`	No	`string`	Cancellation reason.

Unknown fields are rejected. The exact input schema is on the schemas page.

Synthetic request

{
  "purchase": "synthetic-intent-0001"
}

Success data

Every reply uses the shared envelope: ok, the purchase, next, user_action and error. Follow next; outputs may gain fields, so ignore ones you do not recognize.

This tool declares no data payload: a success returns the purchase in purchase and what to do next in next.

Synthetic result

Example synthetic-unauthenticated (synthetic data):

{
  "ok": false,
  "contract": "envoy@2026-10",
  "tool": "cancel_purchase",
  "request_id": "req_synthetic",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "server_time": "2026-09-29T12:00:00Z",
  "replayed": false,
  "purchase": null,
  "data": null,
  "next": {
    "action": "reconnect",
    "tool": null,
    "args": null,
    "instruction": "Ask the user to reconnect Envoy, then retry this call.",
    "after_seconds": null,
    "by": null
  },
  "user_action": null,
  "follow_ups": [],
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Reconnect to Envoy.",
    "fields": [],
    "reason_code": null,
    "retryable": false,
    "retry_after_seconds": null
  }
}

Errors

A failure has ok: false, changes nothing, and carries error plus one next. Branch on error.code and next, not on the HTTP status. The contract declares every code below for every tool; which one a call returns depends on the request and the purchase state.

Code	HTTP status	Meaning	What the agent does
`INVALID_INPUT`	400	Fix the supplied input.	Fix every field listed in error.fields, then call the same tool once more.
`UNAUTHENTICATED`	401	Reconnect through Central Auth.	Ask the user to reconnect Envoy, then retry this call.
`NOT_ALLOWED`	403	The operation is not allowed.	This connection may not do that. Tell the user; do not retry.
`SERVICE_NOT_ENABLED`	403	The service is not enabled.	This Envoy service is not enabled for the user. Tell the user; do not retry.
`NOT_FOUND`	404	Purchase absent or owned by another user.	No purchase matches that reference. Check the purchase id from this task; do not start a new purchase to recover.
`IDEMPOTENCY_CONFLICT`	409	The same key has different input.	Retry with the original inputs unchanged, or use a new idempotency_key only for a genuinely new purchase.
`ACTIVE_PURCHASE_EXISTS`	409	An active purchase already exists.	Another purchase is in progress. Show the user the user_action message and stop this attempt.
`STATE_CONFLICT`	409	The operation conflicts with the current state.	This conflicts with the current state. Tell the user; do not retry.
`NO_RAIL`	422	No rail can serve this purchase; nothing was created.	Envoy cannot pay this purchase. Tell the user why using error.message; do not retry or split it.
`RATE_LIMITED`	429	Wait before retrying.	Wait next.after_seconds, then retry the same call unchanged.
`UNAVAILABLE`	503	The service is unavailable; follow retryable and next.	Wait next.after_seconds, then retry the same call unchanged; never pay elsewhere meanwhile.
`CLIENT_UPDATE_REQUIRED`	426	Update the client.	This client is too old. Tell the user to update it.

Downloads

OpenAPI · MCP catalog · Synthetic examples · Schemas