# RevCent MCP Overview: PayPal Transactions

AI/MCP-focused overview for PayPal Transactions in RevCent.

This document explains how PayPal Transactions relate to PayPal Accounts, how PayPal sales are created in RevCent, how refunds work when a RevCent entity has an associated PayPal Transaction, how WooCommerce integrations work with PayPal Accounts and Transactions, and how RevCent can update PayPal with shipment tracking information.

It is intended for AI agents, MCP clients, and automation tools working with RevCent PayPal-related operations.

---

## Related MCP Operations

### PayPal Account Operations

| Operation | Purpose |
|---|---|
| `GetPayPalAccounts` | List PayPal Accounts connected to RevCent. |
| `CreatePayPalAccount` | Create/connect a PayPal Account in RevCent. Uses secure credential handling. |
| `GetPayPalAccount` | Retrieve a specific PayPal Account. |
| `EditPayPalAccount` | Edit a connected PayPal Account. |
| `DeletePayPalAccount` | Delete a PayPal Account connection. |

### PayPal Transaction Operations

| Operation | Purpose |
|---|---|
| `GetPayPalTransactions` | Retrieve a paginated operational list of PayPal Transactions. Do not use for metrics, aggregation, data mining, or bulk retrieval. |
| `SearchPayPalTransactions` | Search previously created PayPal Transactions using a search term. |

### Related Sale, Refund, Shop, and Analytics Operations

| Operation | Why It Matters |
|---|---|
| `CreateSale` | Creates a Sale with payment. For PayPal, `payment_type` must be `paypal` and `paypal_transaction_id` is required. |
| `GetSale` | Retrieves a Sale and related item IDs, including PayPal Transaction IDs when applicable. |
| `VoidSale` | Voids a Sale in its entirety; if paid, all product sales, shipping, and tax are refunded in full. Use this for full Sale refunds. |
| `GetProductSale` | Retrieves a Product Sale line item related to a Sale. |
| `RefundProductSale` | Refunds a Product Sale. Use this for partial or product-specific PayPal refunds. |
| `GetUserShops` | Lists User Shops, including WooCommerce shops. |
| `CreateUserShop` | Creates a User Shop. WooCommerce requires the RevCent WordPress plugin and credentials. |
| `GetUserShop` | Retrieves User Shop details and remote WooCommerce data such as products, shipping methods, and offline payment methods. |
| `ValidateUserShop` | Validates that the remote shop is configured correctly. |
| `FixUserShop` | Attempts to fix RevCent plugin/settings issues for a User Shop. |
| `BigQueryRunQuery` | Correct operation for PayPal reporting, metrics, aggregation, and business analysis. |

---

## Critical Analytics Rule

Use `BigQueryRunQuery` for **all** PayPal metrics, reporting, aggregation, data-mining, business intelligence, broad record analysis, totals, counts, comparisons, trends, and grouped reporting.

Using `GetPayPalTransactions` for these purposes is **prohibited**.

`GetPayPalTransactions` may only be used for small, bounded, operational lookups, such as inspecting a limited page of recent PayPal Transactions or locating a specific PayPal Transaction before follow-up action.

AI/MCP clients must not loop through pages of `GetPayPalTransactions` to calculate metrics. If the user asks for a metric, report, count, total, ranking, comparison, trend, or analysis, route the request to `BigQueryRunQuery`.

---

## What Is a PayPal Transaction?

A PayPal Transaction in RevCent represents transaction activity from PayPal that is connected into the broader RevCent ecommerce system.

A PayPal Transaction can be associated with:

- A PayPal Account
- A Sale
- Product Sales
- A Customer
- A Campaign
- A third-party shop, such as WooCommerce
- Metadata
- Related refunds or pending refunds
- Shipping records
- Disputes or other related entities when applicable

PayPal Transactions let RevCent connect PayPal payment activity to the same operational, reporting, fulfillment, and analytics model used for credit card payments, offline payments, product sales, shipments, customer records, campaigns, metadata, and BigQuery reporting.

---

## PayPal Transactions Are Associated With PayPal Accounts

Every PayPal Transaction has a PayPal Account association.

In the `GetPayPalTransactions` output, each PayPal Transaction can include a `paypal_account` object containing:

| Field | Meaning |
|---|---|
| `paypal_account.id` | The 20-character PayPal Account ID in RevCent. |
| `paypal_account.name` | The PayPal Account name in RevCent. |
| `paypal_account.paypal_account_email` | The email associated with the PayPal Account. |

