> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trutee.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trutee.app/_mcp/server.

# Reservation lifecycle

> Retrieve, reconcile, cancel, and cancel-and-rebook Reservations.

## Retrieve

`GET /reservations/{reservation_id}` returns the current representation only when it belongs to the selected organization. Unknown and cross-organization IDs both return `reservation_not_found`.

```json title={"Retrieve response"}
{
  "data": {
    "id": "res_example_encrypted",
    "status": "confirmed",
    "course_id": "crs_example_encrypted",
    "external_reference_id": "external-order-1042",
    "guest": {
      "first_name": "Avery",
      "last_name": "Jordan",
      "email": "avery@example.com",
      "phone": "+13035550142"
    },
    "allocations": [
      {
        "tee_time_id": "ttm_example_encrypted",
        "quantity": 2,
        "time": {
          "starts_at": "2026-08-15T14:10:00.000Z",
          "local_date": "2026-08-15",
          "local_time": "08:10",
          "timezone": "America/Denver"
        },
        "selections": { "holes": 18, "cart": "riding" },
        "pricing": {
          "green_fee": { "amount_minor": 8500, "currency": "USD" },
          "cart_fee": { "amount_minor": 1800, "currency": "USD" },
          "total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
        },
        "known_companions": [{ "first_name": "Morgan", "last_name": "Lee" }]
      }
    ],
    "golfer_count": 2,
    "payment": {
      "method": "pay_at_course",
      "amount_due_now_minor": 0,
      "currency": "USD"
    },
    "cancellation_policy": {
      "window_hours": 24,
      "fee": { "amount_minor": 2500, "currency": "USD" },
      "policy_fingerprint": "policy_2026_07"
    },
    "cancellation_eligibility": {
      "allowed": true,
      "code": "allowed",
      "message": "This Reservation may be cancelled through the API.",
      "contact_course": false
    },
    "integration_attribution": {
      "organization_name": "Example Travel",
      "source": "public_api"
    },
    "created_at": "2026-07-29T14:01:00.000Z",
    "updated_at": "2026-07-29T14:01:00.000Z",
    "cancelled_at": null,
    "messaging": {
      "owner": "integration",
      "trutee_confirmation_suppressed": true,
      "trutee_cancellation_suppressed": true,
      "course_name": "Pine Ridge Golf Club",
      "guest_name": "Avery Jordan",
      "allocations": [
        {
          "time": {
            "starts_at": "2026-08-15T14:10:00.000Z",
            "local_date": "2026-08-15",
            "local_time": "08:10",
            "timezone": "America/Denver"
          },
          "quantity": 2,
          "selections": { "holes": 18, "cart": "riding" }
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_reservation_example"
  }
}

```

## Keep Reservations in sync (reconciliation)

Reconciliation is the background sync that keeps your system aligned with Trutee after a Reservation is created. For example, a course may cancel a Reservation or mark it completed outside your integration. Because v1 does not send webhooks, periodically list Reservations changed since your last successful sync and apply those newer representations to your records.

List by course, play-date range, status, External Reference ID (`external_reference_id`), or `updated_after`. Every allocation in a grouped Reservation shares one course-local date, and the group matches when that shared date is inside the inclusive bounds. A cursor is scoped to the exact filters and limit.

```json title={"Reconciliation page"}
{
  "data": [],
  "meta": {
    "request_id": "req_list_example",
    "has_more": true,
    "next_cursor": "cur_example_encrypted",
    "reconciliation": {
      "updated_through": "2026-07-29T15:00:00.000Z",
      "next_updated_after": "2026-07-29T14:59:59.999Z"
    },
    "limits": {
      "max_page_size": 50,
      "max_play_date_range_days": 366
    }
  }
}

```

Follow `next_cursor` until `has_more` is false without changing filters. Keep the first page's fixed `updated_through`. After the last page, persist `next_updated_after` and use it as the next run's `updated_after`. The one-millisecond overlap protects equal-timestamp boundaries; deduplicate by Reservation ID and `updated_at`.

Commit the new watermark only after every page succeeds. If a traversal fails, discard its cursor and restart from the last committed `updated_after`; never advance the watermark from a partial run. Choose a polling cadence that meets your guest-support needs while staying within the published read rate limit, and alert when repeated failures prevent a complete run.

