# RevCent MCP Guide: `GetChargebacks`

AI/MCP-focused guide for retrieving a bounded operational list of RevCent Chargebacks.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Chargeback Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewChargeback.md` | Broad explanation of Chargebacks, dispute lifecycle, representment context, related records, and best practices. |
| GetChargeback | `https://revcent.com/documentation/markdown/mcp/operation/GetChargeback.md` | Retrieve one specific Chargeback by ID. |
| GetChargebacks | `https://revcent.com/documentation/markdown/mcp/operation/GetChargebacks.md` | Retrieve a bounded operational list of Chargebacks. Not for reporting/metrics. |
| SearchChargebacks | `https://revcent.com/documentation/markdown/mcp/operation/SearchChargebacks.md` | Search Chargebacks when the Chargeback ID is unknown. |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` | Retrieve the Customer related to the Chargeback. |
| GetSale | `https://revcent.com/documentation/markdown/mcp/operation/GetSale.md` | Retrieve related Sale context. |
| GetTransaction | `https://revcent.com/documentation/markdown/mcp/operation/GetTransaction.md` | Retrieve related credit-card Transaction context. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for Chargeback reporting, metrics, aggregation, and data mining. |


---

## Operation Summary

Operation:

```text
GetChargebacks
```

Title:

```text
Get Chargebacks
```

Purpose:

```text
Return a bounded list of previously created Chargebacks.
```

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

Do not use it for reporting or analytics.

---

## When to Use

Use `GetChargebacks` when:

- the user wants a small filtered list of Chargebacks,
- the user wants Chargebacks for a specific Customer,
- the user wants Chargebacks in a narrow date range,
- the user wants to filter operationally by campaign, shop, gateway, currency, method, status, or metadata,
- AI/MCP needs to locate a Chargeback ID before using `GetChargeback`.

Do not loop through pages to build reports or metrics.

---

## 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 objects 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. |
| `shop_filter` | Filter by one or more User Shop IDs. |
| `gateway_filter` | Filter by one or more User Gateway IDs. |
| `currency_filter` | Filter by ISO 4217 currency code. |
| `method_filter` | Filter by originating transaction method. |
| `status_filter` | Filter by current representment status. |
| `metadata_filter` | Filter by one or more metadata name/value pairs. |
| `customer_id` | Filter to Chargebacks related to a specific Customer ID. |

Example:

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

---

## Output Summary

`GetChargebacks` 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 Chargeback records. |

Each result can include chargeback amount, ARN, case number, chargeback date, campaign, customer, gateway, gateway transaction ID, third-party integration flag, currency, merchant account ID, metadata, origin API call, and related item arrays.

---

## Customer-Facing AI Verification Warning

`GetChargebacks` may return sensitive chargeback records across multiple customers.

If this operation is used inside a customer-facing AI flow, such as an AI Voice Agent, public chatbot, customer portal assistant, SMS assistant, support chatbot, or other visitor-facing AI workflow, AI/MCP should verify that the visitor is actually related to the selected Chargeback before providing information, details, or taking action.

Recommended rule:

```text
Do not provide Chargeback details to a public-facing visitor based only on visitor-provided filters, lookup input, or list results.
```

Even if the visitor provides a customer name, email, date range, case number, gateway transaction ID, card last 4, or metadata value, that alone should not be treated as authorization.

Safe customer-facing flow:

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

Use a secondary value from the retrieved Chargeback record, such as customer email or phone.


---

## Critical Reporting Rule

This Chargeback 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,
- chargeback rate reports,
- chargeback volume reports,
- chargeback amount reports,
- representment/win-loss reports,
- campaign/shop/gateway/customer chargeback analytics,
- method/status breakdown reports,
- card BIN or last-4 analysis.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If AI/MCP 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 AI/MCP almost used the wrong operation. The correct behavior is to quietly choose the correct operation.



---

## Built-In Usage Warning

`GetChargebacks` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve one known Chargeback | `GetChargeback` |
| Retrieve a bounded operational list | `GetChargebacks` |
| Search by term | `SearchChargebacks` |
| Count Chargebacks | `BigQueryRunQuery` |
| Calculate chargeback rate | `BigQueryRunQuery` |
| Report by campaign/shop/gateway/status/method | `BigQueryRunQuery` |
| Analyze representment outcomes | `BigQueryRunQuery` |
| Bulk export-style retrieval | Bulk export utility guidance or appropriate export workflow. |

---

## Example: Correct Operational Use

```text
User: Show recent Chargebacks for this customer over the last 7 days.
```

Correct:

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

---

## Example: Incorrect Reporting Use

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

Incorrect:

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

Correct:

```text
Use BigQueryRunQuery.
```

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

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` within schema limits.
4. Use `GetChargeback` for detail review after selecting a Chargeback.
5. Do not loop through pages to build metrics.
6. Do not use this operation for reporting or data mining.
7. Verify customer identity before sharing Chargeback details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetChargebacks` only for bounded operational retrieval of Chargebacks.

In customer-facing AI flows, verify the visitor is related to the selected Chargeback 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.