---
uuid: fe4c6617-0d8c-4573-b076-3a5c660cd177
date_created: 2025-07-23T07:38:46.343Z
date_updated: 2026-04-07T09:48:40.789Z
seo_url: booking-path-option-durations
category: Booking
routes: 
  - POST /v3/proposals/search
  - GET /v2/proposals/{proposal_id}
  - POST /v1/proposals/{proposal_id}/refresh
  - PUT /v3/proposals/{proposal_id}/attendees
---

# Booking path with option durations

This scenario documents a booking path focused on proposal creation, consultation, refresh, and attendee qualification, with specific attention to option duration. It fits flows that need to secure a file before it is turned into a booking.

The flow creates a proposal, rereads its details, refreshes it to confirm freshness, and then updates attendees.

## Flow

```mermaid
flowchart LR
    step0["Search matching proposals"]
    step1["Read back the created proposal"]
    step2["Refresh the proposal before attendee qualification"]
    step3["Qualify the proposal attendees"]
    step0 --> step1
    step1 --> step2
    step2 --> step3
    classDef optional fill:transparent,stroke:#ffffff,color:#ffffff,stroke-width:1px,stroke-dasharray: 6\,4
    class step3 optional
```

## Overview

This scenario helps an application prepare a reservation file while monitoring the time validity of the option attached to the proposal.

## Prerequisites

* The search criteria required to create the proposal.
* A `proposal_id` returned by the first step.
* The attendee information needed to complete the proposal.
* A valid `x-api-key` and, depending on the channel, an appropriate authorization context.

## Expected result

The application can build a proposal, track its option duration, refresh its information, and complete attendees before the next step of the journey.

## 1 - Search matching proposals

Use `POST /v3/proposals/search` to create the proposal that will support the rest of the booking path. This route calculates the first pricing and stock context, then returns the `proposal_id` that the following steps will reuse.

#### Prerequisites

* Send `accept-language` and `x-api-key`.
* Add `authorization` when the partner or seller context requires it.
* Prepare the booking criteria expected by the route in the JSON payload.

#### 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 '{ ... }'
```

#### Example answer

```json
{
  "id": "123456",
  "product_id": "MPAC",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "remaining_stock": 2,
  "option_durability": {
    "is_reliable": true,
    "expiration_date_time": "20160415T10:23:00.234Z"
  }
}
```

> **info:** Reuse the returned `proposal_id` and `option_durability` in the next steps to monitor the time window attached to the proposal.

***

**Response codes**

* `200 OK`: returns the matching proposal.
* `400 Bad Request`: the payload is invalid, incomplete, or inconsistent.
* `401 Unauthorized`: authentication is missing, invalid, or expired.
* `403 Forbidden`: the current context cannot create the proposal.
* `404 Not Found`: the product cannot be found.
* `409 Conflict`: 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 - Read back the created proposal

Use `GET /v2/proposals/{proposal_id}` to inspect the proposal that was just created. This readback confirms price, option duration, stock, and the main selling components before you decide whether to refresh or qualify attendees.

#### Prerequisites

* Provide `proposal_id`.
* Send `x-api-key`.
* Keep the same business context used to create the proposal.

#### 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",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "remaining_stock": 2,
  "option_durability": {
    "is_reliable": true,
    "expiration_date_time": "20160415T10:23:00.234Z"
  }
}
```

> **info:** This step is the safest way to confirm the current commercial state of the proposal before any update.

***

**Response codes**

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

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

## 3 - Refresh the proposal before attendee qualification

Use `POST /v1/proposals/{proposal_id}/refresh` to refresh an existing proposal before completing attendee information. This step is especially useful when the option duration is short or when you want to confirm that price and stock are still current.

#### Prerequisites

* Provide `proposal_id`.
* Send `accept-language`, `authorization` when required, and `x-api-key`.
* Keep the same locale used when the proposal was first created.

#### 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:** Refreshing just before attendee qualification reduces the risk of validating a file on stale stock or stale pricing.

***

**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 - Qualify the proposal attendees

Use `PUT /v3/proposals/{proposal_id}/attendees` to attach or update attendees on the proposal before moving to booking creation. This is where identity, household composition, and customer linkage are secured on the file.

#### Prerequisites

* Provide `proposal_id`.
* Send `accept-language`, `authorization` when required, and `x-api-key`.
* Prepare an attendee payload that respects the documented rules for birthdates, documents, and household consistency.

#### Calling CURL

```bash
curl -X 'PUT' \
  'https://api.clubmed.com/v3/proposals/123456/attendees' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### Example answer

```json
[
  {
    "attendees": [
      {
        "id": "A",
        "customer_id": "123456789",
        "customer_status": "NEW_CUSTOMER",
        "loyalty_status": "GOLD"
      }
    ]
  }
]
```

> **info:** Most validation constraints on identity and travel documents are enforced at this step, so it is worth surfacing errors clearly in the UI.

***

**Response codes**

* `200 OK`: returns the updated attendee structure.
* `400 Bad Request`: attendee data is invalid, incomplete, duplicated, or inconsistent.
* `401 Unauthorized`: authentication is missing, invalid, or expired.
* `403 Forbidden`: at least one customer is not allowed to continue.
* `409 Conflict`: the proposal is no longer economically valid.

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