list_gift_card_merchants

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

List merchants selling gift cards. Only a listed merchant can be bought; Envoy picks from amounts or amount_range for the cart total. discount_percent is an indicative product maximum; null means none reported. Say "up to". The actual purchase quote is authoritative; until available, payable is unknown. redeem_at says 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. To buy, call start_purchase with rail "gift_card".

Title	Service	Read only	Destructive	Idempotent	External sites
List gift-card merchants	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": "list_gift_card_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.

Downloads

OpenAPI · MCP catalog · Synthetic examples · Schemas