Take a hire booking

Book studio-owned stock for a date window, and understand how availability is judged.

A hire line rents something you own for a window of dates, rather than buying stems for an event. It goes through the same endpoint as any other line, with mode: "hire".

What can be hired

Only a variant marked hireable, which the app allows on material products only. A hireable variant carries an inventoryQty: how many units the studio owns. Setting it is a catalogue write:

curl -X POST "https://app.bloomcount.com/api/v1/products" \
  -H "Authorization: Bearer bloomcount_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "prod_...",
        "variantId": "var_...",
        "variant": { "hireable": true, "inventoryQty": 24 }
      }
    ]
  }'

Daily fees are not set here. They live on a price list whose productType is hire, and the event points at one through hirePriceListId.

Booking

curl -X POST "https://app.bloomcount.com/api/v1/events/evt_.../items" \
  -H "Authorization: Bearer bloomcount_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "variantId": "var_...",
        "quantity": 10,
        "groupId": "evtgrp_...",
        "mode": "hire",
        "hireStart": 1781424000000,
        "hireEnd": 1781596800000
      }
    ]
  }'

Both dates are required and are milliseconds since the epoch. A hire line takes no supplierId: the stock is yours, so there is nobody to buy it from, and sending one fails the row with supplier_not_allowed_on_hire.

On the way back, a hire line carries hireDays and dailyFeeExclTax, the fee snapshotted from the event’s hire price list when the line was written.

How availability is judged

When a hire line is created, or its quantity or dates change, the API counts what is already committed for that variant and refuses to oversell.

Start from what you own

The variant’s inventoryQty. A variant with none available has nothing to hire, and every booking fails.

Subtract overlapping bookings

Every other hire line for the same variant whose window touches yours, on any event. Two bookings overlap unless one ends before the other starts.

Ignore cancelled events

Lines on an event whose status is cancelled are not held, so cancelling frees the stock immediately.

Count the group multiplier

A line is counted at its effective quantity, not its written one. Ten of something inside a group with quantityMode: "group" and groupQuantity: 4 holds forty units, not ten.

When you edit an existing line, that line is excluded from the count, so changing ten to twelve is judged against the other bookings rather than against itself.

A row asking for more than is free fails with the number that is actually available:

{
  "results": [],
  "errors": [{ "index": 0, "error": "hire_unavailable:6" }]
}

Six units are free across those dates. The rest of the batch still lands, so a single unavailable row does not cost you the others.

Changing or cancelling

Same endpoint, with the line’s id. Changing dates re-checks availability against the new window.

{
  "items": [
    { "itemId": "evti_...", "quantity": 8 },
    { "itemId": "evti_...", "hireStart": 1781424000000, "hireEnd": 1781683200000 },
    { "itemId": "evti_...", "remove": true }
  ]
}

Sending hire dates for a line that is not a hire line fails with not_a_hire_line, and booking a variant that is not marked hireable fails with variant_not_hireable.