Cancel a booking

:bookingUid can be :bookingUid of an usual booking, individual recurrence or recurring booking to cancel all recurrences.

Cancelling normal bookings: If the booking is not seated and not recurring, simply pass :bookingUid in the request URL /bookings/:bookingUid/cancel and optionally cancellationReason in the request body {"cancellationReason": "Will travel"}.

Cancelling seated bookings: It is possible to cancel specific seat within a booking as an attendee or all of the seats as the host.

1. As an attendee - provide :bookingUid in the request URL /bookings/:bookingUid/cancel and seatUid in the request body {"seatUid": "123-123-123"} . This will remove this particular attendance from the booking.

2. As the host or org admin of host - host can cancel booking for all attendees aka for every seat, this also applies to org admins. Provide :bookingUid in the request URL /bookings/:bookingUid/cancel and cancellationReason in the request body {"cancellationReason": "Will travel"} and Authorization: Bearer token request header where token is event type owner (host) credential. This will cancel the booking for all attendees.

Cancelling recurring seated bookings: For recurring seated bookings it is not possible to cancel all of them with 1 call like with non-seated recurring bookings by providing recurring bookind uid - you have to cancel each recurrence booking by its bookingUid + seatUid.

If you are cancelling a seated booking for an event type with ‘show attendees’ disabled, then to retrieve attendees in the response either set ‘show attendees’ to true on event type level or you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.

Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.

POST /v2/bookings/{bookingUid}/cancel

Try it

Cancel a booking

cURL

curl --request POST \
  --url https://api.cal.com/v2/bookings/{bookingUid}/cancel \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: <cal-api-version>' \
  --data '
{
  "cancellationReason": "User requested cancellation",
  "cancelSubsequentBookings": true
}
'

200

{
  "status": "success",
  "data": {
    "id": 123,
    "uid": "booking_uid_123",
    "title": "Consultation",
    "description": "Learn how to integrate scheduling into marketplace.",
    "hosts": [
      {
        "id": 1,
        "name": "Jane Doe",
        "email": "[e-mail]",
        "username": "jane100",
        "timeZone": "America/Los_Angeles"
      }
    ],
    "status": "accepted",
    "start": "2024-08-13T15:30:00Z",
    "end": "2024-08-13T16:30:00Z",
    "duration": 60,
    "eventTypeId": 50,
    "eventType": {
      "id": 1,
      "slug": "some-event"
    },
    "location": "https://example.com/meeting",
    "absentHost": true,
    "createdAt": "2024-08-13T15:30:00Z",
    "updatedAt": "2024-08-13T15:30:00Z",
    "attendees": [
      {
        "name": "John Doe",
        "email": "[e-mail]",
        "timeZone": "America/New_York",
        "absent": false,
        "language": "en",
        "phoneNumber": "[phone]"
      }
    ],
    "bookingFieldsResponses": {
      "customField": "customValue"
    },
    "cancellationReason": "User requested cancellation",
    "cancelledByEmail": "[e-mail]",
    "reschedulingReason": "User rescheduled the event",
    "rescheduledByEmail": "[e-mail]",
    "rescheduledFromUid": "previous_uid_123",
    "rescheduledToUid": "new_uid_456",
    "meetingUrl": "https://example.com/recurring-meeting",
    "metadata": {
      "key": "value"
    },
    "rating": 4,
    "icsUid": "ics_uid_123",
    "guests": [
      "[e-mail]",
      "[e-mail]"
    ]
  }
}

Headers

cal-api-version · string · default: 2024-08-13 · required

Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.

Authorization · string

value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token

x-cal-secret-key · string

For platform customers - OAuth client secret key

x-cal-client-id · string

For platform customers - OAuth client ID

Path Parameters

bookingUid · string · required

Body

application/json

Accepts different types of cancel booking input: Cancel Booking (Option 1 which is for normal or recurring bookings) or Cancel Seated Booking (Option 2 which is for seated bookings)

Option 1

cancellationReason · string

Example:

"User requested cancellation"

cancelSubsequentBookings · boolean

For recurring non-seated booking only - if true, cancel booking with the bookingUid of the individual recurrence and all recurrences that come after it.

Response

200 - application/json

status · enum<string> · required

Available options: success, error

Example:

"success"

data · object · required

Booking data, which can be either a BookingOutput object, a RecurringBookingOutput object, or an array of RecurringBookingOutput objects

Option 1 · object

Show child attributes

data. id · number · required

Example:

123

data. uid · string · required

Example:

"booking_uid_123"

data. title · string · required

Example:

"Consultation"

data. description · string · required

Example:

"Learn how to integrate scheduling into marketplace."

data. hosts · object[] · required

Show child attributes

data.hosts. id · number · required

Example:

1

data.hosts. name · string · required

Example:

"Jane Doe"

data.hosts. email · string · required

Example:

"[e-mail]"

data.hosts. username · string · required

Example:

"jane100"

data.hosts. timeZone · string · required

Example:

"America/Los_Angeles"

data. status · enum<string> · required

Available options: cancelled, accepted, rejected, pending

Example:

"accepted"

data. start · string · required

Example:

"2024-08-13T15:30:00Z"

data. end · string · required

Example:

"2024-08-13T16:30:00Z"

data. duration · number · required

Example:

60

data. eventTypeId · number · required · deprecated

Deprecated - rely on 'eventType' object containing the id instead.

Example:

50

data. eventType · object · required

Show child attributes

data.eventType. id · number · required

Example:

1

data.eventType. slug · string · required

Example:

"some-event"

data. location · string · required

Example:

"https://example.com/meeting"

data. absentHost · boolean · required

Example:

true

data. createdAt · string · required

Example:

"2024-08-13T15:30:00Z"

data. updatedAt · string · required

Example:

"2024-08-13T15:30:00Z"

data. attendees · object[] · required

Show child attributes

data.attendees. name · string · required

Example:

"John Doe"

data.attendees. email · string · required

Example:

"[e-mail]"

data.attendees. timeZone · string · required

Example:

"America/New_York"

data.attendees. absent · boolean · required

Example:

false

data.attendees. language · enum<string>

Available options: ar, ca, de, es, eu, he, id, ja, lv, pl, ro, sr, th, vi, az, cs, el, es-419, fi, hr, it, km, nl, pt, ru, sv, tr, zh-CN, bg, da, en, et, fr, hu, iw, ko, no, pt-BR, sk, ta, uk, zh-TW, bn

Example:

"en"

data.attendees. phoneNumber · string

Example:

"[phone]"

data. bookingFieldsResponses · object · required

Booking field responses consisting of an object with booking field slug as keys and user response as values.

Example:

{ "customField": "customValue" }

data. cancellationReason · string

Example:

"User requested cancellation"

data. cancelledByEmail · string

Example:

"[e-mail]"

data. reschedulingReason · string

Example:

"User rescheduled the event"

data. rescheduledByEmail · string

Example:

"[e-mail]"

data. rescheduledFromUid · string

UID of the previous booking from which this booking was rescheduled.

Example:

"previous_uid_123"

data. rescheduledToUid · string

UID of the new booking to which this booking was rescheduled.

Example:

"new_uid_456"

data. meetingUrl · string · deprecated

Deprecated - rely on 'location' field instead.

Example:

"https://example.com/recurring-meeting"

data. metadata · object

Example:

{ "key": "value" }

data. rating · number

Example:

4

data. icsUid · string

UID of ICS event.

Example:

"ics_uid_123"

data. guests · string[]

Example:

["[e-mail]", "[e-mail]"]