Filmo Docs
Español

Orders

Reserve an order

Moves the order to reserved: checks the stock of each line, deducts it and creates the delivery and return tasks.

POST
/api/v1/orders/{orderId}/reserve

Request examples

curl https://app.filmo.io/api/v1/orders/orde_8f2a1c/reserve \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)"
{
  "data": {
    "id": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "externalReference": "2026-0001",
    "status": "draft",
    "startDate": "2026-09-01T08:00:00.000Z",
    "endDate": "2026-09-01T08:00:00.000Z",
    "rentalDays": 1,
    "projectId": "project_9f3a2b",
    "projectName": "Example project name",
    "contact": {
      "id": "contact_9f3a2b",
      "name": "Example contact"
    },
    "itemsCount": 1,
    "subTotalPrice": "120.00",
    "discountTotal": "120.00",
    "insuranceTotal": "120.00",
    "depositTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "tags": [
      {
        "id": "tag_9f3a2b",
        "name": "Example tag"
      }
    ],
    "customFields": {
      "example": "example"
    },
    "source": "Example source",
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z",
    "billingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "shippingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "contactPerson": {
      "id": "contact_person_9f3a2b",
      "name": "Example contact person"
    },
    "quotes": [
      {
        "id": "quote_9f3a2b",
        "number": "2026-0001",
        "status": "Example status"
      }
    ],
    "invoices": [
      {
        "id": "invoice_9f3a2b",
        "number": "2026-0001",
        "status": "Example status"
      }
    ],
    "proformas": [
      {
        "id": "proforma_9f3a2b",
        "number": "2026-0001",
        "status": "Example status"
      }
    ]
  },
  "meta": {
    "tasksCreated": 1
  }
}

Generated from the schema

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.

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"

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

orderIdstringRequired

Order identifier.

Limits: min length 1

Response

application/json

Successful response.

Response schema: OrderDetailDto

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

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

dataobject

The order in full, as returned by the API.

Show child attributes
data.idstring

Unique order identifier.

data.orderNumberstring

Human-readable order number.

data.externalReferencestring | null

External reference of the order (for example, from the customer system); null if not recorded.

data.statusstring

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.

Available options: draft, reserved, prepared_partially, prepared, picked_up_partially, picked_up, returned_partially, returned, checked_in_partially, checked_in, archived, cancelled

data.startDatestring<date-time>

Start of the rental period in ISO 8601 with offset.

data.endDatestring<date-time>

End of the rental period in ISO 8601 with offset.

data.rentalDaysnumber | null

Number of billable rental days; null if not calculated.

data.projectIdstring | null

Identifier of the project the order belongs to; null if not linked.

data.projectNamestring | null

Name of the project the order belongs to; null if not linked.

data.contactobject | null

Compact reference to the order contact; null if none.

Show child attributes
data.contact.idstring

Unique contact identifier.

data.contact.namestring

Contact name.

data.itemsCountinteger

Number of items in the order.

data.subTotalPricestring

Subtotal before discounts and taxes, as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.discountTotalstring | null

Total discounts as a decimal string "1234.50" (ROUND_HALF_UP); null if there is no discount.

Limits: pattern ^-?\d+\.\d{2}$

data.insuranceTotalstring

Insurance total as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.depositTotalstring

Deposit total as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.taxesPricestring

Tax total as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.netPricestring

Taxable base (net before taxes) as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.grossPricestring

Total including taxes, as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.tagsobject[]

Tags attached to the order, with their identifier and name.

Show child attributes
data.tags.idstring

Unique identifier of the tag.

data.tags.namestring

Tag name.

data.customFieldsobject<string, any>

Custom field values by custom field identifier; the definitions are in /api/v1/custom-fields.

data.sourcestring | null

Source the order was created from (for example web, mobile, admin); null if not recorded.

data.createdAtstring<date-time>

Creation date in ISO 8601 with offset.

data.updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

data.billingAddressobject | null

Billing address of the order; null if none.

Show child attributes
data.billingAddress.labelstring | null

Descriptive label of the address; null if not recorded.

data.billingAddress.addressLine1string | null

First address line; null if not recorded.

data.billingAddress.addressLine2string | null

Second address line; null if not recorded.

data.billingAddress.citystring | null

City; null if not recorded.

data.billingAddress.provincestring | null

Province or region; null if not recorded.

data.billingAddress.postcodestring | null

Postal code; null if not recorded.

data.billingAddress.countrystring | null

Country; null if not recorded.

data.shippingAddressobject | null

Shipping address of the order; null if none.

Show child attributes
data.shippingAddress.labelstring | null

Descriptive label of the address; null if not recorded.

data.shippingAddress.addressLine1string | null

First address line; null if not recorded.

data.shippingAddress.addressLine2string | null

Second address line; null if not recorded.

data.shippingAddress.citystring | null

City; null if not recorded.

data.shippingAddress.provincestring | null

Province or region; null if not recorded.

data.shippingAddress.postcodestring | null

Postal code; null if not recorded.

data.shippingAddress.countrystring | null

Country; null if not recorded.

data.contactPersonobject | null

Contact person linked to the order; null if none.

Show child attributes
data.contactPerson.idstring

Unique contact identifier.

data.contactPerson.namestring

Contact name.

data.quotesobject[]

Informational references to quotes generated from the order.

Show child attributes
data.quotes.idstring

Unique identifier of the referenced document.

data.quotes.numberstring | null

Document number; null until it is numbered.

data.quotes.statusstring | null

Document status at the time the reference was written; null if not recorded. Informational: it may be out of date.

data.invoicesobject[]

Informational references to invoices generated from the order.

Show child attributes
data.invoices.idstring

Unique identifier of the referenced document.

data.invoices.numberstring | null

Document number; null until it is numbered.

data.invoices.statusstring | null

Document status at the time the reference was written; null if not recorded. Informational: it may be out of date.

data.proformasobject[]

Informational references to proformas generated from the order.

Show child attributes
data.proformas.idstring

Unique identifier of the referenced document.

data.proformas.numberstring | null

Document number; null until it is numbered.

data.proformas.statusstring | null

Document status at the time the reference was written; null if not recorded. Informational: it may be out of date.

metaobject

Show child attributes
meta.tasksCreatedinteger

Delivery and return tasks that the reservation created.

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

StatusCodesMeaning
404not_foundIt does not exist or is outside the scope of the API key.
409conflict, insufficient_stockThe 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.
412precondition_failedThe If-Match entity tag does not match the current representation. Read the resource again and retry.
422idempotency_key_reusedThe 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

Related

Related pages

Link to this section: Related pages

  • Rentals

    Order

    The order, as returned by the API.

Was this page helpful?

Cookies

If you accept, we use Google cookies to measure visits and show you ads. Privacy policy

More information

With your consent we use Google Ads and Google Analytics cookies to measure which campaigns bring visitors and requests, and to show you Filmo ads on other sites. Without acceptance, Google receives cookieless measurement signals, including your IP address, browser information and a cleaned page URL. Your choice is shared with the Filmo app.