Reservations

Introduction

When creating a reservation through the Zepl API, you can choose between two booking flows based on your use case: Instant Booking and Pending Confirmation. This determines how the reservation is processed and whether it requires an additional confirmation step.

Reservation Types

Instant Booking

INSTANT_BOOKING is the default reservation type. When you create a reservation with this type, it is immediately confirmed — no further action is required.

The reservation status is set to CONFIRMED
The confirmedAt timestamp is set to the time of creation
Availability is decremented for the booked dates

{
  "listingID": "...",
  "checkInDate": "2025-06-01",
  "checkOutDate": "2025-06-05",
  "reservationType": "INSTANT_BOOKING",
  "guest": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "guests": 2,
  "adults": 2,
  "notes": "Late check-in",
  "source": "website",
  "totalBasePrice": 400,
  "totalFeePrice": 50,
  "totalTaxPrice": 45,
  "totalPrice": 495
}

If you omit the reservationType field, it defaults to INSTANT_BOOKING.

Pending Confirmation

PENDING_CONFIRMATION creates a reservation that requires an explicit confirmation step before it is finalized. This is useful when you need to review or approve bookings before committing them.

The reservation status is set to PENDING
The confirmedAt field is null until confirmed
Availability is still decremented immediately to hold the dates

{
  "listingID": "...",
  "checkInDate": "2025-06-01",
  "checkOutDate": "2025-06-05",
  "reservationType": "PENDING_CONFIRMATION",
  "guest": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "guests": 2,
  "adults": 2,
  "notes": "",
  "source": "website",
  "totalBasePrice": 400,
  "totalFeePrice": 50,
  "totalTaxPrice": 45,
  "totalPrice": 495
}

Even though the reservation is pending, availability is decremented immediately to prevent double bookings for the same dates.

Confirming a Pending Reservation

To confirm a reservation that was created with PENDING_CONFIRMATION, use the confirm endpoint:

POST /api/v1/reservation/{reservationId}/confirm

This will:

Set the reservationType to CONFIRMED
Set the status to CONFIRMED
Set the confirmedAt timestamp

The reservation must have reservationType of PENDING_CONFIRMATION. Attempting to confirm an INSTANT_BOOKING reservation will return an error.

Cancellation Terms

Every reservation is booked under a cancellation policy. The quote returns the terms as cancellationPolicy; send the quote's quoteToken with the reservation and the booking is made under exactly those terms. The reservation response, and later GET /api/v1/reservation/{reservationId}, return the booked terms together with the salesChannel the stay was sold on. See Cancellation Policies for how policies are defined and resolved.

Cancelling a Reservation

To cancel a reservation, use the cancel endpoint and say who asked for the cancellation:

DELETE /api/v1/reservation/{reservationId}?cancelledBy=guest

cancelledBy is guest, host or system. When omitted, the cancellation is recorded without an initiator and no charge is calculated.

Only reservations with a CONFIRMED status can be cancelled. When a reservation is cancelled:

The status is set to CANCELLED
The cancelledAt timestamp is set
Availability is restored for the previously booked dates
For most providers, a cancellation request is sent to the PMS
When the guest cancelled, cancellationCharge is worked out from the booked terms at the moment of the request

{
  "id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
  "status": "CANCELLED",
  "cancelledAt": "2026-11-25T09:00:00.000Z",
  "cancelledBy": "GUEST",
  "cancellationCharge": {
    "penaltyPercentage": 50,
    "penaltyAmount": 243,
    "refundPercentage": 50,
    "refundAmount": 243,
    "currency": "EUR"
  }
}

API Reference

For detailed API documentation, refer to the following endpoints:

On this page