Skip to main content

Rental Reservations

Rental reservations book a unit out for a window of time — a bike, a kayak, a camera, an event space — and track everything that comes with handing physical property to a customer: a duration tier, a rental charge and security deposit, an optional waiver and ID verification, a pickup/return checklist, and the return state (including overdue). They are the most operationally involved reservation type because the unit physically leaves and must come back.

Rental reservation lifecycle and operational extrasA rental moves through upcoming, pickup_soon, out, and returned. Overdue and cancelled are exception states. Rentals add a duration tier, a payment with security deposit, a waiver and ID verification, and a pickup/return checklist.LIFECYCLEupcomingpickup_soonoutreturnedoverduecancelledexception states (past endAt / cancelled)WHAT A RENTAL ADDSTierfixed duration optionPayment & depositcharge + security depositWaiver + ID checksigned · verifiedChecklistpickup & return items
Two SDK shapes

The TypeScript SDK exposes a dedicated client.rentalReservations resource with rental-specific fields (tier, payment, deposit status, checklist). The Python SDK creates every reservation type through the unified client.reservations resource using reservation_type="rental" and the shared reservation fields. Both are shown below.

Create a rental resource​

First, create the rental resource and its physical units (see Resources & Instances).

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

const rentalResource = await client.reservationResources.create({
  name: 'Mountain Bike - Premium',
  resourceType: ResourceType.RENTAL,
  capacity: 1,
  isAvailable: true,
  amenities: ['Helmet included', 'Lock included'],
  checklistTemplate: [],
  applicableTierIds: [],
  instances: [
    { name: 'Bike #001', code: 'MTB-001', status: ResourceInstanceStatus.AVAILABLE, isAvailable: true },
    { name: 'Bike #002', code: 'MTB-002', status: ResourceInstanceStatus.AVAILABLE, isAvailable: true },
  ],
});

Query available rental slots​

Rental slot availability — with pickup and return times — is queried through the TypeScript SDK.

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

const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
const localDate = tomorrow.toISOString().split('T')[0];

const slotResponse = await client.rentalReservations.getAvailableSlots({
  resourceType: ResourceType.RENTAL,
  localDate: localDate,
  resourceId: rentalResource.id,
  durationMinutes: 240, // 4 hours
  maxResults: 10,
});

slotResponse.slots.forEach((slot: RentalCandidateSlot, idx) => {
  console.log(`  ${idx + 1}. Pickup: ${slot.pickupTimeOfDay}, Return: ${slot.returnTimeOfDay}`);
});

Create a rental reservation​

import {
  CreateRentalReservationSchema,
  RentalReservationStatus,
  DepositStatus,
} from 'wiil-core-js';

const slot = slotResponse.slots.find(s => s.isAvailable);
if (!slot) throw new Error('No available rental slots');

// API expects UTC seconds
const rentalReservation = await client.rentalReservations.create({
  resourceId: rentalResource.id,
  customerId: 'cust_789',
  startAt: slot.startTimeUtcSec,
  endAt: slot.endTimeUtcSec,
  tierId: 'tier_standard',
  status: RentalReservationStatus.UPCOMING,
  payment: {
    rentalCharge: 75.00,
    securityDeposit: 200.00,
    depositStatus: DepositStatus.PENDING,
  },
  checklistCompletions: [],
  notes: 'First-time renter, provide extra instructions',
});

console.log(`Rental Reservation Created: ${rentalReservation.id}`);

Read, update, and cancel​

import { DepositStatus } from 'wiil-core-js';

const rental = await client.rentalReservations.get('reservation_123');
const customerRentals = await client.rentalReservations.getByCustomer('cust_789');
const resourceRentals = await client.rentalReservations.getByResource(rentalResource.id);
const all = await client.rentalReservations.list();

const updated = await client.rentalReservations.update(rentalReservation.id, {
  id: rentalReservation.id,
  notes: 'Customer requested early pickup',
  payment: {
    rentalCharge: 85.00,
    securityDeposit: 200.00,
    depositStatus: DepositStatus.PAID,
  },
});

const cancelled = await client.rentalReservations.cancel(
  rentalReservation.id,
  'Weather conditions not suitable'
);

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

RentalReservation fields​

FieldTypeRequiredDescription
idstringYesUnique identifier
customerIdstringYesCustomer identifier
resourceIdstringYesRental resource
tierIdstringYesRental tier from reservation settings
startAtnumberYesPickup / rental start (Unix seconds)
endAtnumberYesExpected return (Unix seconds)
actualReturnAtnumber | nullNoActual return timestamp
statusenumYesLifecycle status (see below; default upcoming)
paymentobjectYesrentalCharge, securityDeposit, depositStatus
checklistCompletionsarrayYesPickup/return checklist results
waiverobject | nullNoWaiver reference and status
idVerificationobject | nullNoID verification reference and status
notesstring | nullNoFree-text notes
locationIdstring | nullNoLocation scope
channelIdstring | nullNoBooking channel

Status lifecycle​

ValueMeaning
upcomingFuture rental
pickup_soonNear the pickup window
outUnit is currently rented
returnedUnit has been returned
overdueExpected return (endAt) has passed
cancelledRental was cancelled

Payment​

FieldTypeDescription
rentalChargenumberRental fee (≥ 0)
securityDepositnumberRefundable deposit (≥ 0)
depositStatusenumpending, paid, returned, or forfeited

Checklist completions​

Each entry records a checklist item result at pickup or return.

FieldTypeDescription
itemIdstringChecklist item from the resource's checklistTemplate
completedbooleanWhether the item was completed (default false)
completedAtnumber | nullWhen it was completed
completedBystring | nullWho completed it

Waiver & ID verification​

A rental can require a signed waiver and a verified identity before the unit goes out. The waiver reference carries a waiverId, optional signedAt, and a status of required, signed, or waived. The idVerification reference carries a verificationId, optional provider and verifiedAt, and a status of required, verified, or rejected. Whether these are required is configured in rental settings.

Validation

endAt must be greater than startAt, and rentalCharge and securityDeposit must be non-negative.

Query options​

RentalReservation queries filter by resourceId, customerId, status[], and date range, sorted by startAt, endAt, or createdAt (asc / desc), with page/pageSize pagination.