> ## Documentation Index
> Fetch the complete documentation index at: https://docs.koulis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /widget/{token}/reservations — Create a Booking

> Create a reservation via a two-step flow: lock a slot to hold it, then confirm with guest details. Prevents double-bookings during simultaneous sessions.

Creating a reservation through the Widget API is a two-step process. First, you lock the desired slot to hold it temporarily. Then, you confirm the reservation by submitting the guest's contact details. This two-step flow prevents double-bookings when multiple guests are viewing the same time slot simultaneously.

<Warning>
  The lock token returned in step 1 expires quickly. You must complete step 2 before it expires — if it does, the slot is released and you must call the lock endpoint again to reserve a new slot.
</Warning>

<Steps>
  <Step title="Lock a slot">
    Send a POST request to reserve a specific date, time, and party size. The API temporarily holds that slot and returns a `lock_token`.

    ### Endpoint

    ```
    POST https://api.lakreme.fr/api/v1/widget/{publicToken}/reservations/lock
    ```

    No authentication is required.

    #### Path parameters

    <ParamField path="publicToken" type="string" required>
      The public token for the restaurant.
    </ParamField>

    #### Request body

    <ParamField body="date" type="string" required placeholder="YYYY-MM-DD">
      The reservation date in `YYYY-MM-DD` format.
    </ParamField>

    <ParamField body="time" type="string" required placeholder="HH:MM">
      The start time of the slot in `HH:MM` format (24-hour clock).
    </ParamField>

    <ParamField body="guests" type="number" required>
      The number of guests in the party.
    </ParamField>

    <ParamField body="lang" type="string" default="fr">
      Language for the confirmation message returned in step 2. Accepted values: `fr`, `en`.
    </ParamField>

    #### Response fields

    <ResponseField name="lock_token" type="string" required>
      A short-lived token that identifies the locked slot. Pass this token in step 2 to confirm the reservation.
    </ResponseField>

    <ResponseField name="expires_at" type="string" required>
      ISO 8601 timestamp indicating when the lock expires. Complete step 2 before this time.
    </ResponseField>

    <ResponseField name="table_id" type="string" required>
      The ID of the table that was assigned to hold this slot.
    </ResponseField>

    <RequestExample>
      ```bash cURL theme={null}
      curl -X POST "https://api.lakreme.fr/api/v1/widget/tok_abc123/reservations/lock" \
        -H "Content-Type: application/json" \
        -d '{
          "date": "2025-05-15",
          "time": "12:30",
          "guests": 2,
          "lang": "en"
        }'
      ```
    </RequestExample>

    <ResponseExample>
      ```json 200 theme={null}
      {
        "lock_token": "lck_9f3a2b1c4d5e6789",
        "expires_at": "2025-05-12T14:07:00Z",
        "table_id": "tbl_001"
      }
      ```
    </ResponseExample>
  </Step>

  <Step title="Confirm the reservation">
    Submit the guest's contact details along with the `lock_token` from step 1. If the lock is still valid, the reservation is created and a confirmation code is returned.

    ### Endpoint

    ```
    POST https://api.lakreme.fr/api/v1/widget/{publicToken}/reservations
    ```

    No authentication is required.

    #### Path parameters

    <ParamField path="publicToken" type="string" required>
      The public token for the restaurant.
    </ParamField>

    #### Request body

    <ParamField body="lock_token" type="string" required>
      The lock token returned from step 1. This token must not have expired.
    </ParamField>

    <ParamField body="guest_first_name" type="string" required>
      Guest's first name.
    </ParamField>

    <ParamField body="guest_last_name" type="string" required>
      Guest's last name.
    </ParamField>

    <ParamField body="guest_email" type="string" required>
      Guest's email address. La Krème sends the confirmation email here.
    </ParamField>

    <ParamField body="guest_phone" type="string" required>
      Guest's phone number.
    </ParamField>

    <ParamField body="lang" type="string" default="fr">
      Language for the confirmation email and response message. Accepted values: `fr`, `en`.
    </ParamField>

    #### Response fields

    <ResponseField name="reservation_id" type="string" required>
      Unique identifier for the newly created reservation.
    </ResponseField>

    <ResponseField name="confirmation_code" type="string" required>
      A short alphanumeric code the guest can use to reference their booking (for example, `ABC-1234`).
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Initial status of the reservation. `confirmed` if the restaurant uses automatic confirmation, or `pending` if manual confirmation is required.
    </ResponseField>

    <ResponseField name="restaurant_name" type="string" required>
      Name of the restaurant, included for display in your confirmation UI.
    </ResponseField>

    <ResponseField name="date" type="string" required>
      The reservation date in `YYYY-MM-DD` format, echoed back.
    </ResponseField>

    <ResponseField name="time" type="string" required>
      The reservation time in `HH:MM` format, echoed back.
    </ResponseField>

    <ResponseField name="guests" type="number" required>
      The party size, echoed back.
    </ResponseField>

    <ResponseField name="message" type="string" required>
      A human-readable confirmation message in the requested language, suitable for displaying directly to the guest.
    </ResponseField>

    <RequestExample>
      ```bash cURL theme={null}
      curl -X POST "https://api.lakreme.fr/api/v1/widget/tok_abc123/reservations" \
        -H "Content-Type: application/json" \
        -d '{
          "lock_token": "lck_9f3a2b1c4d5e6789",
          "guest_first_name": "Marie",
          "guest_last_name": "Dupont",
          "guest_email": "marie.dupont@example.com",
          "guest_phone": "+33 6 98 76 54 32",
          "lang": "en"
        }'
      ```
    </RequestExample>

    <ResponseExample>
      ```json 201 theme={null}
      {
        "reservation_id": "res_a1b2c3d4",
        "confirmation_code": "ABC-1234",
        "status": "confirmed",
        "restaurant_name": "Le Petit Bistro",
        "date": "2025-05-15",
        "time": "12:30",
        "guests": 2,
        "message": "Your reservation is confirmed! See you on May 15 at 12:30."
      }
      ```
    </ResponseExample>
  </Step>
</Steps>