This association is important because the PayPal Account is the connection that allows RevCent to communicate with PayPal.

A PayPal Account connection allows RevCent to:

- Pull PayPal transaction data
- Pull PayPal dispute information
- Process PayPal refunds
- Update PayPal transactions with shipment tracking information
- Associate PayPal transactions with campaigns
- Associate PayPal transactions with third-party shops

When an AI/MCP client works with a PayPal Transaction, it should treat the PayPal Account association as critical transaction context.

---

## PayPal Accounts and Why They Matter

A PayPal Account in RevCent links a merchant’s PayPal account to RevCent.

The PayPal Account stores operational settings such as:

| Field | Purpose |
|---|---|
| `name` | Internal name for the PayPal Account. |
| `paypal_account_email` | Email address associated with the PayPal account inside PayPal. |
| `campaign` | Campaign applied to PayPal transactions associated with this account. |
| `third_party_shop` | User Shop IDs associated with this PayPal Account. |
| `transaction_confirmation` | Whether PayPal transaction confirmation is required before marking the Sale paid. |
| `add_tracking` | Whether RevCent should update PayPal Transactions with shipment tracking information. |
| `enabled` | Whether the PayPal Account is active. |

For ecommerce businesses, PayPal Accounts should be configured carefully because they determine how PayPal payments are attributed, linked to shops, refunded, and updated with fulfillment details.

---

## Creating PayPal Sales in RevCent With `CreateSale`

`CreateSale` supports PayPal as a payment type.

When creating a PayPal Sale through RevCent, use:

```json
{
  "payment_type": "paypal",
  "paypal_transaction_id": "PAYPAL_TRANSACTION_ID_FROM_FRONTEND"
}
```

The `CreateSale` schema states:

- `payment_type` indicates the payment type for the Sale.
- If `payment_type` is `paypal`, the `paypal_transaction_id` property is required.
- `paypal_transaction_id` is the ID issued by PayPal for the transaction.
- `CreateSale` also requires `campaign`, `product`, `payment_type`, and `ip_address`.

This means the frontend store or checkout flow should complete the PayPal payment and then pass the PayPal transaction ID to RevCent when creating the Sale.

### Simplified PayPal `CreateSale` Request

```json
{
  "campaign": "XXXXXXXXXXXXXXXXXXXX",
  "iso_currency": "USD",
  "ip_address": "203.0.113.10",
  "payment_type": "paypal",
  "paypal_transaction_id": "PAYPAL_TRANSACTION_ID_FROM_FRONTEND",
  "customer": {
    "first_name": "Jane",
    "last_name": "Customer",
    "email": "jane@example.com"
  },
  "product": [
    {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "quantity": 1
    }
  ],
  "internal_sale_id": "WOOCOMMERCE_ORDER_ID_OR_STORE_ORDER_ID"
}
```

AI/MCP clients must not invent the PayPal transaction ID. The PayPal transaction ID must come from PayPal or from the frontend store checkout result.

---

## Frontend Store PayPal Flow

A common PayPal flow is:

1. Customer checks out on the frontend store.
2. Customer chooses PayPal.
3. PayPal authorizes/captures the payment and returns a PayPal transaction ID.
4. The frontend store sends a `CreateSale` request to RevCent.
5. `CreateSale` uses `payment_type: "paypal"` and the PayPal transaction ID.
6. RevCent creates the Sale and links the PayPal payment into RevCent.
7. RevCent creates or links related entities such as customer, product sales, shipping, metadata, and PayPal Transaction records.
8. If a PayPal Account is correctly connected and associated, RevCent can tie the PayPal Transaction back to the correct PayPal Account.

This lets RevCent treat PayPal purchases as first-class RevCent Sales rather than disconnected external payments.

---

## WooCommerce + RevCent WordPress Plugin Flow

WooCommerce integrations in RevCent work seamlessly with PayPal Accounts and PayPal Transactions when the RevCent WordPress plugin is installed on the WooCommerce site and the shop is created in RevCent.

The recommended flow is:

1. Install the RevCent WordPress plugin on the WooCommerce site.
2. Create the User Shop in RevCent using the WooCommerce site shop type.
3. Provide WooCommerce credentials securely through `CreateSecureForm` as part of User Shop setup.
4. Validate the User Shop with `ValidateUserShop`.
5. If validation returns fixable issues, use `FixUserShop`.
6. Retrieve remote WooCommerce data using `GetUserShop` with `remote_data` options as needed, such as:
   - `shipping_methods`
   - `offline_payment_methods`
   - `products`
