---
uuid: ee2fdc0f-2144-4817-81b2-9b6f6da7a0bd
date_created: 2026-01-09T09:38:14.824Z
date_updated: 2026-04-07T09:48:40.789Z
seo_url: refresh-proposal-arrangements
category: Booking
routes: 
  - GET /v2/proposals/{proposal_id}
  - GET /v3/schemas/{resource}/{localeOrCountry}
  - POST /v1/proposals/{proposal_id}/refresh
  - POST /v1/accommodations_arrangement/search
---

# Refresh a proposal and search accommodation arrangements

This scenario explains how to reuse an existing proposal to inspect its content, retrieve the validation schema used by the interface, refresh the proposal, and then compare accommodation arrangements. It fits proposal-review and accommodation-optimization journeys.

The flow starts from a known `proposal_id` and chains consultation, validation support, refresh, and arrangement search.

## Flow

```mermaid
flowchart LR
    step0["Get proposal details"]
    step1["Retrieve validation schema"]
    step2["Refresh the proposal"]
    step3["Search for accommodations arrangement"]
    step0 --> step1
    step1 --> step2
    step2 --> step3
```

## Overview

This scenario helps an application reuse an existing proposal to validate its structure, refresh its commercial data, and compare accommodation arrangements before the next booking step.

## Prerequisites

* A valid `proposal_id`.
* The resource and locale values required by the schema route.
* A valid `accept-language` header and `x-api-key`, plus an authorization context when the route requires one.

## Expected result

The application can display the proposal details, validate the payload structure expected by the UI, refresh the proposal, and compare accommodation arrangements ordered by price differential.

## 1 - Get proposal details

Use `GET /v2/proposals/{proposal_id}` to read back an existing proposal before refreshing it or recalculating accommodation arrangements. This route exposes the current price, option duration, accommodations, included services, and first stock indicators.

#### Prerequisites

* Provide `proposal_id`.
* Send `x-api-key`.
* Keep the same functional locale that was used when the proposal was created if you plan to compare downstream results.

#### Calling CURL

```bash
curl -X 'GET' \
  'https://api.clubmed.com/v2/proposals/123456' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'
```

#### Example answer

```json
{
  "id": "123456",
  "product_id": "MPAC",
  "label": "Proposal with one club room",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "remaining_stock": 2,
  "option_available": true,
  "option_durability": {
    "expiration_date_time": "20160415T10:23:00.234Z",
    "is_reliable": true
  }
}
```

> **info:** Reuse `price`, `remaining_stock`, `option_available`, and `option_durability` to decide whether the proposal should be refreshed before moving forward.

***

**Response codes**

* `200 OK`: returns the proposal details.
* `400 Bad Request`: the request is invalid.
* `409 Conflict`: the proposal's economic conditions are no longer valid or the product is closed for the requested dates.

**Related route**: [GET https://api.clubmed.com//v2/proposals/{proposal\_id}](https://api.clubmed.com/doc?search=GET%20%2Fv2%2Fproposals%2F%7Bproposal_id%7D)

## 2 - Retrieve validation schema

Use `GET /v3/schemas/{resource}/{localeOrCountry}` to retrieve the validation schema expected by the UI or by a later update step. This route helps confirm the expected structure and fields before sending data back to the API.

#### Prerequisites

* Provide `resource` and `localeOrCountry`.
* Send `x-api-key`.
* Keep the same business locale that is used to display or edit the proposal.

#### Calling CURL

```bash
curl -X 'GET' \
  'https://api.clubmed.com/v3/schemas/proposals/en-US' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'
```

#### Example answer

```json
{
  "type": "object",
  "properties": {
    "proposal_id": {
      "type": "string"
    }
  }
}
```

> **info:** This step mainly supports UI-side validation. It does not replace the business readback of the proposal itself.

***

**Response codes**

* `200 OK`: returns the schema associated with the resource and locale.
* `400 Bad Request`: the resource or locale is invalid.
* `404 Not Found`: no schema matches the requested combination.

**Related route**: [GET https://api.clubmed.com//v3/schemas/{resource}/{localeOrCountry}](https://api.clubmed.com/doc?search=GET%20%2Fv3%2Fschemas%2F%7Bresource%7D%2F%7BlocaleOrCountry%7D)

## 3 - Refresh the proposal

Use `POST /v1/proposals/{proposal_id}/refresh` to recalculate an existing proposal from its current context. This route refreshes commercial freshness, price, availability, and price differentials before you compare new accommodation options.

#### Prerequisites

* Provide `proposal_id`.
* Send `accept-language`, `authorization` when required, and `x-api-key`.
* Keep the same locale as the initial proposal.

#### Calling CURL

```bash
curl -X 'POST' \
  'https://api.clubmed.com/v1/proposals/123456/refresh' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY'
```

#### Example answer

```json
{
  "id": "123456",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "remaining_stock": 2,
  "option_durability": {
    "is_reliable": true
  }
}
```

> **info:** Refresh the proposal before making decisions on final pricing or accommodation changes whenever the file may be stale.

***

**Response codes**

* `200 OK`: returns the refreshed proposal.
* `400 Bad Request`: the request is invalid.
* `401 Unauthorized`: authentication is missing, invalid, or expired.
* `403 Forbidden`: the current context cannot refresh this proposal.
* `409 Conflict`: the proposal is no longer economically valid.

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

## 4 - Search for accommodations arrangement

Use `POST /v1/accommodations_arrangement/search` to compare several accommodation arrangements based on a proposal and its traveler composition. The route returns compatible options ordered by price differential and remaining stock.

#### Prerequisites

* Provide the proposal data expected by the route, including traveler and accommodation context.
* Send `accept-language`, `authorization` when required, and `x-api-key`.
* Refresh the proposal first if you want to compare up-to-date results.

#### Calling CURL

```bash
curl -X 'POST' \
  'https://api.clubmed.com/v1/accommodations_arrangement/search' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### Example answer

```json
[
  {
    "differential_prices": {
      "amount": 120,
      "currency": "EUR"
    },
    "remaining_stock": 2,
    "accommodation_arrangement": [
      {
        "accommodation_id": "C2",
        "quantity": 1
      }
    ]
  }
]
```

> **info:** This step helps present room alternatives while preserving the pricing context of the proposal.

***

**Response codes**

* `200 OK`: returns the compatible accommodation arrangements with their price differentials.
* `400 Bad Request`: the payload is invalid or incomplete.
* `401 Unauthorized`: authentication is missing, invalid, or expired.
* `403 Forbidden`: the current context is not allowed to run this search.
* `404 Not Found`: the product or proposal cannot be found.
* `409 Conflict`: the proposal or stock is no longer consistent with the request.

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