Sign in

v1

latestOpenAPI 3.0.02026-07-17121287546.7 KB
Bookings

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.

<Note>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.</Note>
post/v2/bookings/{bookingUid}/cancel

Path parameters

bookingUidstring required

Headers

cal-api-versionstring required

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

Authorizationstring

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

x-cal-secret-keystring

For platform customers - OAuth client secret key

x-cal-client-idstring

For platform customers - OAuth client ID

Request body

OR

Example request

{
  "cancellationReason": "User requested cancellation"
}

Response

status'success' | 'error' required

Example response

{
  "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": "jane100@example.com",
        "displayEmail": "jane100@example.com",
        "username": "jane100",
        "timeZone": "America/Los_Angeles"
      }
    ],
    "status": "accepted",
    "cancellationReason": "User requested cancellation",
    "cancelledByEmail": "canceller@example.com",
    "reschedulingReason": "User rescheduled the event",
    "rescheduledByEmail": "rescheduler@example.com",
    "rescheduledFromUid": "previous_uid_123",
    "rescheduledToUid": "new_uid_456",
    "start": "2024-08-13T15:30:00Z",
    "end": "2024-08-13T16:30:00Z",
    "duration": 60,
    "eventTypeId": 50,
    "eventType": {
      "id": 1,
      "slug": "some-event"
    },
    "meetingUrl": "https://example.com/recurring-meeting",
    "location": "https://example.com/meeting",
    "absentHost": true,
    "createdAt": "2024-08-13T15:30:00Z",
    "updatedAt": "2024-08-13T15:30:00Z",
    "metadata": {
      "key": "value"
    },
    "rating": 4,
    "icsUid": "ics_uid_123",
    "attendees": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "displayEmail": "john@example.com",
        "timeZone": "America/New_York",
        "language": "en",
        "phoneNumber": "+1234567890"
      }
    ],
    "guests": [
      "guest1@example.com",
      "guest2@example.com"
    ],
    "bookingFieldsResponses": {
      "customField": "customValue"
    }
  }
}