keepcard_submit_return_reason
Submit the return reason for an eligible return session. The store decision engine evaluates the reason and returns either a keep offer, where the customer keeps the item and receives a discount code, or routes directly to the standard return portal. Call after keepcard_check_return_eligibility for single-item orders or after keepcard_select_return_items for multi-item orders. Map plain language reasons to slugs: "changed my mind" or similar -> changed_mind, "not expected" -> not_expected, "broken" or "damaged" -> damaged, size/fit issues -> size. The server also normalizes these automatically. If the result includes a keep_offer, the next customer reply should usually map directly to keepcard_accept_keep_offer for yes or accept style replies, or keepcard_decline_keep_offer for no, decline, or return-it style replies. If outcome=route_to_return and return_url is present, do not ask another question: display the return link immediately and treat customer_message as final user-facing text.
Input Schema
{
"type": "object",
"required": [
"session_id",
"reason"
],
"properties": {
"reason": {
"type": "string",
"description": "Return reason slug. Common values include size, changed_mind, not_expected, damaged, and other. Natural language such as \"changed my mind\", \"cahnge my mind\", \"not expected\", or \"broken\" is also accepted and normalized server-side."
},
"session_id": {
"type": "string",
"description": "The session_id returned by keepcard_check_return_eligibility."
},
"reason_text": {
"type": "string",
"description": "Optional verbatim detail from the customer, up to 500 characters."
}
}
}Stores exposing the keepcard_submit_return_reason tool
Get the agentic commerce digest every Monday
Real adoption data, ecosystem trends, new spec versions, and the stores that broke or recovered this week. Read by founders and engineers building the next generation of commerce.