Manage Blocks

A block’s lifecycle looks like this:

Tentative ──confirm──▶ Definite ──release──▶ Tentative
    │                      │
    │  set-to-optional     │  cancel
    ▼                      ▼
 Optional              Canceled
    │
    │ cutoff reached / confirm / release
    ▼
 Tentative or Definite

Tentative

The default status on creation. Units are reserved for the group, but availability elsewhere is not reduced yet, so the hold can be adjusted or abandoned with no side effects.

Optional

Optional implements the “option date” pattern familiar from MICE sales: hold the rooms against a cutoff, without committing to a full confirmation yet.

PUT /booking/v1/block-actions/{id}/set-to-optional

{
  "optionalCutoff": "2026-08-12T00:00:00",
  "isOptionalDeductingInventory": false,
  "optionalCutoffBehavior": "DoNothing"
}
  • optionalCutoff must fall between today (property-local time) and the block’s start date.
  • isOptionalDeductingInventory: true makes the block reduce availability the same way a Definite block does, from the next availability query onward. false keeps it a pure soft hold, behaving like Tentative.
  • optionalCutoffBehavior: AutoRelease reverts the block to Tentative automatically if nobody acts by the cutoff. DoNothing leaves it sitting in Optional past its cutoff with no automatic action.
  • If nobody confirms or releases the block by the time its start date arrives, it automatically reverts from Optional to Tentative regardless of optionalCutoffBehavior.

To adjust the cutoff, inventory-deduction flag, or cutoff behaviour on a block that’s already Optional, use the dedicated endpoint:

PUT /booking/v1/block-actions/{id}/set-optional-fields

{
  "optionalCutoff": "2026-08-25T00:00:00",
  "isOptionalDeductingInventory": true,
  "optionalCutoffBehavior": "DoNothing"
}

Same three-field shape as set-to-optional. It only works on a block already in Optional status.

Definite

PUT /booking/v1/block-actions/{id}/confirm

Confirming is what actually reserves the inventory. If the block wasn’t already deducting inventory (a Tentative block, or an Optional block with isOptionalDeductingInventory: false), this call re-checks availability and only succeeds if there is still enough left. Treat it as a normal rejectable call in your integration: if availability has shrunk since the block was created, prompt the organiser to reduce the block rather than assuming confirmation always works.

Amend covers general edits, including moving a block between statuses directly:

PUT /booking/v1/block-actions/{id}/amend

{
  "from": "2026-08-09",
  "to": "2026-08-12",
  "grossDailyRate": { "amount": 160, "currency": "EUR" },
  "timeSlices": [
    { "blockedUnits": 3 },
    { "blockedUnits": 0 },
    { "blockedUnits": 7 }
  ],
  "marketSegmentId": "BUSR",
  "status": "Tentative"
}

Release moves a block from Definite back to Tentative and returns the inventory. Only allowed if no reservation has been picked up yet:

PUT /booking/v1/block-actions/{id}/release

Cancel moves the block to Canceled. Only allowed if no reservation has been picked up yet:

PUT /booking/v1/block-actions/{id}/cancel

Pickup creates reservations against its block. Each pickup consumes one held unit from the block.

POST /booking/v1/groups/{id}/reservations

{
  "reservations": [
    {
      "blockId": "MUC-QJNXJR",
      "arrival": "2026-08-08",
      "departure": "2026-08-10",
      "adults": 1,
      "comment": "Needs a wake-up call",
      "primaryGuest": {
        "title": "Mr",
        "gender": "Male",
        "firstName": "Jon",
        "middleInitial": "D",
        "lastName": "Doe",
        "email": "john.d@doe.com",
        "phone": "+4989123343",
        "address": {
          "addressLine1": "My Street 1",
          "postalCode": "12453",
          "city": "MyCity",
          "countryCode": "GB"
        },
        "company": { "name": "Company GmbH", "taxId": "1442" }
      }
    },
    {
      "blockId": "MUC-WKMCKT",
      "arrival": "2026-08-08",
      "departure": "2026-08-10",
      "adults": 1,
      "childrenAges": [6],
      "primaryGuest": {
        "title": "Mr",
        "gender": "Male",
        "firstName": "Eric",
        "middleInitial": "E",
        "lastName": "Steinmetz",
        "email": "eric.e@steinmetz.com",
        "phone": "+4989123343",
        "address": {
          "addressLine1": "My Street 1",
          "postalCode": "12453",
          "city": "MyCity",
          "countryCode": "GB"
        }
      }
    }
  ]
}
  • blockId ties the new reservation to its block, and the returned reservation ID ties it back to the group.
  • The reservation inherits the block’s rate plan; you don’t repeat rate details on the pickup call.
  • If a picked-up reservation is cancelled, the unit returns to the block’s unpicked pool automatically, it doesn’t need to be manually restored.
  • Everything after pickup (amend, check-in, cancel) runs through the standard reservation-actions endpoints, the same ones you’d use for any non-block reservation.

Wash frees the unpicked remainder of a Definite block back to public availability, without changing the block’s own status. Useful when actual attendance comes in under the negotiated block size:

PUT /booking/v1/block-actions/{id}/wash

Each Block action — created, changed, deleted, set-to-optional, confirmed, released, washed, cancelled — sends an event you can listen to using webhooks.