# RevCent MCP Guide: `EditSubscriptionProfile`

AI/MCP-focused guide for editing Subscription Profiles in RevCent.

This document explains the `EditSubscriptionProfile` operation, safe editing rules, billing frequency updates, subscription-specific profile behavior, and the critical distinction between globally used profiles and one-customer custom profiles.

---

## Related Documentation

AI/MCP clients should also read:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionProfile.md
```

```text
https://revcent.com/documentation/markdown/mcp/operation/CreateSubscriptionProfile.md
```

Related context:

| Overview | Link |
|---|---|
| Product Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md` |
| Payment Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPaymentProfile.md` |
| Shipping Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShippingProfile.md` |
| Shop Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShop.md` |
| Email Template Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md` |
| AI Assistant Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md` |
| AI Voice Agent Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md` |

---

## Operation Summary

Operation:

```text
EditSubscriptionProfile
```

Title:

```text
Edit A Subscription Profile
```

Purpose:

```text
Edit a previously created Subscription Profile using the subscription_profile_id.
```

A Subscription Profile controls renewal behavior for subscriptions associated with it.

It can control:

- renewal frequency,
- frequency type,
- occurrence limits,
- overdue/suspension behavior,
- Payment Profile used for renewals,
- optional Shipping Profile override,
- advanced preferred-gateway behavior.

---

## Critical Safety Rule

A globally used Subscription Profile should only ever be modified upon explicit confirmation by the user because changes can affect all subscriptions associated with that profile.

The live operation description states:

```text
Modifying a subscription profile's billing frequency will affect all subscriptions using this profile.
```

This is the most important rule for AI/MCP clients.

Before editing a shared/global Subscription Profile, especially billing frequency, confirm that the user understands:

```text
This change will affect every subscription currently using this Subscription Profile.
```

Do not silently edit a globally used Subscription Profile for a single customer request.

---

## Global Profile vs Subscription-Specific Profile

There are two important profile types:

| Profile Type | Meaning | Safe Editing Rule |
|---|---|---|
| Global / reusable profile | Used by products and potentially many subscriptions. | Edit only with explicit confirmation because changes affect all associated subscriptions. |
| Subscription-specific profile | Created for one existing subscription only. | Editing is appropriate when modifying that one customer's custom renewal cycle. |

A subscription-specific profile exists for one subscription and cannot be used by any other subscription.

A global profile can be used by many products and subscriptions.

---

## If a Customer Wants a Custom Renewal Cycle

If a customer wants a custom renewal cycle, do **not** edit a globally used Subscription Profile.

Instead:

```text
Create a subscription-specific profile for that customer's existing subscription.
```

Correct workflow:

```text
Customer asks for custom renewal cycle
    ↓
Retrieve the customer's Subscription
    ↓
Determine whether current profile is global or subscription-specific
    ↓
If current profile is global:
        CreateSubscriptionProfile with subscription_specific = true
        include subscription_id
    ↓
If current profile is already subscription-specific:
        EditSubscriptionProfile is OK
```

This prevents a single customer's request from changing every other subscription using the same shared profile.

---

## Subscription-Specific Profile Rule

A subscription-specific profile is created with:

```json
{
  "subscription_specific": true,
  "subscription_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Creation behavior:

```text
CreateSubscriptionProfile creates a custom profile
    ↓
RevCent automatically attaches it to the specified existing subscription
    ↓
The subscription no longer uses the inherited product/global Subscription Profile
    ↓
The custom profile controls that one customer's renewal cycle
```

If the subscription already has a custom profile attached, creating another subscription-specific profile will return an error.

In that case:

```text
Use EditSubscriptionProfile on the existing subscription-specific profile.
```

---

## Edit Is OK When Profile Is Already Specific

If the profile is already subscription-specific, editing it is appropriate for that individual customer's custom renewal behavior.

Examples:

- customer wants to move from every 6 weeks to every 8 weeks,
- customer wants monthly renewal changed to every 45 days,
- support approved a custom cadence change,
- VIP customer has a one-off renewal schedule,
- customer-specific custom schedule needs correction.

Still confirm the change with the user, but the impact is limited to the associated subscription.

---

## When to Create Instead of Edit

Create a new Subscription Profile instead of editing an existing one when:

- only one customer needs a custom cycle,
- only future products/subscriptions should use the new frequency,
- existing subscriptions should not change,
- a product launch needs a new billing cadence,
- the current profile may be used by many subscriptions,
- the user is unsure whether existing subscribers should be affected,
- the requested change is for one subscription only.

Use `CreateSubscriptionProfile` with `subscription_specific = true` for one-customer custom renewal cycles.

Use normal `CreateSubscriptionProfile` for new reusable product-level plans.

---

## Required Schema

`EditSubscriptionProfile` input schema:

```text
type: object
additionalProperties: false
required:
  - subscription_profile_id
```

Required field:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `subscription_profile_id` | string | Yes | 20-character Subscription Profile ID to edit. |

Only include the properties that should be modified.

Example: name-only edit

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Monthly Subscription - Main"
}
```

Do not include fields that should not change.

---

## Editable Fields

| Field | Type | Purpose |
|---|---:|---|
| `name` | string | Rename the Subscription Profile. |
| `description` | string | Update description. |
| `enabled` | boolean | Enable or disable the profile. |
| `frequency` | enum | Change frequency type: `unit`, `calendar`, or `fiscal`. |
| `frequency_unit` | object | Required when changing to or editing `unit` frequency. |
| `frequency_calendar` | object | Required when changing to or editing `calendar` frequency. |
| `frequency_fiscal` | object | Required when changing to or editing `fiscal` frequency. |
| `occurrences` | enum | `indefinite` or `specific`. |
| `occurrences_value` | integer | Number of renewals when occurrences is `specific`. |
| `overdue_limit` | integer | Maximum overdue renewals before suspension. |
| `prefer_gateway` | object | Advanced gateway preference behavior. |
| `shipping_profile` | string/null | Optional Shipping Profile override. Use null/empty string to remove. |
| `payment_profile` | string | Payment Profile used for subscription renewals. |

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `subscription_profile_id` | string | 20-character Subscription Profile ID. |
| `result` | string | Result message. |

---

## Frequency Editing Rules

Subscription Profiles support three frequency types:

```text
unit
calendar
fiscal
```

Each frequency type requires a matching frequency object.

| `frequency` | Required Object |
|---|---|
| `unit` | `frequency_unit` |
| `calendar` | `frequency_calendar` |
| `fiscal` | `frequency_fiscal` |

Important:

```text
If modifying frequency, the corresponding frequency settings must be present.
```

If changing frequency from `unit` to `calendar`, include:

```text
frequency = "calendar"
frequency_calendar = { ... }
```

If changing `frequency_unit` settings, the request must include:

```text
frequency = "unit"
```

If `frequency` is missing or is not set to the matching value, frequency settings may be ignored.

---

## Editing `unit` Frequency

Use `frequency = "unit"` when renewals occur every X days/weeks/months/years.

Allowed units:

```text
days
weeks
months
years
```

Example: change to every 45 days

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "unit",
  "frequency_unit": {
    "unit": "days",
    "value": 45
  }
}
```

Example: change to every 6 weeks

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "unit",
  "frequency_unit": {
    "unit": "weeks",
    "value": 6
  }
}
```

Safety warning:

```text
If this profile is globally used, the change affects all subscriptions using it.
```

For one customer, create a subscription-specific profile instead unless the profile is already specific.

---

## Editing `calendar` Frequency

Use `frequency = "calendar"` when renewals should occur on the nth unit of a parent period.

Allowed `frequency_calendar.unit` values:

```text
day
week
month
```

Allowed `frequency_calendar.parent` values:

```text
week
month
year
```

Example: 1st day of every month

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "calendar",
  "frequency_calendar": {
    "unit": "day",
    "value": 1,
    "parent": "month"
  }
}
```

Example: 2nd week of every month

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "calendar",
  "frequency_calendar": {
    "unit": "week",
    "value": 2,
    "parent": "month"
  }
}
```

---

## Editing `fiscal` Frequency

Use `frequency = "fiscal"` when renewals align to fiscal periods.

Allowed `frequency_fiscal.unit` values:

```text
quarter
year
```

Allowed `frequency_fiscal.setting` values:

```text
standard
infrequent
```

Example: standard quarterly

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "fiscal",
  "frequency_fiscal": {
    "unit": "quarter",
    "setting": "standard"
  }
}
```

Example: every 2nd quarter

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "fiscal",
  "frequency_fiscal": {
    "unit": "quarter",
    "setting": "infrequent",
    "value": 2
  }
}
```

---

## Editing Occurrence Rules

Field:

```text
occurrences
```

Allowed values:

```text
indefinite
specific
```

Use `indefinite` when subscriptions continue until cancelled or suspended.

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "occurrences": "indefinite"
}
```

Use `specific` when subscriptions should renew a fixed number of times.

When `occurrences = "specific"`, include:

```text
occurrences_value
```

Example:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "occurrences": "specific",
  "occurrences_value": 6
}
```

Safety warning:

```text
Changing occurrence rules on a global profile affects all subscriptions associated with that profile.
```

---

## Editing Overdue Limit

Field:

```text
overdue_limit
```

The overdue limit controls the maximum number of overdue renewals before automatic suspension.

Example:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "overdue_limit": 3
}
```

Changing this affects failed-renewal recovery behavior.

Business impact:

- lower overdue limit = faster suspension,
- higher overdue limit = more recovery opportunities,
- Email Templates / AI Assistants / AI Voice Agents should align with the overdue policy.

Confirm before editing a shared profile.

---

## Editing Payment Profile

Field:

```text
payment_profile
```

The Payment Profile determines the processing flow for subscription renewals.

Example:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "payment_profile": "PPPPPPPPPPPPPPPPPPPP"
}
```

This can materially affect renewal payment routing.

Do not guess the Payment Profile ID.

Before editing:

- confirm the target Payment Profile,
- confirm it should process renewals for all affected subscriptions,
- confirm whether a new profile is safer than editing a shared profile.

---

## Editing Shipping Profile

Field:

```text
shipping_profile
```

Optional Shipping Profile override.

Important behavior:

```text
If shipping_profile is provided, the first rate listed in the Shipping Profile is used.
No product, Product Group, revenue rule, or country restrictions are taken into account within that Shipping Profile.
```

Use only when the user intentionally wants a specific rate override for all subscriptions using this profile.

Example:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "shipping_profile": "SSSSSSSSSSSSSSSSSSSS"
}
```

To remove the Shipping Profile override, set:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "shipping_profile": null
}
```

or:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "shipping_profile": ""
}
```

If no override is provided, RevCent calculates shipping by finding a match within all Shipping Profiles.

---

## Editing `prefer_gateway`

Field:

```text
prefer_gateway
```

Advanced gateway behavior.

Schema:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "prefer_gateway": {
    "enabled": false,
    "lock_gateway": false,
    "max": 0
  }
}
```

Fields:

| Field | Purpose |
|---|---|
| `enabled` | Whether to force renewal on the last successful transaction gateway. |
| `lock_gateway` | Whether to force renewal only on the originating Sale's successful gateway. |
| `max` | Maximum number of times to use preferred gateway before falling back to the profile's Payment Profile. |

Important schema guidance:

```text
For advanced users. Recommended set to false.
```

Do not enable this casually.

It can limit renewal flexibility and may bypass normal Payment Profile routing during preferred-gateway behavior.

---

## Simple Safe Edits

These are lower-risk when they do not alter renewal behavior, but still require confirmation.

### Rename Profile

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Monthly Subscription - Main Store"
}
```

### Update Description

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Main monthly renewal profile for replenishment products."
}
```

### Disable Profile

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

Even disabling a profile can affect future usage, so confirm first.

---

## High-Risk Edits

These require explicit confirmation and impact review:

- frequency changes,
- occurrence changes,
- overdue limit changes,
- Payment Profile changes,
- Shipping Profile override changes,
- `prefer_gateway` changes,
- disabling a shared profile.

Before making these changes, AI/MCP clients should say the equivalent of:

```text
This Subscription Profile may be used by multiple subscriptions. Changing it can affect all associated subscriptions. Please confirm you want to modify the shared profile rather than creating a new profile or a subscription-specific profile.
```

---

## Required Workflow Before Editing

Recommended workflow:

```text
1. GetSubscriptionProfile.
2. Review whether the profile is subscription_specific.
3. Determine whether the requested change is global or customer-specific.
4. If customer-specific and profile is global:
       Do not edit.
       Create a subscription-specific profile instead.
5. If customer-specific and profile is already subscription-specific:
       EditSubscriptionProfile is acceptable.
6. If global/shared change:
       Get explicit user confirmation.
7. Build request with only intended fields.
8. Call EditSubscriptionProfile.
9. Verify result.
```

---

## Customer Custom Cycle Workflow

If a customer requests a custom renewal cycle:

### Case 1: Current Profile Is Global

Do not edit the global profile.

Correct action:

```text
CreateSubscriptionProfile
subscription_specific = true
subscription_id = target subscription ID
custom frequency settings
```

Example:

```json
{
  "name": "Custom 6 Week Renewal - Subscription SSSSS",
  "description": "Custom subscription-specific renewal cycle requested by customer.",
  "enabled": true,
  "payment_profile": "PPPPPPPPPPPPPPPPPPPP",
  "frequency": "unit",
  "frequency_unit": {
    "unit": "weeks",
    "value": 6
  },
  "occurrences": "indefinite",
  "overdue_limit": 3,
  "subscription_specific": true,
  "subscription_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

This automatically attaches the custom profile to the specified subscription.

### Case 2: Current Profile Is Already Subscription-Specific

Editing is acceptable.

Example:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "unit",
  "frequency_unit": {
    "unit": "weeks",
    "value": 8
  }
}
```

This updates only the subscription-specific profile, which should affect only the associated subscription.

---

## Do Not Edit Global Profiles for One Customer

Wrong:

```text
Customer asks to renew every 6 weeks.
AI edits "Monthly Subscription" shared global profile from every 1 month to every 6 weeks.
```

Result:

```text
Every subscription using Monthly Subscription may now renew every 6 weeks.
```

Correct:

```text
Create a subscription-specific profile for the customer's existing subscription.
```

This is the key safeguard.

---

## How to Identify a Subscription-Specific Profile

Use `GetSubscriptionProfile`.

Look for:

```text
subscription_specific
subscription_id
```

If:

```text
subscription_specific = true
```

then the profile is specific to one subscription.

If:

```text
subscription_specific = false
```

or the field is absent/false-like, treat it as reusable/global unless proven otherwise.

AI/MCP clients should never assume a profile is subscription-specific based on name alone.

---

## When a Subscription Already Has a Custom Profile

If a target subscription already has a custom profile attached, creating another subscription-specific profile can return an error.

Correct action:

```text
Edit the target subscription's existing custom profile.
```

Workflow:

```text
1. GetSubscription.
2. Identify the current Subscription Profile.
3. GetSubscriptionProfile.
4. If subscription_specific = true:
       use EditSubscriptionProfile on that profile.
5. If subscription_specific = false:
       create a new subscription-specific profile.
```

---

## WooCommerce / Third-Party Shop Guidance

For WooCommerce shops:

```text
WooCommerce = storefront
RevCent = subscription billing backend
```

Do not use WordPress/WooCommerce subscription plugins for subscriptions when RevCent is connected.

If a customer bought a subscription product through WooCommerce and wants a custom renewal cycle:

```text
Use RevCent subscription-specific profiles.
Do not change WooCommerce subscription settings.
Do not edit a shared RevCent profile unless the change should affect all associated subscriptions.
```

This keeps subscription billing, renewals, payment recovery, emails, AI workflows, voice workflows, fulfillment, and reporting inside RevCent.

---

## Shippable Subscription Profile Edits

If changing a profile used by shippable subscription products, review:

- Shipping Profile behavior,
- Fulfillment Account setup on products,
- renewal shipping calculation,
- whether initial WooCommerce Sale shipping differs from renewal shipping,
- subscription shipping emails,
- shipment and fulfillment automation.

Changing `shipping_profile` on a shared Subscription Profile can affect shipping rates for all subscriptions using it.

Remember:

```text
If shipping_profile is provided, the first rate listed in that Shipping Profile is used for subscriptions using this profile.
```

---

## Reporting and Impact Analysis

Do not use operational list endpoints for reporting or metrics.

Use:

```text
BigQueryRunQuery
```

for impact analysis and metrics such as:

- subscriptions using a profile,
- renewal success rate by profile,
- active subscriptions by profile,
- failed renewals by profile,
- overdue subscriptions by profile,
- revenue by profile,
- churn by profile,
- shipping impact by profile,
- customer-specific profile usage,
- WooCommerce subscriptions by profile.

Before editing a global profile, BigQuery can help estimate impact.

---

## Pre-Edit Checklist

Before calling `EditSubscriptionProfile`, verify:

- Subscription Profile ID is correct.
- Existing profile was retrieved with `GetSubscriptionProfile`.
- `subscription_specific` status is known.
- User explicitly confirmed the edit.
- If customer requested a custom cycle, global profile is not being edited.
- If customer requested a custom cycle and profile is global, use `CreateSubscriptionProfile` with `subscription_specific = true`.
- If profile is already subscription-specific, edit is acceptable for that customer.
- Only intended fields are included.
- If changing frequency, matching frequency object is included.
- If changing frequency on a shared profile, user explicitly confirmed impact on all associated subscriptions.
- If changing payment profile, renewal processing impact is understood.
- If changing shipping profile, first-rate-only behavior is understood.
- If changing overdue limit, recovery/suspension impact is understood.
- If enabling `prefer_gateway`, advanced routing consequences are understood.

---

## Common Mistakes to Avoid

Do not:

- edit a globally used profile for a single customer's custom cycle,
- assume a profile is specific because its name sounds specific,
- edit frequency without checking `subscription_specific`,
- edit frequency without including the matching frequency object,
- use `frequency_unit` without `frequency = "unit"`,
- use `frequency_calendar` without `frequency = "calendar"`,
- use `frequency_fiscal` without `frequency = "fiscal"`,
- change Payment Profile on a shared profile without confirmation,
- set a Shipping Profile override without explaining first-rate-only behavior,
- enable `prefer_gateway` casually,
- disable a globally used profile without understanding impact,
- use WordPress/WooCommerce subscription settings instead of RevCent,
- use operational endpoints for reporting instead of BigQuery.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Rename a profile | Use `EditSubscriptionProfile` with `name` only. |
| Update description | Use `EditSubscriptionProfile` with `description` only. |
| Change global billing schedule | Retrieve profile, confirm impact, then edit with matching frequency object. |
| One customer wants custom cycle | Do not edit global profile; create subscription-specific profile. |
| Existing profile is already subscription-specific | EditSubscriptionProfile is OK for that customer's custom schedule. |
| Subscription already has custom profile | Edit the existing custom profile instead of creating another. |
| Remove Shipping Profile override | `shipping_profile: null` or `shipping_profile: ""`. |
| Change payment processing for renewals | Edit `payment_profile` only after confirming impact. |
| Estimate number of affected subscriptions | Use `BigQueryRunQuery`. |
| New product needs different renewal cycle | Create a new reusable Subscription Profile. |

---

## Example: Correct Customer Custom Cycle Handling

Customer says:

```text
Can I get my subscription every 6 weeks instead of every month?
```

AI/MCP should not edit the shared monthly profile.

Correct flow:

```text
1. GetSubscription for the customer's subscription.
2. GetSubscriptionProfile for the current profile.
3. If current profile is global:
       CreateSubscriptionProfile with subscription_specific = true.
4. If current profile is already subscription-specific:
       EditSubscriptionProfile.
```

Correct create request for a global-to-specific conversion:

```json
{
  "name": "Custom 6 Week Renewal - Customer Subscription",
  "description": "Customer-specific custom renewal cycle. Renews every 6 weeks.",
  "enabled": true,
  "payment_profile": "PPPPPPPPPPPPPPPPPPPP",
  "frequency": "unit",
  "frequency_unit": {
    "unit": "weeks",
    "value": 6
  },
  "occurrences": "indefinite",
  "overdue_limit": 3,
  "subscription_specific": true,
  "subscription_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Correct edit request if the profile is already subscription-specific:

```json
{
  "subscription_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "frequency": "unit",
  "frequency_unit": {
    "unit": "weeks",
    "value": 6
  }
}
```

---

## Final AI/MCP Instruction

Use `EditSubscriptionProfile` carefully.

A globally used Subscription Profile should only ever be modified with explicit user confirmation because changes can affect every subscription associated with that profile.

If a customer wants a custom renewal cycle, do not edit the global profile. Create a subscription-specific profile for that customer's existing subscription using `CreateSubscriptionProfile` with `subscription_specific = true` and `subscription_id`.

If the profile is already subscription-specific, editing it is OK for that customer's custom cycle.

When editing frequency, always include the matching frequency object: `frequency_unit`, `frequency_calendar`, or `frequency_fiscal`.

Use BigQueryRunQuery for impact analysis and metrics.


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