---
title: "revert_occurrence_move"
description: "Undo Occurrence move: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/revert_occurrence_move
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# revert_occurrence_move

Undoes the latest move of one of today's Unresolved Occurrences, putting it back where it was before that move: its planned time, or an earlier move. Only the latest move can be undone. When there is nothing to undo or the item changed since you read it, nothing changes and `refusal` explains why.

## Permission and annotations

Required scope: `cadence.occurrences.write`. Contract 1.7.0; available since 1.3.0.

- `title`: "Undo Occurrence move"
- `readOnlyHint`: false
- `destructiveHint`: true
- `idempotentHint`: false
- `openWorldHint`: false

Changes where today's Occurrence sits, so readOnlyHint is false. The planned time and the Behavior's schedule never change and a later move can redo it, but Claude's review criteria ask for destructiveHint true on tools that modify data, so it is set. The same idempotency key returns the first result, but a call without one makes a new move each time, so idempotentHint is false. openWorldHint is false: only the user's own Cadence account is touched.

## Input

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` occurrence_id ` | yes | string | Occurrence id.; format: ` uuid ` |
| ` expected_revision ` | yes | string | Revision the client last read. If the Occurrence changed since, the Undo is refused with `revision_changed`.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` idempotency_key ` | no | string | Optional client-chosen key. Repeating a call with the same key and input within 24 hours returns the first result and changes nothing.; minLength: ` 8 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |

## Output

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` outcome ` | yes | string | Values: ` undone `, ` refused ` |
| ` occurrence ` | yes | object | An Occurrence: one scheduled instance of a Behavior on one local date. |
| ` occurrence.id ` | yes | string | format: ` uuid ` |
| ` occurrence.behavior_id ` | yes | string | format: ` uuid ` |
| ` occurrence.behavior_title ` | yes | string |  |
| ` occurrence.category_name ` | yes | string or null |  |
| ` occurrence.local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` occurrence.timezone ` | yes | string | IANA timezone name.; minLength: ` 1 `; maxLength: ` 64 `; pattern: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` occurrence.scheduled_for ` | yes | string | Planned start as a UTC instant. It never changes when the Occurrence is moved for the day.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.effective_start_at ` | yes | string | Where the Occurrence sits today: its moved start when `move` is set, otherwise the planned start. Show, remind and match by this time.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.move ` | yes | object or null | Set while a per-day move places the Occurrence away from its planned time. Null otherwise. |
| ` occurrence.move.planned_start_at ` | yes | string | The planned start. It does not change when the item moves.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.move.start_at ` | yes | string | The moved start.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.move.end_at ` | yes | string | The moved end. A move keeps the item's length.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.schedule ` | yes | object |  |
| ` occurrence.schedule.kind ` | yes | string | Values: ` exact `, ` range ` |
| ` occurrence.schedule.preset ` | yes | string or null | Values: ` morning `, ` afternoon `, ` evening `, ` night `, ` null ` |
| ` occurrence.schedule.start_time ` | yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` occurrence.schedule.end_time ` | yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` occurrence.schedule.label ` | yes | string |  |
| ` occurrence.status ` | yes | string | Stored status.; Values: ` unresolved `, ` completed `, ` not_completed ` |
| ` occurrence.status_label ` | yes | string | Values: ` Unresolved `, ` Completed `, ` Not Completed ` |
| ` occurrence.needs_decision ` | yes | boolean | Derived: true when the status is unresolved and local_date is before today. Never stored. |
| ` occurrence.origin ` | yes | string | scheduled comes from the Behavior's schedule; opportunity was added to its day from the person's opportunities (contract 1.6.0).; Values: ` scheduled `, ` opportunity ` |
| ` occurrence.added_by ` | yes | string or null | Who added an opportunity Occurrence: user, daily_brief, chat or mcp. Null for scheduled Occurrences.; Values: ` user `, ` daily_brief `, ` chat `, ` mcp `, ` null ` |
| ` occurrence.completed_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.status_marked_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.note ` | yes | string or null |  |
| ` occurrence.parent_behavior_id ` | no | string or null | Parent Behavior id when the Occurrence belongs to a sub-behavior, otherwise null. Present on reads and on set_parent_occurrence_status (contract 1.7.0).; format: ` uuid ` |
| ` occurrence.parent_title ` | no | string or null | Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null. |
| ` occurrence.updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.revision ` | yes | string | Opaque version token of this record. Send it back as `expected_revision` to avoid overwriting a newer change.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` move ` | yes | object or null | The record this call added, or the first call's record on a replay. Null when refused. |
| ` move.id ` | yes | string | format: ` uuid ` |
| ` move.kind ` | yes | string | `revert` is an Undo of the latest move.; Values: ` move `, ` revert ` |
| ` move.from_start_at ` | yes | string | Start before this record.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` move.to_start_at ` | yes | string | Start after this record.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` move.to_end_at ` | yes | string | End after this record.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` move.to_planned ` | yes | boolean | True when this record put the Occurrence back at its planned time. |
| ` move.chain_position ` | yes | integer | 1 for the day's first move or Undo, then 2, 3, and so on.; minimum: ` 1 ` |
| ` move.source ` | yes | string | Who made it: the person, Cadence's advisor, or an outside client.; Values: ` daily_brief `, ` coach `, ` chat `, ` mcp `, ` person ` |
| ` move.created_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` refusal ` | yes | object or null | Set when nothing changed because a rule refused the request. Null when the move or Undo was applied. |
| ` refusal.reason ` | yes | string | Values: ` occurrence_resolved `, ` not_today `, ` revision_changed `, ` range_behavior `, ` start_not_on_day `, ` time_passed `, ` no_change `, ` nothing_to_undo `, ` not_latest_move `, ` slot_taken `, ` calendar_busy ` |
| ` refusal.message ` | yes | string | Plain-language reason to show the user. |
| ` refusal.alternatives ` | yes | array | Up to three free start times today, nearest the requested time first. Empty for Undo.; maxItems: ` 3 ` |
| ` refusal.alternatives[] ` | yes | object |  |
| ` refusal.alternatives[].start_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` refusal.alternatives[].start_time ` | yes | string | Local start time in the Behavior's timezone.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |

