# RevCent MCP Operation: `GetOfflinePayments`

This document explains how MCP/AI clients should use the `GetOfflinePayments` operation in RevCent.

`GetOfflinePayments` retrieves a paginated list of offline payments using date range and optional filters.

Before working with offline payments, MCP/AI should read the Offline Payment overview:

https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md

The overview explains what offline payments are, how they work, supported third-party offline payment integrations, third-party payment retrieval, and refund behavior.

Sources:
- RevCent operation schema for `GetOfflinePayments`
- RevCent operation schema for `GetOfflinePayment`
- RevCent operation guidance for `BigQueryRunQuery`
- RevCent Offline Payment Overview: https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md

---

## Operation Summary

`GetOfflinePayments` returns a paginated list of offline payments previously created.

Use this operation when:

```text
The user wants to retrieve a small filtered/paginated list of offline payments.
The user wants recent offline payment records.
The user wants offline payments for a customer.
The user wants offline payments matching a campaign/shop/currency/metadata filter.
The MCP needs to find an offline_payment_id before using GetOfflinePayment.
```

Important:

```text
GetOfflinePayments is prohibited for reporting, metrics, data mining, bulk retrieval, document property search, or aggregations.
Use BigQueryRunQuery instead.
```

The operation description explicitly warns not to use this method for:

```text
Counting
Aggregations
Metrics
Data mining
Bulk retrieval
Document property search
```

For those cases, MCP/AI should directly use:

```text
BigQueryRunQuery
```

---

# Required Inputs

| Field | Type | Required | Description |
|---|---:|---:|---|
| `date_start` | integer | Yes | Date range start as Unix timestamp in seconds. |
| `date_end` | integer | Yes | Date range end as Unix timestamp in seconds. |
| `limit` | integer | Yes | Number of objects to return. Range: 1 to 25. Default: 25. |
| `page` | integer | Yes | Page number for pagination. |

Example request:

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1
}
```

---

# Optional Filters

`GetOfflinePayments` supports optional filters:

| Filter | Type | Description |
|---|---:|---|
| `campaign_filter` | array<string> | Filter by one or more campaign IDs. |
| `currency_filter` | array<string> | Filter by one or more ISO 4217 currency codes. |
| `shop_filter` | array<string> | Filter by one or more user shop IDs. |
| `metadata_filter` | array<object> | Filter by one or more metadata name/value pairs. |
| `customer_id` | string | Filter to offline payments related to a specific customer ID. |

Example with filters:

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1,
  "customer_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata_filter": [
    {
      "name": "payment_provider",
      "value": "klarna"
    }
  ]
}
```

---

# What the Response Contains

The response contains pagination information and a `results` array.

Each result can include fields such as:

```text
id
created_date_unix
updated_date_unix
amount
status
campaign_id
campaign_name
customer
third_party_integration
third_party_shop
metadata
```

Offline payment results can also expose related item IDs, such as:

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

Use `GetOfflinePayment` for a full detail view of a specific offline payment when deeper inspection is needed.

---

# Use the Overview First

MCP/AI should read the Offline Payment overview before making business decisions about offline payments:

https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md

The overview explains:

```text
What offline payments are.
How offline payments differ from credit-card transactions.
How third-party payment providers are connected.
Supported offline payment integrations.
How RevCent retrieves third-party payment details.
How refunds work through associated entities.
How offline payments can be analyzed with BigQuery.
```

---

# Reporting / Metrics / Data Mining Prohibition

Do not use `GetOfflinePayments` for:

```text
How many offline payments?
How much revenue from Klarna?
Average offline payment amount.
Offline payments by campaign.
Offline payments by shop.
Offline payments by provider.
Offline payments by customer segment.
Offline payment volume over time.
Bulk export-like retrieval.
Document property search.
Data mining.
```

Use:

```text
BigQueryRunQuery
```

for those use cases.

Reason:

```text
GetOfflinePayments is a paginated retrieval operation.
BigQueryRunQuery is the correct operation for counts, sums, grouping, metrics, reports, analytics, and data mining.
```

---

# BigQuery Examples of Correct Use

User asks:

```text
How much revenue came from Klarna this month?
```

Do not page through `GetOfflinePayments`.

Use:

```text
BigQueryRunQuery
```

User asks:

```text
Show offline payment totals by provider.
```

Use:

```text
BigQueryRunQuery
```

User asks:

```text
Which campaign has the most Sezzle offline payments?
```

Use:

```text
BigQueryRunQuery
```

Before writing SQL, use:

```text
GetBigQueryTables
```

to confirm the offline payment table name and field schema.

---

# Offline Payment Provider Context

Offline payments can be associated with third-party payment integrations.

