Availability

Check item availability

Checks the availability of a batch of items (1-100) over a common date range, each with the quantity you intend to book (1 by default).

POST

/api/v1/availability/check

curl https://app.filmo.io/api/v1/availability/check \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "itemId": "itm_9f3a2b",
      "variantId": "var_rojo",
      "transactionType": "rental",
      "quantity": 4
    },
    {
      "itemId": "itm_camara_a7"
    }
  ],
  "startDate": "2026-09-01T08:00:00+02:00",
  "endDate": "2026-09-05T20:00:00+02:00"
}'

Node.jsfetch('https://app.filmo.io/api/v1/availability/check', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ items: [ { itemId: 'itm_9f3a2b', variantId: 'var_rojo', transactionType: 'rental', quantity: 4 }, { itemId: 'itm_camara_a7' } ], startDate: '2026-09-01T08:00:00+02:00', endDate: '2026-09-05T20:00:00+02:00' }) })Pythonimport requests requests.post( "https://app.filmo.io/api/v1/availability/check", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Content-Type": "application/json" }, json={ "items": [ { "itemId": "itm_9f3a2b", "variantId": "var_rojo", "transactionType": "rental", "quantity": 4 }, { "itemId": "itm_camara_a7" } ], "startDate": "2026-09-01T08:00:00+02:00", "endDate": "2026-09-05T20:00:00+02:00" } )

{
  "data": [
    {
      "itemId": "item_9f3a2b",
      "variantId": "variant_9f3a2b",
      "itemName": "Example item name",
      "quantity": 1,
      "available": true,
      "status": "ok",
      "totalStock": 1,
      "reserved": 1,
      "minRemaining": 1,
      "shortfall": 1,
      "temporaryAvailable": 1,
      "conflictingPeriods": [
        "Example conflicting periods"
      ],
      "commitments": [
        {
          "orderId": "order_9f3a2b",
          "orderNumber": "2026-0001",
          "quantity": 1,
          "startDate": "2026-09-01T08:00:00.000Z",
          "endDate": "2026-09-01T08:00:00.000Z"
        }
      ],
      "checkedAt": "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/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": "availability:read"
}

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

Idempotent query (POST because of the structured body). Shares the availability quota of 30 req/min. One entry per requested item, in request order: its availability (available, shortfall, conflictingPeriods for that quantity, and commitments: the orders that hold units of it in the window, with their number, peak quantity and dates) or a per-item error when the item does not exist in the account.

Authorizations

Bearer API key with the scope below. availability:read

Body

application/json

Body schema: AvailabilityCheckBody

itemsobject[]Required

Batch of items to check (between 1 and 100).

Limits: min 1 items, max 100 items

Show child attributes

items.itemIdstringRequired

Identifier of the item to check. Required.

Limits: min length 1, max length 100

items.variantIdstring

Identifier of the specific variant to check; omit for the base item.

Limits: min length 1, max length 100

items.transactionTypestring

Type of transaction to check: rental or sale. Defaults to rental.

Available options: rental, sale

items.quantityinteger

Units you intend to book. Drives available, shortfall, status and conflictingPeriods. Defaults to 1.

Limits: min 1, max 100000

startDatestring<date-time>Required

Start of the range to check (ISO 8601 with offset), shared by the whole batch.

endDatestring<date-time>Required

End of the range to check (ISO 8601 with offset), shared by the whole batch; must be later than startDate.

Response

application/json

Successful response.

Response schema: AvailabilityCheckEntryDto

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

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

dataobject[]

One of 1/2: AvailabilityResult

data.itemIdstring

Identifier of the checked item.

data.variantIdstring | null

Identifier of the checked variant; null if the base item was checked.

data.itemNamestring

Name of the checked item.

data.quantityinteger

Units requested for this item (1 if the request did not say).

data.availableboolean

true if minRemaining covers quantity at every point of the queried window.

data.statusstring

ok (the requested quantity is available), partial (some units are available, fewer than requested) or none (no units available).

Available options: ok, partial, none

data.totalStocknumber

Total stock of the item.

data.reservednumber

Reserved units overlapping the queried window.

data.minRemainingnumber

Minimum available at any point in the queried window.

data.shortfallinteger

Units missing to serve quantity (0 when available).

data.temporaryAvailablenumber | null

Additional temporary availability (e.g. borrowed/temporary stock); null if not applicable.

data.conflictingPeriodsstring[]

Business days (YYYY-MM-DD, in the account timezone) within the window on which the stock does not cover quantity. Empty when available.

data.commitmentsobject[]

Orders that consume stock of the item within the window (the lines behind reserved), earliest first. Empty when nothing is booked.

Show child attributes

data.commitments.orderIdstring

Order that holds units of the item within the window.

data.commitments.orderNumberstring | null

Number of that order; null if it has none yet.

data.commitments.quantitynumber

Peak units the order holds at the same time within the window.

data.commitments.startDatestring<date-time>

Start of the period of its lines, in ISO 8601 UTC (not clipped to the window).

data.commitments.endDatestring<date-time>

End of the period of its lines, in ISO 8601 UTC (not clipped to the window).

data.checkedAtstring<date-time>

Moment the check was performed, in ISO 8601 with offset.

One of 2/2: AvailabilityItemErrorEntry

data.itemIdstring

Identifier the request asked for.

data.variantIdstring | null

Variant the request asked for; null if none.

data.errorobject

Why the item has no result.

Show child attributes

data.error.codestring

The item does not exist in the account.

Available options: not_found

data.error.messagestring

Human-readable explanation.

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.

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

Body

Response

Errors

Deprecation

Related