# RevCent MCP Guide: `EditTaxProfile`

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

This document explains the `EditTaxProfile` operation, safe partial-edit behavior, campaign filter changes, enabling/disabling a Tax Profile, and the critical requirement that any replacement third-party integration must be a user third-party integration whose underlying site third-party integration is type `tax`.

---

## Related Documentation

AI/MCP clients should also read:

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

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

Related operation guides:

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| Tax Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTax.md` | Explains Tax records, Tax Profiles, User Shop/WooCommerce initial tax source behavior, refunds, reporting, and tax-related ecommerce flows. |
| CreateTaxProfile | `https://revcent.com/documentation/markdown/mcp/operation/CreateTaxProfile.md` | Explains how to create a Tax Profile and how the required tax third-party integration prerequisite works. |
| GetTaxProfile | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTaxProfile.md` | Retrieve the current Tax Profile before editing. |
| GetTaxProfiles | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTaxProfile.md` | Locate Tax Profiles when the Tax Profile ID is unknown. |
| GetUserThirdPartyIntegrations | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegrations.md` | List user third-party integrations and find existing tax integrations. |
| GetUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegrations.md` | Verify the selected user integration, credentials, options, and underlying site integration. |
| GetSiteThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegrations.md` | Inspect the site integration and confirm it is type `tax`. |
| EditUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/EditUserThirdPartyIntegration.md` | Update credentials or required options for a user tax integration before using it on a Tax Profile. |
| GetCampaigns |  | Retrieve Campaign IDs for `campaign_filter`. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct method for tax reporting, metrics, aggregation, and data mining. |

---

## Operation Summary

Operation:

```text
EditTaxProfile
```

Title:

```text
Edit A Tax Profile
```

Purpose:

```text
Edit a previously created Tax Profile using the Tax Profile ID.
```

`EditTaxProfile` is used to modify an existing Tax Profile's:

- name,
- description,
- enabled state,
- campaign filter,
- tax third-party integration.

Important:

```text
Only include the properties you wish to modify.
```

If only changing the name, send only the name.

If only disabling the profile, send only `enabled`.

If only changing campaign scope, send only `campaign_filter`.

Do not include fields that should remain unchanged.

---

## Critical Tax Source Reminder

Tax Profiles are used when RevCent is responsible for calculating tax internally, especially for:

- Subscription Renewals,
- Trial Expiration payments,
- custom/API/hosted store flows without external tax calculation.

For initial WooCommerce/User Shop Sales where the external storefront already calculated tax, the shop-calculated tax is used instead of Tax Profiles.

Correct rule:

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

Subscription Renewal:
    use RevCent Tax Profile when RevCent must calculate tax

Trial Expiration Payment:
    use RevCent Tax Profile when RevCent must calculate tax

Custom/API/hosted flow without external tax:
    use RevCent Tax Profile when RevCent must calculate tax
```

Do not edit a Tax Profile expecting it to recalculate tax on initial WooCommerce/User Shop Sales where the storefront already supplied tax.

---

## Required Field

`EditTaxProfile` requires:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `tax_profile_id` | string | Yes | 20-character Tax Profile ID. |

Example minimal request:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT"
}
```

In practice, include at least one editable field in addition to `tax_profile_id`.

---

## Editable Fields

| Field | Type | Description |
|---|---:|---|
| `name` | string | Tax Profile name. Must be unique across all Tax Profiles. |
| `description` | string | Tax Profile description. |
| `enabled` | boolean | Whether the Tax Profile is currently enabled. |
| `campaign_filter` | array[string] | Array of 20-character Campaign IDs to scope where the profile applies. |
| `third_party_integration` | string | 20-character user third-party integration ID. Must be type `tax`. |

---

## 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. |
| `tax_profile_id` | string | 20-character Tax Profile ID. |
| `result` | string | Result message. |

---

## Always Retrieve Before Editing

Before editing a Tax Profile, use:

```text
GetTaxProfile
```

This lets AI/MCP inspect:

- current name,
- description,
- enabled state,
- current campaign filter,
- current third-party integration,
- related site third-party integration,
- created/updated timestamps.

Recommended flow:

