Cancel booking — Calendar

Cancel one booking and release its slot.

Action: app_topolo_calendar.bookings.cancel · POST /api/admin/bookings/{bookingId}/cancel

Declared permission: app_topolo_calendar.bookings:write. For authorized Calendar users; permissions and resource access still apply.

Before you start

• Use the current credential to confirm the production organization and inspect this exact action before preparing a call.
• Declared permission: app_topolo_calendar.bookings:write. Permission discovery is not a grant.
• Discover the authorized Calendar workspace and pass it as resourceType=workspace/resourceId separately from this action input. Calendar records and IDs are scoped to the selected host/workspace.
• Validate and plan the exact payload, obtain effect-specific authorization, then execute unchanged only in a separately authorized operational task. Do not run these synthetic inputs.

Inputs and field meanings

Worked request and response

Source-reviewed illustration only. Nothing below was executed; all identifiers, counts, states, credentials and URLs are synthetic. Replace identifiers through discovery before any separately authorized call.

Resource context: workspace; it is not an extra action input field.

Illustrative action input:

{
  "bookingId": "bkg_example",
  "reason": "Illustrative cancellation."
}

Illustrative HTTP 200 source response:

{
  "booking": {
    "id": "bkg_example",
    "hostId": "hst_example",
    "eventTypeId": "evt_example",
    "calendarUid": "bkg_example@calendar.topolo.app",
    "sequence": 1,
    "startAt": "2026-11-23T06:00:00.000Z",
    "endAt": "2026-11-23T06:30:00.000Z",
    "status": "cancelled",
    "inviteeName": "Example Invitee",
    "inviteeEmail": "invitee@example.com",
    "inviteeTimezone": "Asia/Dubai",
    "inviteeNotes": null,
    "meetingProvider": null,
    "meetingProviderRef": null,
    "createdAt": "2026-11-01T00:00:00.000Z",
    "updatedAt": "2026-11-01T00:00:00.000Z",
    "cancelledAt": "2026-11-01T00:00:00.000Z",
    "cancellationReason": "Illustrative cancellation.",
    "recurrenceSeriesId": null,
    "recurrenceInstanceStart": null,
    "attendees": [
      {
        "id": "att_example",
        "bookingId": "bkg_example",
        "email": "invitee@example.com",
        "name": "Example Invitee",
        "role": "invitee",
        "responseStatus": "needs_action",
        "createdAt": "2026-11-01T00:00:00.000Z",
        "updatedAt": null
      }
    ]
  }
}

status:cancelled and cancellationReason explain the domain result. The source requests a cancellation notification; recipient delivery remains separate. A recurring instance cancellation is not a stated whole-series cancellation. This illustration starts from sequence 0 and returns sequence 1 after the source update; attendees describes the stored invitee row.

The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.

Effects and verification

• Marks the booking cancelled, releases availability and requests a cancellation message.

1. Read bookings.get for cancelled state and inspect notification receipts separately; check recurrence scope.

Refusals and recovery

Selected source refusals are listed below; runtime middleware can return additional structured errors.

Recovery: No published uncancel action exists. Creating a replacement is a new booking with new communication and identity, not a rollback.

After an uncertain mutation, reconcile the named records and provider/delivery evidence before repeating it.

Related actions

• app_topolo_calendar.bookings.get: Read a booking and its related event type and delivery receipts.
• app_topolo_calendar.bookings.list: Find bookings within an explicit time window.

Declared schemas and provenance

The hidden action guide carries these exact current declared schemas. They are not rewritten to make the illustrations pass.

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bookingId": {
      "type": "string",
      "minLength": 1
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "bookingId"
  ],
  "additionalProperties": false
}

Output schema:

{
  "type": "object",
  "title": "Cancel booking response",
  "description": "Operation result returned by bookings.cancel.",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "id": {
      "type": "string"
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "title": "booking record",
          "properties": {
            "id": {
              "type": "string",
              "description": "Stable identifier when the booking exposes one."
            }
          },
          "additionalProperties": true
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "result": {
      "type": "object",
      "additionalProperties": true
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "x-topolo-contract-source": "derived-action-metadata",
  "x-topolo-contract-precision": "structural"
}

Source: TopoloCalendar@b378ceb73800ee1d1e6c4ff6f0b4179918cf632c, apps/api/src/routes/admin-bookings.ts. Current catalog metadata and source were compared without executing the application.

• Source-reviewed synthetic input/response; not captured or executed.
• Source revision is not proof of current deployment, caller access, provider connection or notification delivery.
• The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.