Get offers

This page covers how to load the properties available for booking, search for available rates, and retrieve optional add-on services — along with how to calculate the amount to charge the guest.

Load properties

Start by fetching the properties your IBE should present to guests:

GET /inventory/v1/properties

Each property in the response has an id (for example, MUC). Use this as the propertyId parameter in your offers request. For a single-property IBE you can hardcode this value, but fetching it dynamically makes your integration portable across properties.

Search for offers

Call the offers endpoint with the guest’s search criteria:

GET /booking/v1/offers?propertyId={id}&arrival={date}&departure={date}&adults={n}&channelCode=Ibe

The channelCode=Ibe parameter is required. It filters results to rate plans distributed via the IBE channel and ensures bookings are attributed correctly in reporting.

The adults parameter represents the number of adults per room. For multi-room bookings, call the endpoint once per room and pass the number of adults for that room each time. Each call returns independent availability and pricing for a single unit.

If the guest is travelling with children, pass their ages using the childrenAges parameter — for example, &childrenAges=5,8. Age is required rather than a headcount because rate plans and services (such as breakfast or extra beds) are often priced differently by age. Omitting ages when children are present may return inaccurate pricing.

Response

{
  "offers": [
    {
      "ratePlan": { "name": "Non Refundable", ... },
      "unitGroup": { "name": "Single", ... },
      "minGuaranteeType": "Prepayment",
      "availableUnits": 22,
      "totalGrossAmount": { "amount": 151.00, "currency": "EUR" },
      "prePaymentGrossAmount": { "amount": 151.00, "currency": "EUR" },
      "cancellationFee": { "code": "STR", "fee": { "amount": 151.00, "currency": "EUR" } },
      "noShowFee": { "code": "NOSHOW", "fee": { "amount": 151.00, "currency": "EUR" } },
      "cityTax": { "grossAmount": 21.40, "netAmount": 20.00, ... },
      "timeSlices": [ ... ],
      "services": [ ... ],
      "lineItems": [ ... ],
      "taxDetails": [ ... ]
    }
  ]
}

Each offer includes a minGuaranteeType field. This tells you what the payment step must do for that rate plan — whether to charge the guest now, validate a card, or take no payment. You will use this in the next step. See Authorise the payment.

Some offers include mandatory services — for example, a cleaning fee or a resort charge. These are set up as additional services included in the rate plan. They are booked as extras and cannot be removed. Because they affect the total price, display them to the guest during the booking flow.

Get service offers

Once the guest selects a rate, fetch the optional add-on services available for that rate plan:

GET /booking/v1/service-offers?ratePlanId={id}&arrival={date}&departure={date}&adults={n}&channelCode=Ibe

Response

{
  "services": [
    {
      "service": { "name": "Breakfast", "pricingUnit": "Person", ... },
      "count": 1,
      "totalAmount": { "grossAmount": 20.00, "netAmount": 16.81, ... },
      "prePaymentGrossAmount": { "amount": 20.00, "currency": "EUR" },
      "dates": [
        {
          "serviceDate": "2024-03-15",
          "amount": { "grossAmount": 20.00, "netAmount": 16.81, ... },
          "isDefaultDate": true
        }
      ]
    }
  ]
}

The guest can add one or more service offers as extras to their reservation.

Calculate the payment amount

Sum the prePaymentGrossAmount across the selected stay offer and any service offers the guest has added. This is the total to charge at booking and the figure you will pass to Adyen in the next step.

totalGrossAmount (for the stay) and totalAmount (for services) do not include city tax or additional fees — Apaleo adds those automatically when the booking is created. Calculate the payment amount from prePaymentGrossAmount only. Do not add city tax on top.

For multi-room bookings, calculate the prePaymentGrossAmount per room separately. The prePaymentAmount is set at the reservation level in the booking request — not as a single total for the whole booking. When authorising with Adyen, pass the combined sum of all rooms as a single payment. When creating the booking, split that total back across the individual reservations.

The prePaymentAmount for a reservation cannot exceed its totalGrossAmount. If you apply a discount or adjust the amount for any reason, make sure the figure you pass to Apaleo stays within the reservation total. Exceeding it will cause the booking request to fail.