Appointment lifecycle and statuses

The five appointment statuses and how hold, reserve, book, reschedule, and cancel move between them.

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

Statuses

There is no separate “completed” status. A booked row stays BK after the end time; occupancy ends when the appointment ends.

Status	Meaning
`IN`	Hold. Created by `POST /v3/appointment/hold`. Occupies the slot. A positive location `expirationDelay` (seconds) sets the expiry; new locations default to 900 seconds (15 minutes) when omitted. `0` or `null` disables the timer.
`BK`	Booked. Created by `POST /v3/appointment` or `PUT /v3/appointment/:id/book`.
`RS`	Reserved without hold expiry. Created by `POST /v3/appointment/reserve`. Occupies the slot; does not count toward `bookingLimit`. Finalize with `PUT …/book` or delete the row.
`RE`	Rescheduled-away. The original row after a successful reschedule. Not an extra lifetime booking.
`CN`	Cancelled. `PUT /v3/appointment/:id/cancel`. Counts toward `maxBookingLimit`.

Holds, confirm, and create use the singular /v3/appointment/…. GET /v3/appointments lists rows.

Typical flow

Optional: POST /v3/appointment/hold → IN
PUT /v3/appointment/:id/book or POST /v3/appointment → BK
Optional: PUT /v3/appointment/:id/confirm sets confirmed: true only; it does not change status or external calendars
PUT /v3/appointment/:id/reschedule creates a new row (IN/RS if the original was a hold/reserve, otherwise BK) and leaves the old row RE
PUT /v3/appointment/:id/cancel → CN

DELETE /v3/appointment/:id is for IN or RS only.

Warning: Without a positive location expirationDelay, an IN hold never expires. Locations created before the 900-second default may have no expiry and should set a positive delay. See Availability rules.

See also

Updated 14 days ago

Did this page help you?