> ## 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_set_substitution

> Set the out-of-stock preference for one item in a placed order.

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

**Behavior:** idempotent.

<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

Set the out-of-stock preference for one item in a placed order. item\_msid is the item's msid from buy\_search\_products; preference is similar (any similar item), refund, or contact.

## Inputs

| Field                     | Type                                     | Description                              |
| ------------------------- | ---------------------------------------- | ---------------------------------------- |
| `merchant` *(required)*   | string                                   |                                          |
| `order_id` *(required)*   | string                                   | the order id from buy\_order\_history    |
| `item_msid` *(required)*  | string                                   | the item msid from buy\_search\_products |
| `preference` *(required)* | string: `similar` · `refund` · `contact` |                                          |

## Returns

None.

## Example call

```json theme={null}
{
  "tool": "buy_set_substitution",
  "arguments": {
    "merchant": "\u2026",
    "order_id": "\u2026",
    "item_msid": "\u2026",
    "preference": "\u2026"
  }
}
```