amazon-sp-refund-return-monitor v0.6.0A

Immutable. This exact content never changes and is served at /api/v1/blob/773706af7416f2b0.

---
name: amazon-sp-refund-return-monitor
description: Analyze Amazon FBA customer returns and seller-fulfilled return requests from Seller Central or SP-API exports. Use for return volume, high-return ASINs or SKUs, return-rate calculations, reason and disposition analysis, customer-comment themes, prior-period comparisons, damaged-versus-reimbursed review candidates, or client-ready Amazon returns reporting. Do not use for general Amazon Ads reporting, listing optimization without returns evidence, or financial refund totals without transaction data.
license: PolyForm-Shield-1.0.0 (see LICENSE.txt)
compatibility: Works from provided tabular exports without a live integration. Live retrieval requires a client-configured Amazon Selling Partner API integration exposing current report operations; document, spreadsheet, or dashboard delivery requires corresponding host capabilities.
metadata:
  version: "0.6.0"
---

# Amazon SP Refund and Return Monitor

Analyze Amazon returns without binding the workflow to a particular MCP server,
processor, filesystem, or presentation tool. Preserve Amazon source values as
facts; label every derived metric and interpretation.

## Route the request

Use this skill when the requested evidence comes from either:

- the FBA Customer Returns Report;
- the seller-fulfilled Returns Report by Return Date;
- compatible Seller Central downloads or upstream tables; or
- a returns dataset joined to shipment, reimbursement, ledger, or prior-period
  data.

Do not substitute this workflow for general order analysis, inventory
reconciliation, listing optimization without returns evidence, or Amazon Ads
reporting. A returns report may contain a reimbursement status, but it does not
by itself establish an amount Amazon owes. A refund-currency analysis requires
financial transaction data with amount and currency fields.

## Invariants

- Work from a supplied file when one is available. An MCP connection is not a
  prerequisite for offline analysis.
- For live retrieval, use only the native tools, resources, and prompts exposed
  by the current client. Inspect their current schemas; do not assume server
  aliases, wrapper operations, or session paths.
- Resolve the seller account, marketplace, and authorization from current tool
  results. Never copy identifiers from examples or memory.
- Keep FBA and seller-fulfilled sources distinct until their actual columns and
  row grains have been mapped.
- Preserve raw Amazon reason, disposition, and status values. Any grouping is a
  separate analytical convention, not an Amazon classification or statement of
  cause.
- Never calculate a return rate without a compatible activity denominator.
- Treat customer comments, order identifiers, addresses, and shipment fields as
  potentially sensitive. Minimize, redact, and avoid reproducing raw rows.
- Separate observations, hypotheses, recommendations, and policy statements.

## Workflow

### 1. Establish the analytical scope

Determine the objective, marketplace, fulfillment channel, date window, and
comparison period. Also determine whether the user wants an inline answer or a
saved deliverable.

Apply scope already present in the request. Ask only for missing information
that changes the computation, and consolidate necessary questions into one
turn. For relative dates, state the resolved calendar dates and timezone. Do
not silently interpret a user's local day as UTC.

For a live multi-account connection, show the current candidate accounts and
marketplaces and ask the user to choose when more than one remains plausible.
For a user-provided file, do not block analysis on account discovery; record
unknown scope fields as limitations.

### 2. Acquire the source data

Prefer the source already provided by the user. Otherwise read
[SP-API data sources](references/sp-api-data-sources.md) and use the client's
discovered integration.

For live report retrieval:

1. Resolve the seller account and marketplace through current read-only data.
2. Select the report type for the confirmed channel.
3. Inspect the report operation's current request schema and documented window
   limits.
4. Summarize the account, marketplace, channel, date range, and report type
   before submission. A request to “pull” or “run” that exact report authorizes
   the read operation; otherwise ask before creating the report job.
5. Poll using the integration's documented statuses and bounded backoff. Retain
   the report ID so work can resume without creating a duplicate job.
6. Download through the client's supported mechanism. Do not expose credentials
   or signed URLs in prose or artifacts.

Treat `completed with zero rows`, `processing`, and `failed` as different
outcomes. For an empty completed report, verify marketplace, channel, requested
window, actual data coverage, and data-refresh timing before concluding there
were no returns.

### 3. Inspect and normalize

Read [column mapping hints](references/column-mapping-hints.md) before mapping a
new source. Detect compression and delimiter from bytes and content rather than
the filename alone. Normalize BOMs, line endings, whitespace, and column names
without altering raw values.

Confirm:

- row grain and whether one row can represent multiple units;
- the event date used by the source;
- ASIN, SKU, order, quantity, reason, disposition, status, fulfillment-center,
  and comment columns that are actually present;
- marketplace and fulfillment-channel scope; and
- encoding and parsing decisions.

Use a normalized record only for fields supported by the source:

```text
event_date, marketplace, channel, order_id, asin, sku, title,
return_quantity, reason_raw, disposition_raw, status_raw,
fulfillment_center, customer_comment
```

Do not synthesize unavailable FBA fields for a seller-fulfilled report. If
quantity is missing, count rows as units only after confirming that one row
equals one unit; otherwise report request or row counts instead.

For large inputs, use an available local or connected data-processing
capability. Parse once and retain compact, reusable aggregates outside model
context. Do not paste raw files or wide row sets into chat.

