> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quality review and resolution receipts

> Current account API behavior for quality review work, receipts and resolution confirmation settings.

This page describes six existing account operations. Their authentication and
feature gates are specific to each resource. Each request uses the account in
the URL and requires an authenticated member of that account. Responses are
account scoped. The quality controllers set `Cache-Control: no-store` after
inherited authentication, account and trial callbacks. The receipt controller
prepends `no-store` before authentication, so its refusals also carry it.

| Operation | Request | Current behavior |
| - | - | - |
| `list_quality_review_items` | `GET /api/v1/accounts/{account_id}/quality_review_items` | Administrator-only metadata queue. |
| `show_quality_review_item_work_state` | `GET /api/v1/accounts/{account_id}/quality_review_items/{quality_review_item_id}/work_state` | Administrator-only assignment and work state. |
| `update_quality_review_item_work_state` | `PATCH /api/v1/accounts/{account_id}/quality_review_items/{quality_review_item_id}/work_state` | Updates assignment or worked state with optimistic locking. |
| `show_resolution_receipt` | `GET /api/v1/accounts/{account_id}/billing/resolution_receipts/{resolution_ref}` | Shows evidence for one account-scoped resolution. |
| `show_resolution_confirmation_settings` | `GET /api/v1/accounts/{account_id}/resolution_confirmation_settings` | Reads current account settings and effective flags. |
| `update_resolution_confirmation_settings` | `PATCH /api/v1/accounts/{account_id}/resolution_confirmation_settings` | Validates, locks and audits changed settings. |

All six operations reject a request that supplies more than one account API
credential type with HTTP 400 and `error.code: multiple_credentials`, before the
action runs.

All six operations inherit the account API impersonation guard. Alongside the
ordinary authentication and role errors, a request can return 403 with
`error.code` set to `impersonation_read_only`, `impersonation_wrong_account` or
`impersonation_blocked_action`; an ended session can return 401 with
`error.code` set to `impersonation_ended`.

## Quality review metadata

The queue requires the exact `quality_review_queue_read` deployment switch to be
`on` and an administrator role. It is independent of the
`orchestration_studio` account feature. The response includes only item id,
reason, `flagged_at` and `source_current`; it does not return customer evidence,
a verdict or a golden case.

The only accepted query parameters are `reason`, `limit` and `cursor`. The
reason must be `verifier_uncertain` or `negative_csat`. The limit defaults to 50
and is capped at 100. A cursor is signed and bound to the account and reason
filter; an invalid cursor or other parameter returns 422. Queue items whose
source is no longer current are omitted.

## Manual work state

The work-state operations require both the queue-read and
`quality_review_queue_work` deployment switches to be `on`, plus an
administrator role. This resource coordinates assignment and a worked marker;
it does not create a quality verdict, edit a golden case or adjudicate a bill.

GET takes no query or body parameters. PATCH requires a JSON object at the
request root and no query parameters. Send `lock_version` and at least one of
`assigned_user_id` or `worked`. `assigned_user_id` is an account member's user
id or null to clear the assignment; `worked` must be a JSON boolean. A stale
version returns 409 `stale_version`; invalid fields return 422
`invalid_parameters`. The successful response contains the current item id,
assignee, worked flag and lock version.

## Resolution receipt

Receipt reads require `billing_resolution_receipts_api_enabled` to be exactly
`on`. Administrators receive the full receipt. If the separate
`billing_receipt_restricted_view_enabled` switch is exactly `on`, another
genuine account member may receive a restricted receipt. That view omits
`credits`, `billed_despite_exclusion` and `ledgers`; without that switch a
non-administrator receives 403. These gates are separate.

The reference must be nonempty, at most 255 UTF-8 bytes, and contain no control
characters, colon, slash or backslash. Lookup is scoped to the URL account; a
missing or foreign reference returns 404. The full receipt separates trigger,
confirmation, class, credit, exclusion and dispute evidence. A bounded
correction-chain read can return 503 `receipt_unavailable`; an unexpected
read failure returns 500 `internal_error`. Both have a nested retryable error
object. The controller omits raw verification evidence and resolves receipts
only within the URL account.

When `billing_resolution_ledgers_enabled` is exactly `on`, a full administrator
view may include separate fee and language-model cost ledgers. The key is
omitted when the switch is off and from restricted views. It is not a combined
total, margin or invoice-finality guarantee. The receipt documents evidence
for one resolution and does not assert that an invoice is final.
The fee ledger can return stored settlement pricing provenance when applied
credits still match the original receipt draw. Known fields include resolution
class, modifiers, rate source and disposition, with settled price and rate
identity when present. Historical stored metadata can also include other keys.

## Resolution confirmation settings

Both settings operations require the account's `resolution_confirmation`
feature and an administrator role. They do not inherit the Studio feature
gate. GET returns the current `customer_yes_ask`, `human_marked_no_return`,
`quiet_days`, `window_days` and nullable `ask_text`, plus read-only
`reopen_window_days` and effective flags. Effective ask behavior also depends on
the global switches and service hold ceilings. `human_marked_no_return` is
stored, but has no current consumer.

PATCH accepts a JSON object at the root with no query parameters. It must
contain at least one writable key. Boolean settings require JSON booleans;
`window_days` is an integer from 1 through 30; `ask_text` is null or valid text
up to 200 characters. Unknown keys, read-only fields, wrong types and invalid
values return 422 `invalid_params`. Changes are merged under the account lock
and audited once per changed field with the authenticated actor. Unchanged
values are no-ops, and invalid requests leave settings and audit rows
unchanged.

## Requested action inventory

The following requested actions are currently missing or only partly represented
by the six operations above. Missing actions belong to ENG-5897 and are not
runtime acceptance for this contract.

| Requested action | Current availability | Existing operation or gap |
| - | - | - |
| `quality.list` | Partial metadata queue only | `list_quality_review_items` |
| `quality.summary` | Missing | ENG-5897 |
| `quality.review` | Missing | ENG-5897 |
| `quality.transcript` | Missing | ENG-5897 |
| `quality.newCase` | Missing | ENG-5897 |
| `quality.checkCase` | Missing | ENG-5897 |
| `quality.goldenSets` | Missing | ENG-5897 |
| `quality.goldenCase` | Missing | ENG-5897 |
| `quality.saveVerdict` | Missing | ENG-5897 |
| `quality.dismiss` | Missing | ENG-5897 |
| `quality.addCase` | Missing | ENG-5897 |
| `quality.editCase` | Missing | ENG-5897 |
| `quality.retireCase` | Missing; proposed risk class is destructive | ENG-5897 |
| `receipts.show` | Partial single-receipt read | `show_resolution_receipt` |
| `receipts.list` | Missing; no pagination or max page is defined | ENG-5897 |
| `receipts.summary` | Missing | ENG-5897 |
| `receipts.confirmationRules` | Partial account settings only | `show_resolution_confirmation_settings` |
| `receipts.reconcile` | Missing | ENG-5897 |
| `receipts.saveConfirmationRules` | Partial account settings only; proposed risk class is money-adjacent | `update_resolution_confirmation_settings` |

The internal dated inventory records unapproved scopes and event proposals,
with MCP hidden and SDK exposure excluded pending review. Proposed events are
not delivered events. The three existing `moves_money` operations remain
unchanged.

The issue's proposed administrator-or-billing receipt role is not current
behavior. The current restricted account-member view is documented above; a
different role boundary remains a gap. API scopes, delivered webhook events,
MCP exposure and SDK exposure remain unapproved or pending review.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.