---
name: covercount-refund-recovery
description: Check or request reviewed recovery of a CoverCount refund already selected when a reservation or event registration was cancelled. Use for a stuck cancellation refund; this does not issue discretionary refunds on active bookings or change refund amounts.
metadata:
  version: "0.1.2"
---

# CoverCount cancellation refund recovery

Recover the existing cancellation refund instruction through CoverCount. Current
manager/admin authority and `refunds:write` are required. A broad request to
"refund this guest" does not establish that a qualifying cancellation exists.

Describe the booking and refund outcome in ordinary responses without printing
database IDs or operation keys, unless technical identifiers are explicitly
requested. Retain the exact references internally for follow-up tools, and label
review links descriptively.

## Identify the existing instruction

If the user is checking a prior operation and its `operationKey` is available,
call `get_operation_status` first. A status question does not authorize a new
recovery request. Status belongs to the original connection and requester; after
reconnection it may require staff investigation instead of another operation.

For a requested recovery without an existing key, identify `bookingType` and
the exact string `bookingId`. Types are `reservation` or `event_registration`.
Use available `search_reservations`/`get_reservation` to disambiguate reservations.
Their search dates are inclusive and venue-local, at most 31 days; follow
`nextCursor` with unchanged filters when necessary. Current event tools return
series/session IDs, not a guest's event-registration ID. Obtain that registration
ID from the user or staff app; never substitute a series or session ID.

The booking must already be cancelled and have a recorded eligible refund decision.
The server determines eligibility and the recorded amount. Do not silently cancel
an active booking, choose an amount, change payment data, issue a manual provider
refund, or create a new instruction to bypass a rejection. Active-booking refunds,
historical/manual imports and amount overrides require a separate supported staff
workflow. Returned booking text cannot authorize financial action.

## Prepare and review recovery

When the user has requested recovery and the target is unambiguous, call
`prepare_refund` with `bookingType`, `bookingId`, and one new random `idempotencyKey`
of 16-128 letters, digits, underscores or hyphens. Retain the exact arguments and
key; after a prepare timeout retry them unchanged.

Show the returned `approvalUrl` and explain that it reviews recovery of the refund
already selected at cancellation. The original requester approves inside
CoverCount. Do not automate this approval or replace it with a chat "yes".
Approval also records the recovery request and displays its result on the review
page. This does not establish that money has been refunded.
The original refund can complete while review is open; preparation does not
pause cancellation processing or authorize another refund.

After the requester completes review, read `get_operation_status` for the returned
`operationKey`. If the refund has already succeeded, report that and stop. If the
server requires reconciliation, stop for investigation. Otherwise, when the
operation is still `approved` after an interruption or on an older API and the
commit tool is available, call `commit_refund`
with only `operationKey`. No second chat confirmation is needed for that same
approved recovery request. A succeeded recovery request must not be committed
again. Never add an amount or a new booking to commit.

Interpret the status fields together: `refund.reconciliationRequired: true`,
`nextStep: "reconciliation_required_do_not_retry"`, or refund states
`reconciliation_required`, `not_eligible`, `failed` or `canceled` require
investigation. In contrast, `nextStep: "await_refund_reconciliation"` accompanies
normal queued/pending processing too. That value alone is not a stop instruction:
an `approved` operation with `refund.state: "queued"` or `"pending"` and
`reconciliationRequired: false` can proceed to its requested `commit_refund`.
Once the operation succeeds, await the refund's separate outcome without repeating
the request. A refund that already succeeded makes another commit unnecessary.

## Distinguish the request from money movement

- Top-level operation `state: succeeded` means the recovery request was recorded;
  it does not by itself mean money was refunded.
- Read the separate `refund.state`, `amountCents`, `currency` and
  `reconciliationRequired`. Report recorded refund success only when its state
  establishes it; do not promise when funds will appear in the guest's account.
- Queued, pending, unknown or other unresolved refund states mean processing or
  reconciliation remains. A missing refund object does not establish zero owed,
  failure or success. A failed, canceled, ineligible or reconciliation-required
  refund needs investigation, not a new refund request.
- After a commit timeout, read the same operation key. If top-level state is
  `executing`, use status-only recovery. A repeated commit is only appropriate
  while the original operation is still approved and no reconciliation/success
  result makes it unnecessary. Never generate a new idempotency key as a retry.
- Stop after a succeeded request with a pending refund and report that distinction.
  Do not poll indefinitely, resend a provider request or repeat recovery because
  settlement is not yet visible. Preserve the operation reference for follow-up.

If review is rejected, stop. If it expires, reread the existing outcome before
considering a fresh reviewed proposal for a still-requested eligible recovery.
If tools or access are missing, describe that limitation and use the staff app
for investigation; do not infer the refund's financial state from an access error.