Outcomes

Every call that completes returns an outcome field. Branch on it to decide what to show and what to do next. An outcome is a normal result, not an error; errors come back with isError: true instead. See Errors & Retries.

outcome	Meaning	What the response contains	What your agent should do
SUCCESS	The agent found products and answered.	answer_items is not empty. item_comparison_table is present when the agent compared products.	Show answer_text with the product cards and any comparison table.
NEEDS_CLARIFICATION	The request was too open. The agent asks the shopper one question first.	answer_items is empty. answer_text is the question. conversation_id is set.	Show the question. Send the shopper's reply as the next query with the same conversation_id.
NO_RESULTS	The request was understood, but nothing in the catalog matched.	answer_items is empty. answer_text says nothing matched. conversation_id is set.	Show answer_text. Suggest loosening the budget, brand, or specs, and continue in the same conversation.
UNSUPPORTED	The request is out of scope: cart, orders, coupons or vouchers, store account sign-in, or a market other than US.	answer_items is empty. answer_text states what is not supported. conversation_id is null unless you sent one.	Show answer_text. Do not retry the same request.

Charging by outcome

outcome	Catalog searched	Credits
SUCCESS, NEEDS_CLARIFICATION, NO_RESULTS	Yes	Input tokens, output tokens, and tool calls used by the turn
UNSUPPORTED	No	0
Error (isError: true)	n/a	0

See Credits.

Example: unsupported

{
  "request_id": "53eeb5f5-91fa-488d-9c75-fe4e0f343882",
  "conversation_id": null,
  "outcome": "UNSUPPORTED",
  "answer_text": "This channel cannot look up or place orders.",
  "answer_items": [],
  "usage": { "credits_used": 0, "billing_status": "NOT_REQUIRED" }
}

An unsupported request does not start a new conversation. If you sent a conversation_id, it is returned unchanged and you can keep using it.