Appointments

A service appointment is a scheduled booking for a service. The recommended flow is to query available slots first, then create the appointment.

Query available slots (TypeScript)

Slot availability is demonstrated in the TypeScript SDK guide.

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

const slotResponse = await client.serviceAppointments.getAvailableSlots({
  serviceId: 'service_123',
  localDate: '2026-06-22',
  providerId: 'person_123',
  maxResults: 20,
});

console.log(`Available slots: ${slotResponse.slots.length}`);

A slot carries UTC timestamps (startTimeUtcSec / endTimeUtcSec) to pass directly into create.

Create

TypeScript

const slot = slotResponse.slots[0];
// API expects UTC seconds
const duration = Math.round((slot.endTimeUtcSec - slot.startTimeUtcSec) / 60);

const appointment = await client.serviceAppointments.create({
  businessServiceId: 'service_123',
  customerId: 'cust_456',
  startTime: slot.startTimeUtcSec,
  endTime: slot.endTimeUtcSec,
  duration: duration,
  totalPrice: 80.00,
  depositPaid: 20.00,
});

Python

from time import time
from wiil.models.business_mgt import CreateServiceAppointment

start_ms = int(time() * 1000) + 3600000
appointment = client.service_appointments.create(
    CreateServiceAppointment(
        business_service_id="service_123",
        customer_id="cust_456",
        start_time=start_ms,
        end_time=start_ms + 60 * 60 * 1000,
        duration=60,
        total_price=80.00,
        deposit_paid=20.00,
    )
)

Get

TypeScript

const appointment = await client.serviceAppointments.get('appointment_123');

Python

loaded = client.service_appointments.get(appointment.id)

Get by customer / by service

TypeScript

const byCustomer = await client.serviceAppointments.getByCustomer('cust_123', { page: 1, pageSize: 20 });
const byService  = await client.serviceAppointments.getByService('service_123', { page: 1, pageSize: 20 });

Python

from wiil.types import PaginationRequest

customer_appointments = client.service_appointments.get_by_customer(
    "cust_456", PaginationRequest(page=1, page_size=20)
)
service_appointments = client.service_appointments.get_by_service(
    "service_123", PaginationRequest(page=1, page_size=20)
)

Update status

TypeScript

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

const confirmed = await client.serviceAppointments.updateStatus('appointment_123', AppointmentStatus.CONFIRMED);

Python

confirmed = client.service_appointments.update_status(appointment.id, "confirmed")

The standard progression is pending → confirmed → completed.

Cancel

TypeScript

const cancelled = await client.serviceAppointments.cancel(
  'appointment_123',
  { cancelReason: 'Customer requested cancellation' }
);

Python

cancelled = client.service_appointments.cancel(appointment.id, reason="Customer requested cancellation")

Reschedule

TypeScript

// API expects UTC seconds
const newStartTime = Math.floor(Date.now() / 1000) + (48 * 60 * 60);
const newEndTime = newStartTime + (60 * 60);

const rescheduled = await client.serviceAppointments.reschedule(
  'appointment_123',
  { startTime: newStartTime, endTime: newEndTime }
);

Python

from time import time

rescheduled = client.service_appointments.reschedule(
    appointment.id,
    start_time=str(int(time() * 1000) + 48 * 60 * 60 * 1000),
    end_time=str(int(time() * 1000) + 49 * 60 * 60 * 1000),
)

List, by provider, by date range, delete (TypeScript)

const all = await client.serviceAppointments.list();
const byProvider = await client.serviceAppointments.getByProvider('person_123', { page: 1, pageSize: 20 });

// API expects UTC seconds
const startDate = Math.floor(Date.now() / 1000);
const endDate = startDate + (7 * 24 * 60 * 60);
const inRange = await client.serviceAppointments.getByDateRange(startDate, endDate, { page: 1, pageSize: 50 });

await client.serviceAppointments.delete('appointment_123');

ServiceAppointment fields

Field	Type	Required	Description
businessServiceId	string	Yes	ID of the service being booked
customerId	string	Yes	Customer ID
startTime	number	Yes	Start time (Unix timestamp)
endTime	number	No	End time (Unix timestamp)
duration	number	No	Duration in minutes (default: 30)
totalPrice	number	No	Total price for the service
depositPaid	number	Yes	Deposit amount paid (default: 0)
status	enum	Yes	pending, confirmed, cancelled, completed, no_show
providerId	string | null	No	Assigned ServicePerson ID

Time units

In TypeScript, getAvailableSlots returns UTC seconds — pass slot.startTimeUtcSec directly to create.