## Example call

Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.

```json
{
  "name": "revert_occurrence_move",
  "arguments": {
    "occurrence_id": "00000005-1111-4111-8111-000000000005",
    "expected_revision": "2026-10-18T12:00:00.000001Z",
    "idempotency_key": "undo-walk-1"
  }
}
```

## Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

```json
{
  "outcome": "undone",
  "occurrence": {
    "id": "00000005-1111-4111-8111-000000000005",
    "behavior_id": "00000001-1111-4111-8111-000000000001",
    "behavior_title": "Morning walk",
    "category_name": "Fitness",
    "local_date": "2026-10-18",
    "timezone": "America/New_York",
    "scheduled_for": "2026-10-18T11:30:00Z",
    "effective_start_at": "2026-10-18T11:30:00Z",
    "move": null,
    "schedule": {
      "kind": "exact",
      "preset": null,
      "start_time": "07:30",
      "end_time": null,
      "label": "7:30 AM"
    },
    "status": "unresolved",
    "status_label": "Unresolved",
    "needs_decision": false,
    "origin": "scheduled",
    "added_by": null,
    "completed_at": null,
    "status_marked_at": null,
    "note": null,
    "updated_at": "2026-10-18T12:05:00Z",
    "revision": "2026-10-18T12:05:00Z"
  },
  "move": {
    "id": "0000000a-1111-4111-8111-00000000000a",
    "kind": "revert",
    "from_start_at": "2026-10-18T13:00:00Z",
    "to_start_at": "2026-10-18T11:30:00Z",
    "to_end_at": "2026-10-18T12:00:00Z",
    "to_planned": true,
    "chain_position": 2,
    "source": "mcp",
    "created_at": "2026-10-18T12:05:00Z"
  },
  "refusal": null
}
```

## Errors

- `invalid_input`: The input does not match the tool's schema or rules. `field_errors` names each problem.
- `authentication_required`: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.
- `rate_limited`: Too many requests for this connection. Retry after `retry_after_seconds`.
- `service_unavailable`: Cadence integrations are temporarily unavailable.
- `internal_error`: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same `idempotency_key`.
- `insufficient_scope`: The connection does not include the permission this tool needs. `required_scopes` lists it.
- `not_found`: No record with that id exists for this account.
- `idempotency_key_reused`: The `idempotency_key` was already used with a different input. Use a new key for a new request.

Output size limits can also return `limit_exceeded`. See [error handling](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
