Room Reservations

Room reservations are for hotels and accommodations, with check-in/check-out dates and nightly rates.

Create a room resource

TypeScript

import { ResourceType, ResourceInstanceStatus } from 'wiil-core-js';

const roomResource = await client.reservationResources.create({
  name: 'Deluxe Ocean Suite',
  resourceType: ResourceType.ROOM,
  capacity: 4,
  isAvailable: true,
  amenities: ['WiFi', 'Air Conditioning', 'Mini Bar', 'Ocean View'],
  checklistTemplate: [],
  applicableTierIds: [],
  instances: [
    { name: 'Room 101', code: 'R101', status: ResourceInstanceStatus.AVAILABLE, isAvailable: true },
    { name: 'Room 102', code: 'R102', status: ResourceInstanceStatus.AVAILABLE, isAvailable: true },
  ],
});

Python

from wiil.models.business_mgt import CreateResource, RoomResource

room = client.reservation_resources.create(
    CreateResource(
        resource_type="room",
        name="Room 101",
        capacity=2,
        reservation_duration=1,
        reservation_duration_unit="nights",
        room_resource=RoomResource(
            room_number="101",
            room_type="Deluxe King",
            price_per_night=299.99,
            bed_type="King",
            is_smoking=False,
        ),
    )
)

Create a room reservation

In TypeScript, room reservations use the roomReservations resource. In Python, the unified reservations resource is used with reservation_type="room".

TypeScript

import {
  CreateRoomReservationSchema,
  ReservationStatus,
  PaymentStatus
} from 'wiil-core-js';

// API expects UTC seconds
const nowSec = Math.floor(Date.now() / 1000);
const checkIn = nowSec + (24 * 60 * 60); // Tomorrow
const checkOut = checkIn + (3 * 24 * 60 * 60); // 3 nights later

const roomReservation = await client.roomReservations.create({
  resourceId: roomResource.id,
  guestId: 'cust_456',
  personsNumber: 2,
  checkIn: checkIn,
  checkOut: checkOut,
  nights: 3,
  status: ReservationStatus.PENDING,
  ratePerNight: [
    { date: new Date(checkIn * 1000).toISOString().split('T')[0], amount: 299.00 },
  ],
  totalWithTax: 980.67,
  deposit: 299.00,
  paymentStatus: PaymentStatus.PENDING,
  notes: 'Late check-in requested around 10 PM',
});

Python

from time import time
from wiil.models.business_mgt import CreateReservation

reservation = client.reservations.create(
    CreateReservation(
        reservation_type="room",
        resource_id="resource_room101",
        customer_id="cust_456",
        start_time=int(time() * 1000),
        end_time=int(time() * 1000) + 3 * 24 * 60 * 60 * 1000,
        duration=3,
        persons_number=2,
        total_price=899.97,
        deposit_paid=299.99,
        is_resource_reservation=True,
    )
)

Read, update, and lifecycle (Python)

In Python, the unified reservations resource provides reads and lifecycle operations for all reservation types:

from wiil.models.business_mgt import UpdateReservation
from wiil.types import PaginationRequest

loaded = client.reservations.get(reservation.id)
by_customer = client.reservations.get_by_customer("cust_456", PaginationRequest(page=1, page_size=20))
by_resource = client.reservations.get_by_resource("resource_room101", PaginationRequest(page=1, page_size=20))

updated = client.reservations.update(
    UpdateReservation(id=reservation.id, persons_number=3, notes="Updated guest count")
)

status_updated = client.reservations.update_status(reservation.id, "confirmed")
rescheduled = client.reservations.reschedule(
    reservation.id,
    start_time=str(int(time() * 1000) + 48 * 60 * 60 * 1000),
    end_time=str(int(time() * 1000) + 49 * 60 * 60 * 1000),
)

Read, update, cancel, delete (TypeScript)

import { UpdateRoomReservationSchema, ReservationStatus } from 'wiil-core-js';

const roomRes = await client.roomReservations.get('reservation_123');
const guestReservations = await client.roomReservations.getByGuest('cust_456');
const resourceReservations = await client.roomReservations.getByResource(roomResource.id);
const all = await client.roomReservations.list();

const updated = await client.roomReservations.update(roomReservation.id, {
  id: roomReservation.id,
  personsNumber: 3,
  deposit: 350.00,
});

const cancelled = await client.roomReservations.cancel(roomReservation.id, 'Change of travel plans');

await client.roomReservations.delete('reservation_123');

RoomReservation fields

Field	Type	Required	Description
resourceId	string	Yes	Requested room resource
guestId	string	Yes	Guest or customer identifier
checkIn / checkOut	number	Yes	Check-in / check-out (Unix timestamps)
nights	integer	Yes	Number of nights
ratePerNight	array	Yes	Nightly price snapshot (date, amount)
totalWithTax	number	Yes	Total amount including tax
paymentStatus	enum	Yes	pending, paid, partial, failed, refunded