Booking path with option durations

  • Booking
  • 4 routes
How do I build a booking flow while monitoring a proposal's option duration?

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.

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.

Process workflow

Legend:
Mandatory
Optional
1

Search matching proposals

Mandatory

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

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

{
  "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.
POST/v3/proposals/search
See more
2

Read back the created proposal

Mandatory

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

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

Refresh the proposal before attendee qualification

Mandatory

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

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

Qualify the proposal attendees

Optional

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

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

[
  {
    "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.
PUT/v3/proposals/{proposal_id}/attendees
See more