# RevCent MCP Guide: `GetPendingRefunds`

Brief AI/MCP-focused guide for retrieving a bounded operational list of RevCent Pending Refunds.

---

## Operation Summary

Operation:

```text
GetPendingRefunds
```

Title:

```text
Get Pending Refunds
```

Purpose:

```text
Return a bounded list of previously created Pending Refunds.
```

A Pending Refund is RevCent's internal refund-tracking record created by refund or void operations.

Use `GetPendingRefunds` for narrow operational retrieval over a known date range and small page/limit.

Do not use it for reporting or analytics.

---

## Related Links

| Guide | Link |
|---|---|
| Pending Refund Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPendingRefund.md` |
| GetPendingRefund | `https://revcent.com/documentation/markdown/mcp/operation/GetPendingRefund.md` |
| SearchPendingRefunds | `https://revcent.com/documentation/markdown/mcp/operation/SearchPendingRefunds.md` |
| VoidSale | `https://revcent.com/documentation/markdown/mcp/operation/VoidSale.md` |
| RefundTransaction | `https://revcent.com/documentation/markdown/mcp/operation/RefundTransaction.md` |
| RefundProductSale | `https://revcent.com/documentation/markdown/mcp/operation/RefundProductSale.md` |
| RefundShipment | `https://revcent.com/documentation/markdown/mcp/operation/RefundShipment.md` |
| RefundTax | `https://revcent.com/documentation/markdown/mcp/operation/RefundTax.md` |
| RefundSubscriptionRenewal | `https://revcent.com/documentation/markdown/mcp/operation/RefundSubscriptionRenewal.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetPendingRefunds` only for bounded operational retrieval.

Good uses:

- show recent Pending Refunds for a specific customer,
- retrieve Pending Refunds in a narrow date window,
- review a small operational list of unprocessed refunds,
- locate a Pending Refund ID before using `GetPendingRefund`,
- support a customer refund-status question after verification,
- inspect refund status for a specific operational case.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields:

| Field | Type | Description |
|---|---:|---|
| `date_start` | integer | Date range start as a Unix timestamp in seconds. |
| `date_end` | integer | Date range end as a Unix timestamp in seconds. |
| `limit` | integer | Number of records to return. Range 1 to 25. Default 25. |
| `page` | integer | Pagination page. |

Optional filters:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by one or more Campaign IDs. |
| `currency_filter` | Filter by ISO 4217 currency code. |
| `gateway_filter` | Filter by one or more User Gateway IDs. |
| `payment_type_filter` | Filter by one or more payment types. |
| `paypal_account_filter` | Filter by one or more PayPal Account IDs. |
| `metadata_filter` | Filter by one or more metadata name/value pairs. |
| `customer_id` | Filter to records related to a specific Customer ID. |

Example:

```json
{
  "date_start": 1761955200,
  "date_end": 1764547200,
  "limit": 25,
  "page": 1,
  "customer_id": "CCCCCCCCCCCCCCCCCCCC"
}
```

---

## Output Summary

`GetPendingRefunds` can return:

| Field | Meaning |
|---|---|
| `current_count` | Current number of items in this response. |
| `current_page` | Current page. |
| `total_count` | Total number of matching items for the operational query. |
| `total_pages` | Total pages for the operational query. |
| `results` | Array of Pending Refund objects. |

Pending Refund result objects can include amount, status, processed state, payment type, customer, gateway, shop, metadata, refunded-offsite state, success/refund transaction IDs, and related record IDs.

---

## Important Pending Refund Concepts

A Pending Refund may exist because:

- a refund was requested,
- a void/refund operation created a refund tracking record,
- a processor cannot refund immediately,
- a credit-card transaction has not settled yet,
- an offsite refund was recorded,
- RevCent is preserving refund audit and lifecycle context.

Important fields to inspect:

| Field | Meaning |
|---|---|
| `processed` | Whether the refund has been processed at the payment processor. |
| `status` | Current refund state. Use the returned value, do not guess. |
| `refunded_offsite` | Whether the refund was recorded offsite and not sent through the gateway. |
| `payment_type` | Credit Card, PayPal, Offline Payment, or Check. |
| `refund_transaction_id` | Original transaction being refunded where applicable. |
| `success_transaction_id` | Successful refund transaction where applicable. |

---

## Operations That Can Create Pending Refunds

Pending Refund IDs are commonly returned by refund/void operations in a field such as:

```text
pending_refund
```

Operations that can create Pending Refunds include:

