*MCP › Reference › Rentals › Orders* # Reserve an order > Moves the order to `reserved`: checks the stock of each line, deducts it and creates the delivery and return tasks. It takes no body. If there is not enough stock it responds 409 `insufficient_stock`, and `errors[]` carries one entry per short item or space (`path` is `items` or `spaces`, with `itemId`, `requested`, `available` and `shortfall`). A serial number already assigned to another order, an order that is not a draft (`prepared_partially`, `prepared`, `picked_up_partially`, `picked_up`, `returned_partially`, `returned`, `checked_in_partially`, `checked_in` or `cancelled`: the problem names its status), a sale line without source warehouse or another write on the order in progress respond 409 `conflict`. In every case nothing is reserved. 404 if the order does not exist, belongs to another account or is archived. Reserving an order that is already reserved is not an error: it changes nothing and responds 200 with `meta.tasksCreated` 0 (or the delivery and return tasks it had to restore, if some were missing). `meta.tasksCreated` says how many tasks were born, because your schedule changes with this call. It is undone with `/unreserve`. Returns the full order, the same projection as its GET. TOOL `filmo_orders_reserve` · `orders:write` · 120/min ## Arguments | Name | Type | Required | Description | | --- | --- | --- | --- | | `orderId` | string | Yes | Order identifier. | | `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. | | `ifMatch` | string | No | Optimistic locking: the meta.etag you got from the detail read of this resource (or "*"). If the resource changed since, the call fails with 412 precondition_failed before writing anything; read it again and retry. Omit it to write unconditionally. | ## Result On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`. | Name | Type | Description | | --- | --- | --- | | `id` | string | Unique order identifier. | | `orderNumber` | string | Human-readable order number. | | `externalReference` | string | External reference of the order (for example, from the customer system); null if not recorded. | | `status` | string | Raw order status as stored in the database (12 values): draft, reserved, prepared_partially, prepared, picked_up_partially, picked_up, returned_partially, returned, checked_in_partially, checked_in, archived or cancelled. `archived` is part of the stored set but an archived order is not visible to the API, so you will not observe it. `draft`, `reserved`, `prepared_partially`, `prepared`, `picked_up_partially`, `picked_up`, `returned_partially`, `returned`, `checked_in_partially`, `checked_in`, `archived`, `cancelled` | | `startDate` | string | Start of the rental period in ISO 8601 with offset. | | `endDate` | string | End of the rental period in ISO 8601 with offset. | | `rentalDays` | number | Number of billable rental days; null if not calculated. | | `projectId` | string | Identifier of the project the order belongs to; null if not linked. | | `projectName` | string | Name of the project the order belongs to; null if not linked. | | `contact` | object | Compact reference to the order contact; null if none. | | `contact.id` | string | Unique contact identifier. | | `contact.name` | string | Contact name. | | `itemsCount` | integer | Number of items in the order. | | `subTotalPrice` | string | Subtotal before discounts and taxes, as a decimal string "1234.50" (ROUND_HALF_UP). | | `discountTotal` | string | Total discounts as a decimal string "1234.50" (ROUND_HALF_UP); null if there is no discount. | | `insuranceTotal` | string | Insurance total as a decimal string "1234.50" (ROUND_HALF_UP). | | `depositTotal` | string | Deposit total as a decimal string "1234.50" (ROUND_HALF_UP). | | `taxesPrice` | string | Tax total as a decimal string "1234.50" (ROUND_HALF_UP). | | `netPrice` | string | Taxable base (net before taxes) as a decimal string "1234.50" (ROUND_HALF_UP). | | `grossPrice` | string | Total including taxes, as a decimal string "1234.50" (ROUND_HALF_UP). | | `tags` | object[] | Tags attached to the order, with their identifier and name. | | `tags.id` | string | Unique identifier of the tag. | | `tags.name` | string | Tag name. | | `customFields` | object | Custom field values by custom field identifier; the definitions are in `/api/v1/custom-fields`. | | `source` | string | Source the order was created from (for example web, mobile, admin); null if not recorded. | | `createdAt` | string | Creation date in ISO 8601 with offset. | | `updatedAt` | string | Last update date in ISO 8601 with offset. | | `billingAddress` | object | Billing address of the order; null if none. | | `billingAddress.label` | string | Descriptive label of the address; null if not recorded. | | `billingAddress.addressLine1` | string | First address line; null if not recorded. | | `billingAddress.addressLine2` | string | Second address line; null if not recorded. | | `billingAddress.city` | string | City; null if not recorded. | | `billingAddress.province` | string | Province or region; null if not recorded. | | `billingAddress.postcode` | string | Postal code; null if not recorded. | | `billingAddress.country` | string | Country; null if not recorded. | | `shippingAddress` | object | Shipping address of the order; null if none. | | `shippingAddress.label` | string | Descriptive label of the address; null if not recorded. | | `shippingAddress.addressLine1` | string | First address line; null if not recorded. | | `shippingAddress.addressLine2` | string | Second address line; null if not recorded. | | `shippingAddress.city` | string | City; null if not recorded. | | `shippingAddress.province` | string | Province or region; null if not recorded. | | `shippingAddress.postcode` | string | Postal code; null if not recorded. | | `shippingAddress.country` | string | Country; null if not recorded. | | `contactPerson` | object | Contact person linked to the order; null if none. | | `contactPerson.id` | string | Unique contact identifier. | | `contactPerson.name` | string | Contact name. | | `quotes` | object[] | Informational references to quotes generated from the order. | | `quotes.id` | string | Unique identifier of the referenced document. | | `quotes.number` | string | Document number; null until it is numbered. | | `quotes.status` | string | Document status at the time the reference was written; null if not recorded. Informational: it may be out of date. | | `invoices` | object[] | Informational references to invoices generated from the order. | | `invoices.id` | string | Unique identifier of the referenced document. | | `invoices.number` | string | Document number; null until it is numbered. | | `invoices.status` | string | Document status at the time the reference was written; null if not recorded. Informational: it may be out of date. | | `proformas` | object[] | Informational references to proformas generated from the order. | | `proformas.id` | string | Unique identifier of the referenced document. | | `proformas.number` | string | Document number; null until it is numbered. | | `proformas.status` | string | Document status at the time the reference was written; null if not recorded. Informational: it may be out of date. | *Call · filmo_orders_reserve* ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "filmo_orders_reserve", "arguments": { "orderId": "orde_8f2a1c" } } } ``` *Result (generated from the schema)* ```json { "structuredContent": { "data": { "id": "id_8f2a1c", "orderNumber": "", "externalReference": "", "status": "draft", "startDate": "2026-09-01T08:00:00Z", "endDate": "2026-09-01T08:00:00Z", "rentalDays": 1, "projectId": "proj_8f2a1c", "projectName": "Example", "contact": { "id": "id_8f2a1c", "name": "Example" }, "itemsCount": 1, "subTotalPrice": "1234.50", "discountTotal": "1234.50", "insuranceTotal": "1234.50", "depositTotal": "1234.50", "taxesPrice": "1234.50", "netPrice": "1234.50", "grossPrice": "1234.50", "tags": [ { "id": "id_8f2a1c", "name": "Example" } ], "customFields": { "key": "" }, "source": "", "createdAt": "2026-09-01T08:00:00Z", "updatedAt": "2026-09-01T08:00:00Z", "billingAddress": { "label": "Example", "addressLine1": "", "addressLine2": "", "city": "", "province": "", "postcode": "", "country": "ES" }, "shippingAddress": { "label": "Example", "addressLine1": "", "addressLine2": "", "city": "", "province": "", "postcode": "", "country": "ES" }, "contactPerson": { "id": "id_8f2a1c", "name": "Example" }, "quotes": [ { "id": "id_8f2a1c", "number": "", "status": "" } ], "invoices": [ { "id": "id_8f2a1c", "number": "", "status": "" } ], "proformas": [ { "id": "id_8f2a1c", "number": "", "status": "" } ] }, "meta": { "idempotencyKey": "", "rateLimit": { "limit": 120, "remaining": 119, "reset": 42 } } } } ``` ## Sample prompts *Prompt* ```text Reserve the draft order I just created. ``` ## The same operation by REST This tool runs [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/reserve-an-order). --- Canonical URL: https://docs.filmo.io/mcp/tools/orders/filmo-orders-reserve Last updated: 2026-10-25