Buy and follow a gift card

Discover a supported merchant, start one gift-card purchase, and follow its money, voucher and next action without paying twice.

Call list_gift_card_merchants before you offer a gift card. Start the chosen purchase with rail: "gift_card". Follow each reply's briefing and next until Envoy stops the checking or supplies the gift card.

Support revision: envoy@2026-10. Last updated: 3 November 2026.

This guide applies to agents using MCP or the HTTP API. Available merchants, funding and checkout routes depend on the connected account and service. A listed capability does not prove that every route is available for your purchase. Gift cards are offered only where the connected Envoy service enables them. When they are not enabled, list_gift_card_merchants returns no merchants; do not offer a gift card.

ChatGPT and Claude connectors. A connection Envoy identifies as ChatGPT has no gift cards: it does not list list_gift_card_merchants and buys only from Elixir's marketplace (search_products, then start_purchase with its product_id). A connection Envoy identifies as Claude (claude.ai web, Desktop and Cowork connectors) still lists list_gift_card_merchants, but Envoy drops rail there: a start with rail: "gift_card" becomes a purchase Envoy checks out itself at the merchant total, with no voucher and no payment link. Do not offer a gift card, a gift-card price or a discount on either. Claude Code and API clients with localhost callbacks keep the default profile, where this guide applies.

Call list_gift_card_merchants. Offer only a returned merchant.
Read its amounts or amount_range. Read redeem_at to learn whether the merchant accepts value in its account or at checkout.
Treat discount_percent as an advertised maximum, not a quote or guaranteed saving. Do not promise a discounted charge from discovery. The user confirms the actual payable on the returned payment link or in the Envoy app; do not calculate it from face value or a percentage.
Call start_purchase with rail: "gift_card", one idempotency_key, the merchant URL, total, items and the user's request. Supply the requested delivery details.
Save the purchase reference. Follow the returned user task, checkout_by and next.

On the default profile, without rail: "gift_card", Envoy may select a one-time card instead. If the requested amount is refused, follow the reply. Do not silently increase the purchase or split it.

See the generated MCP tool reference or HTTP tool reference for current inputs and replies.

Which purchase is this, and which reference do I keep?

Keep purchase_id and the original idempotency_key for the task. Later calls accept the purchase ID or original key as purchase.

Retry a lost start_purchase reply with the same key and original input. A new key starts a new purchase. Reconnecting does not settle or replace the existing purchase. An explicitly offered linked retry can create a child purchase with a different ID. Keep both references and follow the returned call; do not assume one public reference spans every retry leg.

Over MCP, purchase_id is for tool calls. Do not show it, keys or the JSON line to the user. Give the returned support_ref only when the user asks for help. Where supplied, the short reference stays stable for that purchase. Some replies omit it. A reply without a purchase can supply a reference for that call instead.

Envoy's agent pages use the same short reference. The current tool reply does not establish an always-visible matching reference on every mobile-app screen. Do not assume a mobile-app receipt or merchant order reference can replace the purchase reference. Keep a merchant order reference separately when supplied.

If the reference is lost, call get_account for active_purchase, or get_purchase_status without purchase. active_purchase points to one open purchase and is not a complete list when several are open. An unavailable purchase read does not mean no purchase exists. See Recover a purchase.

What happened to the money, and how much was paid?

Read money separately from the voucher and merchant checkout. A gift card's face value is not necessarily what the user pays.

Amount	Where to read it	What you may say
Gift-card face value	HTTP `purchase.amount`; the MCP briefing and released voucher's `value`	The value available on the gift card.
Payment-link price	`purchase.funding.amount`, only when a payment-link task is returned	The amount the user must pay on that link.
In-app price	The user sees it on the Envoy app's payment screen	Do not substitute the face value or calculate it from a discovery discount.
Captured payment or refund amount	The quote in the purchase reply, when present, is authoritative for face, payable and discount. Without it, the payable is unknown to the agent; the app shows it before approval.	Do not claim an exact figure from the face value, merchant total or discount.
Recorded completion amount	HTTP `purchase.money.paid` and `purchase.receipt.paid`, when present	Do not use this as proof of the exact funding capture or refund.

The available funding routes are:

Route	User action	Amount distinction
Prepaid balance	The user approves in the Envoy app.	The quote, when present, gives the payable. Without it, the app shows the payable before approval.
Payment link	The user opens and pays the returned link. The agent never pays it.	The returned payable can be lower than the face value.
In-app payment	The user pays on the Envoy app's payment screen.	The app shows the payable, which can differ from the face value.

An approve task does not identify the funding source. It can mean balance approval or in-app payment. Do not infer which source was charged. The connected service determines whether in-app payment is available; do not promise a route before the reply supplies it.

MCP `money`	HTTP `purchase.money.status`	Meaning
`not_charged`	`not_started`	No charge is reported for this purchase.
`set_aside`	`debited`, before completion	Funding moved; merchant checkout is not confirmed by this fact.
`charged`	`debited`, on completion	Envoy reports the purchase complete with a debit.
`refunding`	`refund_pending`	A refund is in progress. It has not been confirmed returned.
`refunded`	`refunded`	Envoy reports the refund confirmed.
`unknown`	`unknown`	The money outcome is unknown. Do not pay again.

Some MCP error replies omit money. A missing field supplies no money fact; it never means zero or refunded. Follow the returned recovery call.

