# refunds_get
This new unprefixed tool has no publ_ alias or historical migration pair. The source runtime is a dependency of this Docs branch, not its installed implementation.
PAY and refund-history reads retain their separate envelope and 2 MiB guards. See [the precise boundary](../guides/orders-refunds.md#core-response-limitations) before interpreting a confirmed result.
Read the selected channel's Refund requests screen with one composed MCP operation.
OWNER or DELEGATEE with MANAGE_ORDER is required. Monetization, sales or member
permissions do not substitute. The private PAY configuration belongs to the
operator; no payment key, token, password or raw URL is accepted as input.
## Input bounds
The outer object, view and search variants are strict. channelCode is required, 1–512 characters; dot/double-dot, slash/backslash, ASCII controls and DEL are rejected. Choose the exact authorized channel code, not a URL or numeric ID. Hosted account scope excludes this operation; unified execute requires an approved matching channel target.
Omitting view supplies {kind:"list",page:1,limit:300}. In list views, page is an integer from 1 to 1,000,000, and limit is one of 15, 30, 50, 100 or 300. Each defaults independently. Record/search identifiers are strings of 1–256 characters, excluding dot/double-dot, whitespace, ASCII controls, DEL, slash, backslash, question mark and hash. Member text is trimmed and then must contain 1–512 characters.
## Choose a view
| view.kind | Inputs and behavior |
| --- | --- |
| list (default) | page defaults to 1, limit defaults to 300; limits 15,30,50,100,300 |
| detail | Supply an observed rid, the refund request identifier, not a numeric database id |
| history | Supply an observed rid and type video or download; buyer/content filters are derived from this refund |
| download | Return the shared monthly CSV console; no records or file are generated |
List option status: ISSUED, REJECTED or REFUNDED selects the source status filter. Omit for all.
The list reads exactly one page, not every page or complete financial history.
The response preserves pagination and nextPage; request the next page explicitly.
Date-based large CSV extraction belongs to the download console, not an invented
list parameter. view objects are strict and cannot mix list/detail/history/export fields.
```json
{"channelCode":"selected-channel-code","view":{"kind":"list","page":1,"limit":15}}
```
## Search and buyer selection
List search can be {kind:"order-number",value:"observed-order-number"} or
{kind:"member",text:"member identifier or nickname"}. Order-number matching
follows the source service. Member search reads at most the first 500 source
profiles. An exact channel profile distinct ID or a single complete match can
resolve immediately. Multiple/truncated results return
COMMERCE_BUYER_SELECTION_REQUIRED with candidates and complete/total metadata,
before any PAY request. No match also requires input; it is not empty financial
history. Refine text to reach results outside this bounded first page.
To choose a candidate, repeat the same member search with profileDistinctId set
to its returned channel profile identifier. Numeric profile ID and global user
ID are different values and must not be substituted. The selected identity is
resolved again before returning financial records; a changed or newly ambiguous
selection discards the result. Global buyer identifiers stay internal.
## Returned records
A successful list contains records, pagination, nextPage and the applied view.
Detail contains record, selectedRecordId, buyerProfile and invoiceSummary. Known
fields include source order/refund identifiers and status, product/invoice
summary, observed prices, timestamps and payment-method category. The bridge
strips card details, payment tokens, raw gateway payloads, global buyer IDs,
issuer addresses, contact dumps and unknown nested properties. Names and reasons
remain untrusted data. It does not fetch a receipt or document URL.
Prices contain currency, decimal-string amount and sourceRepresentation
(decimal-string or json-number). Numeric amounts are recovered from JSON source
lexemes using the Node 24 runtime, including bounded exponent notation, without
using a rounded Number as the monetary value. Strings retain their representation.
Bounds are 60 whole and 30 fractional digits; values outside the exact supported
representation fail instead of rounding. Different currencies and delegated,
original, revenue, requested or refunded prices stay separate. No amount is
calculated, converted or substituted with zero.
Profile and invoice enrichments have observed, not-found or unavailable status.
404 and bounded upstream service failures are explicitly reported; missing
optional enrichment is not a missing order or refund. HTTP authentication failures, malformed projected data and checked identity mismatches fail the observation. The core HTTP 200 envelope must contain its own data property and no non-null error; rejection is sanitized as UPSTREAM_CONTRACT_MISMATCH. The core helper counts all response bytes, including ignored fields; oversized responses fail as UPSTREAM_RESPONSE_TOO_LARGE, and malformed JSON/streams fail as UPSTREAM_CONTRACT_MISMATCH. These errors do not become optional missing enrichment. List and detail
records are reread and compared; changed records or channel/operator/credential
context suppress all partial results. These sequential observations are not an
atomic statement, settlement balance or complete history.
Refund rid, order oid and the numeric row id are distinct. The refund's nested order and buyer references must agree. requestedAmount, refundedAmount and delegated amounts remain separate; missing refundedAmount is not zero. Stored status, withPg and isPgApplied do not mean the same thing. Approve/reject, refund amount entry and pass revocation remain human console operations.
## Console and recovery
Successful reads, buyer-selection guidance and CSV guidance supply one corresponding console address outside demo; refund-history scope or SERIES guidance also selects its exact tab. Authentication guidance and errors can have unavailable navigation. List opens this
channel's orders/refunds; detail appends the verified rid; download opens
orders/download. No account-home substitute or automatic button click occurs.
List `consoleView` states whether the address reproduces the requested selection.
Without member search, `exactMatch:true` preserves page, limit, optional order-number
search and the supported `isCP` or refund `status` filter. Orders use the source
`searchType=ORDER_NUMBER`; refunds use their source default order-number mode.
For member searches, the source console cannot restore the MCP-selected buyer:
its search saga selects the first profile, and the refund search mode is local UI
state. The bridge therefore supplies a broader parent list at page 1 / limit 300,
without search, while retaining `isCP` or `status`. `exactMatch:false`, `omitted`
and the parent relation/notice disclose this difference. Choose and verify the
member in the console; never present this parent as the same buyer-specific page.
Actual API queries and returned records keep the requested selection. Ambiguous
buyer guidance uses the same parent and stays unconfirmed without a PAY list read.
The wrapper requires matching selection, page, row identities, refund parent/status, next page, verification and console view. Inconsistent results or URLs have no navigation fallback. Existing empty out-of-range results retain their read policy without guaranteeing browser behavior. Detail, refund-history and monthly-download paths are unchanged. The person uses the console's own authentication.
Demo has no actual navigation.
The source ISSUER authorization and list profile lookup use POST for reading.
writesPerformed:false means no business write, not zero POST requests. Issuer
credentials are per read and never persisted; no task, automatic retry, payment,
refund submission or CSV generation occurs. verification.confirmed covers the
validated record observation only. Download and buyer-selection guidance remain
unconfirmed. Reread after human financial work; do not use task_resume.
For PAY_SERVICE_UNCONFIGURED, the operator supplies service settings privately.
For AUTH_REQUIRED or PERMISSION_DENIED, stop and use the supported human login/authorization flow; do not widen the target. For
COMMERCE_CHANGED, make a fresh read. A schema/identity/precision error must not
be converted to empty records. Refund consumption history is available only through refunds_get history; this does not provide generic installed-feature access. See the [composed workflow](../guides/orders-refunds.md) and [private operator settings](../guides/payment-gateway.md#operator-configuration).
## Additional input examples
Omit view for the default list:
```json
{"channelCode":"selected-channel-code"}
```
Search by an observed order number (also for refunds):
```json
{"channelCode":"selected-channel-code","view":{"kind":"list","search":{"kind":"order-number","value":"observed-order-number"}}}
```
Resolve a member, then repeat the same search using a returned channel profile identifier:
```json
{"channelCode":"selected-channel-code","view":{"kind":"list","search":{"kind":"member","text":"Example member"}}}
```
```json
{"channelCode":"selected-channel-code","view":{"kind":"list","search":{"kind":"member","text":"Example member","profileDistinctId":"observed-profile-distinct-id"}}}
```
Open a detail by its own observed identifier:
```json
{"channelCode":"selected-channel-code","view":{"kind":"detail","rid":"observed-refund-request-id"}}
```
Request human CSV guidance:
```json
{"channelCode":"selected-channel-code","view":{"kind":"download"}}
```
These are schema-valid shapes with placeholder identifiers, not actual records or permission evidence. Do not add dates, raw URLs, credentials, approval amounts, mutation actions, requestId or task fields. For bounded refund consumption, use the history view below; generic installed-feature access is excluded.
## Refund consumption history
```json
{"channelCode":"selected-channel-code","view":{"kind":"history","rid":"observed-refund-request-id","type":"video"}}
```
```json
{"channelCode":"selected-channel-code","view":{"kind":"history","rid":"observed-refund-request-id","type":"download"}}
```
History type download means file-download events; view kind download still means human monthly CSV guidance. Do not interchange them. No page, limit, cursor, profile ID, membership ID, pApp code, content ID, date or URL is accepted in this history view.
The bridge derives a channel profile and invoice scope from the selected refund: a membership mid, or pApp plus POST/SERIES target. Missing enrichment or unsupported scope returns REFUND_HISTORY_SCOPE_REQUIRED with historyRead:false and one exact refund-history tab. No history query is sent, and no empty history or refund eligibility is inferred.
REFUND_HISTORY returns projected records, selection and coverage with maxRecords:300, complete:false and paginationAvailable:false. The source has no total/cursor; even zero records do not prove no other consumption. History, refund, buyer profile, invoice and final context are checked through repeated sequential observations. Changes discard partial results. Records retain content IDs/titles, source type, timestamps and optional locked/membership-inclusion flags; raw logs, device/browser/consumer data and playback payloads are removed.
Present buyer references and selected pApp/POST values are checked before SERIES ambiguity is considered. Missing optional buyer references rely on the scoped source endpoint. For SERIES, each row must have exactly one targetContent.serieses entry matching the invoice target, and row.seriesId must be absent or equal to that target. Successful rows add selectedSeries:{id,title,basis:"invoice_target_in_source_serieses"}; other nested series remain source metadata.
A conflicting row.seriesId or missing/duplicate nested target match returns action_required / REFUND_HISTORY_SERIES_UNVERIFIED after the parent and context checks. It has reason:series-relationship-unverified, selection:{type,targetModel,targetId}, confirmed:false, refundObserved:true, historyRead:true and historyRecordsReturned:false. It contains no records or coverage, including no valid subset or false empty list. If the first read is ambiguous, no second history read occurs; second-read ambiguity also discards all first-read rows. The handoff is not a repeated-history verification, proof of foreign data or proof of no usage. Use its one exact console tab without changing the target or retrying automatically. Ordinary identity, authentication, body and drift failures still fail the observation instead of becoming SERIES guidance.
Usage outside a membership may be returned and does not determine eligibility. No viewing duration, consumed amount or refund amount is calculated. See [scope, fields and failure behavior](../guides/orders-refunds.md#refund-consumption-history). The exact history URL ends with /orders/refunds/{rid}/history/video-viewing-history or /history/download-history. A successful history observation is not a transfer, entitlement change or financial approval.
## Inputs
| Field | Required here | Contract |
| --- | --- | --- |
| `view` | No | one of: `list`, `detail`, `history`, `download` (by `kind`); default `{"kind":"list","page":1,"limit":300}` |
| `view.page` | No | When `view.kind` is `list`: integer; maximum 1000000; greater than 0; default `1` |
| `view.limit` | No | When `view.kind` is `list`: `15` or `30` or `50` or `100` or `300`; default `300` |
| `view.search` | No | When `view.kind` is `list`: one of: `order-number`, `member` (by `kind`) |
| `view.search.value` | Yes | When `view.kind` is `list` and `view.search.kind` is `order-number`: string; min length 1; max length 256 |
| `view.search.text` | Yes | When `view.kind` is `list` and `view.search.kind` is `member`: string; min length 1; max length 512 |
| `view.search.profileDistinctId` | No | When `view.kind` is `list` and `view.search.kind` is `member`: string; min length 1; max length 256 |
| `view.status` | No | When `view.kind` is `list`: `ISSUED`, `REJECTED`, `REFUNDED` |
| `view.rid` | Yes | When `view.kind` is `detail`: string; min length 1; max length 256; The observed refund request rid, not order oid or numeric database id. |
| `view.rid` | Yes | When `view.kind` is `history`: string; min length 1; max length 256 |
| `view.type` | Yes | When `view.kind` is `history`: `video`, `download`; The refund detail history tab. Buyer and content filters are derived from this refund. |
| `view.month` | No | When `view.kind` is `download`: string; pattern `^\d{4}-(?:0[1-9]\|1[0-2])$`; The month to read, YYYY-MM, as the console download month picker selects it. |
