Cancel booking

POST /api/v1/bookings/{bookingId}/cancel

Cancel booking using the current permissions of the key holder. The school comes from the verified key. MCP equivalent: cancel_booking.

Authorization

Organization role

Business authorization

Owner/admin can act on any call in this school. A closer can act only on their currently assigned call; a setter cannot. The service rechecks assignment during mutation. The prospect late-report cutoff does not restrict authorized operator rescheduling.

Path parameters

Request headers

Request body

Example

curl -X POST "$COHORTE_API_BASE_URL/api/v1/bookings/00000000-0000-4000-8000-000000000001/cancel" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: scheduling-intention-001" \
  --data '{"reason": "Requested by prospect"}'

Response

• 200 — successful read, mutation or retry.
• 400 — invalid request.
• 401 — invalid key, bearer or school membership.
• 403 — insufficient permission.
• 404 — absent or outside the permitted scope.
• 409 — conflicting state, changed intention for this key, or unverifiable historical key.
• 500 — unexpected failure; retry only the identical intention.

Response fields

Example response

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "status": "cancelled",
    "startsAt": "2030-01-10T09:00:00.000Z",
    "endsAt": "2030-01-10T09:45:00.000Z",
    "personId": "00000000-0000-4000-8000-000000000001",
    "prospectName": "Alex",
    "prospectEmail": null,
    "prospectPhone": null,
    "closerUserId": "00000000-0000-4000-8000-000000000001",
    "closerName": "Sam",
    "source": "api",
    "sourceDetail": null,
    "linkSlug": "discovery",
    "bookedByName": "Owner",
    "linkName": "Discovery",
    "createdAt": "2030-01-01T00:00:00.000Z",
    "cancelledAt": null,
    "cancelReason": null
  }
}

Notes

Reuse the same key only for the same normalized payload and resource. An identical retry rechecks current permissions, returns the resource and creates no new audit event or notification. A changed payload or an older unverifiable key returns 409; inspect the original outcome before deciding on any new command.

History is retained. A genuinely new mutation notifies the affected participants once through the existing notification flow. Staff never receive or reuse the prospect management token. Slot availability is checked again when applying the command.

Related

• Bookings
• Sales availability
• Coaching sessions