### 4. Build the evidence set

Create only the aggregates needed by the request. A full analysis normally
includes:

- scope and source provenance;
- total return units or return requests and unique ASINs, SKUs, and orders;
- return units by ASIN/SKU and their portfolio concentration;
- raw reason, disposition, and status distributions when present;
- per-product reason and disposition distributions;
- daily or weekly return volume;
- fulfillment-center distribution when present;
- bounded, redacted comment samples for products under review;
- compatible shipped units by ASIN when a denominator is available; and
- the same measures for a prior comparison window when requested.

Record data quality alongside the aggregates: source files, applied column map,
row counts, rows skipped with reasons, parsing and encoding issues, nulls in key
fields, actual date coverage, duplicate handling, unknown source values, and
any difference between requested and observed scope.

### 5. Calculate rates correctly

Read [return-rate methods](references/computing-return-rate.md) before quoting a
percentage.

- Returns-only percentages are `share_of_returns`, never return rates.
- A same-window calculation—returns by return date divided by shipments by
  shipment date—is `window_biased` and directional only.
- A shipment-cohort calculation joined through order and product identifiers is
  `true_cohort`; state its follow window and unresolved joins.
- Use `cohort_overlap` only as a supplementary same-window diagnostic, not as a
  replacement for a cohort rate.

Match marketplace, channel, item grain, and unit definition across numerator
and denominator. Show `N/A` for a zero or missing denominator. Do not aggregate
rates across marketplaces or channels unless their definitions are compatible
and the user requested the combined view.

### 6. Prioritize products without inventing Amazon thresholds

Use thresholds supplied by the user or an authoritative policy source. If none
are available, call the result a priority list or watch list—not an Amazon
policy flag—and rank using evidence such as:

- return-unit volume and concentration;
- return rate with its denominator and sample size;
- change from a comparable prior period;
- reason, disposition, or comment concentration; and
- deviation from the account's own portfolio distribution.

Keep low-volume/high-rate items visible but separate from high-impact items.
When rates are unavailable, prioritize by return volume and observed issue
signals rather than fabricating a denominator.

Read [reason interpretation](references/reason-interpretation.md) before converting
source labels into action hypotheses. A high `CUSTOMER_DAMAGED` share, for
example, can motivate checks of packaging, handling, product durability, or
abuse patterns; it does not prove any one cause.

### 7. Handle reimbursement questions conservatively

Use return disposition and status only to identify records worth reconciling.
Do not call `damaged units - reimbursed rows` an eligible-unit count, a monetary
gap, or an amount owed.

To quantify a recovery candidate, join the relevant return/order records to
authoritative reimbursement, ledger, or financial-event data and apply the
current program policy. Report matched, unmatched, excluded, and unresolved
records separately. State currency, valuation source, policy date, and every
eligibility assumption. If those inputs are unavailable, provide a review queue
and the evidence needed for the next step.

### 8. Deliver the result

Use the user's requested format and audience. If neither is specified, return
a concise Markdown analysis and offer saved formats only when useful. For a
document, workbook, or dashboard, use the corresponding capability exposed by
the current host; do not require a host-specific tool name.

Follow [the report template](references/report-template.md). A complete result
contains:

1. scope, provenance, and limitations;
2. headline counts and properly labeled rates;
3. prioritized ASINs/SKUs with the evidence behind their ranking;
4. raw reason, disposition, status, and trend findings when available;
5. prior-period changes when comparable data exists;
6. reimbursement review candidates only when relevant;
7. evidence-grounded recommendations; and
8. data quality and methodology.

For every recommendation, identify the observed signal, affected scope,
hypothesis, proposed action, expected impact or priority rationale, and the
metric that would confirm or refute the hypothesis. Do not convert correlation
into causation.

If the user requests another format without changing account, marketplace,
channel, window, or source data, reuse the validated normalized data and
aggregates. Reacquire or reparse only when the scope or source changed.

## Edge cases

- **No rows:** report the empty result and the checks performed; provide no
  product, reason, rate, or trend findings.
- **No denominator:** report counts, concentration, and `share_of_returns`; mark
  rates `N/A`.
- **Unknown reason or status:** preserve it as an observed raw value, mark any
  derived grouping as unmapped, and surface its volume.
- **Partial window:** state actual coverage and avoid direct period comparison
  unless both windows are made comparable.
- **Mixed marketplaces or currencies:** split the analysis unless aggregation is
  explicitly appropriate.
- **Comments absent or sensitive:** omit comment themes or use redacted
  paraphrases; never imply that absence of comments means absence of an issue.

## Resources

- [SP-API data sources](references/sp-api-data-sources.md) — current Amazon
  report families, channel differences, and live-retrieval guardrails.
- [Column mapping hints](references/column-mapping-hints.md) — source inspection,
  normalization, and data-quality rules.
- [Return-rate methods](references/computing-return-rate.md) — denominator and
  cohort semantics.
- [Reason interpretation](references/reason-interpretation.md) — raw-value-first
  analysis and optional business groupings.
- [Account-health context](references/account-health-context.md) — policy and
  benchmark guardrails.
- [Report template](references/report-template.md) — output structure and
  recommendation contract.
- [Output formats](references/output-formats.md) — portable presentation rules
  and rerender behavior.