```text
GetTaxProfile
    ↓
Review current configuration
    ↓
Identify exactly what should change
    ↓
Confirm change with user
    ↓
EditTaxProfile with only intended fields
    ↓
GetTaxProfile again to verify
```

Do not edit blind.

---

## Editing Name

Use this when the profile needs a clearer or corrected name.

Example:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "name": "Subscription Renewal Tax Profile"
}
```

Best practice:

```text
Use names that describe the tax use case, provider, shop, brand, or campaign scope.
```

Good names:

```text
Subscription Renewal Tax
Trial Expiration Tax
Brand A Tax Profile
Main Tax Profile
Custom Checkout Tax
WooCommerce Renewal Tax
```

Avoid vague names:

```text
Tax
Profile
Test
New Tax
```

---

## Editing Description

Use the description to document the profile's purpose.

Example:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "description": "Tax Profile for RevCent-calculated subscription renewals and trial expiration payments. Initial WooCommerce checkout tax is supplied by WooCommerce."
}
```

Good descriptions mention:

- tax provider/integration,
- campaign scope,
- shop/brand context,
- whether used for renewals,
- whether used for trial expirations,
- whether used for custom/API/hosted flows,
- whether initial WooCommerce/User Shop Sale tax is externally supplied.

---

## Editing Enabled State

Use `enabled` to activate or disable a Tax Profile.

Disable example:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "enabled": false
}
```

Enable example:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "enabled": true
}
```

Be careful enabling a Tax Profile.

Before enabling, verify:

- the tax third-party integration is correct,
- the integration is enabled,
- credentials are saved,
- required third-party options are configured,
- campaign scope is correct,
- test flows are complete or planned,
- the user understands where this profile applies.

Disable a Tax Profile when:

- tax configuration is being tested,
- the tax provider is being changed,
- campaign scope is wrong,
- integration credentials/options need repair,
- the user wants to stop future tax calculation through this profile.

Disabling affects future eligible tax calculation behavior. It does not erase existing Tax records.

---

## Editing Campaign Filter

`campaign_filter` controls where the Tax Profile applies.

Schema:

```json
{
  "campaign_filter": [
    "CCCCCCCCCCCCCCCCCCCC"
  ]
}
```

If provided:

```text
Only eligible RevCent-calculated tax events originating from the specified Campaigns use this Tax Profile.
```

If not provided:

```text
The profile applies broadly to eligible RevCent-calculated tax events.
```

Eligible RevCent-calculated tax events primarily include:

- Subscription Renewals,
- Trial Expiration payments,
- custom/API/hosted Sale flows without external tax calculation.

Important:

```text
Initial WooCommerce/User Shop Sales that supply shop-calculated tax do not use Tax Profiles for recalculation.
```

### Add or Replace Campaign Filter

`campaign_filter` should be treated as the intended final campaign scope.

Example:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "campaign_filter": [
    "CCCCCCCCCCCCCCCCCCCC",
    "DDDDDDDDDDDDDDDDDDDD"
  ]
}
```

Before changing `campaign_filter`, confirm:

- which Campaigns should be included,
- whether existing Campaigns should remain,
- whether the profile should apply broadly,
- whether the change affects renewal/trial/custom-store tax calculation,
- whether other Tax Profiles may overlap.

Do not guess Campaign IDs.

Use:

```text
GetCampaigns
```

to retrieve and confirm Campaign IDs.

---

## Clearing Campaign Filter

If the API/client supports sending an empty array, then:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "campaign_filter": []
}
```

may represent an intentional clearing of campaign scope.

However, AI/MCP must confirm behavior and user intent before clearing.

Important:

```text
Removing campaign filtering can cause the profile to apply broadly to all eligible RevCent-calculated tax events.
```

Never clear `campaign_filter` accidentally.

---

## Editing Third Party Integration

`third_party_integration` is the user third-party integration used for tax calculation.

