*MCP › Reference › Rentals › Orders*

# Return order lines

> Marks the returning material as returned: which line, how many units and in what condition.

> **Send your own idempotencyKey:** A retry without the same key duplicates the effect. Send your own `idempotencyKey` (a UUID) and resend the same one if you retry.

> **Requires human confirmation:** Put this tool on your client's “ask before running” list. The annotations are hints that the server declares, not guarantees: do not decide the approval from `destructiveHint` alone. The server flags this tool with `_meta["anthropic/requiresUserInteraction"]`, which clients that honor it use to ask a person before every call.

It hangs off the resource and not off an order because an unload crosses orders, which is what this call resolves at once. Send `Idempotency-Key`: returning the same line twice would put the material into the pool twice, and each line goes at most once per request (add up its quantities). It is a batch: `atomic` is true by default, so a line that cannot be returned rejects the whole batch with 409 and one issue per failing line, touching nothing; with `atomic: false` each order is processed on its own and the response is 207 with one result per element, where the failed ones were not returned and the rest HAVE been. On success the response is 200 with one result per element, in request order.

TOOL `filmo_orders_line_items_return` · `orders:write` · 120/min · Server annotation: Destructive · Requires human confirmation · Send your own idempotencyKey

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | object[] | Yes | Lines being returned. At least one, at most 500, each line at most once. |
| `items.lineItemId` | string | Yes | Order line being returned. |
| `items.checkInQuantity` | number | Yes | Units being returned, at least one. It can be a partial return. |
| `items.returnCondition` | string | Yes | Physical condition the material comes back in: `good`, `damaged`, `lost`, `needs_repair` or `incident`. `good`, `damaged`, `lost`, `needs_repair`, `incident` |
| `checkedInAt` | string<date-time> | No | Effective date of the return, in ISO 8601 with offset. Defaults to now. |
| `atomic` | boolean | No | All or nothing (default true): if any line cannot be returned, none is, and the response is 409 with one issue per line. With false, each order is processed on its own, the response is 207 and every element carries its own status. = `true` |
| `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `index` | integer | Position of the element in the request array. |
| `id` | string | Identifier of the element as it was sent. |
| `status` | string | `returned` or `failed`. `returned`, `failed` |
| `error` | object | Why it failed; null when `returned`. |
| `error.code` | string | Stable error code of the element, from the same catalog as `errors[]`. |
| `error.message` | string | Localized reason. |

*Call · filmo_orders_line_items_return*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_orders_line_items_return",
    "arguments": {
      "items": [
        {
          "lineItemId": "line_8f2a1c",
          "checkInQuantity": 1,
          "returnCondition": "good"
        }
      ],
      "idempotencyKey": "<a UUID you generate>"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": [
      {
        "index": 1,
        "id": "id_8f2a1c",
        "status": "returned",
        "error": {
          "code": "<code>",
          "message": "<message>"
        }
      }
    ],
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`POST /api/v1/orders/line-items/returns`](https://docs.filmo.io/rest-api/endpoint-reference/orders/return-order-lines).

---

Canonical URL: https://docs.filmo.io/mcp/tools/orders/filmo-orders-line-items-return  
Last updated: 2026-10-25