Simple booking

Booking
Booking
4 routes

How do I create a simple booking from a proposal?

This scenario explains how to search for the best proposal, prepare the prebooking, create a booking, and finally review the newly created customer booking.

Overview

The journey chains proposal search, prebooking preparation, booking creation, and booking read-back. It covers a simple end-to-end booking path built from an existing proposal context.

Prerequisites

Booking criteria must be available to create the initial proposal.
The proposal context must remain valid through prebooking and booking creation.
Customer-scoped booking review requires customer_id, booking_id, authorization, accept-language, and x-api-key.

Process workflow

Legend:

Mandatory

Optional

Search for a best-fit proposal

Mandatory

Use POST/v1/proposals/search/best to search for a best-fit proposal.

Prerequisites

Prepare the parameters required by the call. Keep x-api-key and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

Calling CURL

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "product-1", "start_date": "2026-07-05", "end_date": "2026-07-12", "attendees": [{"birthdate": "1990-03-12"}]}' \
  "https://api.clubmed.com/v1/proposals/search/best"

Example answer

{
  "id": "proposal-1",
  "product_id": "product-1",
  "price": {
    "amount": 2890,
    "currency": "EUR"
  },
  "option_available": true
}

info: Réutilisez le proposal_id obtenu pour enchaîner avec la pré-réservation puis la création du booking.

Response codes

200 OK: the operation succeeds and the resource is returned.
400 Bad Request: the body or parameters are invalid.
404 Not Found: the target resource cannot be found.

POST/v1/proposals/search/best

Prepare the prebooking

Mandatory

Use POST/v1/prebookings to convert a priced proposal into a prebooking context that can be safely reviewed before booking creation.

Prerequisites

Prepare the parameters required by the call. Keep x-api-key and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

Calling CURL

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"proposal_id": "proposal-1"}' \
  "https://api.clubmed.com/v1/prebookings"

Example answer

{
  "id": "prebooking-1",
  "status": "READY_FOR_BOOKING",
  "proposal_id": "proposal-1"
}

info: The prebooking response helps confirm price, stock, and booking context before the final booking creation.

Response codes

200 OK: the operation succeeds and the resource is returned.
400 Bad Request: the body or parameters are invalid.
404 Not Found: the target resource cannot be found.

POST/v1/prebookings

Create the booking

Mandatory

Use POST/v3/bookings to turn the prepared proposal into a booking once pricing and prebooking checks are complete.

Prerequisites

Prepare the parameters required by the call. Keep x-api-key and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

Calling CURL

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"proposal_id": "proposal-1"}' \
  "https://api.clubmed.com/v3/bookings"

Example answer

{
  "booking_id": "booking-1",
  "booking_status": "OPTION",
  "payment_status": "PENDING"
}

info: Keep the returned booking_id and option data to continue with booking review, payment, or downstream services.

Response codes

200 OK: the operation succeeds and the resource is returned.
400 Bad Request: the body or parameters are invalid.
404 Not Found: the target resource cannot be found.

POST/v3/bookings

Review the created booking

Mandatory

Use GET/v3/customers/{customer_id}/bookings/{booking_id} to confirm that the newly created booking contains the expected stay, status, and travelers.

Prerequisites

Prepare customer_id, booking_id. Keep x-api-key and, when the route is customer-scoped, a valid bearer token.

Calling CURL

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v3/customers/{customer_id}/bookings/{booking_id}"

Example answer

{
  "id": "booking-1",
  "booking_status": "OPTION",
  "payment_status": "PENDING",
  "stays": [
    {
      "product_id": "product-1",
      "label": "Club Med Valmorel"
    }
  ]
}

info: Read back the booking immediately after creation to confirm the proposal was turned into the expected file.

Response codes

200 OK: the expected data is returned.
400 Bad Request: the request is invalid or incomplete.
401 Unauthorized: the token is missing or invalid.
403 Forbidden: access is denied in this context.
404 Not Found: the requested resource cannot be found.

GET/v3/customers/{customer_id}/bookings/{booking_id}