Example:

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "third_party_integration": "UUUUUUUUUUUUUUUUUUUU"
}
```

Critical requirement:

```text
The user third-party integration must be associated with a site third-party integration whose integration_type = "tax".
```

Do not use:

- site third-party integration IDs,
- AI integrations,
- AI voice integrations,
- offline payment integrations,
- shipping integrations,
- any user integration whose underlying site integration is not `tax`.

Changing `third_party_integration` can affect future tax calculations.

Before changing it, verify:

- the target user third-party integration exists,
- it is the correct tax provider/account,
- it is enabled or intended to be enabled,
- credentials are saved,
- required options are configured,
- the underlying site third-party integration type is `tax`,
- user understands the profile will use the new integration for future eligible tax calculations.

---

## Verifying Replacement Tax Integration

Use:

```text
GetUserThirdPartyIntegrations
```

or:

```text
GetUserThirdPartyIntegration
```

Then confirm:

```text
site_third_party_integration.integration_type = "tax"
```

Also review:

- user integration ID,
- user integration name,
- enabled state,
- `third_party_credentials_saved`,
- `third_party_options_saved`,
- site integration name,
- account-specific options.

If the chosen tax integration lacks credentials or required options, fix that first.

Use:

```text
EditUserThirdPartyIntegration
```

for credentials/options changes.

Use Secure Form for credentials. Never ask the user to paste API keys, passwords, tokens, or secrets into chat.

---

## When to Create a New Tax Integration Instead of Editing Profile

If the desired tax provider/account is not already connected, create or configure the user third-party integration before editing the Tax Profile.

Correct prerequisite flow:

```text
1. GetSiteThirdPartyIntegrations.
2. Find a site integration where integration_type = "tax".
3. GetSiteThirdPartyIntegration to inspect credentials/options.
4. CreateSecureForm with form_source = "third_party_integration" and form_source_id = site_third_party_integration ID.
5. User completes the Secure Form.
6. CreateUserThirdPartyIntegration.
7. GetUserThirdPartyIntegration.
8. Configure required third_party_options with EditUserThirdPartyIntegration if needed.
9. EditTaxProfile with the new user_third_party_integration_id.
```

Do not edit the Tax Profile to point at an incomplete integration.

---

## Example: Rename Only

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "name": "Main Subscription Renewal Tax"
}
```

---

## Example: Disable Only

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "enabled": false
}
```

---

## Example: Update Campaign Scope

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "campaign_filter": [
    "CCCCCCCCCCCCCCCCCCCC",
    "DDDDDDDDDDDDDDDDDDDD"
  ]
}
```

---

## Example: Change Tax Integration

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "third_party_integration": "UUUUUUUUUUUUUUUUUUUU"
}
```

Use only after verifying the user third-party integration is type `tax`.

---

## Example: Combined Intentional Edit

Only combine fields when the user clearly wants all changes made together.

```json
{
  "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT",
  "name": "Brand A Renewal Tax",
  "description": "Tax Profile for Brand A subscription renewals and trial expiration payments.",
  "enabled": true,
  "campaign_filter": [
    "CCCCCCCCCCCCCCCCCCCC"
  ],
  "third_party_integration": "UUUUUUUUUUUUUUUUUUUU"
}
```

Do not combine changes casually.

For risky changes, separate edits may be easier to review:

```text
Edit 1: description/name
Edit 2: campaign_filter
Edit 3: third_party_integration
Edit 4: enabled
```

---

## What Existing Tax Records Are Affected?

Editing a Tax Profile changes future eligible tax calculations.

It does not rewrite historical Tax records already created.

For historical tax reporting or review, use:

```text
BigQueryRunQuery
```

or bounded operational retrieval for specific records.

Do not use `EditTaxProfile` to change past Tax records.

---

## Reporting and Metrics

Do not use Tax Profile operations for reporting, aggregation, or data mining.

Use:

```text
BigQueryRunQuery
```

for tax reporting such as:

- tax collected by day,
- tax collected by campaign,
- tax collected by shop,
- tax by Tax Profile,
- tax by Product,
- tax by Subscription Renewal,
- tax by Trial Expiration payment,
- refunded tax,
- tax by payment type,
- tax by customer geography.

Correct operation choice:

| Need | Correct Operation |
|---|---|
| Edit tax calculation configuration | `EditTaxProfile` |
| Retrieve one Tax Profile | `GetTaxProfile` |
| Retrieve Tax records operationally | `GetTax` / `GetTaxes` |
| Refund tax | `RefundTax` |
| Tax reporting/metrics | `BigQueryRunQuery` |

---

## Recommended Edit Workflow

```text
1. User asks to edit a Tax Profile.
2. Use GetTaxProfile to retrieve current settings.
3. Identify exactly what the user wants changed.
4. If changing third_party_integration:
       verify replacement user integration is type tax.