7. Map shipping methods and offline payment methods correctly.
8. Create or sync WooCommerce products into RevCent.
9. Associate the relevant User Shop with the appropriate PayPal Account using the PayPal Account `third_party_shop` setting.
10. Ensure the PayPal Account is enabled and configured with `add_tracking: true` when shipping tracking should be sent to PayPal.

Once configured, PayPal purchases from WooCommerce can flow into RevCent with the PayPal transaction ID, shop association, campaign attribution, products, customer data, and related fulfillment/refund data.

---

## PayPal Account `third_party_shop` Association

The PayPal Account `third_party_shop` array is important for frontend store integrations.

It contains one or more User Shop IDs associated with the PayPal Account.

Why this matters:

- It helps RevCent link PayPal transactions from a given shop to the correct PayPal Account.
- It supports multi-store businesses.
- It improves attribution and reporting.
- It helps distinguish PayPal activity across multiple brands, websites, or WooCommerce installs.
- It helps RevCent connect PayPal transaction, sale, product sale, and shipment data correctly.

Best practice:

- Associate a PayPal Account only with the User Shop(s) that actually use that PayPal Account.
- Do not associate every shop by default.
- For WooCommerce, make sure the RevCent WordPress plugin is installed and the User Shop is created, validated, and mapped before relying on seamless PayPal transaction flow.

---

## PayPal Refund Behavior in RevCent

When a refund is issued in RevCent for an entity associated with a PayPal Transaction, RevCent can communicate directly with PayPal to perform the actual refund.

This is possible because the PayPal Transaction is connected to a PayPal Account, and the PayPal Account allows RevCent to process PayPal refunds.

For example:

- A Sale paid by PayPal may have an associated PayPal Transaction.
- Product Sale line items within that Sale may also be related to the PayPal payment context.
- If `RefundProductSale` is used for a Product Sale associated with a PayPal Transaction, RevCent can refund the associated PayPal payment rather than merely recording an internal adjustment.
- If `VoidSale` is used for a paid PayPal Sale, RevCent will fully refund the associated payments for the entire Sale, including product sales, shipping, and tax.

Important distinction:

- A normal RevCent refund attempts to refund through the associated payment path, including PayPal where applicable.
- An offsite-recorded refund, when a refund operation supports `refunded_offsite: true`, records the refund in RevCent without contacting the payment processor.

AI/MCP clients must confirm refund intent before executing any refund operation. Refunds are consequential financial actions.

---

## PayPal Refund Routing: Partial vs Full Refunds

When a PayPal Transaction is associated with a Sale, choose the refund operation based on refund intent.

### Use `RefundProductSale` for Partial PayPal Refunds

Use `RefundProductSale` when the user wants to refund:

- A specific product line item
- Part of a product line item
- A product-specific amount
- One product in a multi-product PayPal Sale
- A damaged item, missing item, customer service credit, or SKU-specific refund

For partial refunds, provide the `amount` field:

```json
{
  "product_sale_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 15.00
}
```

This is the best-practice approach for product-specific partial PayPal refunds because it preserves product-level refund metrics.

### Use `VoidSale` for Full PayPal Sale Refunds

Use `VoidSale` when the user wants to refund the entire PayPal Sale.

`VoidSale` voids a Sale in its entirety. If the Sale is paid, all product sales, shipping, and tax are refunded in full.

Request:

```json
{
  "sale_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

`VoidSale` may return related IDs such as:

- `pending_refund`
- `product_sale_refunded`
- `shipping_refunded`
- `tax_refunded`
- `subscription_cancelled`
- `trial_cancelled`

### Do Not Use Product Sale Refunds for a Full Sale Unless Explicitly Intended

If the user wants a full PayPal Sale refund, do not refund every Product Sale manually unless the user explicitly wants that workflow.

Use `VoidSale` for full Sale refunds because it handles the Sale as a whole and refunds product sales, shipping, and tax in their entirety.

---

## Product Sale-Level Refunds for PayPal Sales

If a PayPal Sale includes multiple products and the user wants to issue a partial refund for a specific product line item, Product Sale-level refunding is often the best practice.

Why:

- It ties the refund to the specific product.
- It improves refund metrics at the product level.
- It improves SKU-level profitability analysis.
- It preserves accurate line-item reporting.
- It makes BigQuery reporting more useful.

Example:

A WooCommerce order paid by PayPal contains three products. One product was damaged and needs a $15 refund. The best path is typically:

1. Identify the Sale.
2. Identify the relevant Product Sale line item.
3. Verify the Product Sale with `GetProductSale`.
4. Use `RefundProductSale` with `amount: 15.00`.
5. RevCent refunds the associated PayPal payment as appropriate.
6. Product-level refund metrics remain accurate.

If the entire PayPal Sale is being fully refunded, use `VoidSale`.

---

## PayPal Shipment Tracking Updates

RevCent can update existing PayPal Transactions in PayPal with shipment tracking information.

This behavior is controlled by the PayPal Account `add_tracking` setting.

When `add_tracking` is `true`:

- RevCent can add shipment tracking information to the respective PayPal Transactions when shipments are shipped.
- This helps keep PayPal transaction records up to date.
- This can improve customer transparency.
- This can support dispute defense by ensuring PayPal has shipment and tracking information.
- This can reduce manual work for ecommerce operators.

Recommended default:

```json
{
  "add_tracking": true
}
```

AI/MCP clients should generally recommend `add_tracking: true` for physical goods businesses.

For digital-only products with no shipments, this setting may not matter, but it is still safe to document as the standard PayPal Account tracking behavior.

---

## `GetPayPalTransactions` Operation

`GetPayPalTransactions` returns a paginated list of PayPal Transactions.

### Critical Usage Rule

Do **not** use `GetPayPalTransactions` for:

- Counting
- Aggregation
- Metrics
- Reporting
- Data mining
- Business intelligence
- Trend analysis
- Ranking
- Comparisons
- Bulk retrieval
- Broad document/property search
- Export-like workflows

For those use cases, `BigQueryRunQuery` is the required operation.

Using `GetPayPalTransactions` for PayPal metrics/reporting/data-mining is prohibited.

`GetPayPalTransactions` is an operational listing endpoint, not an analytics endpoint.

### Required Inputs

| Field | Type | Required | Description |
|---|---:|---:|---|
| `date_start` | integer | Yes | Start date as Unix timestamp in seconds. |
| `date_end` | integer | Yes | End date as Unix timestamp in seconds. |
| `limit` | integer | Yes | Number of records to return. Range 1 to 25. |
| `page` | integer | Yes | Page number for pagination. |

### Optional Filters

| Field | Type | Description |
|---|---:|---|
| `campaign_filter` | array<string> | Filter by one or more Campaign IDs. |
| `currency_filter` | array<string> | Filter by ISO 4217 currency code. |
| `shop_filter` | array<string> | Filter by one or more User Shop IDs. |
| `paypal_account_filter` | array<string> | Filter by one or more PayPal Account IDs. |
| `metadata_filter` | array<object> | Filter by metadata name/value objects. |
| `customer_id` | string | Filter records related to a specific customer. |

### Example

```json
{
  "date_start": 1735689600,
  "date_end": 1738367999,
  "limit": 25,
  "page": 1,
  "paypal_account_filter": ["XXXXXXXXXXXXXXXXXXXX"]
}
```

Use this only for bounded operational review or lookup, not for reporting.

---

## Important PayPal Transaction Fields

PayPal Transaction records can include:

| Field | Meaning |
|---|---|
| `id` | RevCent PayPal Transaction ID. |
| `paypal_transaction_id` | Transaction ID generated by PayPal. |
| `paypal_transaction_amount` | Amount from PayPal. |
| `paypal_transaction_date` | PayPal transaction date in ISO8601 format. |
| `paypal_transaction_date_unix` | PayPal transaction date as Unix timestamp. |
| `paypal_customer_id` | Customer ID generated by PayPal. |
| `paypal_account` | PayPal Account associated with this transaction. |
| `campaign_id` / `campaign_name` | Campaign attribution. |
| `third_party_shop` | Originating User Shop, if applicable. |
| `customer` | Related customer object. |
| `amount_original_total` | Original calculated amount. |
| `amount_total` | Current total after refunds and discounts. |
| `amount_gross` | Money actually transacted after refunded payments. |
| `amount_net` | Gross amount minus fees. |
| `amount_fees` | Processor fee estimate/calculation. |
| `amount_captured` | Captured amount. |
| `amount_settled` | Settled amount. |
| `amount_remaining` | Remaining amount. |
| `amount_refunded` | Current refunded amount. |
| `metadata` | Metadata attached to the PayPal Transaction. |
| `sales` | Related Sale IDs. |
| `product_sales` | Related Product Sale IDs. |
| `shipping` | Related Shipping IDs. |
| `pending_refunds` | Related Pending Refund IDs. |

---

## `SearchPayPalTransactions` Operation

`SearchPayPalTransactions` searches previously created PayPal Transactions using a full-text search term.

Input:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `search_term` | string | Yes | Search term or phrase. |

Use this when the user has a specific PayPal transaction ID, customer email, name, or other searchable value and needs to locate a PayPal Transaction record.

Do not use search for metrics, aggregation, or broad reporting. Use `BigQueryRunQuery` for reporting.

---

## PayPal Transactions and BigQuery

For **all** PayPal metrics, reporting, aggregation, business intelligence, data-mining, trend analysis, counting, grouping, ranking, and broad record analysis, use `BigQueryRunQuery`.

Using `GetPayPalTransactions` for metrics, reporting, aggregation, data-mining, bulk retrieval, or business intelligence is **prohibited**.

`GetPayPalTransactions` is only for small, bounded, operational lookups. It must not be paginated repeatedly to simulate reporting or analytics.

Examples of analytics requests that must use `BigQueryRunQuery`:

- PayPal revenue by campaign
- PayPal refunds by shop
- PayPal transaction count by PayPal Account
- PayPal transaction volume by day
- PayPal net revenue by product
- PayPal disputes by campaign
- PayPal refund rate by product
- PayPal gross versus net by account
- WooCommerce PayPal sales by store
- PayPal transactions with missing shipment tracking
- Product-level PayPal refund analysis
- Any PayPal report grouped by campaign, shop, account, product, customer, metadata, date, or currency
- Any PayPal total, count, average, rate, ranking, or comparison

Do not paginate `GetPayPalTransactions` and aggregate client-side. Use `BigQueryRunQuery` instead.

Before writing BigQuery SQL, use `GetBigQueryTables` if the exact table name or schema is not known.

---

## AI/MCP Workflow: Create a PayPal Account

1. Use `GetPayPalAccounts` to check existing PayPal Accounts.
2. Confirm the correct campaign.
3. Confirm the correct User Shop(s), especially for WooCommerce.
4. Use `CreateSecureForm` for PayPal credentials.
5. Have the user complete the secure form.
6. Call `CreatePayPalAccount`.
7. Set recommended defaults:
   - `enabled: true`
   - `transaction_confirmation: false`
   - `add_tracking: true`
8. Associate only the User Shops that use this PayPal Account.

Do not ask the user to paste PayPal credentials into chat.

---

## AI/MCP Workflow: Create a PayPal Sale From a Frontend Store

1. Frontend store completes PayPal payment.
2. Frontend receives PayPal transaction ID from PayPal.
3. Frontend calls RevCent `CreateSale`.
4. Request includes:
   - `payment_type: "paypal"`
   - `paypal_transaction_id`
   - `campaign`
   - `product`
   - `ip_address`
   - customer/billing/shipping data as available
   - `internal_sale_id` if the store has an order ID
5. RevCent creates the Sale and links PayPal transaction data.
6. Product Sales are created as line items.
7. Shipping and fulfillment data can be created/updated.
8. If PayPal Account `add_tracking` is enabled, RevCent can update PayPal with shipment tracking when shipped.

---

## AI/MCP Workflow: WooCommerce PayPal Integration

1. Verify the RevCent WordPress plugin is installed on the WooCommerce site.
2. Create the WooCommerce User Shop in RevCent.
3. Use secure form credential handling.
4. Run `ValidateUserShop`.
5. Run `FixUserShop` if needed.
6. Retrieve and map:
   - WooCommerce shipping methods
   - WooCommerce offline payment methods
   - WooCommerce products
7. Ensure products are created/synced in RevCent and associated with the User Shop.
8. Create or verify the PayPal Account in RevCent.
9. Associate the WooCommerce User Shop with the PayPal Account.
10. Use `add_tracking: true`.
11. Allow WooCommerce PayPal purchases to create RevCent Sales using PayPal transaction IDs from the frontend/plugin flow.

---

## Best Practices

- Always keep PayPal Accounts associated with the correct User Shop(s).
- Use clear PayPal Account names, such as `Brand A PayPal - WooCommerce`.
- Use `transaction_confirmation: false` unless delayed PayPal confirmation is intentionally required.
- Use `add_tracking: true` for physical product stores.
- Use `CreateSale` with `payment_type: "paypal"` and a real PayPal transaction ID from the frontend checkout.
- Do not invent or guess PayPal transaction IDs.
- Use `RefundProductSale` for product-specific or partial PayPal refunds.
- Use `VoidSale` for full PayPal Sale refunds.
- Use normal RevCent refund operations for actual PayPal refunds.
- Use offsite refund flags only when intentionally recording a refund that happened outside RevCent.
- Use `BigQueryRunQuery` for all PayPal metrics, reporting, aggregation, data-mining, business intelligence, counts, totals, rankings, comparisons, and trend analysis.
- Do not use `GetPayPalTransactions` for aggregation, metrics, reporting, data-mining, business intelligence, bulk retrieval, or broad analysis. This is prohibited.
- For WooCommerce, install and configure the RevCent WordPress plugin before expecting seamless transaction flow.

---

## Common Mistakes to Avoid

Do not:

- Create a PayPal Sale without `paypal_transaction_id`.
- Guess the PayPal transaction ID.
- Associate a PayPal Account with the wrong User Shop.
- Leave `add_tracking` disabled for a physical goods store unless the user explicitly wants that.
- Use `transaction_confirmation: true` without explaining the possible 2 to 4 hour PayPal API confirmation lag.
- Use `GetPayPalTransactions` for revenue reports, refund metrics, counts, totals, aggregation, data-mining, business intelligence, or any broad PayPal analysis.
- Use `RefundProductSale` repeatedly when the user wants a full PayPal Sale refund; use `VoidSale` for full Sale refunds.
- Use `VoidSale` when the user only wants a partial or product-specific PayPal refund; use `RefundProductSale`.
- Attempt PayPal refunds outside the correct RevCent refund workflow if the transaction is already associated in RevCent.
- Ask users to paste PayPal credentials directly into chat.
- Assume WooCommerce PayPal transactions will sync properly before the RevCent WordPress plugin and User Shop are configured.
- Treat PayPal Transactions as isolated records; they are connected to PayPal Accounts, Sales, Product Sales, Customers, Shops, Campaigns, Shipping, Refunds, and reporting.

---

## Quick Reference

| Task | Recommended Operation |
|---|---|
| List connected PayPal Accounts | `GetPayPalAccounts` |
| Create PayPal Account | `CreatePayPalAccount` |
| Retrieve PayPal Account | `GetPayPalAccount` |
| Edit PayPal Account settings | `EditPayPalAccount` |
| Delete PayPal Account | `DeletePayPalAccount` |
| List recent PayPal Transactions for operational lookup | `GetPayPalTransactions` |
| Search for a specific PayPal Transaction | `SearchPayPalTransactions` |
| Create a PayPal Sale | `CreateSale` with `payment_type: "paypal"` and `paypal_transaction_id` |
| Partial/product-specific PayPal refund | `RefundProductSale` |
| Full PayPal Sale refund | `VoidSale` |
| Analyze PayPal revenue/refunds/metrics/reporting/data-mining | `BigQueryRunQuery` only; `GetPayPalTransactions` is prohibited for this |
| Configure WooCommerce shop | `CreateUserShop`, `ValidateUserShop`, `FixUserShop`, `GetUserShop` |
| Update PayPal with shipment tracking | Enabled through PayPal Account `add_tracking: true` and shipment lifecycle |

---

## Final AI/MCP Instruction

PayPal Transactions in RevCent should be understood as PayPal payment records connected to a PayPal Account and integrated into RevCent’s Sale, Product Sale, Customer, Campaign, Shop, Shipping, Refund, and analytics model.

For PayPal sales created from a frontend store, the PayPal transaction ID must come from PayPal/frontend checkout and be passed to `CreateSale` using `payment_type: "paypal"`.

For refunds tied to PayPal Transactions:

- Use `RefundProductSale` for partial or product-specific PayPal refunds.
- Use `VoidSale` for full PayPal Sale refunds.
- Do not issue refunds without explicit user authorization.

For shipment tracking, configure the PayPal Account with `add_tracking: true` so RevCent can update PayPal Transactions with tracking information when shipments are shipped.

For all metrics, reporting, aggregation, data-mining, business intelligence, counts, totals, rankings, comparisons, and trend analysis, use `BigQueryRunQuery`. Using `GetPayPalTransactions` for those purposes is prohibited.


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