# RevCent MCP Guide: `CreateTaxProfile`

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

This document explains the `CreateTaxProfile` operation, the required tax-type third-party integration prerequisite, the correct Third Party Integration setup workflow, campaign filtering, and when Tax Profiles should be used.

---

## Related Documentation

AI/MCP clients should also read:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewTax.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. |
| GetSiteThirdPartyIntegrations | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Lists available native RevCent site integrations and their integration types, including `tax`. |
| GetSiteThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Retrieves required credential fields and option fields for a selected site integration. |
| CreateSecureForm | `https://revcent.com/documentation/markdown/mcp/operation/CreateSecureForm.md` | Securely collects sensitive third-party tax integration credentials. |
| CreateUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserThirdPartyIntegration.md` | Creates the user-owned third-party integration that the Tax Profile will use. |
| GetUserThirdPartyIntegrations | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Lists the user's existing integrations so AI/MCP can find an existing tax integration. |
| GetUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Retrieves the user's integration details, saved credentials, and account-specific option values. |
| EditUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/EditUserThirdPartyIntegration.md` | Updates credentials or required options for a user integration after creation. |
| GetCampaigns |  | Retrieves Campaign IDs for optional `campaign_filter` scoping. |

---

## Operation Summary

Operation:

```text
CreateTaxProfile
```

Title:

```text
Create A Tax Profile
```

Purpose:

```text
Create a Tax Profile, which will issue a unique Tax Profile ID.
```

A Tax Profile tells RevCent how to calculate tax for eligible RevCent-calculated tax events.

Tax Profiles are used when RevCent needs to calculate tax internally, especially for:

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

Important:

```text
For initial User Shop / WooCommerce Sales where the external shop already calculated tax, use the tax calculated by the shop instead of Tax Profiles.
```

Tax Profiles are not meant to recalculate initial WooCommerce/User Shop Sale tax that was already supplied by the storefront/cart.

---

## Critical Prerequisite: Tax Third-Party Integration Required

`CreateTaxProfile` requires an existing user third-party integration:

```text
third_party_integration
```

This must be:

```text
A 20-character user third-party integration ID
```

and the underlying site third-party integration must have:

```text
integration_type = "tax"
```

The Tax Profile uses this user third-party integration to calculate tax.

Correct relationship:

```text
Site Third Party Integration
    integration_type = "tax"
        ↓
User Third Party Integration
    connected to that tax site integration
    credentials saved via Secure Form
        ↓
Tax Profile
    third_party_integration = user third-party integration ID
        ↓
RevCent can calculate tax using that tax provider
```

Do not create a Tax Profile with a third-party integration whose site integration type is:

- `ai`,
- `ai_voice`,
- `offline_payment`,
- `shipping`,
- any type other than `tax`.

A non-tax integration cannot be used for tax calculation.

---

## Third Party Integration Terms

| Term | Meaning |
|---|---|
| Site Third Party Integration | RevCent-supported native integration definition. It defines integration type, required credential fields, and possible options. |
| User Third Party Integration | The user's connected instance of a site integration, with credentials and options saved. |
| Tax Third Party Integration | A User Third Party Integration whose underlying Site Third Party Integration has `integration_type = "tax"`. |
| Tax Profile | A RevCent tax calculation profile that references a tax-type User Third Party Integration. |

Simple example:

```text
Site Third Party Integration = Tax provider supported by RevCent
User Third Party Integration = Merchant's account connected to that provider
Tax Profile = RevCent profile using that connected account to calculate tax
```

---

## Correct Prerequisite Workflow

Before calling `CreateTaxProfile`, AI/MCP should determine whether a usable tax integration already exists.

Recommended workflow:

```text
1. Use GetUserThirdPartyIntegrations.
2. Look for an enabled user integration whose site_third_party_integration.integration_type = "tax".
3. If one exists, confirm with the user that it is the correct tax integration.
4. If no tax integration exists, use GetSiteThirdPartyIntegrations.
5. Find a site third-party integration whose integration_type = "tax".
6. Use GetSiteThirdPartyIntegration to inspect required credentials and options.
7. Create a Secure Form with form_source = "third_party_integration" and form_source_id = site_third_party_integration ID.
8. User completes the Secure Form with credentials.
9. Call CreateUserThirdPartyIntegration with the tax site integration ID and secure_form_id.
10. Retrieve the new user integration using GetUserThirdPartyIntegration.
11. If the site integration has third_party_options, configure them with EditUserThirdPartyIntegration.
12. Verify credentials/options are saved and integration is enabled.
13. Call CreateTaxProfile using the user_third_party_integration_id as third_party_integration.
```

Do not skip the tax integration prerequisite.

---

## Finding an Existing Tax Integration

Use:

```text
GetUserThirdPartyIntegrations
```

Then inspect each result:

```text
site_third_party_integration.integration_type
```

Correct match:

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

Also review:

- user integration name,
- enabled state,
- saved credentials,
- saved options,
- site integration name,
- whether this is the correct tax provider/account.

A user may have multiple tax integrations. If more than one exists, ask the user which one should be used for the Tax Profile.

Do not guess.

---

## Creating a Tax Integration When One Does Not Exist

If no usable tax user integration exists, AI/MCP should create one first.

### Step 1: List Site Third Party Integrations

Use:

```text
GetSiteThirdPartyIntegrations
```

Find a site integration with:

```text
integration_type = "tax"
```

Site integration types include:

```text
ai
ai_voice
offline_payment
tax
shipping
```

Only use `tax` for Tax Profiles.

---

### Step 2: Retrieve the Site Integration

Use:

```text
GetSiteThirdPartyIntegration
```

Input:

