# RevCent MCP Guide: `GetSubscriptionRenewals`

Brief AI/MCP-focused guide for retrieving a bounded operational list of RevCent Subscription Renewals.

---

## Operation Summary

Operation:

```text
GetSubscriptionRenewals
```

Purpose:

```text
Return a bounded list of previously created Subscription Renewals.
```

A Subscription Renewal is a specific renewal event or renewal attempt generated from a Subscription.

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

Do not use it for reporting or analytics.

---

## Related Links

| Guide | Link |
|---|---|
| Subscription Renewals Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionRenewal.md` |
| Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` |
| GetSubscriptionRenewal | `https://revcent.com/documentation/markdown/mcp/operation/GetSubscriptionRenewal.md` |
| GetSubscription | `https://revcent.com/documentation/markdown/mcp/operation/GetSubscription.md` |
| RefundSubscriptionRenewal | `https://revcent.com/documentation/markdown/mcp/operation/RefundSubscriptionRenewal.md` |
| RenewSubscription | `https://revcent.com/documentation/markdown/mcp/operation/RenewSubscription.md` |
| Salvage Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSalvageTransaction.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetSubscriptionRenewals` only for bounded operational retrieval.

Good uses:

- show recent renewals for a specific customer,
- retrieve renewals in a narrow date window,
- review renewals for a specific campaign/shop/subscription context,
- locate a Subscription Renewal ID before using `GetSubscriptionRenewal`,
- operational support review with a strict date range, page, and limit,
- inspect a short list of renewal attempts before a support or recovery workflow.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields:

| Field | Type | Description |
|---|---:|---|
| `date_start` | integer | Unix timestamp in seconds for start of date range. |
| `date_end` | integer | Unix timestamp in seconds for end of date range. |
| `limit` | integer | Number of records to return. Range 1 to 25. |
| `page` | integer | Pagination page. |

Common optional filters may include:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by Campaign IDs. |
| `currency_filter` | Filter by ISO 4217 currency codes. |
| `shop_filter` | Filter by User Shop IDs. |
| `status_filter` | Filter by renewal status where available. |
| `metadata_filter` | Filter by metadata name/value pairs. |
| `customer_id` | Filter by a specific Customer ID. |

Example:

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

---

## Output Summary

`GetSubscriptionRenewals` 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 Subscription Renewal objects. |

Subscription Renewal result objects can include amount fields, customer context, subscription/product context, payment type, third-party shop, metadata, and related record IDs.

---

## Customer-Facing AI Verification Warning

This operation may return sensitive customer, subscription, payment, renewal, shipment, tax, refund, salvage, or lifecycle context across multiple Subscription Renewals.

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 Subscription Renewal(s) before providing details or taking action.

Recommended rule:

```text
Do not provide Subscription Renewal details to a public-facing visitor based only on visitor-provided filters or lookup input.
```

Even if the visitor provides a customer name, email, subscription ID, date range, phone number, order reference, or other lookup detail, that alone should not be treated as authorization to disclose renewal information.

Safe customer-facing flow:

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

Recommended secondary verification values:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Date range or recent renewal request | Customer email from the retrieved Subscription Renewal. |
| Customer name | Email, phone, or another value already on the retrieved customer record. |
| Customer email | Secondary phone, subscription-related value, or another record-backed verification value where available. |
| Phone number | Customer email from the retrieved Subscription Renewal. |
| Subscription/shop/order context | Customer email or phone from the retrieved Subscription Renewal/Subscription/Sale context. |

Important:

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

For example, if the visitor asks about recent renewals for a name or date range, verify against the customer email returned by `GetSubscriptionRenewal` or the retrieved Subscription Renewal details before discussing a specific renewal.

Do not disclose sensitive details such as:

- payment details,
- subscription details unrelated to the verified visitor,
- shipment details,
- tax details,
- fraud/risk logic,
- unrelated customer records,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as `RefundSubscriptionRenewal`, subscription cancellation/suspension, manual renewal, or salvage processing, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Subscription Renewal lookup 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,
- renewal revenue reports,
- renewal success/failure reports,
- renewal recovery reports,
- salvage recovery reports,
- renewal refund reports,
- campaign/shop/product/subscription performance metrics.

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.


---

## Built-In Usage Warning

`GetSubscriptionRenewals` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent Subscription Renewals | `GetSubscriptionRenewals` |
| Retrieve one known Subscription Renewal | `GetSubscriptionRenewal` |
| Refund one Subscription Renewal | `RefundSubscriptionRenewal` |
| Count renewals | `BigQueryRunQuery` |
| Calculate renewal revenue | `BigQueryRunQuery` |
| Calculate renewal success/failure rate | `BigQueryRunQuery` |
| Report recoveries, refunds, salvage, campaign/shop/product performance | `BigQueryRunQuery` |

---

## Example: Correct Operational Use

```text
User: Show recent Subscription Renewals for customer C over the last 7 days.
```

Correct:

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

---

## Example: Incorrect Reporting Use

```text
User: What was renewal revenue last month by campaign?
```

Incorrect:

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

Correct:

```text
Use BigQueryRunQuery.
```

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

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` small and within schema limits.
4. Use `GetSubscriptionRenewal` for detail review after selecting a renewal.
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 Subscription Renewal details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetSubscriptionRenewals` only for bounded operational retrieval of Subscription Renewals.

In customer-facing AI flows, verify the visitor is related to the returned Subscription Renewal(s) 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.