Examples include:

```text
Affirm
Afterpay
Amazon Pay
Klarna
Sezzle
```

The result may include:

```text
third_party_integration
third_party_shop
metadata
```

These fields can help identify:

```text
Which provider powered the payment.
Which user integration/account was used.
Which third-party shop originated the payment.
Which external references or custom metadata apply.
```

---

# Filtering by Metadata

`metadata_filter` can be useful for retrieving small slices of offline payment records.

Examples:

```text
payment_provider = klarna
external_order_id = shop_12345
checkout_page = version_b
bnpl_plan = pay_in_4
```

Use `metadata_filter` when the user needs a paginated list of matching records.

Use `BigQueryRunQuery` when the user needs counts, sums, grouping, or analytics by metadata.

---

# Filtering by Customer

Use `customer_id` when the user asks for offline payments related to one customer.

Example:

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1,
  "customer_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

For complete customer context, MCP/AI may also retrieve the customer or related sales/subscriptions.

---

---

# Offline Payments Are Not Compatible With Subscription Billing

Offline payments should not be used as the payment method for subscription billing.

Important:

```text
Subscriptions and subscription billing are not compatible with offline payments.
Only credit card sales/payments are subscription capable in RevCent.
```

This means MCP/AI should not recommend or attempt to configure an offline payment method as the billing source for a recurring subscription, subscription renewal, or trial expiration billing flow.

Offline payments are useful for:

```text
One-time alternate payment records.
Third-party payment sources such as Affirm, Afterpay, Amazon Pay, Klarna, and Sezzle.
Manual or external payment flows.
Third-party shop payment context.
Customer/order/payment visibility.
Offline payment retrieval, support, reconciliation, and reporting.
```

But subscription billing requires credit card payment capability.

---

## How to Interpret Subscription-Related IDs

Offline payment schemas may expose related arrays such as:

```text
subscriptions
subscription_renewals
```

These relationships should not be interpreted to mean that offline payments are a valid recurring billing method.

They may provide relationship/context visibility, but they do not make offline payments subscription-capable.

MCP/AI should explain this clearly when a user asks whether Klarna, Affirm, Sezzle, Afterpay, Amazon Pay, or another offline payment source can be used for subscription renewals.

Correct guidance:

```text
Offline payments can represent alternate/third-party payment sources.
Credit card payments are required for subscription-capable billing.
```

# Refunding Offline Payments

Important:

```text
Do not refund offline payments by trying to refund the offline payment object itself.
```

If the user wants to refund an offline payment, first identify the entity the offline payment is associated with.

Relevant operations include:

```text
VoidSale
RefundProductSale
RefundTax
RefundShipment
```

Examples:

```text
Refund or void the associated sale with VoidSale when appropriate.
Refund a specific associated product sale with RefundProductSale.
Refund associated tax with RefundTax.
Refund associated shipping with RefundShipment. Provide shipping_id; optionally provide amount for a partial shipment refund.
```

Use the related arrays returned by `GetOfflinePayments` or `GetOfflinePayment`:

```text
sales
product_sales
tax
shipping
```

The correct refund target depends on what the user wants refunded.

---

# Recommended Refund Workflow From a List Result

When the user identifies an offline payment from a list and wants a refund:

```text
1. Use GetOfflinePayments only to locate the relevant offline payment record.
2. Take the offline payment ID.
3. Call GetOfflinePayment for detailed context.
4. Review related sales/product_sales/tax/shipping IDs.
5. Retrieve the associated entity details if needed.
6. Use the correct associated entity refund operation:
   - VoidSale
   - RefundProductSale
   - RefundTax
   - RefundShipment
7. Do not try to refund the offline payment record directly.
```


---

# Why Associated-Entity Refunds Matter

Offline payment records provide payment context, but sale/product/tax/shipping entities represent the actual business objects being refunded.

Refunding through the associated entity helps keep RevCent aligned with:

```text
Sale totals
Product sale totals
Tax totals
Shipping totals
Customer history
Reporting
Third-party provider refund execution
```

For supported third-party offline payment integrations, RevCent can communicate with the provider so the user does not need to log into the third-party provider dashboard separately.

---

# GetOfflinePayments vs GetOfflinePayment

| Goal | Operation |
|---|---|
| Retrieve one known offline payment by ID | `GetOfflinePayment` |
| Retrieve a filtered list/page of offline payments | `GetOfflinePayments` |
| Inspect all related IDs and payment details for one record | `GetOfflinePayment` |
| Locate candidate offline payments by date/customer/campaign/shop/metadata | `GetOfflinePayments` |
| Run analytics or reports | `BigQueryRunQuery` |

