# RevCent MCP Guide: `GetSalvageTransactions`

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

---

## Operation Summary

Operation:

```text
GetSalvageTransactions
```

Purpose:

```text
Return a bounded list of previously created Salvage Transactions.
```

A Salvage Transaction represents recoverable revenue created from a failed or partially successful payment attempt.

Use `GetSalvageTransactions` 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 |
|---|---|
| Salvage Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSalvageTransaction.md` |
| ProcessSalvageTransaction | `https://revcent.com/documentation/markdown/mcp/operation/ProcessSalvageTransaction.md` |
| GetSalvageTransaction | `https://revcent.com/documentation/markdown/mcp/operation/GetSalvageTransaction.md` |
| Subscription Renewal Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionRenewal.md` |
| Trial Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrial.md` |
| Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTransaction.md` |
| Payment Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPaymentProfile.md` |
| AI Assistant Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md` |
| AI Voice Agent Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetSalvageTransactions` only for bounded operational retrieval.

Good uses:

- show recent Salvage Transactions for a specific customer,
- retrieve recovery items in a narrow date window,
- review a small operational list of open/recent recovery opportunities,
- locate a Salvage Transaction ID before using `GetSalvageTransaction`,
- inspect a short list before manual recovery or support review,
- support an AI Assistant or AI Voice Agent workflow that already has a narrow customer/item context.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields commonly follow RevCent bounded-list patterns:

| Field | Type | Description |
|---|---:|---|
| `date_start` | integer | Unix timestamp in seconds for start of date range. |
| `date_end` | integer | Unix timestamp in seconds for end of date range. |
| `limit` | integer | Number of records to return. Range is typically bounded by the operation schema. |
| `page` | integer | Pagination page. |

Common optional filters may include:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by Campaign IDs where available. |
| `currency_filter` | Filter by ISO 4217 currency codes where available. |
| `shop_filter` | Filter by User Shop IDs where available. |
| `status_filter` | Filter by recovery/status value where available. |
| `metadata_filter` | Filter by metadata name/value pairs where available. |
| `customer_id` | Filter by a specific Customer ID where available. |

Example:

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

AI/MCP should always follow the exact live schema for available filters.

---

## Output Summary

`GetSalvageTransactions` 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 Salvage Transaction objects. |

Salvage Transaction result objects can include amount fields, source flags, customer context, payment profile/gateway context, metadata, and related record IDs.

---

## External Notification Guidance

Do not poll `GetSalvageTransactions` as a long-term discovery method for new recovery opportunities.

Preferred automation pattern:

```text
salvage_transaction.created event
    ↓
RevCent Function / AI Assistant trigger / external notification
    ↓
review context and decline reason
    ↓
decide whether to process, wait, contact customer, or skip
```

Use account-event Functions or AI Assistant triggers for automated discovery.

Use `GetSalvageTransactions` for bounded operational lookup only.

---

## Customer-Facing AI Verification Warning

This operation may return sensitive customer, payment, decline, subscription, trial, sale, recovery, gateway, or lifecycle context across multiple Salvage Transactions.

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 Salvage Transaction(s) before providing details or taking action.

Recommended rule:

```text
Do not provide Salvage Transaction 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, subscription reference, or other lookup detail, that alone should not be treated as authorization to disclose Salvage Transaction information.

Safe customer-facing flow:

```text
Visitor provides lookup/filter input
    ↓
AI uses GetSalvageTransactions for a narrow operational lookup
    ↓
AI identifies likely Salvage Transaction(s)
    ↓
AI uses GetSalvageTransaction for the specific selected item when needed
    ↓
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 recovery request | Customer email from the retrieved Salvage Transaction. |
| Customer name | Email, phone, or another value already on the retrieved customer record. |
| Customer email | Secondary phone, subscription/trial/order-related value, or another record-backed verification value where available. |
| Phone number | Customer email from the retrieved Salvage Transaction. |
| Subscription / Trial / Sale context | Customer email or phone from the retrieved Salvage Transaction 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 a failed payment recovery item using a name or date range, verify against the customer email returned by `GetSalvageTransaction` or the retrieved Salvage Transaction details before discussing a specific item.

Do not disclose sensitive details such as:

- gateway decline details beyond what is appropriate for customer support,
- payment profile internals,
- fraud/risk logic,
- unrelated subscription/trial/sale details,
- 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 `ProcessSalvageTransaction`, payment retry, subscription changes, trial changes, refunds, or customer outreach, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Salvage Transaction lookup 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,
- salvage recovery reports,
- recovery-rate reports,
- declined revenue reports,
- trial-expiration recovery reports,
- subscription-renewal recovery reports,
- pending recovery reports,
- campaign/shop/product/payment-profile performance 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

`GetSalvageTransactions` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent Salvage Transactions | `GetSalvageTransactions` |
| Retrieve one known Salvage Transaction | `GetSalvageTransaction` |
| Process one recovery item | `ProcessSalvageTransaction` after review. |
| Count salvage records | `BigQueryRunQuery` |
| Calculate recovery rate | `BigQueryRunQuery` |
| Calculate recovered revenue | `BigQueryRunQuery` |
| Report failed/recovered revenue by campaign/shop/product/payment profile | `BigQueryRunQuery` |
| Discover new recovery items automatically | Event Function / AI Assistant trigger, not polling. |

---

## Example: Correct Operational Use

```text
User: Show recent Salvage Transactions for customer C over the last 7 days.
```

Correct:

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

---

## Example: Incorrect Reporting Use

```text
User: What was my salvage recovery rate last month by campaign?
```

Incorrect:

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

Correct:

```text
Use BigQueryRunQuery.
```

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

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` small and within schema limits.
4. Use `GetSalvageTransaction` for detail review after selecting a recovery item.
5. Do not loop through pages to build metrics.
6. Do not use this operation for reporting or data mining.
7. Do not poll this operation to discover new recovery items; use events/functions/AI triggers.
8. Verify customer identity before sharing Salvage Transaction details in customer-facing AI flows.
9. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetSalvageTransactions` only for bounded operational retrieval of Salvage Transactions.

In customer-facing AI flows, verify the visitor is related to the returned Salvage Transaction(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.