Occupancy & allocation

Learn how to handle guest allocation, room occupancy, and potential allocation issues using the Accommodation API collection.

Overview

This guide explains how to interpret room occupancy rules and manage guest allocation in Booking.com’s Demand API. It covers:

• Maximum occupancy per room (maximum_occupancy)
• Recommended guest allocation (recommendation)
• Allocation warnings (occupancy_mismatch)
• Best practices for multi-room and mixed-age bookings.

This guide applies to both adults and children, ensuring partners can handle allocation consistently. For children specific rates and policies

Guest parameters and room allocation

When making search or availability requests, always include:

• guest.number_of_adults — Number of adults.
• guest.children — Ages of all children.
• guest.number_of_rooms — Number of rooms.
• allocation — Distribution of adults and children per room.

Example allocation for 2 rooms:

{
  "guests": {
    "allocation": [
      {
        "number_of_adults": 2,
        "children": [2, 10]
      },
      {
        "number_of_adults": 2,
        "children": [0, 5]
      }
    ],
    "number_of_adults": 4,
    "children": [0, 2, 5, 10],
    "number_of_rooms": 2
  }
}

Room allocation

When booking multiple rooms, use allocation field, to assign adults/children to each room.

{
  "guests": {
    "allocation": [
      {
        "number_of_adults": 2,
        "children": [2, 10]
      },
      {
        "number_of_adults": 2,
        "children": [0, 5]
      }
    ],
    "number_of_adults": 4,
    "children": [0, 2, 5, 10],
    "number_of_rooms": 2
  }
}

Maximum occupancy

Use the maximum_occupancy object from the availability or accommodations/details (with "rooms" in request) response to determine:

• How many guests a room can accommodate (adults + children)
• The maximum number of adults.
• Which children are eligible for child rates.

Example:

{
  "maximum_occupancy": {
    "adults": 2,
    "children": [
      {
        "total": 1,
        "from_age": 0,
        "to_age": 5,
        "free_stay": true
      },
      {
        "total": 1,
        "from_age": 6,
        "to_age": 12,
        "free_stay": false
      }
    ],
    "total": 4
  }
}

Recommended allocation

The recommendation object returned in the availability response provides the best guest distribution per room:

• Allocates adults and children efficiently across multiple rooms.
• Helps ensure that occupancy rules are respected.
• Returns null if no suitable products are available.

Example:

{
  "recommendation": {
    "price": {...},
    "total": 2140.4,
    "products": [
      {
        "id": "1000426_95127794_3_2_0",
        "children": [2],
        "number_of_adults": 1,
        "price": {...}
      },
      {
        "id": "1000434_95127794_1_2_0",
        "children": [4],
        "number_of_adults": 1,
        "price": {...}
      }
    ]
  }
}

Occupancy mismatch

The occupancy_mismatch object is returned by /orders/preview when the requested guest allocation exceeds the room’s capacity.

This preview warning allows you to review and adjust the booking before confirming it.

This object contains:

• allocated — guests that can be accommodated in the room.
• unallocated — guests that cannot be accommodated.

If all guests fit in the room, occupancy_mismatch is null.

Example:

{
  "occupancy_mismatch": {
    "allocated": {
      "number_of_adults": 1,
      "children": null
    },
    "unallocated": {
      "number_of_adults": 1,
      "children": null
    }
  }
}

Explanation:

• The room can host 1 adult.
• 1 adult cannot be accommodated.

If all guests fit the room capacity, occupancy_mismatch is returned as:

"occupancy_mismatch": null

Recommended integration behaviour

When occupancy_mismatch is returned:

1. Inform the traveller that the selected room cannot accommodate all guests:

2. Allow them to:

   • Select additional rooms, or
   • Choose a different product.

3. Verify the room maximum_occupancy if needed.

4. Call orders/preview again with the updated allocation before confirming the booking.

Best practices

✅ Always include children’s ages in search and availability requests.

✅ Respect the maximum_occupancy limits for adults and children.

✅ Use the recommendation object for optimal allocation.

✅ Handle occupancy_mismatch gracefully and provide clear warnings.

✅ Display occupancy-specific details such as cots, extra beds, and free child stays at room level.

References