*REST API › Endpoint reference › Rentals › Orders*

# Return order lines

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

> **Send your own Idempotency-Key:** A retry without the same key duplicates the effect. Send your own Idempotency-Key and follow the retry table. With `atomic: false` a 207 lists the lines that failed: resend only those, with a new key.

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.

`POST /api/v1/orders/line-items/returns` — scope `orders:write`

Scope: `orders:write` · 120/min · Idempotency-Key · Send your own Idempotency-Key · MCP: `filmo_orders_line_items_return`

## Authorizations

Bearer API key with the scope below. `orders:write`

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | No | Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 `validation_error`, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the `Idempotent-Replay: true` header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout. |

## Body

Body schema: `OrderLineItemsReturnBody`

| 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` |

## Request examples

*Return order lines*

**cURL**

```bash
curl https://app.filmo.io/api/v1/orders/line-items/returns \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "lineItemId": "oli_00913",
      "checkInQuantity": 3,
      "returnCondition": "good"
    },
    {
      "lineItemId": "oli_01120",
      "checkInQuantity": 1,
      "returnCondition": "damaged"
    }
  ],
  "checkedInAt": "2026-09-10T18:30:00+02:00"
}'
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/orders/line-items/returns', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      {
        lineItemId: 'oli_00913',
        checkInQuantity: 3,
        returnCondition: 'good'
      },
      {
        lineItemId: 'oli_01120',
        checkInQuantity: 1,
        returnCondition: 'damaged'
      }
    ],
    checkedInAt: '2026-09-10T18:30:00+02:00'
  })
})
```

**Python**

```python
import uuid
import requests

requests.post(
    "https://app.filmo.io/api/v1/orders/line-items/returns",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY",
      "Idempotency-Key": str(uuid.uuid4()),
      "Content-Type": "application/json"
    },
    json={
      "items": [
        {
          "lineItemId": "oli_00913",
          "checkInQuantity": 3,
          "returnCondition": "good"
        },
        {
          "lineItemId": "oli_01120",
          "checkInQuantity": 1,
          "returnCondition": "damaged"
        }
      ],
      "checkedInAt": "2026-09-10T18:30:00+02:00"
    }
)
```

## Response

Response schema: `OrderLineReturnResultDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 207 | Multi-Status (`atomic: false`): the batch was processed element by element; read each `status` and `error`. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 404 | Resource not found (not_found): it does not exist or is outside the scope of the API key. |
| 409 | Conflict (conflict): the current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. |
| 422 | Idempotency-Key reused (idempotency_key_reused): the same key was used before with a different body. Change the key. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.index` | integer | Position of the element in the request array. |
| `data.id` | string | Identifier of the element as it was sent. |
| `data.status` | string | `returned` or `failed`. `returned`, `failed` |
| `data.error` | object | Why it failed; null when `returned`. |
| `data.error.code` | string | Stable error code of the element, from the same catalog as `errors[]`. |
| `data.error.message` | string | Localized reason. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": [
    {
      "index": 1,
      "id": "order_line_return_result_9f3a2b",
      "status": "returned",
      "error": {
        "code": "Example code",
        "message": "Example text."
      }
    }
  ]
}
```

**207**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.index` | integer | Position of the element in the request array. |
| `data.id` | string | Identifier of the element as it was sent. |
| `data.status` | string | `returned` or `failed`. `returned`, `failed` |
| `data.error` | object | Why it failed; null when `returned`. |
| `data.error.code` | string | Stable error code of the element, from the same catalog as `errors[]`. |
| `data.error.message` | string | Localized reason. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 207*

```json
{
  "data": [
    {
      "index": 1,
      "id": "order_line_return_result_9f3a2b",
      "status": "returned",
      "error": {
        "code": "Example code",
        "message": "Example text."
      }
    }
  ]
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |
| 404 | `not_found` | It does not exist or is outside the scope of the API key. |
| 409 | `conflict` | The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. |
| 422 | `idempotency_key_reused` | The same key was used before with a different body. Change the key. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/orders/return-order-lines  
Last updated: 2026-10-25