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).

PATCH

/api/v1/subrents/{subrentId}

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

{
  "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"
  }
}

{
  "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/addon_required",
  "title": "Add-on required",
  "status": 402,
  "code": "addon_required",
  "detail": "Your plan does not include the add-on this operation requires",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredAddon": "purchases"
}

{
  "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": "subrents: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/precondition_failed",
  "title": "Precondition failed",
  "status": 412,
  "code": "precondition_failed",
  "detail": "The resource changed since you read it: read it again and retry",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "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

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.

Authorizations

Bearer API key with the scope below. subrents: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"

If-Matchstring

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.

Example:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Path parameters

subrentIdstringRequired

Subrent identifier.

Limits: min length 1

Body

application/json

Body schema: SubrentUpdateBody

statusstring

New subrent status.

Available options: pending, active, completed, cancelled

startDatestring<date-time> | null

Start of the subrent (ISO 8601 with offset); null clears it.

endDatestring<date-time> | null

End of the subrent (ISO 8601 with offset); null clears it.

needResolvedboolean

true when the material need that motivated the subrent is already covered.

purchaseOrderIdstring | null

Purchase order the subrent is linked to; null unlinks it.

Limits: min length 1

linkQuantityinteger

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.

Limits: > 0

notesstring | null

Subrent notes; null clears them.

Response

application/json

Successful response.

Response schema: SubrentDto

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

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

dataobject

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.

Show child attributes

data.idstring

Unique subrent identifier.

data.typestring

bulk if it is a quantity of a bulk item, serialized if it is a specific unit.

Available options: bulk, serialized

data.statusstring

Subrent status.

Available options: pending, active, completed, cancelled

data.itemIdstring

Identifier of the subrented item.

data.itemNamestring

Name of the subrented item.

data.itemSkustring | null

Item SKU; null if it has none.

data.quantitynumber | null

Subrented units; null if it is a specific unit.

data.serializedItemIdstring | null

Identifier of the specific unit; null if bulk.

data.serializedItemCodestring | null

Code of the specific unit; null if bulk.

data.providerIdstring | null

Identifier of the supplier that lends the material; null if not decided yet.

data.providerNamestring | null

Supplier name; null if not decided yet.

data.needResolvedboolean

true if the need is already covered, that is, if the supplier and material are confirmed.

data.startDatestring<date-time> | null

Start of the required period in ISO 8601 UTC; null if not set.

data.endDatestring<date-time> | null

End of the required period in ISO 8601 UTC; null if not set.

data.pickupDatestring<date-time> | null

Pickup date from the supplier in ISO 8601 UTC; null if not set.

data.returnDatestring<date-time> | null

Return date to the supplier in ISO 8601 UTC; null if not set.

data.orderIdstring | null

Order that motivates the subrent; null if it has none.

data.projectIdstring | null

Associated project; null if it has none.

data.purchaseOrderIdstring | null

Purchase order that formalizes it; null if none has been issued.

data.spaceIdstring | null

Warehouse where the material is received; null if not applicable.

data.notesstring | null

Subrent notes; null if it has none.

data.createdAtstring<date-time>

Creation date in ISO 8601 UTC.

data.updatedAtstring<date-time>

Last modification date in ISO 8601 UTC.

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

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

Rentals
Subrent
Material rented from another company to cover a job.

Was this page helpful?

Request examples

Authorizations

Headers

Path parameters

Body

Response

Errors

Deprecation

Related

Related pages

Subrent