> ## 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"
  }
}
```