# RevCent MCP Guide: `SearchPendingRefunds`

Brief AI/MCP-focused guide for searching RevCent Pending Refunds.

---

## Operation Summary

Operation:

```text
SearchPendingRefunds
```

Purpose:

```text
Search previously created Pending Refunds using a search term.
```

Use `SearchPendingRefunds` when the exact Pending Refund ID is unknown and the user provides a search term such as customer email, customer name, phone, order/internal ID, refund ID, metadata value, payment context, or another searchable phrase.

---

## 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` |
| GetPendingRefunds | `https://revcent.com/documentation/markdown/mcp/operation/GetPendingRefunds.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 `SearchPendingRefunds` for targeted lookup when the Pending Refund ID is unknown.

Good search terms may include:

- customer email,
- customer name,
- customer phone,
- Pending Refund ID,
- Sale/order/internal ID,
- transaction ID,
- payment/refund context,
- metadata value,
- external/customer/internal identifier.

After finding a likely match:

```text
SearchPendingRefunds
    ↓
Review result/highlights/score
    ↓
GetPendingRefund
    ↓
Confirm exact Pending Refund before action
```

---

## Input Schema

Expected search input:

| Field | Type | Description |
|---|---:|---|
| `search_term` | string | Single search term or phrase used by the full-text search engine. |

Example:

```json
{
  "search_term": "customer@example.com"
}
```

AI/MCP should use the exact field names from the live schema.

---

## Output Summary

Search results commonly include identifying and match-context fields.

Possible fields include:

| Field | Meaning |
|---|---|
| `item_type` | Pending Refund item type. |
| `id` | Pending Refund ID. |
| `created_date_unix` | Creation timestamp. |
| `first_name` / `last_name` | Customer name when returned. |
| `email` | Customer email when returned. |
| `phone` | Customer phone when returned. |
| `status` | Pending Refund status when returned. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent details URL when returned. |
| `highlights` | Fields and values matched by the search. |
| `score` | Search score. Higher means a better match. |

After selecting a likely result, use `GetPendingRefund` before providing details or taking action.

---

## Search Safety Rule

Search results are possible matches.

They are not enough to perform consequential actions.

Before discussing refund status, initiating another refund, escalating support, or making account/order changes:

```text
SearchPendingRefunds
    ↓
Select likely result
    ↓
GetPendingRefund
    ↓
Confirm customer, refund status, processed state, payment type, and related records
    ↓
Only then take action if appropriate
```

Do not take refund/lifecycle actions directly from a search result.

---

## Customer-Facing AI Verification Warning

This operation can help locate sensitive customer, order, refund, payment, gateway, subscription, trial, shipping, tax, or lifecycle context.

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 resulting Pending Refund before providing information, details, or taking action.

Recommended rule:

```text
Do not provide Pending Refund details to a public-facing visitor based only on the search input they supplied.
```

Search inputs can be guessed, mistyped, shared, or discovered. A search result is only a possible match, not proof that the visitor is authorized.

Safe customer-facing flow:

```text
Visitor provides search input
    ↓
AI runs SearchPendingRefunds
    ↓
AI selects likely result
    ↓
AI runs GetPendingRefund for the selected Pending Refund
    ↓
AI verifies the visitor against a secondary value from the GetPendingRefund response
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Recommended secondary verification values:

| Search Input | Secondary Verification Value |
|---|---|
| Customer name | Customer email or phone from `GetPendingRefund`. |
| Customer email | Secondary phone, order-related value, or another record-backed verification value where available. |
| Phone number | Customer email from `GetPendingRefund`. |
| Sale/order/refund context | Customer email or phone from `GetPendingRefund`. |
| Metadata/external ID | Customer email or phone from the retrieved Pending Refund. |
| Pending Refund ID | Customer email from the retrieved Pending Refund. |

Important:

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

For example, if the visitor searches by order ID, refund ID, or name, do not reveal matching Pending Refund details until they verify a customer email or another secondary value from `GetPendingRefund`.

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.


---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Find the refund for this customer email.” | Use `SearchPendingRefunds`, then `GetPendingRefund`. |
| “Find this refund/order ID.” | Use `SearchPendingRefunds`, then verify with `GetPendingRefund`. |
| “Search for this metadata value.” | Use `SearchPendingRefunds`, then verify with `GetPendingRefund`. |
| “How many pending refunds mention X?” | Use `BigQueryRunQuery`, not `SearchPendingRefunds`. |
| “Analyze pending refunds by metadata value.” | Use `BigQueryRunQuery`, not `SearchPendingRefunds`. |
| “Find refund delay by payment type.” | Use `BigQueryRunQuery`, not `SearchPendingRefunds`. |

---

## Example: Correct Lookup Flow

```text
User: Find the Pending Refund for customer@example.com.
```

Correct:

```text
1. SearchPendingRefunds with search_term = "customer@example.com".
2. Review results.
3. GetPendingRefund for the correct result ID.
4. Summarize the exact refund status after verification.
```

---

## Example: Incorrect Reporting Flow

```text
User: Search all Pending Refunds with payment_type=Credit Card and tell me average pending time.
```

Incorrect:

```text
Use SearchPendingRefunds repeatedly and aggregate results manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` without telling the user it changed plans.

---

## Best Practices

1. Use specific search terms.
2. Prefer customer email, phone, order/internal ID, refund ID, or unique metadata values over broad names.
3. Review result highlights and score where returned.
4. Use `GetPendingRefund` after selecting a result.
5. Do not use search results alone for refund or lifecycle actions.
6. Do not use search for reporting or data mining.
7. Verify customer identity with a secondary value from `GetPendingRefund` before sharing details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for metrics and analysis.

---

## Final AI/MCP Instruction

Use `SearchPendingRefunds` only for targeted full-text lookup of Pending Refunds when the exact Pending Refund ID is unknown.

In customer-facing AI flows, search results are not proof of authorization. After finding a likely match, use `GetPendingRefund` and verify the visitor with a secondary value from the retrieved record, such as `customer.email`, before providing details or taking action.

Do not use it for reporting, metrics, aggregation, counting, broad analysis, or data mining. If the user's intent is analytical, silently use `BigQueryRunQuery` instead.


---
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.