---
---

# Customer-Facing AI Verification Warning

Offline payment list results can expose sensitive customer, order, payment, provider, shop, refund, subscription-context, shipment, tax, and lifecycle information across multiple records.

If `GetOfflinePayments` is used inside a customer-facing AI flow, such as:

```text
AI Voice Agent
Public chatbot
Customer portal assistant
SMS assistant
Any visitor-facing AI workflow
```

MCP/AI should verify that the visitor is actually related to the offline payment record before providing information, details, or taking action.

Important:

```text
Do not provide offline payment 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, phone number, provider name, date range, shop/order reference, or metadata value, that alone should not be treated as authorization to disclose offline payment information.

Recommended customer-facing flow:

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

Recommended secondary verification values include:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Date range or recent offline payment request | Customer email from the selected `GetOfflinePayment.customer.email` response. |
| Customer name | Customer email or phone from the selected offline payment. |
| Customer email | Secondary phone, order-related value, or another record-backed verification value where available. |
| Phone number | Customer email from the selected offline payment. |
| Provider name, such as Klarna or Affirm | Customer email or phone from the selected offline payment. |
| Shop/order context | Customer email from the selected offline payment or related Sale. |
| Metadata/external ID | Customer email or phone from the selected offline payment. |

The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original lookup/filter input.

Example:

```text
If a visitor asks about a Klarna payment by providing only a name or order reference, MCP/AI should first locate the offline payment, retrieve the exact record with GetOfflinePayment, and verify the visitor against the customer email returned by that record before providing details.
```

Do not disclose sensitive details such as:

```text
Full customer address
Provider-side/internal payment details
Third-party integration configuration
Unrelated Sale/Product Sale/Subscription/Trial details
Refund workflow details beyond what is appropriate for support
Fraud/risk logic
Internal notes or metadata not meant for customers
Other related records unless the visitor is verified and authorized
```

For consequential actions, such as refunds, sale voids, product refunds, tax refunds, shipment refunds, subscription changes, or customer account changes, require explicit confirmation and use the appropriate operation-specific safety guidance.


# Common Use Cases

## Retrieve Recent Offline Payments

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1
}
```

## Retrieve Offline Payments for a Customer

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1,
  "customer_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

## Retrieve Offline Payments With Metadata

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1,
  "metadata_filter": [
    {
      "name": "payment_provider",
      "value": "sezzle"
    }
  ]
}
```

## Retrieve Offline Payments by Shop

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1,
  "shop_filter": [
    "XXXXXXXXXXXXXXXXXXXX"
  ]
}
```

---

# MCP/AI Decision Guide

Use `GetOfflinePayments` when:

```text
The user wants a small list of offline payment records.
The user provides a date range.
The user wants to find records for one customer.
The user wants to filter by campaign/shop/currency/metadata.
The MCP needs an offline_payment_id before retrieving details.
```

Do not use `GetOfflinePayments` when:

```text
The user asks for totals.
The user asks for counts.
The user asks for metrics.
The user asks for reports.
The user asks for trends.
The user asks for data mining.
The user asks for bulk retrieval.
The user asks for provider/campaign/shop/customer analytics.
```

Use `BigQueryRunQuery` instead.

---

# Validation Checklist

Before calling `GetOfflinePayments`:

1. `date_start` is provided.
2. `date_end` is provided.
3. `limit` is provided and between 1 and 25.
4. `page` is provided.
5. The user is asking for paginated retrieval, not reporting/metrics.
6. If reporting/metrics/data mining is requested, use `BigQueryRunQuery`.
7. Optional filters are properly formatted.
8. If metadata filtering is used, the metadata name/value is exact.
9. If customer filtering is used, `customer_id` is a valid 20-character ID.
10. If refunding is requested, use this operation only to locate the offline payment, then refund the associated entity.
11. If the user asks about subscription billing, explain that offline payments are not subscription compatible; only credit card sales/payments are subscription capable.

---

# Key Takeaways

```text
GetOfflinePayments retrieves a paginated list of offline payments.
```

```text
It requires date_start, date_end, limit, and page.
```

```text
It supports campaign, currency, shop, metadata, and customer filters.
```

```text
It is prohibited for reporting, metrics, aggregations, data mining, bulk retrieval, and document property search.
```

```text
Use BigQueryRunQuery for reports and analytics.
```

```text
To refund an offline payment, refund the associated entity using VoidSale, RefundProductSale, RefundTax, or RefundShipment.
```

```text
Offline payments are not compatible with subscription billing; only credit card sales/payments are subscription capable.
```

```text
MCP/AI should read the Offline Payment overview before working deeply with offline payment workflows:
https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md
```


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