Webhooks are deferred, so polling reconciliation is the v1 change-detection contract.

## Cancel

Cancellation is atomic across the complete group and requires a new idempotency key.

```json title={"Cancellation request"}
{
  "reason": "Guest requested cancellation"
}

```

```json title={"Cancellation success"}
{
  "data": {
    "id": "res_example_encrypted",
    "status": "cancelled",
    "course_id": "crs_example_encrypted",
    "external_reference_id": "external-order-1042",
    "guest": {
      "first_name": "Avery",
      "last_name": "Jordan",
      "email": "avery@example.com",
      "phone": "+13035550142"
    },
    "allocations": [
      {
        "tee_time_id": "ttm_example_encrypted",
        "quantity": 2,
        "time": {
          "starts_at": "2026-08-15T14:10:00.000Z",
          "local_date": "2026-08-15",
          "local_time": "08:10",
          "timezone": "America/Denver"
        },
        "selections": { "holes": 18, "cart": "riding" },
        "pricing": {
          "green_fee": { "amount_minor": 8500, "currency": "USD" },
          "cart_fee": { "amount_minor": 1800, "currency": "USD" },
          "total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
        },
        "known_companions": [{ "first_name": "Morgan", "last_name": "Lee" }]
      }
    ],
    "golfer_count": 2,
    "payment": {
      "method": "pay_at_course",
      "amount_due_now_minor": 0,
      "currency": "USD"
    },
    "cancellation_policy": {
      "window_hours": 24,
      "fee": { "amount_minor": 2500, "currency": "USD" },
      "policy_fingerprint": "policy_2026_07"
    },
    "cancellation_eligibility": {
      "allowed": false,
      "code": "already_cancelled",
      "message": "This Reservation is already cancelled.",
      "contact_course": false
    },
    "integration_attribution": {
      "organization_name": "Example Travel",
      "source": "public_api"
    },
    "created_at": "2026-07-29T14:01:00.000Z",
    "updated_at": "2026-07-29T15:30:00.000Z",
    "cancelled_at": "2026-07-29T15:30:00.000Z",
    "messaging": {
      "owner": "integration",
      "trutee_confirmation_suppressed": true,
      "trutee_cancellation_suppressed": true,
      "course_name": "Pine Ridge Golf Club",
      "guest_name": "Avery Jordan",
      "allocations": [
        {
          "time": {
            "starts_at": "2026-08-15T14:10:00.000Z",
            "local_date": "2026-08-15",
            "local_time": "08:10",
            "timezone": "America/Denver"
          },
          "quantity": 2,
          "selections": { "holes": 18, "cart": "riding" }
        }
      ]
    }
  },
  "cancellation": {
    "already_cancelled": false
  },
  "meta": {
    "request_id": "req_cancellation_example"
  }
}

```

If a fee is required, play started, the Reservation is not cancellable, or stored state cannot be safely released, the API does not partially cancel:

```json title={"Policy denial"}
{
  "error": {
    "type": "conflict_error",
    "code": "cancellation_fee_required",
    "message": "The course cancellation policy requires a fee that cannot be collected through this API. Contact the course.",
    "doc_url": "https://docs.trutee.app/home/operate/errors#cancellation_fee_required",
    "request_id": "req_cancellation_denied"
  }
}

```

Contact the course when `contact_course` is true or the error directs you to do so. A later logical cancellation request with a new idempotency key succeeds and reports `already_cancelled: true` when the Reservation is already cancelled. A same-key retry replays the original response unchanged, so its `already_cancelled` value may remain `false`.

## Cancel and rebook

Changes are not supported in place. Retrieve the Reservation, collect the requested change, and explain that replacement capacity is not guaranteed. Search replacement availability immediately before the guest confirms, then cancel the old Reservation and create the replacement with a new booking idempotency key and External Reference ID.

This is not an atomic replacement: the new offer can expire or lose capacity after cancellation succeeds. If cancellation is denied, do not book a replacement automatically because that can leave two active Reservations. If cancellation succeeds but replacement creation fails, stop automatic retries that would change the request, keep the guest informed, and contact the Inventory Course about recovery. Send messaging only for operations that returned success.