# RevCent MCP Guide: `GetTrial`

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

---

## Operation Summary

Operation:

```text
GetTrial
```

Purpose:

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

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

Trials are lifecycle records created from Product-level Trial settings such as:

```text
trial_days
price_trial
trial_shipping_setting
```

RevCent automatically expires Trials on their scheduled expiration date.

---

## Related Links

| Guide | Link |
|---|---|
| Trial Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrial.md` |
| GetTrials | `https://revcent.com/documentation/markdown/mcp/operation/GetTrials.md` |
| SearchTrials | `https://revcent.com/documentation/markdown/mcp/operation/SearchTrials.md` |
| CancelTrial | `https://revcent.com/documentation/markdown/mcp/operation/CancelTrial.md` |
| ExpireTrial | `https://revcent.com/documentation/markdown/mcp/operation/ExpireTrial.md` |
| ExtendTrial | `https://revcent.com/documentation/markdown/mcp/operation/ExtendTrial.md` |
| ShortenTrial | `https://revcent.com/documentation/markdown/mcp/operation/ShortenTrial.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetTrial` for one known Trial.

Good uses:

- review one Trial's active/expired state,
- check Trial start/end/expired dates,
- check days total and days remaining,
- inspect Trial amount fields,
- inspect customer context,
- inspect payment type,
- inspect related Sale/Product Sale,
- inspect related Subscription or Subscription Renewal,
- inspect related Transaction, PayPal Transaction, Offline Payment, Shipping, Tax, or Salvage Transaction IDs,
- verify context before `CancelTrial`, `ExpireTrial`, `ExtendTrial`, or `ShortenTrial`.

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `trial_id` | string | 20-character Trial ID. |

Example:

```json
{
  "trial_id": "TTTTTTTTTTTTTTTTTTTT"
}
```

---

## Useful Output Areas

`GetTrial` can return detailed Trial context, including:

| Area | Examples |
|---|---|
| Lifecycle | `active`, `days_total`, `days_remaining`, `start_date_unix`, `end_date_unix`, `expired_date_unix`. |
| Amounts | `amount`, `amount_original_total`, `amount_total`, `amount_gross`, `amount_net`, `amount_fees`, `amount_captured`, `amount_settled`, `amount_remaining`, `amount_refunded`, `amount_to_salvage`. |
| Customer | Customer ID, name, email, phone, address, enabled/blocked state, metadata. |
| 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, Trial, payment, subscription, shipment, tax, 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 Trial before providing details or taking action.

Recommended rule:

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

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

Recommended verification examples:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Trial ID | Customer email from `GetTrial.customer.email`. |
| Customer name | Customer email or phone from the retrieved Trial. |
| Phone number | Customer email from the retrieved Trial. |
| Metadata/external ID | Customer email or phone from the retrieved Trial. |
| Shop/order context | Customer email from the retrieved Trial or related Sale. |

Example safe flow:

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

Do not disclose sensitive details such as:

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

For consequential actions, such as `CancelTrial`, `ExpireTrial`, `ExtendTrial`, or `ShortenTrial`, require stronger confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Trial 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,
- Trial conversion reports,
- Trial cancellation reports,
- Trial expiration reports,
- Trial revenue summaries,
- Trial salvage recovery reports,
- product/campaign/shop 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 Trial ID.” | Use `GetTrial`. |
| “When does this specific Trial expire?” | Use `GetTrial`. |
| “Can I cancel this Trial?” | Use `GetTrial` first, then confirm and use `CancelTrial` if appropriate. |
| “How many Trials expired last month?” | Use `BigQueryRunQuery`, not `GetTrial`. |
| “What is trial conversion rate by campaign?” | Use `BigQueryRunQuery`, not `GetTrial`. |

---

## Best Practices

1. Use this only for one known Trial ID.
2. Use `SearchTrials` when the Trial ID is unknown.
3. Retrieve before `CancelTrial`, `ExpireTrial`, `ExtendTrial`, or `ShortenTrial`.
4. Check related Subscription IDs before cancellation.
5. Remember `CancelTrial` also cancels any associated Subscription.
6. Use `ExpireTrial` only for intentional premature expiration, not normal lifecycle expiration.
7. Verify customer identity before sharing Trial details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all reporting and analytics.

---

## Final AI/MCP Instruction

Use `GetTrial` to retrieve one specific Trial by ID.

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