```json
{
  "site_third_party_integration_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Review:

- `integration_type`,
- `third_party_credentials`,
- required credential fields,
- `third_party_options`,
- required option fields,
- remote option behavior.

Important:

```text
Confirm integration_type = "tax" before creating the user integration.
```

---

### Step 3: Create a Secure Form for Credentials

Sensitive third-party tax credentials must not be collected in chat.

Use:

```text
CreateSecureForm
```

Request:

```json
{
  "form_source": "third_party_integration",
  "form_source_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Where:

```text
form_source_id = site_third_party_integration ID
```

The Secure Form response includes:

- `secure_form_id`,
- `form_url`,
- `expiration_date_unix`,
- `completed`.

The user must open the secure form URL and complete credentials there.

Important:

```text
Secure Forms expire after 1 hour.
```

Do not ask the user to paste tax provider API keys, secrets, usernames, passwords, or tokens into chat.

---

### Step 4: Create the User Third Party Integration

After the user completes the Secure Form, use:

```text
CreateUserThirdPartyIntegration
```

Required:

| Field | Required | Purpose |
|---|---:|---|
| `name` | Yes | Unique name for the user integration. |
| `site_third_party_integration` | Yes | 20-character site third-party integration ID. |

Optional:

| Field | Purpose |
|---|---|
| `description` | Human-readable explanation. |
| `enabled` | Whether the integration is enabled. |
| `secure_form_id` | Secure Form ID containing credentials. |

Example:

```json
{
  "name": "Main Tax Provider",
  "description": "Tax provider integration used by RevCent Tax Profiles for renewals, trial expirations, and custom checkout tax calculation.",
  "enabled": true,
  "site_third_party_integration": "SSSSSSSSSSSSSSSSSSSS",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

The response returns:

```text
user_third_party_integration_id
```

This is the ID that will later be used in:

```text
CreateTaxProfile.third_party_integration
```

---

### Step 5: Configure Required Third Party Options

Some site third-party integrations have:

```text
third_party_options
```

If the selected tax site integration has non-empty `third_party_options`, additional configuration may be required after creating the user integration.

Correct flow:

```text
CreateUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
    ↓
Review account-specific options and remote assets
    ↓
EditUserThirdPartyIntegration with third_party_options
    ↓
Verify saved options
```

Use:

```text
EditUserThirdPartyIntegration
```

Example shape:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "third_party_options": [
    {
      "id": "option_id_from_site_integration",
      "fields": [
        {
          "id": "field_id_from_site_integration",
          "value": [
            "selected_or_entered_value"
          ]
        }
      ]
    }
  ]
}
```

Do not invent option IDs or field IDs.

Use IDs returned by `GetSiteThirdPartyIntegration` and account-specific values returned by `GetUserThirdPartyIntegration`.

---

## Input Schema: `CreateTaxProfile`

`CreateTaxProfile` input schema:

```text
type: object
additionalProperties: false
required:
  - name
  - third_party_integration
```

Only send supported fields.

---

## Required Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | Unique Tax Profile name. |
| `third_party_integration` | string | Yes | Existing user third-party integration ID. Must be type `tax`. |

---

## Optional Fields

| Field | Type | Description |
|---|---:|---|
| `description` | string | Human-readable Tax Profile description. |
| `enabled` | boolean | Whether the Tax Profile is enabled. |
| `campaign_filter` | array[string] | Campaign IDs that scope where this Tax Profile applies. |

---

## Field Details

### `name`

The Tax Profile name must be unique across all Tax Profiles.

Good names:

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

Avoid vague names:

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

---

### `description`

Use the description to explain:

- tax provider,
- integration/account,
- campaign scope,
- shop/brand context,
- whether it is used for renewals,
- whether it is used for trial expirations,
- whether it is used for custom stores/API/hosted flows,
- whether it should not be used for initial WooCommerce tax.

Example:

```text
Tax Profile using Main Tax Provider integration for subscription renewals, trial expiration payments, and custom checkout flows. Initial WooCommerce checkout tax is supplied by WooCommerce and not recalculated by this profile.
```

---

### `enabled`

Whether the Tax Profile is enabled.

Recommended:

```text
Set enabled = false until the tax integration, credentials, campaign scope, and test flows are confirmed.
```

Use `enabled = true` only when ready for eligible RevCent-calculated tax events.

---

### `campaign_filter`

Optional array of 20-character Campaign IDs.

If provided:

```text
Only eligible RevCent-calculated tax events originating from the listed Campaigns will 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.

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

Use campaign filters when different campaigns/brands/stores should use different tax configurations.

Do not omit `campaign_filter` accidentally if the profile should only apply to a specific campaign.

---

### `third_party_integration`

Required.

This is the existing user third-party integration ID.

Critical:

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

Example:

```json
{
  "third_party_integration": "UUUUUUUUUUUUUUUUUUUU"
}
```

Do not pass:

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

---

## Example Request

```json
{
  "name": "Subscription Renewal Tax Profile",
  "description": "Tax Profile for RevCent-calculated subscription renewals and trial expiration payments. Uses Main Tax Provider user integration. Initial WooCommerce checkout tax is supplied by WooCommerce.",
  "enabled": true,
  "campaign_filter": [
    "CCCCCCCCCCCCCCCCCCCC"
  ],
  "third_party_integration": "UUUUUUUUUUUUUUUUUUUU"
}
```

---

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

Store the returned:

```text
tax_profile_id
```

for future retrieval/editing.

---

## Correct End-to-End Workflow

```text
1. User asks to create a Tax Profile.
2. AI/MCP reads the Tax Overview.
3. AI/MCP explains initial WooCommerce/User Shop Sales use shop-calculated tax.
4. AI/MCP confirms the profile is needed for renewals, trial expirations, or custom/non-shop tax calculation.
5. Use GetUserThirdPartyIntegrations.
6. If a tax user integration exists, confirm the correct one with the user.
7. If no tax user integration exists:
       a. Use GetSiteThirdPartyIntegrations.
       b. Find integration_type = "tax".
       c. Use GetSiteThirdPartyIntegration.
       d. Create Secure Form for credentials.
       e. User completes Secure Form.
       f. CreateUserThirdPartyIntegration.
       g. Use GetUserThirdPartyIntegration.
       h. Configure required third_party_options with EditUserThirdPartyIntegration if needed.
8. Confirm Campaign scope.
9. Call CreateTaxProfile.
10. Verify with GetTaxProfile.
11. Test an eligible RevCent-calculated tax event where appropriate.
```

---

## When Not to Create a Tax Profile

Do not create a Tax Profile just to handle tax for initial WooCommerce/User Shop checkout tax when the external shop already calculates tax.

Correct rule:

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

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

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

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

This prevents duplicate tax calculation and mismatch between storefront totals and RevCent totals.

---

## Required Pre-Checks

Before calling `CreateTaxProfile`, verify:

- user explicitly wants a Tax Profile,
- the use case is renewal, trial expiration, or custom/non-shop RevCent tax calculation,
- initial WooCommerce/User Shop tax source behavior is understood,
- a user third-party integration exists,
- the user integration is enabled or intended to be enabled,
- the user integration's site integration type is `tax`,
- credentials were saved through Secure Form,
- required third-party options are configured,
- Campaign scope is known,
- `campaign_filter` is provided if the profile should be campaign-specific,
- omitting `campaign_filter` is intentional,
- `enabled` state is intentional,
- user understands Tax Profile changes affect future eligible tax calculations.

---

## Best Practices

1. Verify or create a tax user third-party integration before creating the Tax Profile.
2. Confirm the underlying site third-party integration has `integration_type = "tax"`.
3. Use Secure Form for tax provider credentials.
4. Never ask the user to paste API keys, tokens, passwords, or secrets into chat.
5. Configure required third-party options before relying on the Tax Profile.
6. Use clear Tax Profile names.
7. Include the tax source/use case in the description.
8. Use Campaign filters intentionally.
9. Avoid broad/global profiles unless intended.
10. Create disabled profiles while testing.
11. Verify with `GetTaxProfile` after creation.
12. Test eligible tax calculation flows after setup.
13. Remember initial WooCommerce/User Shop Sales use shop-calculated tax.
14. Use Tax Profiles for renewals, trial expirations, and custom/API/hosted flows without external tax calculation.
15. Use BigQueryRunQuery for tax reporting.

---

## Common Mistakes to Avoid

Do not:

- create a Tax Profile before creating/selecting a tax user third-party integration,
- use a site third-party integration ID where a user third-party integration ID is required,
- use an integration whose site integration type is not `tax`,
- ask for tax provider credentials in chat,
- skip Secure Form for credentials,
- skip required third-party options,
- guess Campaign IDs,
- omit `campaign_filter` when the profile should only apply to specific Campaigns,
- assume Tax Profiles recalculate initial WooCommerce/User Shop Sales tax,
- create a Tax Profile for initial WooCommerce checkout tax when WooCommerce already calculated tax,
- enable a Tax Profile before verifying the tax integration and scope,
- use Tax Profile operations for reporting.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Create Tax Profile | First verify a tax user third-party integration exists. |
| No tax integration exists | Create one using Site Third Party Integration + Secure Form + CreateUserThirdPartyIntegration. |
| Need to select tax provider | Use `GetSiteThirdPartyIntegrations` and select one with `integration_type = "tax"`. |
| Need credential fields | Use `GetSiteThirdPartyIntegration`. |
| Need to collect credentials | Use `CreateSecureForm`; do not collect secrets in chat. |
| Need to configure provider options | Use `GetUserThirdPartyIntegration`, then `EditUserThirdPartyIntegration`. |
| Need profile scoped to campaigns | Provide `campaign_filter`. |
| Initial WooCommerce Sale tax | Use shop-calculated tax, not Tax Profile recalculation. |
| Renewal/trial/custom-store tax calculation | Use Tax Profile. |
| Tax reporting | Use `BigQueryRunQuery`. |

---

## Final AI/MCP Instruction

Use `CreateTaxProfile` only after a valid tax user-third-party integration exists.

The `third_party_integration` field must be a user third-party integration ID, and that user integration must be connected to a site third-party integration whose `integration_type` is `tax`. Create or verify that integration first using `GetSiteThirdPartyIntegrations`, `GetSiteThirdPartyIntegration`, `CreateSecureForm`, `CreateUserThirdPartyIntegration`, `GetUserThirdPartyIntegration`, and `EditUserThirdPartyIntegration` where required.

Tax Profiles are used when RevCent must calculate tax internally, especially for Subscription Renewals, Trial Expiration payments, and custom/API/hosted flows without external tax calculation. Initial WooCommerce/User Shop Sales should use tax calculated by the external shop/storefront instead of Tax Profiles.


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