Complete booking journey

Booking
Booking
6 routes

How do I move from a proposal to a validated and reviewed booking?

This journey covers a full booking flow, from proposal search to final review of the validated booking. In addition to creation steps, it includes payment schedule review and booking validation through payment.

The scenario is suited for end-to-end functional documentation, with a specific focus on dependencies between proposal, booking, and payment.

Overview

This scenario documents a full booking journey when the objective is to cover the main lifecycle end to end: proposal search, preparation, payment schedule review, booking creation, payment-based validation, and final booking control.

Prerequisites

A valid x-api-key and a consistent locale across the full journey.
An authorization bearer token for protected routes.
The ability to obtain or build a usable proposal before creating the booking.
A booking_id after creation, and then a customer_id for the final read-back.
Payment information required for validation, even though the exact payload is not visible in the available excerpt.

Expected result

The journey should end with a validated booking, a readable view of expected amounts, and a final response that exposes booking and payment statuses.

Flow assumptions

The selected path reads the payment schedule at proposal level before booking validation. It also assumes that final validation relies on PATCH/v2/bookings/{booking_id}, whose business purpose is documented even though the detailed request body is not exposed in the available excerpt.

Process workflow

Legend:

Mandatory

Optional

Search for a best-fit proposal

Mandatory

This step uses POST/v1/proposals/search/best to look for the best proposal matching the booking criteria. It returns a proposal identifier, pricing information, stock indicators, and option eligibility when available.

Prerequisites

Send accept-language and x-api-key.
Add authorization when the customer or partner context requires it.
Prepare the booking criteria in the request body before running the search.

Calling CURL

curl -X POST \
  -H "accept-language: en-US" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v1/proposals/search/best"

Example answer

{
  "id": "123456",
  "label": "Proposal with one club room",
  "product_id": "MPAC",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "option_available": true
}

info: This route is mainly used to obtain the best proposal for a booking context before qualifying attendees or continuing the flow.

Response codes

200 OK: the best available proposal is returned.
400 Bad Request: the submitted criteria are incomplete, inconsistent, or the JSON payload is invalid.
403 Forbidden: at least one added customer is not allowed to continue.
404 Not Found: the requested product is unknown.

POST/v1/proposals/search/best

Prepare the prebooking

Mandatory

Use POST/v1/prebookings to retrieve the first prebooking details from a priced proposal. This intermediate step helps confirm the attendee structure and the transformation readiness of the file before final booking creation.

Prerequisites

Send accept-language, authorization when required, and x-api-key.
Reuse a priced proposal in the request payload.
Keep the same locale context as the proposal.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v1/prebookings' \
  -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

[
  {
    "customer_id": "123456789",
    "type": "MAIN"
  }
]

info: This route does not create the booking yet. It validates that the priced proposal can be transformed correctly before the final step.

Response codes

200 OK: returns the prebooking information.
400 Bad Request: the payload is invalid, incomplete, or malformed.
401 Unauthorized: authentication is missing, invalid, or expired.

POST/v1/prebookings

Review the payment schedule

Mandatory

Use GET/v1/proposals/{proposal_id}/payment_schedule to review the payment schedule attached to the proposal. This step documents expected amounts, deadlines, and household breakdown before the booking is validated and paid.

Prerequisites

Provide proposal_id.
Send x-api-key.
Keep the selected proposal stable until the final payment step.

Calling CURL

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

Example answer

{
  "currency": "EUR",
  "commission_included": true,
  "households": [
    {
      "total": 9815.4,
      "deposit_repayment_schedule": [
        {
          "expected_payment_amount": 1200,
          "deadline": "2026-04-20"
        }
      ]
    }
  ]
}

info: This route helps the UI explain the payment plan before the file moves to booking and payment validation.

Response codes

200 OK: returns the proposal payment schedule.
400 Bad Request: the request is invalid.
403 Forbidden: the proposal is not accessible in the current context.
404 Not Found: the proposal cannot be found.
409 Conflict: the promotion or commercial context is no longer applicable.

GET/v1/proposals/{proposal_id}/payment_schedule

Create the booking from the proposal

Mandatory

POST/v3/bookings creates a booking from the selected proposal. The documentation indicates that the proposal must already be qualified and that booking creation decreases Club Med stock.

Prerequisites

Send accept-language and x-api-key.
Add authorization when the context requires it.
Keep the same locale that was used to create and qualify the proposal.
Prepare the minimal body expected to create the booking from the proposal.

Calling CURL

curl -X POST \
  -H "accept-language: en-US" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v3/bookings"

Example answer

{
  "booking_id": "0123456789",
  "attendees": [
    {
      "customer_id": "123456789",
      "type": "ADULT"
    }
  ]
}

info: Booking creation is the step that commits the reservation from the qualified proposal.

Response codes

200 OK: the booking was created and returns confirmation data.
201 Created: the booking is successfully created.
400 Bad Request: the submitted payload is invalid or incomplete.
403 Forbidden: some usages, such as reserved parameters, are not allowed.

POST/v3/bookings

Validate the booking with payment

Mandatory

Use PATCH/v2/bookings/{booking_id} to validate the booking through one or more payments. This is the final confirmation step once the proposal has been turned into a booking.

Prerequisites

Provide booking_id.
Send accept-language, authorization when required, x-agent-id if your context needs it, and x-api-key.
Prepare the payment payload expected for the targeted booking.

Calling CURL

curl -X 'PATCH' \
  'https://api.clubmed.com/v2/bookings/0123456789' \
  -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

HTTP/1.1 204 No Content

info: This payment-validation step happens after booking creation. When the API returns 204, the booking is confirmed with no response body.

Response codes

204 No Content: the booking has been validated through payment.
400 Bad Request: the request or payment payload is invalid.
401 Unauthorized: authentication is missing, invalid, or expired.

PATCH/v2/bookings/{booking_id}

Review the final booking

Mandatory

GET/v3/customers/{customer_id}/bookings/{booking_id} reads back the validated file from the customer scope. It exposes booking and payment statuses, stay details, packages, accommodations, and several useful links.

Prerequisites

Send accept-language, authorization, and x-api-key.
Provide customer_id and booking_id.

Calling CURL

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

Example answer

{
  "id": "12345",
  "booking_status": "VALIDATED",
  "payment_status": "PAID",
  "locale": "fr-FR"
}

info: This final readback confirms booking and payment statuses from the customer scope.

Response codes

200 OK: the customer booking details are returned.
403 Forbidden: customer_id, issuer, or locale do not match.
404 Not Found: the booking cannot be found for this customer.

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