# RevCent MCP Overview: PayPal Disputes

AI/MCP-focused overview of PayPal Disputes in RevCent.

---

## Purpose

This guide explains what PayPal Disputes are in RevCent, how RevCent monitors linked PayPal accounts for new disputes and dispute updates, and how AI/MCP clients should use the `GetPayPalDisputes` and `GetPayPalDispute` operations.

PayPal Disputes are dispute records pulled from PayPal and associated with RevCent commerce data such as PayPal Accounts, Campaigns, Customers, Shops, Sales, PayPal Transactions, Product Sales, Shipping, Subscriptions, Fraud Detections, Chargebacks, and related entities.

---

## Core Concept

A **PayPal Dispute** is a RevCent record representing a dispute that exists in PayPal.

Simple model:

```text
Linked PayPal Account
    ↓
RevCent monitors PayPal API
    ↓
New PayPal dispute or PayPal dispute update is detected
    ↓
RevCent creates/updates PayPal Dispute record
    ↓
AI/MCP can retrieve and review the PayPal Dispute
```

A PayPal Dispute record contains both RevCent context and PayPal context.

RevCent context can include:

```text
Campaign
Customer
PayPal Account
Third-Party Shop
Related Sales
Related PayPal Transactions
Related product/shipping/tax/subscription/fraud/chargeback records
```

PayPal context can include:

```text
PayPal dispute ID
PayPal dispute amount
PayPal dispute reason
PayPal dispute status
PayPal dispute outcome
PayPal dispute messages
Raw PayPal API details response
PayPal created/updated timestamps
```

---

## How RevCent Monitors PayPal Disputes

RevCent PayPal Accounts are linked to PayPal using PayPal API credentials.

The PayPal Account operation details explain that linking a PayPal account allows RevCent to:

```text
pull PayPal transaction data
pull dispute information
process refunds
update shipping tracking information
and more
```

For disputes, this means RevCent monitors linked PayPal accounts directly through the PayPal API for:

```text
new disputes
existing dispute status updates
dispute outcome updates
new dispute messages/details
PayPal-side created/updated timestamps
```

When PayPal returns a new dispute or changed dispute details, RevCent stores that information in a PayPal Dispute record.

Important fields showing PayPal API-originated dispute context include:

```text
paypal_dispute_id
paypal_dispute_created_date_unix
paypal_dispute_updated_date_unix
paypal_status
paypal_reason
paypal_dispute_outcome
paypal_messages
paypal_details_response
```

The `paypal_details_response` field contains the raw stringified JSON response from the PayPal API.

---

## PayPal Account Relationship

A PayPal Dispute is associated with a RevCent PayPal Account.

The PayPal Account object on a dispute can include:

```text
id
name
paypal_account_email
```

Use PayPal Account operations when you need to understand which PayPal account generated or owns the dispute:

```text
GetPayPalAccounts
GetPayPalAccount
```

Important PayPal Account context:

```text
A PayPal Account can be associated with a Campaign.
A PayPal Account can be associated with Third-Party Shop(s).
The associated Campaign applies to PayPal transactions associated with the PayPal Account.
Third-Party Shop association helps RevCent correctly link PayPal transactions from shops to the appropriate PayPal Account.
```

This matters because PayPal Disputes should be interpreted in the context of the PayPal Account, Campaign, Customer, and Shop where applicable.

---

## Campaign, Customer, and Shop Context

PayPal Dispute records can include:

```text
campaign_id
campaign_name
customer
third_party_shop.id
third_party_shop.name
```

Campaign context is important for business/store attribution, reporting, organization visibility, AI Assistant filtering, customer support routing, and risk/dispute trend analysis.

Customer context can include customer ID, email, name, phone, address, enabled/blocked status, and metadata.

Third-Party Shop context is important when PayPal payments/disputes are tied to a specific WooCommerce store or other external shop integration.

AI/MCP should be careful when discussing customer-facing or sensitive dispute information. Do not expose sensitive details unless the user is authorized and the task requires it.

---

## Related RevCent Entities

A PayPal Dispute can return arrays of related RevCent IDs.

These can include:

```text
sales
product_sales
shipping
tax
discounts
trials
subscriptions
subscription_renewals
invoices
transactions
ai_threads
ai_assistants
paypal_transactions
offline_payments
check_directs
salvage_transactions
pending_refunds
chargebacks
fraud_detections
api_calls
```

Use the appropriate Get operation to retrieve details for related IDs.

Examples:

```text
sales → GetSale
product_sales → GetProductSale
shipping → GetShipment
tax → GetTax
trials → GetTrial
subscriptions → GetSubscription
subscription_renewals → GetSubscriptionRenewal
paypal_transactions → GetPayPalTransaction
chargebacks → GetChargeback
fraud_detections → GetFraudDetection
ai_threads → GetAIThread
api_calls → GetAPICall
```

Important:

```text
Do not assume the PayPal Dispute alone contains every detail needed for a support, dispute response, or reporting workflow.
```

Use related IDs to retrieve full context when needed.

---

## Related Operations

| Operation | Purpose |
|---|---|
| `GetPayPalDisputes` | Retrieve a paginated list of PayPal Disputes for review/lookup. Not for reporting/aggregations. |
| `GetPayPalDispute` | Retrieve the details of one PayPal Dispute. |
| `GetPayPalAccounts` | Retrieve linked PayPal Accounts. |
| `GetPayPalAccount` | Retrieve one linked PayPal Account. |
| `GetPayPalTransactions` | Retrieve PayPal Transactions for review/lookup. Not for reporting/aggregations. |
| `GetPayPalTransaction` | Retrieve one PayPal Transaction related to a dispute. |
| `GetSale` | Retrieve Sale context related to the dispute. |
| `GetBigQueryTables` | Inspect BigQuery table schemas for reporting. |
| `BigQueryRunQuery` | Run PayPal Dispute reports/analytics. |

---

# Operation: `GetPayPalDisputes`

## Purpose

```text
Returns a list of PayPal disputes previously created.
```

Use `GetPayPalDisputes` when AI/MCP needs a paginated review/list of disputes in a date range, optionally filtered by Campaign, currency, shop, PayPal Account, PayPal dispute reason/status, or customer.

Important:

```text
Do not use GetPayPalDisputes for counting, aggregations, metrics, data mining, bulk retrieval, or report generation.
```

Use BigQuery for reports.

---

## `GetPayPalDisputes` Input Schema

Required:

```json
{
  "date_start": 1717200000,
  "date_end": 1719791999,
  "limit": 25,
  "page": 1
}
```

Optional filters:

```text
campaign_filter
currency_filter
shop_filter
paypal_account_filter
paypal_dispute_reason_filter
paypal_dispute_status_filter
customer_id
```

Filter notes:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by one or more Campaign IDs. |
| `currency_filter` | Filter by ISO 4217 currency code. |
| `shop_filter` | Filter by one or more User Shop IDs. |
| `paypal_account_filter` | Filter by one or more PayPal Account IDs. |
| `paypal_dispute_reason_filter` | Filter by PayPal dispute reason. |
| `paypal_dispute_status_filter` | Filter by PayPal dispute status. |
| `customer_id` | Filter to disputes related to a specific Customer. |

---

## `GetPayPalDisputes` Output Highlights

Each result can include:

```text
id
paypal_dispute_id
paypal_dispute_amount
paypal_dispute_created_date_unix
paypal_dispute_updated_date_unix
campaign_id
campaign_name
customer
iso_currency
paypal_account
paypal_status
paypal_reason
paypal_dispute_outcome
paypal_details_response
paypal_messages
third_party_shop
related entity ID arrays
created_date_unix
updated_date_unix
```

Use the result `id` as the RevCent `paypal_dispute_id` input for `GetPayPalDispute`.

Important distinction:

```text
id = RevCent 20-character PayPal Dispute ID
paypal_dispute_id = dispute ID generated by PayPal
```

Do not confuse the two.

---

# Operation: `GetPayPalDispute`

## Purpose

```text
Retrieve the details of a specific PayPal dispute.
```

Use `GetPayPalDispute` when AI/MCP needs the full detail for one PayPal Dispute.

---

## `GetPayPalDispute` Input Schema

Required:

```json
{
  "paypal_dispute_id": "PPPPPPPPPPPPPPPPPPPP"
}
```

Important:

```text
The input paypal_dispute_id is the RevCent 20-character PayPal Dispute ID, not the PayPal-generated dispute ID.
```

The PayPal-generated dispute ID appears inside the record as `paypal_dispute_id`, so AI/MCP should clarify which ID is being used.

---

## `GetPayPalDispute` Output Highlights

`GetPayPalDispute` can return:

```text
id
paypal_dispute_id
paypal_dispute_amount
paypal_dispute_created_date_unix
paypal_dispute_updated_date_unix
campaign_id
campaign_name
customer
iso_currency
paypal_account
paypal_status
paypal_reason
paypal_dispute_outcome
paypal_details_response
paypal_messages
third_party_shop
sales
product_sales
shipping
tax
ai_threads
ai_assistants
paypal_transactions
api_calls
created_date_unix
updated_date_unix
```

Use related IDs to retrieve more detail as needed.

