Proposals: Add or change accommodations

Option creation
4 routes

How do I add more rooms or change the accommodation split in a proposal?

This guide explains how to add rooms or change the accommodation split of a proposal before confirmation.

The journey starts by retrieving a workable proposal, continues with the product accommodation catalog and the proposal-level arrangement search, and ends by applying the selected arrangement to the proposal.

Overview

This journey helps you evolve the accommodation setup of a proposal without leaving the booking flow. It combines product-level accommodation metadata with proposal-level availability and price differentials.

The two reads do not serve the same purpose:

GET/v2/products/{product_id}/accommodations describes room types, capacities, and product attributes.
POST/v1/accommodations_arrangement/search returns the room splits actually available for a given proposal, together with their differential prices.

Prerequisites

Have a valid proposal_id, or be able to generate one with POST/v3/proposals/search.
Have a valid product_id to browse the product accommodation catalog.
Send accept-language and x-api-key on every route in the journey.
Make sure the proposal is still valid before applying a new arrangement.

Notes

The product catalog is not a guarantee of proposal-level availability.
The final update mutates the proposal in place.
The exact request body expected by PUT/v1/proposals/{proposal_id}/accommodations_arrangement is not verifiable with the consulted sources.

Process workflow

Legend:

Mandatory

Optional

Generate a baseline proposal

Mandatory

Use POST/v3/proposals/search to retrieve the proposal candidates matching the booking criteria and reuse the returned id as proposal_id for the rest of the journey.

Prerequisites

Send accept-language and x-api-key.
The request body must contain the booking criteria that define the stay context.
Keep the returned id for the following accommodation steps.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v3/proposals/search' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"product_id":"MPAC","resort_arrival_date":"20260415","duration":7,"number_attendees":2}'

Example answer

[
  {
    "id": "123456",
    "accommodations": [],
    "price": {
      "amount": 9815.4,
      "currency": "EUR"
    },
    "alternative_price": {
      "amount": 9650.4,
      "currency": "EUR"
    },
    "remaining_stock": 3,
    "option_available": true
  }
]

info: this route usually returns the best priced proposal candidates for the requested stay context, which makes it a good baseline before comparing room arrangements.

Response codes

OK Response (200): returns the proposal candidates that match the submitted criteria.
Error (400): invalid attendee combinations, invalid departure-city rules, bad_request, validation_error, or malformed JSON payload.
Error (401): unauthorized.
Error (403): at least one customer cannot proceed with the booking, or the submitted seller context is not allowed.
Error (404): the product was not found.
Error (409): the proposal criteria are no longer valid.

POST/v3/proposals/search

Browse the product accommodation catalog

Optional

Use GET/v2/products/{product_id}/accommodations to explore the room catalog of one product before choosing a different room arrangement.

Prerequisites

Reuse the product_id coming from the proposal step.
Send accept-language and x-api-key.
Optionally add stay_date, filter, sort, or date_format depending on the browsing experience you need to support.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v2/products/MPAC/accommodations?stay_date=20260415' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "id": "CD",
    "label": "Club room",
    "capacity": 2,
    "comfort_type": "STANDARD",
    "accommodation_categories": ["ROOM"],
    "equipments": ["AIR_CONDITIONING"],
    "services": ["HOUSEKEEPING"]
  }
]

info: this route is product-centric: it helps describe the room offer, but it does not guarantee that a given arrangement is available on the current proposal.

Response codes

OK Response (200): returns the accommodation catalog for the requested product.
Error (400): bad_request or validation_error.
Error (403): forbidden.
Error (404): not_found or unknown product.

GET/v2/products/{product_id}/accommodations

Compare the available room arrangements

Mandatory

Use POST/v1/accommodations_arrangement/search to retrieve the room arrangements available for one proposal and compare their pricing impact before updating the proposal.

Prerequisites

Reuse the proposal_id returned by the first step.
Send accept-language and x-api-key.
Optionally pass booking_id or customer_id in query when the journey is tied to a booking or customer context.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v1/accommodations_arrangement/search?proposal_id=123456' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "accommodation_arrangement": [
      {
        "quantity": 1,
        "occupancy": 2,
        "shared_room": false,
        "attendees": ["A", "B"],
        "accommodation_categories": ["ROOM"]
      }
    ],
    "differential_prices": [
      {
        "amount": 250,
        "currency": "EUR"
      }
    ],
    "remaining_stock": 2,
    "is_upgradable_online": true
  }
]

info: the response is ordered from the lowest differential price to the highest one, which helps rank alternatives in a comparison UI.

Response codes

OK Response (200): returns the room arrangements compatible with the current proposal context.
Error (400): invalid booking or proposal, inconsistent customer context, bad_request, validation_error, or malformed JSON payload.
Error (401): unauthorized.
Error (404): the booking or proposal was not found, or was not found for the submitted customer.
Error (409): the proposal criteria are no longer valid.

POST/v1/accommodations_arrangement/search

Apply the selected room arrangement

Mandatory

Use PUT/v1/proposals/{proposal_id}/accommodations_arrangement to apply the chosen room arrangement once the business target has been validated.

Prerequisites

Reuse the proposal_id of the proposal to update.
Send accept-language and x-api-key.
Build the request body from the arrangement selected in the previous step.

Calling CURL

curl -X 'PUT' \
  'https://api.clubmed.com/v1/proposals/123456/accommodations_arrangement' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '@selected-arrangement.json'

Example answer

{}

info: the API returns 204 No Content on success, so the safest way to verify the change is to re-read the proposal after the update.

Response codes

OK Response (204): the selected room arrangement was applied successfully.
Error (400): missing attendees, duplicated attendees, invalid booking criteria, unavailable room, bad_request, validation_error, or malformed JSON payload.
Error (403): forbidden.

PUT/v1/proposals/{proposal_id}/accommodations_arrangement