Orders

Return order lines

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

POST

/api/v1/orders/line-items/returns

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.jsfetch('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' }) })Pythonimport 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" } )

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

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

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "orders:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

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.

Authorizations

Bearer API key with the scope below. orders:write

Headers

Idempotency-Keystring

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.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

Body

application/json

Body schema: OrderLineItemsReturnBody

itemsobject[]Required

Lines being returned. At least one, at most 500, each line at most once.

Limits: min 1 items, max 500 items

Show child attributes

items.lineItemIdstringRequired

Order line being returned.

Limits: min length 1

items.checkInQuantitynumberRequired

Units being returned, at least one. It can be a partial return.

Limits: min 1

items.returnConditionstringRequired

Physical condition the material comes back in: good, damaged, lost, needs_repair or incident.

Available options: good, damaged, lost, needs_repair, incident

checkedInAtstring<date-time>

Effective date of the return, in ISO 8601 with offset. Defaults to now.

atomicbooleandefault:true

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.

Response

application/json

Successful response.

Response schema: OrderLineReturnResultDto

Envelope: OrderLineReturnResultItems. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay

dataobject[]

Show child attributes

data.indexinteger

Position of the element in the request array.

data.idstring

Identifier of the element as it was sent.

data.statusstring

returned or failed.

Available options: returned, failed

data.errorobject | null

Why it failed; null when returned.

Show child attributes

data.error.codestring

Stable error code of the element, from the same catalog as errors[].

data.error.messagestring

Localized reason.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

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.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

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

Was this page helpful?

Request examples

Authorizations

Headers

Body

Response

Errors

Deprecation

Related