- `VoidSale`
- `RefundTransaction`
- `RefundProductSale`
- `RefundShipment`
- `RefundTax`
- `RefundSubscriptionRenewal`
- other payment-type-specific refund workflows where applicable.

Capture returned `pending_refund` IDs and use them for refund tracking.

---

## Customer-Facing AI Verification Warning

This operation may return sensitive customer, order, refund, payment, gateway, subscription, trial, shipping, tax, or lifecycle context across multiple Pending Refunds.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- support chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

the AI/MCP client should verify the visitor is actually related to the Pending Refund(s) before providing information, details, or taking action.

Recommended rule:

```text
Do not provide Pending Refund details to a public-facing visitor based only on visitor-provided filters or lookup input.
```

Even if the visitor provides a customer name, email, date range, phone number, order reference, refund reference, or other lookup detail, that alone should not be treated as authorization to disclose Pending Refund information.

Safe customer-facing flow:

```text
Visitor provides lookup/filter input
    ↓
AI uses GetPendingRefunds for a narrow operational lookup
    ↓
AI identifies likely Pending Refund(s)
    ↓
AI uses GetPendingRefund for the specific selected Pending Refund
    ↓
AI verifies the visitor against a secondary value from the retrieved record
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Recommended secondary verification values:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Date range or recent refund request | Customer email from the retrieved Pending Refund. |
| Customer name | Email, phone, or another value already on the retrieved customer record. |
| Customer email | Secondary phone, order-related value, or another record-backed verification value where available. |
| Phone number | Customer email from the retrieved Pending Refund. |
| Sale/order/refund context | Customer email or phone from the retrieved Pending Refund context. |

Important:

```text
The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original lookup/filter input.
```

For example, if the visitor asks about recent refunds for a name, order, or date range, verify against the customer email returned by `GetPendingRefund` before discussing a specific refund.

Do not disclose sensitive details such as:

- payment processor internals,
- gateway details beyond what is appropriate for customer support,
- full payment details,
- unrelated order/subscription/trial details,
- fraud/risk logic,
- full customer details,
- unrelated customer records,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as additional refunds, sale voids, product/shipping/tax refunds, subscription changes, or customer outreach, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Pending Refund lookup/search operation is **not** a reporting tool.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- refund volume reports,
- pending-vs-processed refund reports,
- refund timing reports,
- processor settlement reports,
- refund by payment type reports,
- campaign/shop/product/customer refund metrics.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If the AI/MCP client intended to use this operation for reporting, metrics, aggregation, or data mining and then realizes BigQueryRunQuery is the correct operation, it does not need to tell the user about the correction.

It should simply use BigQueryRunQuery instead.
```

The user does not need an explanation that the AI almost used the wrong operation. The correct behavior is to quietly choose the correct operation.


---

## Built-In Usage Warning

`GetPendingRefunds` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent Pending Refunds | `GetPendingRefunds` |
| Retrieve one known Pending Refund | `GetPendingRefund` |
| Search for a Pending Refund by term | `SearchPendingRefunds` |
| Count pending refunds | `BigQueryRunQuery` |
| Calculate pending-vs-processed refund rate | `BigQueryRunQuery` |
| Report refund timing or settlement delay | `BigQueryRunQuery` |
| Report refunds by campaign/shop/product/payment type | `BigQueryRunQuery` |

---

## Example: Correct Operational Use

```text
User: Show recent Pending Refunds for customer C over the last 7 days.
```

Correct:

```text
Use GetPendingRefunds with customer_id, date_start, date_end, limit, and page.
```

---

## Example: Incorrect Reporting Use

```text
User: How many refunds are still pending by payment type?
```

Incorrect:

```text
Loop through GetPendingRefunds pages and calculate manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` and not explain that it almost used `GetPendingRefunds`.

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` within schema limits.
4. Use `GetPendingRefund` for detail review after selecting a Pending Refund.
5. Inspect `processed`, `status`, and `refunded_offsite`.
6. Use related IDs to retrieve Sale/Product Sale/Shipping/Tax/Transaction context where needed.
7. Do not loop through pages to build metrics.
8. Do not use this operation for reporting or data mining.
9. Verify customer identity before sharing Pending Refund details in customer-facing AI flows.
10. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetPendingRefunds` only for bounded operational retrieval of Pending Refunds.

In customer-facing AI flows, verify the visitor is related to the returned Pending Refund(s) using a secondary value from the retrieved record, such as customer email, before providing details or taking action.

Never use it for reporting, metrics, aggregation, counting, broad analysis, data mining, or bulk export. If the user intent is analytical, silently switch to `BigQueryRunQuery`.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.