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

# How do I request a replacement order?

> PUT /api/v1/orders/{order_id}/request_replacement with a reason. Blend creates a brand-new order linked to the original, and it does not consume a fill from the prescription.

A replacement is a genuinely new order — its own order number, its own lifecycle — with two differences from an ordinary one: it carries a link back to the order it replaces, and **it does not decrement fills** on the underlying prescription. A patient whose shipment arrived damaged doesn't lose a refill because of it.

```bash theme={null}
curl -X PUT https://api.byblend.com/api/v1/orders/ORD250312003548IAU4/request_replacement \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Product arrived damaged" }'
```

The `reason` reaches the pharmacy staff who fulfil the request, so make it specific — "damaged in transit, vial cracked" is more actionable than "problem".

## Tracking the request

The order object carries the full replacement picture:

| Field                          | What it tells you                                  |
| ------------------------------ | -------------------------------------------------- |
| `replacement_request_status`   | `pending`, `fulfilled`, `declined`, or `cancelled` |
| `replacement_requested_at`     | When the request was raised                        |
| `replacement_requested_reason` | The reason you sent                                |
| `replacement_order_ids`        | The new orders created from this one               |
| `is_replacement`               | True on the replacement order itself               |
| `original_order_id`            | On the replacement, points back to the original    |

## Finding the replacement order

Once created, the replacement is visible immediately — you don't need to wait for anyone to send you the number. Poll the original order and read `replacement_order_ids`, or find it in the Blend Dashboard on the orders list, filtered to your account. It also appears on the patient's order history.

<Note>
  Approvals and declines are recorded as comments on the replacement thread, and anyone who has previously commented on that thread is notified by email. If a request is declined, the reason reaches the requester through that channel.
</Note>

## What a replacement doesn't do

A replacement also doesn't cancel or reverse the original order. The original keeps its own status and history; the two are linked, not merged.

## Replacement, cancellation, or a new order?

* Shipment was wrong or damaged, patient should not lose a fill → **replacement**
* Order shouldn't ship at all and hasn't been picked → [cancel](/guides/cancel-an-order)
* Order shouldn't ship yet → [pause](/guides/pause-an-order)
* Patient wants more product and has fills remaining → an ordinary new order

<CardGroup cols={2}>
  <Card title="Replace an order" icon="rotate" href="/api-reference/orders/replace-an-order">
    PUT /orders/{'{'}order\_id{'}'}/request\_replacement
  </Card>

  <Card title="Get an order's details" icon="magnifying-glass" href="/api-reference/orders/get-an-orders-details">
    Read `replacement_request_status`
  </Card>

  <Card title="Get orders" icon="list" href="/api-reference/orders/get-orders">
    Find replacements across your account
  </Card>

  <Card title="Request cancellation" icon="hand" href="/api-reference/orders/request-cancellation-of-an-order">
    When it shouldn't ship instead
  </Card>
</CardGroup>