Decline a booking

POST
/v1/scheduling/bookings/{id}/decline

Refuses a pending_approval booking and frees the time.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Path Parameters

id*string

The booking's id.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Response Body

The booking.

application/json
  1. response
object*"scheduling.booking"
Value in"scheduling.booking"
id*string
event_type*string

The id of the booked event type.

status*string

held: a hold keeping the slot until hold_expires_at, uncharged and known to nobody. pending_approval: holds the time until approved, declined or approval_expires_at. confirmed: booked. cancelled: cancelled, or a hold released or expired. declined: refused, or its approval deadline passed.

Value in"held""pending_approval""confirmed""cancelled""declined"
title*string

The event type's title when this was booked.

start*string

When the booking starts.

end*string

When the booking ends, without buffers.

hosts*array<string>

The ids of the hosts taking it.

attendees*array<>

Who's booked: the attendee first, then any guests they added. A group session's seat is its own booking.

location*||||||

Where a booking meets. link, phone and in_person carry their details, and on an event type, left blank, use the booked host's own if they have one; google_meet, microsoft_teams and zoom get a meeting made on the host's connected account.

hold_expires_at*|

When a held booking gives up its slot. null otherwise.

approval_expires_at*|

When a pending_approval booking is declined if nobody decides. null otherwise.

series*|

The id of the series it belongs to. null: not part of one.

series_index*|

Its place in the series, from 0. null: not part of one.

group_session*|

The id of the group session whose seat this is. null: not a seat.

calendar_unverified*boolean

Reserved for flagging a booking made on last known calendar data. Nothing sets it yet, so it's always false.

external_conflict_at*|

When something else landed on this time in the host's calendar, or the host changed the event. The booking stands. null: no conflict known.

no_show_at*|

When the attendee was marked as a no-show. null: not marked.

cancelled_at*|

When it was cancelled. null: not cancelled.

cancelled_by*|

Who cancelled it: api_key, user (the dashboard), host_session, booker_session, manage_session (the attendee's link) or system. null: not cancelled, or cancelled before this was recorded.

Value in"api_key""user""host_session""booker_session""manage_session""manager_session""system"null
cancellation_reason?|

Why, if they said. Only when retrieving one booking. It's erased with the attendee's details, and it's never in webhooks, logs or emails.

metadata*

Your own key-value pairs.

created_at*string
updated_at*string
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.scheduling.bookings.decline("book_01kd2m9a0b1c2d3e4f5g6h7j8m");
{  "object": "scheduling.booking",  "id": "book_01kd2m9a0b1c2d3e4f5g6h7j8m",  "event_type": "evtype_01kd2m9a0b1c2d3e4f5g6h7j8m",  "status": "confirmed",  "title": "Initial consultation",  "start": "2027-01-04T15:00:00.000Z",  "end": "2027-01-04T15:30:00.000Z",  "hosts": [    "host_01kd2m9a0b1c2d3e4f5g6h7j8m"  ],  "attendees": [    {      "id": "attn_01kd2m9a0b1c2d3e4f5g6h7j8m",      "role": "attendee",      "uid": "patient_77",      "name": "Sam Lee",      "email": "sam@example.com",      "phone": null,      "time_zone": "UTC",      "locale": null    }  ],  "location": null,  "hold_expires_at": null,  "approval_expires_at": null,  "series": null,  "series_index": null,  "group_session": null,  "calendar_unverified": false,  "external_conflict_at": null,  "no_show_at": null,  "cancelled_at": null,  "cancelled_by": null,  "metadata": {},  "created_at": "2027-01-01T10:00:00.000Z",  "updated_at": "2027-01-01T10:00:00.000Z"}