Modify room in a proposal

  • Rooms
  • Booking
  • 4 routes
How can I change the room arrangement of an existing proposal?

This scenario explains how to inspect the current room distribution of a proposal, search alternative arrangements, validate a selected combination, and finally apply the new arrangement to the proposal.

It is designed for advanced accommodation management flows where the traveler or seller wants to reassign attendees and rooms before the proposal is turned into a booking.

Overview

Use this scenario when you need to modify the room arrangement of an existing proposal. The full flow starts by reading the current allocation, continues with the search for alternative room combinations, validates the selected arrangement, and ends by applying it to the proposal.

This is the right sequence when you want to keep the proposal context while changing room composition and attendee distribution.

Prerequisites

  • Have a valid x-api-key.
  • Use an accept-language value returned by GET/v0/locales for the routes that require it.
  • Know the proposal_id.
  • Make sure the proposal is still valid and can accept accommodation changes.
  • Be aware that some request payload details are not visible in the available sources for the search, check, and apply operations.

Functional notes

  • Reading the current arrangement first helps compare the existing state with the target state.
  • The search route returns alternative arrangements with stock and differential prices.
  • The check route is recommended before the final update because it validates the selected combination in the current proposal context.
  • The final PUT applies the arrangement and can fail if attendees are duplicated, missing, or if the room is no longer available.

Process workflow

Legend:
Mandatory
Optional
1

Inspect current room arrangement

Mandatory

This route returns the current room and attendee arrangement stored in the proposal.

Prerequisites

Have the proposal identifier and a valid API key. Add merge_accommodations=true if you want equivalent rooms to be merged in the response.

Calling CURL

curl -X GET \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/accommodations_arrangement?merge_accommodations=true"

Example answer

[
  {
    "id": "accommodation-1",
    "label": "Deluxe Room",
    "occupancy": 2,
    "quantity": 1,
    "shared_room": false,
    "attendees": [
      {
        "id": "attendee-1",
        "first_name": "Jane"
      },
      {
        "id": "attendee-2",
        "first_name": "John"
      }
    ],
    "accommodation_categories": [
      {
        "id": "DLX",
        "label": "Deluxe"
      }
    ]
  }
]

info: Use this payload as the baseline before searching or validating a new arrangement.

Response codes

  • 200 OK: the current arrangement is returned.
  • 400 Bad Request: the request is malformed or invalid.
  • 403 Forbidden: the proposal is not accessible in the current context.
GET/v1/proposals/{proposal_id}/accommodations_arrangement
See more
2

Search alternative room arrangements

Mandatory

This route searches alternative room arrangements and orders them by lowest price differential.

Prerequisites

Pass proposal_id in the query string. You can also use booking_id and customer_id depending on the context.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"occupancies": [{"adults": 2}]}' \
  "https://api.clubmed.com/v1/accommodations_arrangement/search?proposal_id={proposal_id}"

Example answer

[
  {
    "remaining_stock": 3,
    "is_upgradable_online": true,
    "accommodation_arrangement": [
      {
        "room_id": "room-1",
        "label": "Deluxe Room",
        "attendees": [
          "attendee-1",
          "attendee-2"
        ]
      }
    ],
    "differential_prices": {
      "amount": 180,
      "currency": "EUR"
    }
  }
]

info: The response helps compare room combinations and the associated price differential before validation.

Response codes

  • 200 OK: compatible arrangements are returned.
  • 400 Bad Request: invalid proposal, inconsistent criteria, or invalid JSON.
  • 401 Unauthorized: missing or invalid access token.
  • 404 Not Found: the booking or proposal cannot be found.
  • 409 Conflict: the proposal is no longer valid in its current state.
POST/v1/accommodations_arrangement/search
See more
3

Validate selected room arrangement

Mandatory

This route checks that a selected arrangement is still available and consistent before it is applied.

Prerequisites

Send the candidate arrangement in the body and pass proposal_id in the query string.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"accommodation_arrangement": [{"room_id": "room-1", "attendees": ["attendee-1", "attendee-2"]}]}' \
  "https://api.clubmed.com/v1/accommodations_arrangement/check?proposal_id={proposal_id}"

Example answer

[
  {
    "remaining_stock": 3,
    "accommodation_arrangement": [
      {
        "room_id": "room-1",
        "label": "Deluxe Room",
        "attendees": [
          "attendee-1",
          "attendee-2"
        ]
      }
    ],
    "differential_prices": {
      "amount": 180,
      "currency": "EUR"
    }
  }
]

info: If this step returns an updated price differential or stock level, reuse those values before the final application step.

Response codes

  • 200 OK: the selected arrangement is validated.
  • 400 Bad Request: unavailable room, invalid criteria, or invalid JSON.
  • 401 Unauthorized: missing or invalid access token.
  • 404 Not Found: booking or proposal not found.
POST/v1/accommodations_arrangement/check
See more
4

Apply new room arrangement

Mandatory

This route applies the new room arrangement to the proposal.

Prerequisites

Reuse a validated arrangement and the proposal identifier. The body must map each room to the correct attendees.

Calling CURL

curl -X PUT \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"accommodation_arrangement": [{"room_id": "room-1", "attendees": ["attendee-1", "attendee-2"]}]}' \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/accommodations_arrangement"

Example answer

HTTP/1.1 204 No Content

info: Success is returned without a response body. Keep the submitted arrangement client-side if you need to display it immediately after the call.

Response codes

  • 204 No Content: the new arrangement is saved.
  • 400 Bad Request: missing attendees, duplicate attendees, invalid criteria, or invalid JSON.
  • 403 Forbidden: the proposal is not accessible with this API key.
PUT/v1/proposals/{proposal_id}/accommodations_arrangement
See more