---
uuid: 2cadf04c-293d-49b0-9484-26f26b54dc9a
date_created: 2026-02-26T16:41:37.048Z
date_updated: 2026-04-07T09:48:40.789Z
seo_url: complete-booking-journey
category: Booking
tags: 
  - Booking
  - Proposal service
  - Customers
routes: 
  - POST /v1/proposals/search/best
  - POST /v1/prebookings
  - GET /v1/proposals/{proposal_id}/payment_schedule
  - POST /v3/bookings
  - PATCH /v2/bookings/{booking_id}
  - GET /v3/customers/{customer_id}/bookings/{booking_id}
---

# Complete booking journey

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.

## Flow

```mermaid
flowchart LR
    step0["Search for a best-fit proposal"]
    step1["Prepare the prebooking"]
    step2["Review the payment schedule"]
    step3["Create the booking from the proposal"]
    step4["Validate the booking with payment"]
    step5["Review the final booking"]
    step0 --> step1
    step1 --> step2
    step2 --> step3
    step3 --> step4
    step4 --> step5
```

## 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.

## 1 - Search for a best-fit proposal

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

```bash
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

```json
{
  "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.

**Related route**: [POST https://api.clubmed.com//v1/proposals/search/best](https://api.clubmed.com/doc?search=POST%20%2Fv1%2Fproposals%2Fsearch%2Fbest)

## 2 - Prepare the prebooking

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

```bash
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

```json
[
  {
    "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.

**Related route**: [POST https://api.clubmed.com//v1/prebookings](https://api.clubmed.com/doc?search=POST%20%2Fv1%2Fprebookings)

## 3 - Review the payment schedule

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

```bash
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

```json
{
  "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.

**Related route**: [GET https://api.clubmed.com//v1/proposals/{proposal\_id}/payment\_schedule](https://api.clubmed.com/doc?search=GET%20%2Fv1%2Fproposals%2F%7Bproposal_id%7D%2Fpayment_schedule)

## 4 - Create the booking from the proposal

`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

```bash
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

```json
{
  "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.

**Related route**: [POST https://api.clubmed.com//v3/bookings](https://api.clubmed.com/doc?search=POST%20%2Fv3%2Fbookings)

## 5 - Validate the booking with payment

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

```bash
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
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.

**Related route**: [PATCH https://api.clubmed.com//v2/bookings/{booking\_id}](https://api.clubmed.com/doc?search=PATCH%20%2Fv2%2Fbookings%2F%7Bbooking_id%7D)

## 6 - Review the final booking

`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

```bash
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

```json
{
  "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.

**Related route**: [GET https://api.clubmed.com//v3/customers/{customer\_id}/bookings/{booking\_id}](https://api.clubmed.com/doc?search=GET%20%2Fv3%2Fcustomers%2F%7Bcustomer_id%7D%2Fbookings%2F%7Bbooking_id%7D)