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

# remove_opportunity_occurrence

Removes an opportunity Occurrence that was added to a day, today or still in Needs decision, and cancels its pending reminders. The Behavior stays available as an opportunity. Only a clean item can be removed: Unresolved, never marked, with no note, tracked time or connected activity. A scheduled Occurrence is never removed. When a rule stops it, nothing changes and `refusal` says why.

## Permission and annotations

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

- `title`: "Remove added opportunity"
- `readOnlyHint`: false
- `destructiveHint`: true
- `idempotentHint`: true
- `openWorldHint`: false

Deletes an added Occurrence, so destructiveHint is true under both Claude's and OpenAI's guidance; the rules allow it only for a clean, unmarked item, and add_opportunity_occurrence can add it again. Repeating it leaves the same end state, the item gone, so idempotentHint is true. openWorldHint is false.

## 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 ` | no | string | Revision the client last read. If the Occurrence changed since, the call 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: ` removed `, ` 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._:-]+$ ` |
| ` refusal ` | yes | object or null | Set when nothing changed because a rule refused the request. Null when the change was made. |
| ` refusal.reason ` | yes | string | Values: ` scheduled `, ` marked `, ` kept `, ` revision_changed ` |
| ` refusal.message ` | yes | string | Plain-language reason to show the user. |

## 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": "remove_opportunity_occurrence",
  "arguments": {
    "occurrence_id": "00000006-1111-4111-8111-000000000006",
    "expected_revision": "2026-10-18T18:40:00Z",
    "idempotency_key": "remove-stretch-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": "removed",
  "occurrence": {
    "id": "00000006-1111-4111-8111-000000000006",
    "behavior_id": "00000002-1111-4111-8111-000000000002",
    "behavior_title": "Stretch",
    "category_name": null,
    "local_date": "2026-10-18",
    "timezone": "America/New_York",
    "scheduled_for": "2026-10-18T19:00:00Z",
    "effective_start_at": "2026-10-18T19:00:00Z",
    "move": null,
    "schedule": {
      "kind": "exact",
      "preset": null,
      "start_time": "15:00",
      "end_time": null,
      "label": "3:00 PM"
    },
    "status": "unresolved",
    "status_label": "Unresolved",
    "needs_decision": false,
    "origin": "opportunity",
    "added_by": "user",
    "completed_at": null,
    "status_marked_at": null,
    "note": null,
    "updated_at": "2026-10-18T18:40:00Z",
    "revision": "2026-10-18T18:40: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).
