*REST API › Endpoint reference › Rentals › Subrents*

# Update a subrent

> Changes the terms of a subrent: status (`pending`, `active`, `completed` or `cancelled`), dates, notes, whether the need is resolved and its link to a purchase order (send only the fields to change).

`linkQuantity` deserves attention: if it is LOWER than the quantity of the subrent, the record is SPLIT —the original keeps that quantity and another one is born with the rest—, and what is returned is the original. What is paid to the supplier is NOT part of the public contract, neither to read nor to write. It requires subrents in the plan of the account —included in the current offer, and with the purchases add-on in older plans— (402 without it). Returns the full subrent, the same projection as its GET.

`PATCH /api/v1/subrents/{subrentId}` — scope `subrents:write`

Scope: `subrents:write` · 120/min · Strict tenancy · Add-on (402) · Idempotency-Key · If-Match · MCP: `filmo_subrents_update`

## Authorizations

Bearer API key with the scope below. `subrents: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. |
| `If-Match` | string | No | Optimistic locking: the `ETag` you read from the resource (or `*`). If the resource changed since, the write is rejected with `412 precondition_failed` before doing anything; read it again and retry. Without the header the write always proceeds. |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subrentId` | string | Yes | Subrent identifier. |

## Body

Body schema: `SubrentUpdateBody`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | New subrent status. `pending`, `active`, `completed`, `cancelled` |
| `startDate` | string<date-time> | No | Start of the subrent (ISO 8601 with offset); null clears it. |
| `endDate` | string<date-time> | No | End of the subrent (ISO 8601 with offset); null clears it. |
| `needResolved` | boolean | No | true when the material need that motivated the subrent is already covered. |
| `purchaseOrderId` | string | No | Purchase order the subrent is linked to; null unlinks it. |
| `linkQuantity` | integer | No | Quantity linked to the purchase order. If it is lower than the subrent quantity, the record is split: the original keeps this quantity and a new one is created with the rest. |
| `notes` | string | No | Subrent notes; null clears them. |

## Request examples

*Update a subrent*

**cURL**

```bash
curl https://app.filmo.io/api/v1/subrents/subr_8f2a1c \
  --request PATCH \
  --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 '{
  "status": "active",
  "purchaseOrderId": "po_00317",
  "needResolved": true,
  "notes": "Cubierto con la grúa de Alquileres Norte"
}'
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/subrents/subr_8f2a1c', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'active',
    purchaseOrderId: 'po_00317',
    needResolved: true,
    notes: 'Cubierto con la grúa de Alquileres Norte'
  })
})
```

**Python**

```python
import uuid
import requests

requests.patch(
    "https://app.filmo.io/api/v1/subrents/subr_8f2a1c",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY",
      "Idempotency-Key": str(uuid.uuid4()),
      "Content-Type": "application/json"
    },
    json={
      "status": "active",
      "purchaseOrderId": "po_00317",
      "needResolved": True,
      "notes": "Cubierto con la grúa de Alquileres Norte"
    }
)
```

## Response

Response schema: `SubrentDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 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). |
| 402 | Add-on required (addon_required): the account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 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. |
| 412 | Precondition failed (precondition_failed): the `If-Match` entity tag does not match the current representation. Read the resource again and retry. |
| 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 | Material rented from another company to cover a job. It does NOT include what is paid to the supplier: crossing it with the sale price of the line would give the exact margin. |
| `data.id` | string | Unique subrent identifier. |
| `data.type` | string | bulk if it is a quantity of a bulk item, serialized if it is a specific unit. `bulk`, `serialized` |
| `data.status` | string | Subrent status. `pending`, `active`, `completed`, `cancelled` |
| `data.itemId` | string | Identifier of the subrented item. |
| `data.itemName` | string | Name of the subrented item. |
| `data.itemSku` | string | Item SKU; null if it has none. |
| `data.quantity` | number | Subrented units; null if it is a specific unit. |
| `data.serializedItemId` | string | Identifier of the specific unit; null if bulk. |
| `data.serializedItemCode` | string | Code of the specific unit; null if bulk. |
| `data.providerId` | string | Identifier of the supplier that lends the material; null if not decided yet. |
| `data.providerName` | string | Supplier name; null if not decided yet. |
| `data.needResolved` | boolean | true if the need is already covered, that is, if the supplier and material are confirmed. |
| `data.startDate` | string<date-time> | Start of the required period in ISO 8601 UTC; null if not set. |
| `data.endDate` | string<date-time> | End of the required period in ISO 8601 UTC; null if not set. |
| `data.pickupDate` | string<date-time> | Pickup date from the supplier in ISO 8601 UTC; null if not set. |
| `data.returnDate` | string<date-time> | Return date to the supplier in ISO 8601 UTC; null if not set. |
| `data.orderId` | string | Order that motivates the subrent; null if it has none. |
| `data.projectId` | string | Associated project; null if it has none. |
| `data.purchaseOrderId` | string | Purchase order that formalizes it; null if none has been issued. |
| `data.spaceId` | string | Warehouse where the material is received; null if not applicable. |
| `data.notes` | string | Subrent notes; null if it has none. |
| `data.createdAt` | string<date-time> | Creation date in ISO 8601 UTC. |
| `data.updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC. |
| `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": {
    "id": "subrent_9f3a2b",
    "type": "bulk",
    "status": "pending",
    "itemId": "item_9f3a2b",
    "itemName": "Example item name",
    "itemSku": "Example item sku",
    "quantity": 1,
    "serializedItemId": "serialized_item_9f3a2b",
    "serializedItemCode": "Example serialized item code",
    "providerId": "provider_9f3a2b",
    "providerName": "Example provider name",
    "needResolved": true,
    "startDate": "2026-09-01T08:00:00.000Z",
    "endDate": "2026-09-01T08:00:00.000Z",
    "pickupDate": "2026-09-01T08:00:00.000Z",
    "returnDate": "2026-09-01T08:00:00.000Z",
    "orderId": "order_9f3a2b",
    "projectId": "project_9f3a2b",
    "purchaseOrderId": "purchase_order_9f3a2b",
    "spaceId": "space_9f3a2b",
    "notes": "Example text.",
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |
| 402 | `addon_required` | The account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 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. |
| 412 | `precondition_failed` | The `If-Match` entity tag does not match the current representation. Read the resource again and retry. |
| 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/subrents/update-a-subrent  
Last updated: 2026-10-25