Real time booking cancellation notification

Stay up-to-date on your bookings

There can be many reasons why a booking might be cancelled — from a change in travel plans to unexpected events. At Holidu, it is our responsibility to make sure that our partners are informed of booking cancellations in a timely manner.

This document covers the booking cancellation notification for both Holidu Payment (HoPa) and non-Holidu Payment partners.

How It Works

Guest Experience

Guest initiates cancellation — The guest visits their Holidu post-booking page and selects "Cancel booking"
Reason selection — Guest chooses a cancellation reason and confirms
Confirmation — Guest sees a confirmation page and receives a cancellation email
Partner notification — Holidu sends a cancellation notification to your API endpoint

Before You Start

The cancellation notification is not enabled by default. As a Holidu API partner, you will need to implement a certain degree of logic on your system in order to consume the event successfully.

Requirements

Dedicated endpoint — Have an endpoint to accept booking cancellation events (and in the future, booking modification events as well)
Idempotency — Ensure that your endpoint is idempotent. This guarantees that all cancellation notification requests are processed consistently and simplifies error handling

Implementing Booking Cancellation Notification

Request

Method: POST
Content-Type: application/json

Your endpoint will receive a JSON payload with the following structure:

{
  "holiduBookingId": 3536882,
  "providerBookingId": "test_bk-6148266",
  "action": "CANCELLATION",
  "cancellationFee": {
    "amount": 50,
    "currency": "EUR"
  },
  "cancellationReason": "CUSTOMER_UNKNOWN_REASON",
  "paymentHandler": "HOLIDU"
}

Request Fields

Parameter	Type	Required	Description
`holiduBookingId`	Integer	Yes	The booking ID on the Holidu system
`providerBookingId`	String	Yes	The corresponding booking ID on your system
`action`	String	Yes	The action of the notification. Currently only `CANCELLATION` is supported
`cancellationFee`	Object	No	Cancellation fee details. Only included for Holidu Payment bookings
`cancellationFee.amount`	Integer	No	The cancellation fee amount
`cancellationFee.currency`	String	No	The cancellation fee currency (e.g., `EUR`)
`cancellationReason`	String	Yes	The reason for the booking cancellation
`paymentHandler`	String	Yes	Indicates who handles the payment: `HOLIDU` or `PARTNER`

Response

Your endpoint must respond with an acknowledgment:

{
  "status": "ACKNOWLEDGED"
}

HTTP Status: 200 OK

Parameter	Type	Required	Description
`status`	String	Yes	Confirmation that you acknowledged the request and will process it on your system

Holidu Payment vs Non-Holidu Payment

The cancellation notification works for both payment models, with some key differences:

Aspect	Holidu Payment (HoPa)	Non-Holidu Payment
`paymentHandler` value	`"HOLIDU"`	`"PARTNER"`
`cancellationFee` object	Included (when applicable)	Not included
Payment processing	Holidu handles refunds	Partner handles refunds

Example: Holidu Payment Request

{
  "holiduBookingId": 3536882,
  "providerBookingId": "test_bk-6148266",
  "action": "CANCELLATION",
  "cancellationFee": {
    "amount": 50,
    "currency": "EUR"
  },
  "cancellationReason": "CUSTOMER_UNKNOWN_REASON",
  "paymentHandler": "HOLIDU"
}

Example: Non-Holidu Payment Request

{
  "holiduBookingId": 4930433,
  "providerBookingId": "709489",
  "action": "CANCELLATION",
  "cancellationReason": "CUSTOMER_UNKNOWN_REASON",
  "paymentHandler": "PARTNER"
}

Testing Your Integration

You can test your endpoint using curl:

curl --location --request POST 'https://your-domain.com/booking/cancel' \
  --header 'Content-Type: application/json' \
  --data '{
    "holiduBookingId": 4930433,
    "providerBookingId": "709489",
    "action": "CANCELLATION",
    "cancellationReason": "CUSTOMER_UNKNOWN_REASON",
    "paymentHandler": "PARTNER"
  }'

Expected Response:

HTTP 200
{
  "status": "ACKNOWLEDGED"
}

Important Notes

For Holidu Payment bookings: The notification is initiated only after Holidu has successfully cancelled the booking. As soon as you receive the notification, mark the corresponding booking as cancelled in your system.

For non-Holidu Payment bookings: Since payment handling remains with you, ensure you process any necessary refunds according to your cancellation policy after receiving the notification.

Integration Checklist

Implement a cancellation endpoint that accepts the request format above
Ensure your endpoint is idempotent
Return {"status": "ACKNOWLEDGED"} with HTTP 200
Process the cancellation in your system upon receiving the notification
Provide your cancellation endpoint URL to your Holidu Technical Account Manager