Create the booking

This page covers how to submit the booking to Apaleo once the guest has confirmed their details and the payment has been authorised.

Booking request

Call the bookings endpoint with the guest details, reservation data, and the PSP reference from the payment step:

POST /booking/v1/bookings

{
  "booker": {
    "firstName": "Jon",
    "lastName": "Doe",
    "email": "jon.doe@example.com",
    "phone": "+4989123343",
    "address": {
      "addressLine1": "My Street 1",
      "postalCode": "12453",
      "city": "Munich",
      "countryCode": "DE"
    }
  },
  "reservations": [
    {
      "arrival": "2026-03-15",
      "departure": "2026-03-17",
      "adults": 2,
      "channelCode": "Ibe",
      "primaryGuest": {
        "firstName": "Jon",
        "lastName": "Doe",
        "email": "jon.doe@example.com"
      },
      "guaranteeType": "Prepayment",
      "timeSlices": [
        { "ratePlanId": "MUC-NONREF-SGL" },
        { "ratePlanId": "MUC-NONREF-SGL" }
      ],
      "services": [
        { "serviceId": "MUC-BRKF" }
      ],
      "prePaymentAmount": {
        "amount": 151.00,
        "currency": "EUR"
      }
    }
  ],
  "transactionReference": "851570021506441J"
}

channelCode

Always set channelCode to "Ibe" for reservations created through your booking engine. This field drives reporting, revenue attribution, and channel-specific rate plan filtering. Using "Direct" will misattribute bookings.

transactionReference

Set transactionReference to the pspReference returned by Adyen after a successful authorisation. When a transactionReference is present, Apaleo finalises the transaction automatically once the booking is confirmed — regardless of the reservation’s guarantee type or the property’s payment automation settings.

Only set transactionReference if you collected a payment from the guest. For CreditCard and PM6Hold guarantee types where no charge was made, omit this field. Passing a transactionReference without a corresponding prepayment intent will trigger an unintended capture.

prePaymentAmount

Set prePaymentAmount to the sum of the prePaymentGrossAmount values from all selected offers, including any service offers the guest added.

Do not include city tax or custom fees — Apaleo adds those automatically. All amounts must be gross amounts.

Amount alignment: prePaymentAmount is in major currency units (for example, 151.00 EUR). The amount you passed to Adyen in the payment step was in minor units (15100). These must represent the same value. A mismatch will cause transaction finalisation to fail.

Payment account

If you want to store the guest’s card against the booking for future charges — no-shows, late cancellations, post-stay billing — you can create the payment account directly in the booking creation request by including the tokenisation values from the Adyen response in the request body:

{
  "booker": { ... },
  "reservations": [ ... ],
  "transactionReference": "851570021506441J",
  "paymentAccount": {
    "payerReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3",
    "storedPaymentMethodId": "8415689021960227"
  }
}

Set storedPaymentMethodId to "LATEST" to use the most recent authorisation for a given payerReference.

If you need to create or update a payment account after the booking is already confirmed, use the dedicated endpoints:

Using the pspReference from the authorisation:

POST /booking/v1/payment-accounts/by-authorization

{
  "target": { "type": "Booking", "id": "KYKXKLWL" },
  "transactionReference": "851570021506441J"
}

Using the tokenisation values from the Adyen response:

POST /booking/v1/payment-accounts/by-stored-payment-method

{
  "target": { "type": "Booking", "id": "KYKXKLWL" },
  "payerReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3",
  "storedPaymentMethodId": "8415689021960227"
}

For the full payment accounts guide, see Payment accounts.

Webhooks

If you subscribe to the ReservationCreated event, you can trigger notifications — for example, a booking confirmation email — as soon as Apaleo confirms the reservation. See Webhooks.