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.

Cancelling a Reservation

To cancel a reservation, use the cancel endpoint:

DELETE /api/v1/reservation/{reservationId}

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

API Reference

For detailed API documentation, refer to the following endpoints: