# RevCent Trial Overview for AI/MCP

AI/MCP-focused overview for Trials in RevCent.

This document explains what Trials are, how they are created from Product-level settings, how RevCent automatically expires trials, what happens at trial expiration, how trial-related operations should be used, and how Trials connect to Sales, Products, Subscriptions, Shipping, Tax, Salvage Transactions, AI Assistants, AI Voice Agents, Email Templates, and reporting.

---

## Core Concept

A Trial is a RevCent commerce record representing a customer’s trial period for a Product.

A Trial is created when a customer purchases or starts a Product that is configured with Trial settings at the Product level.

Simple model:

```text
Product trial settings define trial behavior
    ↓
Customer purchases/starts the trial Product
    ↓
RevCent creates a Trial record
    ↓
Trial remains active until its end date
    ↓
RevCent automatically expires the Trial
    ↓
At expiration, RevCent attempts the trial expiration payment where applicable
```

A Trial can be connected to:

- customer,
- campaign,
- Sale,
- Product Sale,
- Product,
- payment type,
- third-party shop,
- shipping,
- tax,
- transactions,
- PayPal transactions,
- Offline Payments,
- subscription/subscription profile where applicable,
- salvage transactions,
- discounts,
- pending refunds,
- chargebacks,
- fraud detections,
- AI threads,
- AI Assistants,
- API calls,
- metadata.

Trials are important because they let ecommerce businesses offer low-friction trial offers while RevCent handles the later expiration billing and related lifecycle events automatically.

---

## Related Operation Links

| Operation / Overview | Link | Purpose |
|---|---|---|
| Product Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md` | Explains Product-level configuration, including Trial settings. |
| CreateProduct | `https://revcent.com/documentation/markdown/mcp/operation/CreateProduct.md` | Creates Products and defines trial behavior through Product fields. |
| EditProduct | `https://revcent.com/documentation/markdown/mcp/operation/EditProduct.md` | Edits Product-level trial settings. |
| GetProduct | `https://revcent.com/documentation/markdown/mcp/operation/GetProduct.md` | Retrieves Product configuration, including trial settings. |
| GetTrials | `https://revcent.com/documentation/markdown/mcp/operation/GetTrials.md` | Retrieves a bounded operational list of Trials. Not for reporting/metrics. |
| GetTrial | `https://revcent.com/documentation/markdown/mcp/operation/GetTrial.md` | Retrieves one Trial by Trial ID. |
| SearchTrials | `https://revcent.com/documentation/markdown/mcp/operation/SearchTrials.md` | Searches Trials when the Trial ID is unknown. |
| CancelTrial | `https://revcent.com/documentation/markdown/mcp/operation/CancelTrial.md` | Cancels a Trial by Trial ID and cancels any associated Subscription. |
| ShortenTrial | `https://revcent.com/documentation/markdown/mcp/operation/ShortenTrial.md` | Shortens an active Trial by a specified number of days. |
| ExtendTrial | `https://revcent.com/documentation/markdown/mcp/operation/ExtendTrial.md` | Extends an active Trial by a specified number of days. |
| ExpireTrial | `https://revcent.com/documentation/markdown/mcp/operation/ExpireTrial.md` | Manually expires a Trial immediately before its official expiration date. Use only when intentional. |
| Sales Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` | Initial Sales can create Trial records when trial Products are purchased. |
| Product Sales Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProductSale.md` | Product Sales represent line items that can create or relate to Trials. |
| Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` | Trial products may be related to Subscriptions and future recurring lifecycle. |
| Subscription Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionProfile.md` | Subscription Profiles define recurring billing behavior where trial/subscription products are used. |
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` | Shippable trial Products may create shipments at trial creation and/or expiration depending on Product settings. |
| Shipping Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShippingProfile.md` | Trial expiration payments for shippable products may need Shipping Profiles to calculate shipping. |
| Tax Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTax.md` | Trial Expiration payments can calculate tax using Tax Profiles. |
| Salvage Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSalvageTransaction.md` | Declined trial expiration payments can create salvage transactions. |
| Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTransaction.md` | Credit card trial creation/expiration attempts can create Transactions. |
| Email Template Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md` | Trial-related emails can notify customers before/after trial expiration. |
| AI Assistant Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md` | AI Assistants can monitor trial events, recover failed expiration payments, and support lifecycle workflows. |
| AI Voice Agent Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md` | AI Voice Agents can support inbound trial questions and outbound recovery/retention calls. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct method for trial reporting, metrics, aggregation, and data mining. |

---

## How Trials Are Created

Trials are created from Product-level configuration.

When a Product is configured as a trial Product and is purchased/started by a customer, RevCent creates the related Trial record.

Typical flow:

```text
Product has trial settings
    ↓
Customer starts or purchases the trial Product
    ↓
Initial Sale / Product Sale is created
    ↓
RevCent creates a Trial record
    ↓
Trial is active until its configured end date
```

The Trial record stores trial lifecycle information such as:

- trial amount,
- customer,
- active state,
- total trial days,
- days remaining,
- start date,
- end date,
- expired date,
- payment type,
- related Sale/Product Sale,
- related Subscription where applicable,
- related payment, shipping, tax, and salvage records.

AI/MCP should treat a Trial as a purchased/started instance of a Product’s trial behavior, not as the Product configuration itself.

---

## Product-Level Trial Settings

Trial settings are defined on the Product.

The Product overview identifies these Product-level trial fields:

```text
trial_days
price_trial
trial_shipping_setting
```

A trial Product should be configured intentionally before it is enabled or sold.

---

## `trial_days`

`trial_days` defines how long the Trial lasts.

Example:

```json
{
  "trial_days": 14
}
```

If a customer starts this trial on June 1, a 14-day trial would be expected to expire after the configured trial period.

Trial records then expose lifecycle fields such as:

```text
days_total
days_remaining
start_date_unix
end_date_unix
expired_date_unix
active
```

---

## `price_trial`

`price_trial` defines the Trial expiration price.

The Product overview states:

```text
price_trial = Trial expiration price.
```

It defaults to the Product price when not set.

Use `price_trial` when the amount charged at trial expiration should be different from the initial Product price.

Example:

```json
{
  "price": 4.95,
  "price_trial": 49.95
}
```

Conceptual interpretation:

```text
Initial trial offer price = Product price
Trial expiration price = price_trial
```

AI/MCP should confirm both the initial Product price and the trial expiration price when creating or editing a trial Product.

---

## `trial_shipping_setting`

`trial_shipping_setting` defines when shipping is tied to a trial Product.

Allowed values:

```text
trial_expiration
trial_creation
both_trial_expiration_creation
```

Default:

```text
trial_expiration
```

Meanings:

| Value | Meaning |
|---|---|
| `trial_expiration` | Shipping is tied to trial expiration. |
| `trial_creation` | Shipping is tied to trial creation. |
| `both_trial_expiration_creation` | Shipping can apply to both trial creation and trial expiration. |

This matters for shippable trial Products.

Example:

```json
{
  "trial_days": 14,
  "price_trial": 49.95,
  "trial_shipping_setting": "trial_expiration"
}
```

If the Product is shippable, AI/MCP should also verify:

- `is_shippable`,
- `shipping_attributes`,
- fulfillment account,
- shipping profile/rate behavior for trial expiration,
- whether shipment should occur at trial creation, trial expiration, or both.

---

## Trial Product Setup Checklist

Before creating or editing a trial Product, AI/MCP should confirm:

- Product name,
- SKU,
- initial Product price,
- `trial_days`,
- `price_trial`,
- `trial_shipping_setting`,
- whether the Product is shippable,
- fulfillment account if shippable,
- shipping profile/rates for expiration where required,
- whether the Product is also a subscription Product,
- subscription profile if subscriptions are involved,
- tax behavior for trial expiration payments,
- Email Template notifications,
- AI Assistant / AI Voice Agent recovery or support workflows,
- whether the Product comes from a third-party shop such as WooCommerce,
- whether the Product should be enabled immediately or remain disabled until setup is complete.

Do not enable a trial Product until the trial amount, expiration behavior, shipping behavior, and fulfillment requirements are understood.

---

## How RevCent Automatically Expires Trials

RevCent automatically handles Trial expiration.

AI/MCP should not create external polling systems to manually expire trials.

Conceptual flow:

```text
Trial is created
    ↓
Trial remains active
    ↓
Trial end date arrives
    ↓
RevCent automatically expires the Trial
    ↓
Trial becomes inactive/expired
    ↓
RevCent processes the trial expiration payment where applicable
    ↓
Related records may be created:
        Transaction / PayPal Transaction / Offline Payment
        Subscription / Subscription Renewal where applicable
        Shipping
        Tax
        Salvage Transaction if declined or partially declined
        Email / AI / Voice / Function events
```

Trial records expose the lifecycle fields needed to inspect this state:

| Field | Meaning |
|---|---|
| `active` | Whether the Trial is still active and not yet expired. |
| `days_total` | Trial lifespan in days. |
| `days_remaining` | Number of days remaining until expiration. |
| `start_date_unix` | When the Trial started. |
| `end_date_unix` | When the Trial is scheduled to end. |
| `expired_date_unix` | When the Trial expired, if expired. |

---


## Manual Trial Timing Operations

RevCent includes operations to manually adjust Trial timing.

These operations are for intentional operational changes, not normal trial lifecycle management.

| Operation | Purpose |
|---|---|
| `ShortenTrial` | Shortens a Trial by a specified number of days. |
| `ExtendTrial` | Extends a Trial by a specified number of days. |
| `ExpireTrial` | Expires a Trial immediately before its official expiration date. |

Best practice:

```text
Let RevCent automatically expire Trials on their configured expiration date.
```

Use manual timing operations only when there is a clear business reason.

---

## ShortenTrial

Use:

```text
ShortenTrial
```

to shorten a Trial by a specified number of days.

Input schema:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `trial_id` | string | Yes | 20-character Trial ID. |
| `days` | integer | No | Number of days to shorten the Trial period by. |

Example:

```json
{
  "trial_id": "TTTTTTTTTTTTTTTTTTTT",
  "days": 3
}
```

Use `ShortenTrial` when:

- support intentionally shortens a customer Trial,
- a Trial was created with too many days,
- a customer requests earlier conversion,
- internal policy requires a shorter Trial period,
- an AI/support workflow has explicit approval to shorten the Trial.

Before using `ShortenTrial`, retrieve the Trial with `GetTrial` and confirm:

- correct Trial ID,
- correct customer,
- current `end_date_unix`,
- current `days_remaining`,
- number of days to shorten,
- whether shortening may cause earlier payment,
- whether customer communication is needed.

Do not shorten Trials casually.

---

## ExtendTrial

Use:

```text
ExtendTrial
```

to extend a Trial by a specified number of days.

Input schema:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `trial_id` | string | Yes | 20-character Trial ID. |
| `days` | integer | No | Number of days to extend the Trial period by. |

Example:

```json
{
  "trial_id": "TTTTTTTTTTTTTTTTTTTT",
  "days": 7
}
```

Use `ExtendTrial` when:

- customer support grants additional trial time,
- shipment delay justifies more time,
- a technical issue prevented the customer from using the Trial,
- a retention workflow offers an extension,
- a business policy permits trial extensions.

Before using `ExtendTrial`, retrieve the Trial with `GetTrial` and confirm:

- correct Trial ID,
- correct customer,
- current `end_date_unix`,
- current `days_remaining`,
- extension length,
- whether related subscription/payment timing should be impacted,
- whether customer notification is needed.

Extending a Trial can delay Trial expiration payment and related lifecycle events.

---

## ExpireTrial

Use:

```text
ExpireTrial
```

to manually expire a Trial immediately.

Input schema:

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

Example:

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

Critical warning:

```text
ExpireTrial is a manual premature-expiration operation.
```

RevCent automatically expires Trials on behalf of the merchant.

The live operation description explains that `ExpireTrial` should be used when the user wishes to expire a Trial before its official expiration date.

Best practice:

```text
Do not manually expire Trials as a normal workflow.
Let RevCent expire Trials automatically on their expiration date.
```

Use `ExpireTrial` only when the user explicitly wants to expire a Trial early and trigger the related expiration behavior/payment now.

---

## ExpireTrial Should Be Used Only for Premature Expiration With Payment

`ExpireTrial` should be treated as a manual method for expiring a Trial early with payment.

Use it only when:

- the business intentionally wants the Trial to expire before its scheduled end date,
- the customer explicitly agrees to end the Trial early and proceed,
- support has a clear reason to manually expire the Trial,
- the user understands the Trial expiration payment may be attempted immediately,
- the user understands related lifecycle events may occur early.

Do not use `ExpireTrial` when:

- the Trial can simply expire naturally,
- the user is only asking when a Trial will expire,
- the user wants to cancel the Trial instead,
- the user wants to extend or shorten the Trial date without immediate expiration,
- the user wants reporting/metrics,
- the user is unsure about payment consequences.

If the user wants to cancel the Trial, use `CancelTrial` after confirmation instead.

If the user wants to change the Trial end date, use `ShortenTrial` or `ExtendTrial`.

If no special action is needed, allow RevCent to expire the Trial automatically.

---

## Manual Timing Operation Safety Workflow

Recommended workflow before `ShortenTrial`, `ExtendTrial`, or `ExpireTrial`:

```text
1. Retrieve the Trial with GetTrial.
2. Verify correct customer and Trial.
3. Review active state, days remaining, start date, end date, and expiration date.
4. Confirm the requested action:
       shorten
       extend
       expire now
5. Explain payment/lifecycle impact where relevant.
6. Require explicit user confirmation.
7. Run the appropriate operation.
8. Retrieve the Trial again with GetTrial to verify.
9. Notify customer/internal team if needed.
```

For customer-facing AI flows, verify the visitor is related to the Trial before discussing details or taking action.


## Trial Expiration Payments

At expiration, RevCent can attempt the trial expiration payment.

Important amount fields on a Trial can include:

| Field | Meaning |
|---|---|
| `amount` | Trial amount. |
| `amount_original_total` | Original calculated total before discounts/refunds. |
| `amount_total` | Current total after refunds/discounts. |
| `amount_gross` | Money actually transacted. |
| `amount_net` | Gross amount minus fees. |
| `amount_fees` | Processor fees. |
| `amount_captured` | Captured but unsettled amount. |
| `amount_settled` | Settled amount. |
| `amount_remaining` | Amount remaining to be processed, including awaiting trial expirations or salvage amounts. |
| `amount_refunded` | Refunded amount, including cancelled trial amounts. |
| `amount_to_salvage` | Salvage transaction amount not yet recovered. |

At trial expiration, the payment can create related records such as:

- credit card Transactions,
- PayPal Transactions,
- Offline Payments,
- Tax records,
- Shipping records,
- Salvage Transactions,
- Pending Refunds,
- Chargebacks,
- Fraud Detections.

---

## Trial Expiration Declines and Salvage Transactions

If a trial expiration payment is declined in full or partially, RevCent can create a Salvage Transaction.

Salvage Transactions help recover lost revenue from failed or partially declined trial expiration payments.

Recommended recovery approach:

```text
Trial expiration payment declines
    ↓
Salvage Transaction is created where applicable
    ↓
AI Assistant reviews the customer, trial, payment attempt, decline reason, and amount
    ↓
Assistant waits X days where appropriate
    ↓
Assistant decides recovery path:
        ProcessSalvageTransaction
        Email Template
        AI Voice Agent
        manual support
        skip unrecoverable decline
```

Do not immediately retry every declined trial expiration payment.

Review decline reason and avoid processing attempts that have little chance of success, such as invalid/stolen card or fraud-related decline reasons.

---

## Trials and Subscriptions

Trials may be related to subscription behavior.

A trial Product can be part of a subscription lifecycle where the customer begins with a trial and later transitions into a paid billing cycle.

Trial records can include related Subscription IDs and Subscription Renewal IDs.

AI/MCP should retrieve related records when needed:

```text
GetTrial
    ↓
subscriptions[]
    ↓
GetSubscription
```

or:

```text
GetTrial
    ↓
subscription_renewals[]
    ↓
GetSubscriptionRenewal
```

If a Trial is cancelled through `CancelTrial`, the operation description states that any subscription associated with the trial is also cancelled.

This is a consequential lifecycle action and should require explicit user confirmation.

---

## Trials and Shipping

Shippable trial Products need careful shipping configuration.

Product-level `trial_shipping_setting` controls whether shipping is tied to:

- trial creation,
- trial expiration,
- both trial creation and expiration.

For trial expiration shipments, RevCent needs enough shipping configuration to calculate and create the shipment correctly.

Important for WooCommerce/User Shops:

```text
Initial shop checkout shipping may be determined by WooCommerce/User Shop.
Trial expiration shipping happens later in RevCent and should rely on RevCent shipping configuration.
```

For shippable trial Products, verify:

- Product is marked shippable,
- shipping attributes are present,
- fulfillment account is present,
- shipping profiles/rates exist for trial expiration where needed,
- fulfillment integration is ready,
- shipment email templates are ready.

---

## Trials and Tax

Tax Profiles can apply to Trial Expiration payments.

This is different from an initial WooCommerce/User Shop Sale where the external shop may supply checkout tax.

Correct distinction:

```text
Initial WooCommerce/User Shop Sale tax:
    use external shop/storefront tax when supplied

Trial Expiration payment:
    use RevCent Tax Profiles when RevCent must calculate tax
```

Trial expiration happens later inside RevCent, not inside the original WooCommerce checkout session.

AI/MCP should verify Tax Profile setup for trial expiration payments when tax calculation is required.

---

## Trials and Third-Party Shops / WooCommerce

A WooCommerce/User Shop can sell or originate products that have trial behavior in RevCent.

Correct model:

```text
WooCommerce/User Shop = storefront
RevCent = backend commerce engine for trial lifecycle
```

The shop can originate the initial Sale, but RevCent owns the trial lifecycle after creation:

- Trial record,
- expiration timing,
- expiration payment,
- related shipping where applicable,
- tax calculation where applicable,
- failed expiration recovery,
- salvage transactions,
- subscription lifecycle where applicable,
- reporting.

WooCommerce should not be the system responsible for trial expiration billing when RevCent is managing the backend lifecycle.

---

## Trial Email Templates

Email Templates can automate trial communications.

Useful trial email workflows:

| Email Workflow | Purpose |
|---|---|
| Trial started | Confirm trial start and explain expiration terms. |
| Trial ending soon | Notify customer before trial expiration. |
| Trial expired / payment successful | Confirm expiration billing. |
| Trial expiration payment failed | Ask customer to update payment method. |
| Trial cancelled | Confirm cancellation. |
| Trial shipment created | Notify customer about trial-related shipment. |
| Trial shipment delivered | Delivery notification. |
| Internal high-value failed trial alert | Notify support/retention team. |

Best practice:

```text
Use RevCent Email Templates for trial lifecycle messaging because RevCent has the authoritative Trial, payment, customer, shipment, and lifecycle data.
```

---

## AI Assistants for Trials

AI Assistants can automate trial lifecycle workflows.

Useful Trial AI Assistant workflows:

- monitor trial creation,
- notify customer before expiration,
- review failed trial expiration payments,
- analyze decline reasons,
- trigger salvage recovery after a wait period,
- create AI Memos for high-value failed trials,
- notify internal support,
- trigger AI Voice Agents,
- summarize trial lifecycle for support,
- monitor trial shipping issues,
- run scheduled trial performance reports through BigQuery.

Example:

```text
trial expiration payment failed
    ↓
AI Assistant reviews Trial, customer, payment type, amount, and decline reason
    ↓
Assistant checks for salvage transaction
    ↓
Assistant waits X days if appropriate
    ↓
Assistant sends email, triggers voice call, processes salvage, or escalates
```

AI Assistants should use filters and max-runs-per-item to avoid repeated unnecessary actions.

---

## AI Voice Agents for Trials

AI Voice Agents can support both inbound and outbound trial workflows.

Inbound examples:

- customer asks when trial ends,
- customer asks why they were charged after trial,
- customer asks to cancel trial,
- customer asks about trial shipment,
- customer asks to update payment before expiration.

Outbound examples:

- trial expiration payment recovery,
- failed trial payment follow-up,
- high-value trial retention,
- payment update call before expiration,
- cancellation-save call where allowed.

Customer-facing AI warning:

```text
Before giving trial details in a public/customer-facing AI flow, verify the visitor is related to the Trial using a secondary value from the retrieved Trial record, such as customer email or phone.
```

Do not disclose Trial, payment, shipment, or customer details based only on a visitor-provided Trial ID or search term.

---

## GetTrials

Use:

```text
GetTrials
```

to retrieve a bounded operational list of Trials.

Required input fields:

| Field | Purpose |
|---|---|
| `date_start` | Date range start as Unix timestamp in seconds. |
| `date_end` | Date range end as Unix timestamp in seconds. |
| `limit` | Number of records to return. Range 1 to 25. |
| `page` | Pagination page. |

Optional filters include:

| Filter | 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 Trial status. |
| `metadata_filter` | Filter by metadata name/value pairs. |
| `customer_id` | Filter by related Customer ID. |

Use `GetTrials` for operational review only.

Do not use `GetTrials` for reporting, metrics, aggregation, data mining, broad analysis, or bulk export.

Use `BigQueryRunQuery` for those purposes.

---

## GetTrial

Use:

```text
GetTrial
```

to retrieve one Trial by Trial ID.

Required input:

| Field | Purpose |
|---|---|
| `trial_id` | 20-character Trial ID. |

Example:

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

Use `GetTrial` when:

- Trial ID is known,
- support needs exact trial lifecycle state,
- AI needs to inspect a specific Trial,
- customer asks about a Trial,
- cancellation or recovery workflow needs exact context,
- related records must be retrieved.

---

## SearchTrials

Use:

```text
SearchTrials
```

to search previously created Trials using a full-text search term.

Required input:

| Field | Purpose |
|---|---|
| `search_term` | Single search term or phrase. |

Search results can include:

- item type,
- Trial ID,
- created timestamp,
- customer name,
- email,
- phone,
- address,
- status,
- metadata,
- direct RevCent URL,
- highlighted matches,
- search score.

After finding a likely result:

```text
SearchTrials
    ↓
Review candidate result
    ↓
GetTrial
    ↓
Confirm exact Trial before taking action
```

Do not cancel a Trial directly from search results without retrieving and confirming with `GetTrial`.

---

## CancelTrial

Use:

```text
CancelTrial
```

to cancel a Trial by Trial ID.

Important:

```text
CancelTrial also cancels any Subscription associated with the Trial.
```

This is a consequential action.

Before calling `CancelTrial`, AI/MCP should verify:

- correct Trial ID,
- correct customer,
- current Trial status,
- whether the Trial is active or already expired,
- whether a related Subscription exists,
- whether cancelling the related Subscription is intended,
- business/user confirmation,
- whether customer-facing disclosure/verification is required.

Use `CancelTrial` only when the user explicitly wants to cancel the Trial and understands related subscription impact.

---


## ShortenTrial / ExtendTrial / ExpireTrial

RevCent also provides operations for manually adjusting Trial timing.

| Operation | Input | Purpose |
|---|---|---|
| `ShortenTrial` | `trial_id`, `days` | Shorten the Trial period by a specified number of days. |
| `ExtendTrial` | `trial_id`, `days` | Extend the Trial period by a specified number of days. |
| `ExpireTrial` | `trial_id` | Expire the Trial immediately before its official expiration date. |

Important:

```text
ExpireTrial is not the normal trial expiration method.
```

RevCent automatically expires Trials on the configured Trial expiration date.

Use `ExpireTrial` only when the user intentionally wants to expire the Trial early and trigger expiration behavior/payment now.

Best practice:

```text
Let RevCent expire Trials automatically unless there is a specific business reason to expire early.
```

Always use `GetTrial` before and after these operations to verify state and outcome.

## Operational Retrieval vs Reporting

Trial list/search operations are not reporting tools.

Do not use `GetTrials` or `SearchTrials` for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- broad analysis,
- bulk retrieval,
- trial conversion reports,
- trial cancellation rate reports,
- failed expiration reports,
- trial revenue reports,
- retention reports.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If the AI/MCP client planned to use GetTrials or SearchTrials for reporting and then realizes BigQueryRunQuery is correct, it does not need to tell the user.

It should simply use BigQueryRunQuery instead.
```

---

## Trial Reporting With BigQuery

Use BigQuery for reports such as:

- trials created by day/week/month,
- active trials,
- expired trials,
- upcoming expirations,
- trial conversion revenue,
- failed trial expiration payments,
- salvage transactions created from trial expirations,
- trial cancellation rates,
- trial revenue by Product,
- trial revenue by Product Group,
- trial performance by Campaign,
- trial performance by WooCommerce/User Shop,
- trial shipping outcomes,
- trial refund/cancellation metrics,
- trial-to-subscription lifecycle reporting,
- AI Assistant recovery performance,
- AI Voice Agent recovery performance.

Example report ideas:

```text
Trials expiring in the next 7 days
Trial expiration payment success rate
Trial cancellation rate by campaign
Trial salvage recovery by product
Trial revenue by acquisition source
```

Before running production queries, use `GetBigQueryTables` to confirm exact table and column names.

---

## Customer-Facing AI Verification

Trial operations can expose sensitive customer/order/payment information.

If using `GetTrials`, `GetTrial`, or `SearchTrials` inside a customer-facing AI flow, such as:

- AI Voice Agent,
- chatbot,
- customer portal assistant,
- SMS assistant,
- public support assistant,

verify that the visitor is related to the Trial before providing details or taking action.

Recommended flow:

```text
Visitor provides trial/search input
    ↓
AI uses SearchTrials and/or GetTrial
    ↓
AI retrieves Trial record
    ↓
AI verifies a secondary value from the retrieved record
        such as customer email or phone
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Do not disclose Trial details based only on visitor-provided Trial ID, name, email, phone, or metadata value.

For consequential actions such as `CancelTrial`, require explicit confirmation and stronger verification.

---

## Common Trial Workflows

### Trial Creation

```text
Product configured with trial settings
    ↓
Customer starts/purchases trial Product
    ↓
Sale/Product Sale created
    ↓
Trial record created
    ↓
Trial lifecycle begins
```

### Trial Expiration

```text
Trial reaches end date
    ↓
RevCent automatically expires Trial
    ↓
RevCent attempts trial expiration payment where applicable
    ↓
Creates payment, tax, shipping, salvage, subscription, or other related records as needed
```

### Failed Trial Expiration Recovery

```text
Trial expiration payment fails
    ↓
Salvage Transaction created where applicable
    ↓
AI Assistant reviews recoverability
    ↓
Wait period if appropriate
    ↓
Email / AI Voice Agent / ProcessSalvageTransaction / manual support
```

### Trial Cancellation

```text
User asks to cancel Trial
    ↓
GetTrial
    ↓
Verify customer/status/subscription impact
    ↓
Confirm cancellation
    ↓
CancelTrial
```

---


### Manual Trial Timing Change

```text
User requests trial timing change
    ↓
GetTrial
    ↓
Verify customer, current end date, days remaining, and subscription impact
    ↓
Choose correct operation:
        ShortenTrial
        ExtendTrial
        ExpireTrial only for immediate premature expiration with payment
    ↓
Run operation after explicit confirmation
    ↓
GetTrial to verify result
```

Best practice is still to let RevCent expire Trials automatically on the scheduled expiration date unless an early/manual change is explicitly intended.

## Best Practices

1. Configure trial behavior at the Product level before selling the Product.
2. Confirm `trial_days`, `price_trial`, and `trial_shipping_setting`.
3. Keep trial Products disabled until setup is complete.
4. Verify shipping and fulfillment setup for shippable trial Products.
5. Verify Tax Profiles for trial expiration payments when RevCent calculates tax.
6. Let RevCent automatically expire trials; do not build external polling expiration systems.
7. Use AI Assistants and Email Templates to support trial lifecycle notifications.
8. Use salvage workflows for failed trial expiration payments.
9. Review decline reasons before retrying failed trial expiration payments.
10. Use `GetTrial` before cancelling.
11. Remember `CancelTrial` also cancels any associated Subscription.
12. Use BigQuery for reporting and metrics.
13. Use `ShortenTrial` and `ExtendTrial` only for intentional trial timing changes.
14. Use `ExpireTrial` only when the user explicitly wants to expire the Trial early with payment.
15. Let RevCent automatically expire Trials on their scheduled expiration date whenever possible.
16. Verify customer identity in customer-facing AI flows before sharing Trial details.

---

## Common Mistakes to Avoid

Do not:

- use `ExpireTrial` as a normal scheduled-expiration workflow,
- manually expire a Trial when RevCent can automatically expire it on schedule,
- call `ExpireTrial` without understanding that expiration payment/lifecycle behavior may occur immediately,
- use `ExpireTrial` when the user actually wants to cancel, shorten, or extend the Trial,
- create a trial Product without confirming `trial_days`,
- confuse initial Product price with `price_trial`,
- ignore `trial_shipping_setting` for shippable products,
- forget fulfillment setup for shippable trial Products,
- assume WooCommerce handles trial expiration billing when RevCent owns the lifecycle,
- retry failed trial expiration payments without reviewing decline reason,
- immediately process salvage transactions without a wait period and recoverability review,
- use `GetTrials` or `SearchTrials` for reporting/metrics,
- cancel a Trial without understanding related Subscription impact,
- disclose Trial details in public AI flows without verifying the customer.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Explain Trials | Describe Trials as Product-driven lifecycle records created from Product trial settings. |
| Configure trial behavior | Use `CreateProduct` or `EditProduct` with `trial_days`, `price_trial`, and `trial_shipping_setting`. |
| Retrieve one Trial | Use `GetTrial`. |
| Search for a Trial | Use `SearchTrials`, then `GetTrial`. |
| Retrieve recent operational Trials | Use `GetTrials` with date range, limit, page, and filters. |
| Cancel a Trial | Use `GetTrial`, confirm impact, then `CancelTrial`. |
| Shorten a Trial | Use `GetTrial`, confirm intended day reduction, then `ShortenTrial`. |
| Extend a Trial | Use `GetTrial`, confirm extension length, then `ExtendTrial`. |
| Expire a Trial early | Use `GetTrial`, confirm premature expiration/payment impact, then `ExpireTrial`. |
| Let Trial expire normally | Do nothing manually; RevCent automatically expires the Trial on its expiration date. |
| Report on trial metrics | Use `BigQueryRunQuery`. |
| Investigate failed expiration | Retrieve Trial, related payment records, and salvage transaction. |
| Recover failed expiration | Use salvage recovery workflows, AI Assistants, Email Templates, and AI Voice Agents where appropriate. |
| Handle shippable Trial Product | Review Product shipping attributes, fulfillment, Shipping Profiles, and `trial_shipping_setting`. |
| Handle trial tax | Review Tax Profile setup for trial expiration payments. |

---

## Final AI/MCP Instruction

Trials in RevCent are created from Product-level trial settings.

The key Product trial fields are:

```text
trial_days
price_trial
trial_shipping_setting
```

RevCent automatically handles Trial expiration internally. AI/MCP should not build polling systems to expire trials. At expiration, RevCent can process the trial expiration payment, calculate tax, create shipments where applicable, and create salvage transactions if the payment declines in full or partially.

Use `GetTrial` for one Trial, `SearchTrials` when the Trial ID is unknown, `GetTrials` only for bounded operational retrieval, and `CancelTrial` only with explicit confirmation because it also cancels any associated Subscription.

Use `ShortenTrial` and `ExtendTrial` only for intentional trial timing changes. Use `ExpireTrial` only when the user explicitly wants to expire a Trial before its official expiration date with payment/expiration behavior occurring now. Best practice is to let RevCent expire Trials automatically on their scheduled expiration date.

Use `BigQueryRunQuery` for all trial reporting, metrics, aggregation, and data mining.


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