get_merchants
Deprecated name of list_gift_card_merchants; same input and result.
POST https://api.envoy.money/tools/get_merchants
Deprecated name of list_gift_card_merchants; same input and result. Prefer list_gift_card_merchants.
| Title | Service | Read only | Destructive | Idempotent | External sites |
|---|---|---|---|---|---|
| List gift-card merchants (old name) | shared | 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
Send an empty JSON object, {}.
Unknown fields are rejected. The exact input schema is on the schemas page.
Synthetic request
{}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 |
|---|---|---|---|
merchants | Yes | array of object | Merchants the user can buy a gift card for right now. Empty when gift cards are not available. maxItems 1000 |
merchants[].name | Yes | string | Merchant name, taken from its domain. minLength 1; maxLength 253 |
merchants[].domain | Yes | string | Merchant website domain. minLength 1; maxLength 253 |
merchants[].amounts | Yes | array of object | Gift card face values sold. Empty when amount_range is set. maxItems 1000 |
merchants[].amount_range | Yes | object or null | Any whole rupee from min to max; null: listed amounts only. |
merchants[].discount_percent | Yes | number or null | Indicative product discount maximum, 0 to 100, may be fractional (2.5); null means none reported. Say "up to". The actual purchase quote is authoritative; until available, payable is unknown. Do not infer price from payment method or card ownership. minimum 0; maximum 100 |
merchants[].redeem_at | Yes | "account" | "checkout" | null | Where the gift card is used. account: add it to the user's account balance on the merchant site, then check out normally. checkout: enter it at the merchant's payment step. Null: not known yet. |
Synthetic result
Example synthetic-compatible-payload (synthetic data):
{
"ok": true,
"contract": "envoy@2026-10",
"tool": "get_merchants",
"request_id": "req_synthetic",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"server_time": "2026-09-29T12:00:00Z",
"replayed": false,
"purchase": null,
"data": {
"merchants": [
{
"name": "shop.example.test",
"domain": "shop.example.test",
"amounts": [
{
"minor": 50000,
"currency": "INR",
"display": "₹500.00"
},
{
"minor": 100000,
"currency": "INR",
"display": "₹1,000.00"
}
],
"amount_range": null,
"discount_percent": 2.5,
"redeem_at": "checkout"
}
]
},
"next": {
"action": "continue",
"tool": null,
"args": null,
"instruction": "Envoy needs nothing more. Carry on with the user's task.",
"after_seconds": null,
"by": null
},
"user_action": null,
"follow_ups": [],
"error": 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. |