Cancel and Reschedule

Read as Markdown

Description #

Cancels the event booked for a Scheduling Request and reopens the request so the same recipient can be offered a fresh time.

This is an integration operation. Read Integration Operations first for the shared response envelope, result vocabulary, authentication, and error shapes.

Calling it cancels the current booking, with the same calendar writes, notifications, and workflow triggers as cancelling from the dashboard, and moves the request back to awaiting slot selection under a new token. On success the response advertises that new token’s simple_available_slots_url, so you can list the new times and book one with Select Slot without reading the request again.

This operation requires the organizational_unit_scheduling scope.

You do not build this URL. It is returned as the opaque cancel_and_reschedule_url under the request’s integration_operations. No request body is required.

When a request qualifies #

A Scheduling Request advertises cancel_and_reschedule_url only when it is booked and could be completed again with just a time. A request is booked once a time has been selected for it, making its slot_selection complete; the operation stays available from that point, even if the recipient or host later declines the booking. To qualify it must also place a single event, and its availability_mode must be able to offer a fresh set of times to choose from.

Requests that are not booked, or that place an event per step (multi-event and sequence requests), are excluded. So are requests that cannot be re-offered a single set of times: those that search across multiple separate query_periods, and those built from a fixed list of specific_slots. An excluded request has no cancel_and_reschedule_url. If the operation is called by URL regardless, the response is not_possible; see Error responses.

A booking the recipient or host has declined reports a slot_selection of pending_rescheduling while still advertising cancel_and_reschedule_url. The link appearing does not mean rescheduling is already underway — slot_selection reads the same whether the booking was declined or has genuinely moved into rescheduling. Rely on what integration_operations advertises to decide the next action, rather than inferring it from slot_selection.

Example Request #

Send the request to the cancel_and_reschedule_url returned on the Scheduling Request, exactly as given.

POST {CANCEL_AND_RESCHEDULE_URL} HTTP/1.1
Authorization: Bearer {API_KEY}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "integration_operation_result": {
    "type": "cancel_and_reschedule",
    "result": "success",
    "integration_operations": {
      "simple_available_slots_url": "{SIMPLE_AVAILABLE_SLOTS_URL}"
    }
  },
  "scheduling_request": {
    "scheduling_request_id": "srq_7b9784257940f9bbbfcad097",
    "slot_selection": "pending_rescheduling",
    "primary_select_url": "https://app.cronofy.com/rts/wZ9tLbN4sWjH6yD1cF0a",
    "dashboard_url": "https://app.cronofy.com/scheduler/requests/7b9784257940f9bbbfcad097",
    "summary": "Intro call with Riya Patel",
    "duration": { "minutes": 30 },
    "recipient_operations": {
      "view_url": "https://app.cronofy.com/rts/wZ9tLbN4sWjH6yD1cF0a"
    },
    "integration_operations": {
      "simple_available_slots_url": "{SIMPLE_AVAILABLE_SLOTS_URL}"
    }
  }
}

Request parameters #

API_KEY Required  #

An access token for the Organizational Unit with the organizational_unit_scheduling scope, or the client_secret of the linked Internal Application. See Authentication.

Response parameters #

integration_operation_result  #

An Object describing the outcome of the operation. See The response envelope.

integration_operation_result.type  #

A String of cancel_and_reschedule for this operation.

integration_operation_result.result  #

A String outcome, one of:

  • success: the booking was cancelled and the request reopened for a new time (200).
  • conflict: another scheduling change was briefly in progress; retry the request (409).
  • not_possible: the request’s state means this cannot be done (409); see result_detail.

integration_operation_result.result_detail  #

Returned only with a not_possible result, and only when a specific reason applies. When present it is a String, one of the common values superseded, no_longer_possible, or configuration_error. A not_possible result can also come back with no result_detail when there is no more specific reason to give, so treat its absence as a generic “cannot be done right now”. See Error responses.

integration_operation_result.integration_operations  #

An Object of the actions available next. On success it carries the new token’s simple_available_slots_url so you can list the fresh times and book one straight away. It is empty when the reopened request now needs more than a time to complete, such as required data capture, in which case send the person to recipient_operations.view_url.

scheduling_request  #

The full Scheduling Request, in the same shape as the Query response. It travels alongside every envelope response so you can render the current state without a second call. After a successful call it reflects the reopened request, with a slot_selection of pending_rescheduling, awaiting a new time under a new token.

Error responses #

Beyond the shared errors for authentication, authorization, an unknown token, and rate limiting, this operation can return the following.

Request can no longer be rescheduled #

not_possible with a result_detail of no_longer_possible (409): the request is not in a state that can be cancelled and reopened for a new time. This covers a request that was never booked, that is already cancelled or expired, that places an event per step (multi-event or sequence), or that otherwise cannot be rescheduled. The request is left untouched.

{
  "integration_operation_result": {
    "type": "cancel_and_reschedule",
    "result": "not_possible",
    "result_detail": "no_longer_possible",
    "integration_operations": {}
  },
  "scheduling_request": { ... }
}

Token superseded #

not_possible with a result_detail of superseded (409): the token was replaced, so it no longer points at the current booking. Re-read the accompanying scheduling_request and follow whatever it now advertises.

{
  "integration_operation_result": {
    "type": "cancel_and_reschedule",
    "result": "not_possible",
    "result_detail": "superseded",
    "integration_operations": {}
  },
  "scheduling_request": { ... }
}

Configuration prevents rescheduling #

not_possible with a result_detail of configuration_error (409): some configuration of the request or its participants prevents a new time from being found, for example when a fresh time would fall beyond the date range the request searches — its query_periods, or the rolling window set by scheduling_period. The underlying configuration will need to be resolved before the request can be rescheduled.

{
  "integration_operation_result": {
    "type": "cancel_and_reschedule",
    "result": "not_possible",
    "result_detail": "configuration_error",
    "integration_operations": {}
  },
  "scheduling_request": { ... }
}

Another change already in progress #

conflict (409): another scheduling change was briefly in progress for the request. Nothing is wrong; retry the request in a moment.

{
  "integration_operation_result": {
    "type": "cancel_and_reschedule",
    "result": "conflict",
    "integration_operations": {}
  },
  "scheduling_request": { ... }
}