---

## PayPal Messages

PayPal Disputes can include `paypal_messages`.

Each message can include:

```text
time_posted
posted_by
content
```

These messages come from the PayPal API and are associated with the dispute.

Use these messages to understand communication or updates related to the dispute, but be careful when exposing message content in customer-facing summaries.

---

## PayPal Raw Details Response

The `paypal_details_response` field contains the raw stringified JSON response from the PayPal API.

Use this field when:

```text
the structured fields are not enough
the user needs PayPal-specific details
a dispute status/reason/outcome needs deeper inspection
a support or operations team needs raw PayPal dispute context
```

Do not overexpose raw JSON to users who only need a summary.

---

## Typical Review Workflow

When a user asks about one PayPal Dispute:

```text
1. Confirm or find the RevCent PayPal Dispute ID.
2. Use GetPayPalDispute.
3. Review PayPal status, reason, amount, outcome, and messages.
4. Review PayPal Account, Campaign, Customer, and Shop context.
5. Review related Sales and PayPal Transactions.
6. Retrieve related Sale/PayPal Transaction details if needed.
7. Summarize the dispute and recommended next review steps.
```

---

## Typical List Workflow

When a user asks to see recent disputes:

```text
1. Determine date range.
2. Use GetPayPalDisputes with date_start/date_end/limit/page.
3. Apply filters if known: Campaign, PayPal Account, Shop, status, reason, currency, or Customer.
4. Present key fields: dispute ID, PayPal dispute ID, amount, currency, status, reason, account, customer, campaign, shop, updated date.
5. Use GetPayPalDispute for any dispute that needs full detail.
```

---

## Reporting and Analytics

Use BigQuery when the user asks for:

```text
counts
totals
grouped reports
trends
percentages
status distributions
reason distributions
campaign comparisons
PayPal account comparisons
shop comparisons
customer dispute frequency
outcome analysis
```

Do not use `GetPayPalDisputes` for reporting, aggregations, metrics, bulk retrieval, or data mining.

Recommended reporting workflow:

```text
1. GetBigQueryTables.
2. Locate the PayPal dispute table and exact field names.
3. Build a BigQuery Standard SQL query.
4. Run BigQueryRunQuery.
5. If a query errors, fix it and run it again.
```

BigQuery table references must use:

```text
`revcent.user.<table_name>`
```

The exact PayPal dispute table name should be confirmed with `GetBigQueryTables`.

Likely conceptual table name:

```text
`revcent.user.paypal_dispute`
```

AI/MCP should confirm the exact table name before running a report.

---

## BigQuery Query Rules

When using `BigQueryRunQuery`:

```text
Use BigQuery Standard SQL.
Surround table references with backticks.
Use project ID revcent.
Use dataset ID user.
Avoid COALESCE.
When using TIMESTAMP_SUB, only use INTERVAL in DAY.
Optimize queries because query runs are limited to 30 seconds.
If a query error occurs, fix the query and run it again.
```

---

## Conceptual BigQuery Report Examples

These are conceptual examples. AI/MCP should confirm table and field names with `GetBigQueryTables` first.

### PayPal Disputes by Status

```sql
SELECT
  paypal_status,
  COUNT(*) AS dispute_count
FROM `revcent.user.paypal_dispute`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY paypal_status
ORDER BY dispute_count DESC
```

### PayPal Disputes by Reason

```sql
SELECT
  paypal_reason,
  COUNT(*) AS dispute_count,
  SUM(paypal_dispute_amount) AS total_dispute_amount
FROM `revcent.user.paypal_dispute`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY paypal_reason
ORDER BY dispute_count DESC
```

### PayPal Disputes by Campaign

```sql
SELECT
  campaign_id,
  campaign_name,
  COUNT(*) AS dispute_count,
  SUM(paypal_dispute_amount) AS total_dispute_amount
FROM `revcent.user.paypal_dispute`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY campaign_id, campaign_name
ORDER BY total_dispute_amount DESC
```

### PayPal Dispute Updates by Day

```sql
SELECT
  DATE(TIMESTAMP_SECONDS(paypal_dispute_updated_date_unix)) AS paypal_update_day,
  COUNT(*) AS updated_dispute_count
FROM `revcent.user.paypal_dispute`
WHERE paypal_dispute_updated_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY paypal_update_day
ORDER BY paypal_update_day DESC
```

---

## Relationship to PayPal Transactions

PayPal Disputes may include related PayPal Transaction IDs.

Use `GetPayPalTransaction` to retrieve the transaction details.

PayPal Transaction details can include:

```text
PayPal transaction ID generated by PayPal
PayPal transaction amount
PayPal transaction date
PayPal Account
Campaign
Customer
Third-Party Shop
Related Sale IDs
Metadata
```

This helps connect the dispute to the original transaction and sale context.

---

## Relationship to Sales

PayPal Disputes may include related Sale IDs.

Use `GetSale` to retrieve the full Sale.

Sale context can help with:

```text
customer/order verification
product details
shipping details
tax/discount details
subscription/trial context
fraud/risk review
support response preparation
PayPal dispute evidence preparation
```

---

## Relationship to AI Threads and AI Assistants

PayPal Disputes can include related:

```text
ai_threads
ai_assistants
```

This means an AI workflow may have acted on or reviewed the dispute.

Use:

```text
GetAIThread
GetAIAssistant
```

when auditing AI activity related to a PayPal Dispute.

---

## Suggested AI/MCP Summary Format

When summarizing one PayPal Dispute:

```text
PayPal Dispute
- RevCent PayPal Dispute ID: [id]
- PayPal Dispute ID: [paypal_dispute_id]
- Status: [paypal_status]
- Reason: [paypal_reason]
- Outcome: [paypal_dispute_outcome]
- Amount: [paypal_dispute_amount] [iso_currency]
- PayPal Account: [name / id / email]
- Campaign: [campaign_name / campaign_id]
- Customer: [customer name/email/id]
- Shop: [third_party_shop name/id]
- PayPal Created: [paypal_dispute_created_date_unix]
- PayPal Updated: [paypal_dispute_updated_date_unix]

Related Records:
- Sales: [ids/count]
- PayPal Transactions: [ids/count]
- Chargebacks/Fraud Detections/Pending Refunds: [ids/count if present]

Messages:
- [summarize PayPal messages if relevant]
```

---

## Human-in-the-Loop Guidance

When a human is actively working with AI/MCP, ask for confirmation before:

```text
summarizing sensitive dispute communications externally
using raw PayPal API details in customer-facing responses
taking action on related Sales, refunds, shipments, fraud detections, or chargebacks
triggering an AI Assistant related to the dispute
sending a customer-facing email about the dispute
```

PayPal Disputes can include sensitive customer/payment/support details. AI/MCP should summarize carefully.

---

## No-Human-in-the-Loop Guidance

For external AI/agent workflows without a human in the loop:

```text
Only inspect or summarize PayPal Disputes when the task payload provides the required dispute ID or precise filters.
```

Do not guess:

```text
which dispute to inspect
which PayPal Account to filter by
which Campaign or Shop applies
whether to take action on related records
whether to expose PayPal messages or raw details
```

If required information is missing, stop safely and return the missing requirements.

---

## Common Mistakes to Avoid

Do not:

- confuse the RevCent PayPal Dispute ID with the PayPal-generated dispute ID,
- use `GetPayPalDisputes` for reporting/analytics,
- ignore PayPal Account, Campaign, Customer, or Shop context,
- assume the dispute record alone contains full Sale/Transaction details,
- expose raw `paypal_details_response` unnecessarily,
- overlook `paypal_messages`,
- assume PayPal status/reason/outcome values are static,
- take refund/fraud/chargeback actions without explicit authorization,
- assume a PayPal Dispute is the same as a credit-card Chargeback.

---

## Best Practices

1. Use `GetPayPalDisputes` for paginated review and lookup.
2. Use `GetPayPalDispute` for full dispute details.
3. Use related IDs to retrieve Sales, PayPal Transactions, and other records when needed.
4. Use `GetPayPalAccount` to understand the linked PayPal account and account context.
5. Use BigQuery for dispute reports, counts, metrics, trends, and grouped analytics.
6. Treat PayPal messages and raw details as sensitive operational data.
7. Preserve Campaign and Shop context in summaries.
8. Be clear whether an ID is the RevCent PayPal Dispute ID or the PayPal-generated dispute ID.
9. Do not take financial or customer-impacting actions without explicit authorization.
10. Remember that RevCent monitors linked PayPal accounts directly through the PayPal API for new disputes and updates.

---

## Final AI/MCP Instruction

PayPal Disputes in RevCent are records created and updated from PayPal dispute data monitored through linked PayPal Accounts and the PayPal API.

Use `GetPayPalDisputes` to retrieve filtered, paginated dispute lists for review. Use `GetPayPalDispute` to inspect one dispute in detail. Use related IDs to retrieve Sale, PayPal Transaction, Customer, Campaign, Shop, AI Thread, Fraud Detection, Chargeback, and other context when needed.

For reports, trends, counts, and aggregations, use `GetBigQueryTables` and `BigQueryRunQuery`, not `GetPayPalDisputes`.


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