Refresh a proposal and search accommodation arrangements

  • Booking
  • 4 routes
How do I inspect a proposal, refresh it, and compare 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.

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.

Process workflow

Legend:
Mandatory
Optional
1

Get proposal details

Mandatory

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

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

Example answer

{
  "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.
GET/v2/proposals/{proposal_id}
See more
2

Retrieve validation schema

Mandatory

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

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

{
  "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.
GET/v3/schemas/{resource}/{localeOrCountry}
See more
3

Refresh the proposal

Mandatory

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

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

{
  "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.
POST/v1/proposals/{proposal_id}/refresh
See more
4

Search for accommodations arrangement

Mandatory

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

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

[
  {
    "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.
POST/v1/accommodations_arrangement/search
See more