# RevCent MCP Guide: `GetSale`

Brief AI/MCP-focused guide for retrieving one RevCent Sale.

---

## Operation Summary

Operation:

```text
GetSale
```

Purpose:

```text
Retrieve the details of a specific Sale.
```

A Sale is the top-level commerce record for a customer purchase/order in RevCent.

Use `GetSale` when the exact 20-character Sale ID is known and the user needs to inspect one Sale and its related commerce lifecycle.

---

## Related Links

| Guide | Link |
|---|---|
| Sale Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` |
| GetSales | `https://revcent.com/documentation/markdown/mcp/operation/GetSales.md` |
| SearchSales | `https://revcent.com/documentation/markdown/mcp/operation/SearchSales.md` |
| Product Sale Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProductSale.md` |
| GetProductSale | `https://revcent.com/documentation/markdown/mcp/operation/GetProductSale.md` |
| Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTransaction.md` |
| GetTransaction | `https://revcent.com/documentation/markdown/mcp/operation/GetTransaction.md` |
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` |
| GetShipment | `https://revcent.com/documentation/markdown/mcp/operation/GetShipment.md` |
| Tax Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTax.md` |
| GetTax | `https://revcent.com/documentation/markdown/mcp/operation/GetTax.md` |
| Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` |
| GetSubscription | `https://revcent.com/documentation/markdown/mcp/operation/GetSubscription.md` |
| Trial Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrial.md` |
| GetTrial | `https://revcent.com/documentation/markdown/mcp/operation/GetTrial.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetSale` for one known Sale.

Good uses:

- review one customer order/purchase,
- inspect total, refunded, discounted, captured, settled, remaining, or salvage-related amounts,
- inspect payment attempt status,
- inspect products purchased,
- inspect customer and ship-to context,
- inspect fraud alert or PayPal dispute flags,
- inspect third-party shop/internal order ID context,
- inspect related Product Sales, Transactions, Shipping, Tax, Subscriptions, Trials, and other lifecycle records,
- verify context before void/refund/support actions.

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `sale_id` | string | 20-character Sale ID. |

Example:

```json
{
  "sale_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

---

## Useful Output Areas

`GetSale` can return detailed Sale context, including:

| Area | Examples |
|---|---|
| Amounts | `amount`, `amount_original_total`, `amount_total`, `amount_gross`, `amount_net`, `amount_fees`, `amount_captured`, `amount_settled`, `amount_remaining`, `amount_refunded`, `amount_to_salvage`. |
| Payment attempts | payment attempted/success/declined/fail/held/error flags, attempt count, credit card payment attempts, gateway details. |
| Customer | Customer ID, name, email, phone, address, enabled/blocked state, metadata. |
| Ship-to | Shipping recipient name, email, phone, address, city, state, zip, country. |
| Products | Product details purchased within the Sale, quantity, price, total, SKU, trial/subscription flags, product images. |
| Commerce context | Campaign, currency, payment type, third-party shop, tracking visitor, internal ID. |
| Flags | `cancelled`, `has_fraud_alert`, `has_paypal_dispute`, live/test mode. |
| Related records | Product Sales, Transactions, Shipping, Tax, Discounts, Trials, Subscriptions, Subscription Renewals, Invoices, PayPal Transactions, Offline Payments, Salvage Transactions, Pending Refunds, Chargebacks, Fraud Detections, AI Threads, AI Assistants, API Calls. |
| Metadata/notes | Metadata name/value pairs and notes related to the Sale. |

---

## Related Item Arrays

`GetSale` returns related item arrays. These arrays contain IDs for records related to the Sale.

Use the correct detail operation for each related item type:

| Related Array | ID Type | Detail Operation |
|---|---|---|
| `product_sales` | Product Sale IDs | `GetProductSale` |
| `transactions` | Credit card Transaction IDs | `GetTransaction` |
| `shipping` | Shipment / Shipping IDs | `GetShipment` |
| `tax` | Tax IDs | `GetTax` |
| `subscriptions` | Subscription IDs | `GetSubscription` |
| `trials` | Trial IDs | `GetTrial` |
| `subscription_renewals` | Subscription Renewal IDs | `GetSubscriptionRenewal` |
| `paypal_transactions` | PayPal Transaction IDs | PayPal Transaction get operation where available. |
| `offline_payments` | Offline Payment IDs | Offline Payment get operation where available. |
| `salvage_transactions` | Salvage Transaction IDs | `GetSalvageTransaction` |
| `pending_refunds` | Pending Refund IDs | Pending Refund get operation where available. |
| `chargebacks` | Chargeback IDs | Chargeback get operation where available. |
| `fraud_detections` | Fraud Detection IDs | Fraud Detection get operation where available. |

Important:

```text
Do not assume the Sale response contains full details for every related item.
Use the related IDs with the appropriate get-details operation.
```

---

## Customer-Facing AI Verification Warning

This operation may expose sensitive customer, order, sale, payment, shipping, tax, subscription, trial, refund, fraud, 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 Sale before providing details or taking action.

Recommended rule:

```text
Do not provide Sale details to a public-facing visitor based only on the Sale ID or a value the visitor supplied.
```

Use a secondary value from the retrieved Sale response to verify identity.

Recommended verification examples:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Sale ID | Customer email from `GetSale.customer.email`. |
| Customer name | Customer email or phone from the retrieved Sale. |
| Phone number | Customer email from the retrieved Sale. |
| Order/internal ID | Customer email or phone from the retrieved Sale. |
| Tracking/shop/product context | Customer email from the retrieved Sale or related Shipment. |
| Metadata/external ID | Customer email or phone from the retrieved Sale. |

Example safe flow:

```text
Visitor provides sale/search input
    ↓