5. If changing campaign_filter:
       confirm Campaign IDs with GetCampaigns.
6. If enabling:
       verify tax integration credentials/options are ready.
7. Build request with only intended fields.
8. Call EditTaxProfile.
9. Use GetTaxProfile again to verify.
10. Test an eligible RevCent-calculated tax flow if needed.
```

---

## Pre-Edit Checklist

Before calling `EditTaxProfile`, verify:

- Tax Profile ID is correct.
- Current profile was retrieved with `GetTaxProfile`.
- User explicitly confirmed the edit.
- Only intended fields are included.
- If changing name, the new name is unique.
- If changing campaign filter, Campaign IDs are confirmed.
- If clearing campaign filter, broad/global scope is intentional.
- If changing third-party integration, the new user integration exists.
- If changing third-party integration, its site integration type is `tax`.
- If changing third-party integration, credentials/options are saved.
- If enabling, tax integration and campaign scope are ready.
- User understands this affects future eligible tax calculations.
- User understands initial WooCommerce/User Shop Sale tax comes from the shop when the shop already calculates tax.

---

## Best Practices

1. Retrieve the Tax Profile before editing.
2. Only send fields that should change.
3. Separate risky edits when review is easier.
4. Verify tax user third-party integration before changing `third_party_integration`.
5. Confirm the underlying site integration is type `tax`.
6. Use Secure Form for any credential updates on the user integration.
7. Do not ask for tax provider secrets in chat.
8. Confirm Campaign IDs before changing `campaign_filter`.
9. Avoid clearing campaign filters accidentally.
10. Keep profiles disabled while integration or scope is being tested.
11. Verify the edit with `GetTaxProfile`.
12. Use BigQuery for tax reporting.
13. Remember initial WooCommerce/User Shop Sale tax is shop-calculated when supplied externally.
14. Use Tax Profiles for RevCent-calculated tax on renewals, trial expirations, and custom/API/hosted flows.

---

## Common Mistakes to Avoid

Do not:

- edit without first retrieving the current Tax Profile,
- send all fields when only one field should change,
- use a site third-party integration ID in `third_party_integration`,
- use a non-tax user integration,
- change `third_party_integration` before credentials/options are saved,
- collect tax provider credentials in chat,
- clear `campaign_filter` unintentionally,
- enable a profile with an unverified tax integration,
- assume Tax Profiles recalculate initial WooCommerce/User Shop Sale tax,
- use Tax Profile operations for reporting,
- edit a Tax Profile to fix historical Tax records,
- give tax/legal advice through AI/MCP.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Rename Tax Profile | `EditTaxProfile` with `name` only. |
| Update description | `EditTaxProfile` with `description` only. |
| Disable profile | `EditTaxProfile` with `enabled: false`. |
| Enable profile | Verify tax integration and campaign scope, then `enabled: true`. |
| Change campaign scope | Confirm Campaign IDs, then edit `campaign_filter`. |
| Change tax provider/account | Verify/create tax user integration, then edit `third_party_integration`. |
| Update tax provider credentials | Use `CreateSecureForm` / `EditUserThirdPartyIntegration`, not `EditTaxProfile`. |
| Report tax collected/refunded | Use `BigQueryRunQuery`. |
| Handle initial WooCommerce Sale tax | Use shop-calculated tax, not Tax Profile recalculation. |

---

## Final AI/MCP Instruction

Use `EditTaxProfile` to modify an existing Tax Profile by Tax Profile ID. It is a partial-edit operation: only include fields that should change.

Be especially careful with `campaign_filter`, `enabled`, and `third_party_integration`.

If changing `third_party_integration`, the replacement must be a user third-party integration whose underlying site third-party integration has `integration_type = "tax"`. Verify that with `GetUserThirdPartyIntegrations` or `GetUserThirdPartyIntegration` before editing.

Tax Profiles are for RevCent-calculated tax, especially Subscription Renewals, Trial Expiration payments, and custom/API/hosted flows without external tax calculation. Initial WooCommerce/User Shop Sales should use shop-calculated tax when the external shop already supplies tax.


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