---
uuid: 0e4b4174-6a89-4815-aebf-2505c4f6699b
date_created: 2025-07-04T13:46:03.264Z
date_updated: 2026-04-03T17:59:08.857Z
seo_url: proposals-add-or-change-accommodations
category: Option creation
routes: 
  - POST /v3/proposals/search
  - GET /v2/products/{product_id}/accommodations
  - POST /v1/accommodations_arrangement/search
  - PUT /v1/proposals/{proposal_id}/accommodations_arrangement
---

# Proposals: Add or change accommodations

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.

## Flow

```mermaid
flowchart LR
    step0["Generate a baseline proposal"]
    step1["Browse the product accommodation catalog"]
    step2["Compare the available room arrangements"]
    step3["Apply the selected room arrangement"]
    step0 --> step1
    step1 --> step2
    step2 --> step3
    classDef optional fill:transparent,stroke:#ffffff,color:#ffffff,stroke-width:1px,stroke-dasharray: 6\,4
    class step1 optional
```

## 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.

## 1 - Generate a baseline proposal

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

```bash
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

```json
[
  {
    "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.

**Related route**: [POST https://api.clubmed.com//v3/proposals/search](https://api.clubmed.com/doc?search=POST%20%2Fv3%2Fproposals%2Fsearch)

## 2 - Browse the product accommodation catalog

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

```bash
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

```json
[
  {
    "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.

**Related route**: [GET https://api.clubmed.com//v2/products/{product\_id}/accommodations](https://api.clubmed.com/doc?search=GET%20%2Fv2%2Fproducts%2F%7Bproduct_id%7D%2Faccommodations)

## 3 - Compare the available room arrangements

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

```bash
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

```json
[
  {
    "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.

**Related route**: [POST https://api.clubmed.com//v1/accommodations\_arrangement/search](https://api.clubmed.com/doc?search=POST%20%2Fv1%2Faccommodations_arrangement%2Fsearch)

## 4 - Apply the selected room arrangement

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

```bash
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

```json
{}
```

> **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.

**Related route**: [PUT https://api.clubmed.com//v1/proposals/{proposal\_id}/accommodations\_arrangement](https://api.clubmed.com/doc?search=PUT%20%2Fv1%2Fproposals%2F%7Bproposal_id%7D%2Faccommodations_arrangement)