AI uses SearchSales and/or GetSale
    ↓
AI retrieves the Sale
    ↓
AI asks the visitor to verify a secondary value from the retrieved record, such as customer email
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

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 provides a Sale ID or order/internal ID, verify against the customer email returned by `GetSale` before discussing the Sale.

Do not disclose sensitive details such as:

- payment details beyond what is appropriate for customer support,
- transaction/gateway internals,
- full shipment address,
- fraud/risk logic,
- unrelated subscription/trial/customer details,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as voiding a Sale, refunding Product Sales, refunding shipping/tax, processing pending recovery, changing subscriptions, or editing shipment information, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Sale 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,
- sales revenue reports,
- conversion reports,
- campaign performance reports,
- shop performance reports,
- product performance reports,
- refund reports,
- payment-attempt reports,
- tax/shipping/subscription/trial lifecycle reports.

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 |
|---|---|
| “Show me this Sale ID.” | Use `GetSale`. |
| “What products were purchased in this Sale?” | Use `GetSale`; use `GetProductSale` for line-item detail if needed. |
| “What shipments are related to this Sale?” | Use `GetSale`, then `GetShipment` for each relevant shipping ID. |
| “Can I refund/void this order?” | Use `GetSale` first, then choose the correct refund/void operation with confirmation. |
| “How much revenue did we make last month?” | Use `BigQueryRunQuery`, not `GetSale`. |
| “Show sales by campaign/shop/product.” | Use `BigQueryRunQuery`, not `GetSale`. |

---

## Best Practices

1. Use this only for one known Sale ID.
2. Use `SearchSales` when the Sale ID is unknown.
3. Use related item arrays to retrieve specific child records.
4. Retrieve and verify Sale context before void/refund/support actions.
5. Prefer item-specific refund operations for clean metrics where applicable.
6. Verify customer identity before sharing Sale details in customer-facing AI flows.
7. Use `BigQueryRunQuery` for all reporting and analytics.

---

## Final AI/MCP Instruction

Use `GetSale` to retrieve one specific Sale by ID.

In customer-facing AI flows, verify the visitor is related to the Sale using a secondary value from the retrieved record, such as `customer.email`, before providing details or taking action.

Do not use this operation for reporting, metrics, counting, aggregation, data mining, or broad analysis. If the task is reporting-related, 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.