list_purchases
Use this when the user asks about a purchase and you lack its purchase_id: purchases made through you, newest first.
POST https://api.envoy.money/tools/list_purchases
Use this when the user asks about a purchase and you lack its purchase_id: purchases made through you, newest first. States may be out of date: check one with get_purchase_status before telling the user.
| Title | Service | Read only | Destructive | Idempotent | External sites |
|---|---|---|---|---|---|
| List purchases | purchase | true | false | 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 |
|---|---|---|---|
limit | No | integer | How many, newest first. minimum 1; maximum 20; default 10 |
Unknown fields are rejected. The exact input schema is on the schemas page.
Synthetic request
{
"limit": 5
}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 returns its payload in data:
Field in data | Required | Type | Description and rules |
|---|---|---|---|
purchases | Yes | array of object | maxItems 20 |
purchases[].purchase_id | Yes | string | Purchase ID: pur_ followed by 32 lowercase hexadecimal digits. pattern ^pur_[a-f0-9]{32}$ |
purchases[].state | Yes | "needs_details" | "needs_answer" | "waiting_for_user" | "processing" | "ready" | "verifying" | "completed" | "failed" | "cancelled" | "superseded" | Purchase lifecycle state. |
purchases[].merchant | Yes | object | — |
purchases[].amount | Yes | object | — |
purchases[].checkout_by | Yes | "agent" | "envoy" | null | Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected. |
purchases[].created_at | Yes | string | Creation time. format date-time |
truncated | Yes | boolean | True when the user has more purchases than were returned. |
Synthetic result
Example synthetic-unauthenticated (synthetic data):
{
"ok": false,
"contract": "envoy@2026-10",
"tool": "list_purchases",
"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. |