# RevCent MCP Guide: `GetSubscription`

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

---

## Operation Summary

Operation:

```text
GetSubscription
```

Purpose:

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

A Subscription is the customer-level recurring billing relationship created when a customer purchases a Product configured for subscription billing.

Simple model:

```text
Subscription = customer's recurring billing relationship
Subscription Profile = renewal schedule/rules
Subscription Renewal = one renewal event or attempt
```

Use `GetSubscription` when the exact 20-character Subscription ID is known and the user needs to inspect one Subscription record.

---

## Related Links

| Guide | Link |
|---|---|
| Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` |
| GetSubscriptions | `https://revcent.com/documentation/markdown/mcp/operation/GetSubscriptions.md` |
| SearchSubscriptions | `https://revcent.com/documentation/markdown/mcp/operation/SearchSubscriptions.md` |
| GetSubscriptionRenewals | `https://revcent.com/documentation/markdown/mcp/operation/GetSubscriptionRenewals.md` |
| GetSubscriptionRenewal | `https://revcent.com/documentation/markdown/mcp/operation/GetSubscriptionRenewal.md` |
| RenewSubscription | `https://revcent.com/documentation/markdown/mcp/operation/RenewSubscription.md` |
| CancelSubscription | `https://revcent.com/documentation/markdown/mcp/operation/CancelSubscription.md` |
| SuspendSubscription | `https://revcent.com/documentation/markdown/mcp/operation/SuspendSubscription.md` |
| ActivateSubscription | `https://revcent.com/documentation/markdown/mcp/operation/ActivateSubscription.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetSubscription` for one known Subscription.

Good uses:

- review one customer's Subscription status,
- inspect active/overdue/suspended/cancelled state,
- review next renewal date and last renewal date,
- inspect Subscription Profile behavior,
- inspect related customer/product/payment context,
- inspect related Subscription Renewals,
- review related Transactions, PayPal Transactions, Offline Payments, Shipping, Tax, Trials, Salvage Transactions, Pending Refunds, Chargebacks, or Fraud Detections,
- verify context before `CancelSubscription`, `SuspendSubscription`, `ActivateSubscription`, `RenewSubscription`, or subscription-specific Subscription Profile changes.

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `subscription_id` | string | 20-character Subscription ID. |

Example:

```json
{
  "subscription_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

---

## Useful Output Areas

`GetSubscription` can return detailed Subscription context, including:

| Area | Examples |
|---|---|
| Lifecycle | Subscription status, active/cancelled/overdue/suspended flags, replacement/occurrence-limit context. |
| Billing | `next_renewal_date_unix`, `last_renewal_date_unix`, `last_renewal_id`, `future_renewal_dates`, overdue count. |
| Subscription Profile | Renewal schedule/rules, payment profile, profile behavior. |
| Customer | Customer ID, name, email, phone, address, enabled/blocked state, metadata. |
| Product | Product ID/name, SKU/internal ID, subscription/trial/shippable context. |
| Commerce context | Campaign, currency, payment type, third-party shop. |
| Related records | Sales, Product Sales, Shipping, Tax, Discounts, Trials, Subscriptions, Subscription Renewals, Invoices, Transactions, PayPal Transactions, Offline Payments, Salvage Transactions, Pending Refunds, Chargebacks, Fraud Detections, AI Threads, AI Assistants, API Calls. |

Use related record IDs to retrieve the full lifecycle when needed.

---

## Customer-Facing AI Verification Warning

This operation may expose sensitive customer, subscription, billing, payment, renewal, shipment, tax, refund, salvage, 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 Subscription before providing details or taking action.

Recommended rule:

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

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

Recommended verification examples:

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

Example safe flow:

```text
Visitor provides subscription/search input
    ↓
AI uses SearchSubscriptions and/or GetSubscription
    ↓
AI retrieves the Subscription
    ↓
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 Subscription ID, verify against the customer email returned by `GetSubscription` before discussing the Subscription.

Do not disclose sensitive details such as:

- payment details,
- unrelated subscription details,
- 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 `CancelSubscription`, `SuspendSubscription`, `ActivateSubscription`, `RenewSubscription`, Subscription Profile changes, or salvage processing, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Subscription 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,
- subscription revenue reports,
- subscription status reports,
- churn reports,
- renewal performance reports,
- overdue subscription reports,
- cancellation/suspension 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.


---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Show me this Subscription ID.” | Use `GetSubscription`. |
| “When does this subscription renew next?” | Use `GetSubscription`. |
| “Can I cancel/suspend/activate this subscription?” | Use `GetSubscription` first, then confirm and use the correct lifecycle operation. |
| “How many active subscriptions do I have?” | Use `BigQueryRunQuery`, not `GetSubscription`. |
| “Show churn rate by campaign.” | Use `BigQueryRunQuery`, not `GetSubscription`. |

---

## Best Practices

1. Use this only for one known Subscription ID.
2. Use `SearchSubscriptions` when the Subscription ID is unknown.
3. Retrieve before lifecycle operations such as cancel, suspend, activate, or manual renewal.
4. Remember `CancelSubscription` is irreversible while `SuspendSubscription` is reversible via `ActivateSubscription`.
5. Do not call `RenewSubscription` unless there is explicit purpose to charge immediately.
6. Inspect related renewal and salvage records for failed renewal support.
7. Verify customer identity before sharing Subscription details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all reporting and analytics.

---

## Final AI/MCP Instruction

Use `GetSubscription` to retrieve one specific Subscription by ID.

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