Tell the user the refund status the reply supplies. Do not promise an amount, destination or arrival date that the reply does not establish. A stopped purchase alone is not proof of a refund.

Has the voucher been issued or delivered?

The current reply does not separately label voucher progress as not started, issuing, outcome unknown, issued or delivered. Do not turn a general purchase state into an exact issuance claim.

MCP situation	HTTP state	What you know
`working`	`processing`	Envoy is preparing the gift card or handling checkout. This does not prove the voucher request was sent.
`confirming` or `needs_support`	`verifying`	Envoy is checking an unresolved result. This does not identify an exact voucher stage.
`ready`	`ready`	Gift-card details may be released through the authorized status read.
`done`	`completed`	The purchase is complete. This is separate from the earlier voucher handout.

The handout is MCP card with kind: "gift_card" and voucher. On HTTP it is data.payment_details with the same kind and voucher. The voucher includes its value, redemption instructions and expiry when known.

A ready reply without the voucher is not a handout. Follow next to obtain the details. A handout supplies an issued voucher in that reply; there is no separate durable delivery-history field.

Read the brand's redemption instructions. For redeem_at: "account", add the value to the user's merchant account before checkout. For redeem_at: "checkout", use it at the merchant payment step. If the location is unknown, do not guess.

Use the released voucher once as the reply directs. Never show its code or PIN to the user. Never put them in messages, logs, files, screenshots, memory, reports or feedback.

Do not poll or automatically refresh a ready purchase. A ready status read releases the voucher again. Continue with the instructed redemption and report. See Credentials and secrets.

Who acts next: the user, the agent or Envoy?

Over MCP, read the briefing's What to do line and next. Over HTTP, read user_action, purchase.user_task, purchase.checkout_by and next.

Reply	Actor and action
`working` or `confirming` with a continuation	Envoy's background processing or provider checks continue. The agent follows the returned check; it does not issue or refund a voucher itself.
`needs_support`, or an unresolved result with no continuation	Follow the briefing. Stop repeated checks, tell the user what is unresolved, and use Envoy support when needed.
User task `approve` on a gift card	The user completes the approval or payment in the Envoy app. Do not give them a payment link unless the reply supplies a payment-link task.
User task `pay_link`	The user pays the full returned link themselves. The agent never opens or pays it.
A question	The agent shows `purchase.question.prompt` verbatim, waits for the user, then calls `answer_purchase_question` with the returned arguments and their answer.
`checkout_by: "envoy"`	Envoy handles merchant checkout. The agent follows status and never opens the payment step or reports checkout.
`checkout_by: "agent"` with a voucher handout	The agent redeems the gift card as instructed, then reports what the merchant confirmed.

Tell the user the requested app step once. Continue the supplied status calls while the user acts. The user does not need to say "done" while Envoy still supplies a next status call.

Use the latest reply because checkout ownership can change. Never infer ownership from a previous purchase or from the presence of money alone.

May I cancel, retry or start another purchase?

Before a checkout report, request cancellation with cancel_purchase when the user changes their mind. Read the returned purchase and next action. A cancellation request does not prove the purchase stopped or money returned.

If Envoy refuses cancellation because issuance has started, do not repeat the cancellation. Continue the same purchase as the reply directs. Do not promise delivery or a refund beyond what that reply says.

After redemption, call report_checkout_result only when checkout belongs to the agent. Report paid only when the merchant confirmed payment. If completion is unclear, report failed with failure_reason: other.

A report records the agent's observation; it does not establish settlement. Follow status after the report. Do not retry payment to retry a report.

Follow a retry only when the latest reply permits it. Repeat an allowed tool retry with its original input and key. Do not invent a gift-card retry from a one-time-card recovery option.

An unknown outcome stops another payment, another rail and a replacement purchase. Keep the same reference until Envoy resolves it. A timeout, missing voucher or cancellation request is not evidence that starting again is safe.

See Recover a purchase and Errors and reason codes.

When should I check again, stop waiting or ask for help?

Follow the returned cadence. MCP next.wait_seconds is the delay before the next call. On HTTP, use next.after_seconds; pass next.args unchanged.

A status call with after_revision can wait for a change. The wait inside that call is different from the delay before calling. Do not replace returned arguments with a local polling schedule.

Stop checking when Envoy supplies no next tool or tells you to stop. On HTTP, also respect next.by. Tell the user what remains unresolved. Do not treat a checking deadline as a refund deadline or permission to pay again.

Returned time	Meaning
HTTP `user_action.by` or `purchase.approval.decide_by`	Deadline for the requested user action.
`purchase.funding.expires_at`	Deadline for the returned payment link.
Payment details `expires_at` or HTTP `purchase.payment_ready.expires_at`	Spending-access deadline, when supplied.
`voucher.valid_until`	Gift-card validity, when supplied.

Use server-supplied times and the briefing's relative wording. A missing expiry does not mean expired. A payment deadline passing does not prove that an in-flight payment failed.

The current purchase reply supplies no separate refund-arrival promise, provider-check schedule or escalation deadline. Do not invent one. If checking stops with an unresolved result, follow the briefing and direct the user to Envoy support in the app when needed. Give support_ref if they ask for help. Never include the voucher code or PIN.

See Replies and next steps and Make a purchase, start to finish.