> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# buy_return_order

> Start a return for a placed retail order (Amazon/Walmart lane) — use the order id from buy_order_history / the placement confirmation.

Connect to `https://mcp.agentcard.sh/mcp` with the **user's connection token** (or a `buy_token` for org-owned accounts).

**Behavior:** destructive.

<Note>Not in the default `tools/list`. It is still callable by exact name, and appears when the client sends the `x-expert-tools: 1` header.</Note>

## What it does

Start a return for a placed retail order (Amazon/Walmart lane) — use the order id from buy\_order\_history / the placement confirmation. Returns the WHOLE order unless product\_ids narrows it. reason must be one of the listed codes (pick the closest to the user's words; use 'other' + notes when none fits). The refund is automatic once the merchant receives the items: it posts back to the card that paid. Return labels are issued asynchronously — the create response usually has none yet; poll buy\_return\_status and relay the label URLs when they appear.

## Inputs

| Field | Type | Description |
| - | - | - |
| `merchant` *(required)* | string | merchant slug (e.g. retail) |
| `order_id` *(required)* | string | the placed order id (from buy\_order\_history or the placement confirmation) |
| `reason` *(required)* | string: `damaged` · `not_delivered` · `empty_box` · `wrong_item` · `defective` · `not_as_described` · `wrong_size` · `no_longer_needed` · `other` | why the user is returning — closest code to their words; 'other' needs notes |
| `notes` | string | extra context in the user's words (recommended; required in spirit for reason 'other') |
| `product_ids` | array | return only these products (ids from the order); omit to return every item |

## Returns

None.

## Example call

```json theme={null}
{
  "tool": "buy_return_order",
  "arguments": {
    "merchant": "\u2026",
    "order_id": "\u2026",
    "reason": "\u2026"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.