# RevCent MCP Guide: `EditUserThirdPartyIntegration`

AI/MCP-focused guide for editing a User Third Party Integration in RevCent.

This document explains the `EditUserThirdPartyIntegration` operation, how it fits after creating and retrieving a User Third Party Integration, how to safely update credentials, how to save third-party options/assets, and when not to edit.

---

## Related Documentation

AI/MCP clients should also read:

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

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

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

Related operation guides:

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| Third Party Integration Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Explains native Site Third Party Integrations, User Third Party Integrations, integration types, and custom Function-based integrations. |
| CreateUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserThirdPartyIntegration.md` | Explains how user integrations are initially created and why post-creation option configuration may be required. |
| GetUserThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/GetUserThirdPartyIntegration.md` | Explains how to retrieve saved credentials/options and account-specific third-party assets/options. |
| GetSiteThirdPartyIntegration | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Shows the native Site integration credential/option schema and exact option/field IDs. |
| CreateSecureForm | `https://revcent.com/documentation/markdown/mcp/operation/CreateSecureForm.md` | Securely collects new or replacement credentials without exposing secrets in chat. |
| CreateFunction | `https://revcent.com/documentation/markdown/mcp/operation/CreateFunction.md` | Use Functions for non-native custom third-party integrations. |
| EditFunction | `https://revcent.com/documentation/markdown/mcp/operation/EditFunction.md` | Edit Function-based custom integrations. |

---

## Operation Summary

Operation:

```text
EditUserThirdPartyIntegration
```

Title:

```text
Edit A User Third Party Integration
```

Purpose:

```text
Edit a previously created User Third Party Integration using the integration ID.
```

Use `EditUserThirdPartyIntegration` to modify a connected User Third Party Integration's:

- name,
- description,
- enabled state,
- saved credentials via Secure Form,
- third-party options/assets/settings.

Important:

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

If only changing the name, send only `name`.

If only disabling, send only `enabled`.

If only changing credentials, send only `secure_form_id`.

If only setting provider options, send only `third_party_options`.

Do not include fields that should remain unchanged.

---

## Where Edit Fits in the Integration Lifecycle

`EditUserThirdPartyIntegration` usually appears after creating and retrieving the integration.

Full native integration lifecycle:

```text
GetSiteThirdPartyIntegrations
    ↓
GetSiteThirdPartyIntegration
    ↓
CreateSecureForm for credentials
    ↓
CreateUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration
    ↓
If third_party_options/assets are required:
        EditUserThirdPartyIntegration
    ↓
GetUserThirdPartyIntegration again to verify
    ↓
Use the User Third Party Integration in the appropriate RevCent feature
```

Use Edit only after understanding what needs to change.

---

## Critical Rule: Do Not Edit Options Casually

Updating third-party options/assets should only be done in two cases:

1. **Initial integration setup**
   - immediately after `CreateUserThirdPartyIntegration`,
   - after `GetUserThirdPartyIntegration` retrieves account-specific options/assets,
   - when required options must be saved before the integration is ready.

2. **Explicit user-requested settings change**
   - when the user clearly wants to change the integration's options/settings,
   - when switching provider accounts, locations, stores, models, services, warehouses, voices, tax companies, payment accounts, or other provider assets.

Do not change saved options/assets during normal retrieval.

Do not overwrite saved options just because new assets are available.

Do not edit production integration settings without explicit user confirmation.

---

## Input Schema

`EditUserThirdPartyIntegration` input schema:

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

Only send supported fields.

---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `user_third_party_integration_id` | string | Yes | 20-character User Third Party Integration ID. |

Example minimal shape:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU"
}
```

In practice, include at least one field to modify.

---

## Optional Editable Fields

| Field | Type | Purpose |
|---|---:|---|
| `name` | string | Rename the User Third Party Integration. Must be unique. |
| `description` | string | Update the integration description. |
| `enabled` | boolean | Enable or disable the integration. |
| `secure_form_id` | string | Replace/update saved credentials using a completed Secure Form. |
| `third_party_options` | array | Save selected third-party options/assets/settings. |

---

## 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 call response code. `1` indicates success. |
| `user_third_party_integration_id` | string | 20-character User Third Party Integration ID. |
| `result` | string | Result message. |

---

## Always Retrieve Before Editing

Before editing, use:

```text
GetUserThirdPartyIntegration
```

This lets AI/MCP inspect:

- current name,
- description,
- enabled state,
- integration type,
- saved credentials,
- saved options,
- Site Third Party Integration schema,
- required options,
- account-specific third-party assets/options.

Recommended flow:

```text
GetUserThirdPartyIntegration
    ↓
Review current state
    ↓
Identify exact intended change
    ↓
Confirm with user if change affects live behavior
    ↓
EditUserThirdPartyIntegration with only intended fields
    ↓
GetUserThirdPartyIntegration again to verify
```

Do not edit blind.

---

## Editing Name

Use this when the user wants to rename the connected integration.

Example:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "name": "Main Tax Provider - Production"
}
```

Best practice:

```text
Use names that identify provider, purpose, environment, shop, brand, or feature.
```

Good examples:

```text
Main Tax Provider - Production
Brand A Shipping Integration
AI Provider - Support Assistant
Voice Provider - Main Store
Offline Payment - Sezzle
```

---

## Editing Description

Use the description to document purpose and scope.

Example:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "description": "Tax integration used by Tax Profiles for subscription renewals and trial expiration payments. Initial WooCommerce checkout tax is supplied by WooCommerce."
}
```

A good description can include:

- provider,
- integration type,
- where it is used,
- shop/brand/campaign context,
- production/test environment,
- credential/setup notes,
- option/asset selections,
- dependent RevCent features.

---

## Editing Enabled State

Use `enabled` to activate or disable the integration.

Enable:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "enabled": true
}
```

Disable:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "enabled": false
}
```

Before enabling, verify:

- credentials are saved,
- required options are saved,
- account-specific assets are selected if needed,
- integration type matches intended feature,
- dependent RevCent features are ready,
- user understands the integration may be used by live workflows.

Before disabling, consider dependent features such as:

- Tax Profiles,
- Shipping/tracking workflows,
- Offline Payments,
- AI Assistants,
- AI Voice Agents,
- any other features using this integration.

Disabling can break or pause dependent workflows.

---

## Editing Credentials

Use `secure_form_id` only when changing credentials.

Credentials are sensitive and must never be requested in chat.

Correct credential update flow:

```text
1. User explicitly wants to update credentials.
2. CreateSecureForm with form_source = third_party_integration and form_source_id = Site Third Party Integration ID.
3. User opens secure form URL and enters credentials.
4. User confirms the form is completed.
5. EditUserThirdPartyIntegration with secure_form_id.
6. GetUserThirdPartyIntegration to verify credentials are saved.
7. Re-check options/assets because changed credentials may expose different provider assets.
```

Example:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Important:

```text
Only provide secure_form_id if modifying saved credentials.
```

Do not include `secure_form_id` for name, description, enabled-state, or option-only edits.

---

## Rechecking Options After Credential Updates

Changing credentials may change available third-party assets/options.

After editing credentials:

```text
EditUserThirdPartyIntegration with secure_form_id
    ↓
GetUserThirdPartyIntegration
    ↓
Review available third-party assets/options
    ↓
If required and user confirms:
        EditUserThirdPartyIntegration with third_party_options
```

Examples:

- new tax provider credentials expose different company profiles,
- shipping credentials expose different warehouses/services,
- AI credentials expose different models/accounts,
- voice credentials expose different phone numbers/voices,
- payment credentials expose different merchant accounts.

Do not assume previously saved options are still valid after credential changes.

---

## Editing Third Party Options

Use `third_party_options` to save integration-specific option values.

This is needed when the Site Third Party Integration has a non-empty `third_party_options` array.

Options are based on the Site Third Party Integration schema and may require account-specific values retrieved from `GetUserThirdPartyIntegration`.

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"
          ]
        }
      ]
    }
  ]
}
```

Rules:

- option `id` must come from `site_third_party_integration.third_party_options[].id`,
- field `id` must come from `site_third_party_integration.third_party_options[].fields[].id`,
- `value` must be an array,
- for single-value fields, use one value in the array,
- for multi-select fields, include all selected values,
- do not invent IDs,
- do not guess third-party assets,
- verify after editing.

---

## Option Field Types

Third-party option fields can be:

| Field Type | Meaning |
|---|---|
| `input` | User provides a non-secret value. |
| `select` | User selects from available options. |

Select fields can have:

| Select Setting | Meaning |
|---|---|
| `third_party_asset = false` | Options are static and available from the Site Third Party Integration schema. |
| `third_party_asset = true` | Options are pulled from the third-party API after credentials are saved and retrieved through `GetUserThirdPartyIntegration`. |
| `multiple = true` | Multiple values may be saved in the `value` array. |
| `multiple = false` | One value should be saved in the `value` array. |

---

## Third Party Assets

Third-party assets are option values pulled from the provider's API.

They are specific to the user's third-party account.

Examples may include:

- tax companies/profiles,
- stores,
- warehouses,
- locations,
- carrier accounts,
- shipping services,
- AI models,
- voice provider assets,
- phone numbers,
- payment accounts,
- merchant accounts,
- provider resources.

Important:

```text
Third-party assets are retrieved through GetUserThirdPartyIntegration after credentials are saved.
```

Correct asset-selection flow:

```text
GetUserThirdPartyIntegration
    ↓
Show current saved options
    ↓
Show available account-specific options/assets
    ↓
User chooses exact asset(s)
    ↓
EditUserThirdPartyIntegration with third_party_options
    ↓
GetUserThirdPartyIntegration verifies saved selection
```

Do not default to the first option unless the user explicitly confirms that choice.

---

## Initial Creation + Options Workflow

After `CreateUserThirdPartyIntegration`, options may still need to be configured.

Correct initial setup flow:

```text
1. CreateUserThirdPartyIntegration with credentials from Secure Form.
2. GetUserThirdPartyIntegration.
3. Inspect site_third_party_integration.third_party_options.
4. If options exist:
       a. Determine which options are required.
       b. Retrieve account-specific assets/options.
       c. Ask user to choose values.
       d. EditUserThirdPartyIntegration with third_party_options.
       e. GetUserThirdPartyIntegration to verify.
5. Enable integration only after required settings are complete.
```

If no `third_party_options` exist, no post-creation option edit is required.

---

## Explicit Settings Change Workflow

When the user explicitly wants to change an integration setting:

```text
1. GetUserThirdPartyIntegration.
2. Show current saved option/settings.
3. Show available options/assets.
4. Confirm what the user wants changed.
5. Build EditUserThirdPartyIntegration with only the intended fields.
6. Run EditUserThirdPartyIntegration.
7. Verify with GetUserThirdPartyIntegration.
```

Examples:

- switch tax provider company profile,
- change shipping warehouse/location,
- change AI model selection,
- change AI Voice account/voice/number,
- change alternate payment account setting,
- enable or disable the integration,
- update credentials after provider key rotation.

---

## When Not to Edit

Do not use `EditUserThirdPartyIntegration` when:

- the user only asked to view the integration,
- the user only asked whether it is configured,
- an AI workflow is only checking available integrations,
- the integration already has saved options and no change was requested,
- another operation only needs the integration ID,
- the AI/MCP client is not sure which option/asset should be selected,
- editing would change live production behavior without explicit confirmation.

Read-only verification should use:

```text
GetUserThirdPartyIntegration
```

not Edit.

---

## Example: Rename Only

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "name": "Main Shipping Provider - Production"
}
```

---

## Example: Disable Only

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "enabled": false
}
```

---

## Example: Update Credentials Only

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Use this only after the user completes a new Secure Form.

---

## Example: Save a Single Select Option

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "third_party_options": [
    {
      "id": "provider_account",
      "fields": [
        {
          "id": "account_id",
          "value": [
            "acct_123"
          ]
        }
      ]
    }
  ]
}
```

---

## Example: Save a Multi-Select Option

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "third_party_options": [
    {
      "id": "shipping_services",
      "fields": [
        {
          "id": "service_ids",
          "value": [
            "ground",
            "two_day"
          ]
        }
      ]
    }
  ]
}
```

---

## Example: Combined Intentional Edit

Only combine fields when the user clearly wants all of the changes.

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "name": "Brand A Tax Provider",
  "description": "Tax integration for Brand A subscription renewals and trial expirations.",
  "enabled": true,
  "third_party_options": [
    {
      "id": "tax_company",
      "fields": [
        {
          "id": "company_id",
          "value": [
            "company_abc"
          ]
        }
      ]
    }
  ]
}
```

For safer review, separate risky changes:

```text
Edit 1: name / description
Edit 2: credentials
Edit 3: options/assets
Edit 4: enabled state
```

---

## Integration-Type-Specific Editing Notes

### Tax Integrations

For tax integrations:

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

Options may control tax provider accounts, companies, profiles, or other tax assets.

Changing these settings can affect future Tax Profile calculations.

Only edit tax options during initial setup or explicit user-requested changes.

### Shipping Integrations

For shipping integrations:

```text
integration_type = "shipping"
```

Options may control carrier accounts, warehouses, tracking services, locations, or shipping provider settings.

Changing these can affect shipment tracking or fulfillment-related behavior.

### Offline Payment Integrations

For offline/alternate payment integrations:

```text
integration_type = "offline_payment"
```

Options may control provider accounts or payment method settings.

Changing these can affect alternate payment retrieval/refund workflows where supported.

### AI Integrations

For AI integrations:

```text
integration_type = "ai"
```

Options may control model/provider/account settings.

Changing these can affect AI Assistants and AI behavior.

### AI Voice Integrations

For AI Voice integrations:

```text
integration_type = "ai_voice"
```

Options may control voice provider settings, accounts, voices, numbers, or voice resources.

Changing these can affect live AI Voice Agents.

---

## Native vs Custom Integration Reminder

`EditUserThirdPartyIntegration` only edits a User Third Party Integration that was created from a native Site Third Party Integration.

If no native Site Third Party Integration exists for a provider, do not use `EditUserThirdPartyIntegration`.

Use Functions instead.

Custom integration options include:

- Account Event Functions,
- Webhook Functions,
- Function URLs,
- Schedule Functions,
- API/AI Functions,
- Email Template Functions,
- Payment Profile Functions,
- Key Values,
- encrypted values,
- RevCent API/MCP operations.

Correct rule:

```text
Native integration exists:
    use Create/Get/Edit User Third Party Integration.

No native integration exists:
    use Functions and related RevCent tools.
```

---

## Verification After Editing

Always verify after mutation.

Use:

```text
GetUserThirdPartyIntegration
```

Check:

- name updated correctly,
- description updated correctly,
- enabled state is correct,
- credentials saved if changed,
- options saved if changed,
- selected assets are correct,
- integration type remains correct,
- dependent feature can use the integration.

Verification is especially important after:

- credential update,
- option/asset update,
- enabling,
- disabling,
- switching production/test provider accounts.

---

## Pre-Edit Checklist

Before calling `EditUserThirdPartyIntegration`, verify:

- User Third Party Integration ID is correct.
- Current integration was retrieved with `GetUserThirdPartyIntegration`.
- User explicitly confirmed the edit.
- Only intended fields are included.
- If changing credentials, a Secure Form was created and completed.
- If changing credentials, `secure_form_id` is not expired.
- If changing options/assets, available options were retrieved first.
- If changing options/assets, the user chose the values.
- Option IDs and field IDs come from the Site Third Party Integration schema.
- Remote third-party asset values are not guessed.
- If enabling, credentials/options are complete.
- If disabling, dependent workflows are understood.
- If no native integration exists, Functions are used instead.

---

## Best Practices

1. Retrieve before editing.
2. Only include fields that should change.
3. Use Secure Form for credential updates.
4. Never ask users to paste secrets in chat.
5. Use `third_party_options` only when needed.
6. Edit options/assets only during initial setup or explicit settings changes.
7. Ask the user to choose third-party assets when multiple options exist.
8. Do not guess option IDs, field IDs, or values.
9. Keep risky edits separate when useful.
10. Verify after editing.
11. Do not enable incomplete integrations.
12. Check dependent RevCent features before disabling.
13. Confirm integration type before relying on the integration.
14. Use Functions for non-native integrations.

---

## Common Mistakes to Avoid

Do not:

- edit without retrieving current integration details first,
- send all fields when only one should change,
- provide `secure_form_id` unless changing credentials,
- collect credentials in chat,
- overwrite saved options without explicit user intent,
- change third-party assets casually,
- assume the first returned asset is correct,
- guess option IDs or field IDs,
- ignore `multiple` setting on select fields,
- enable an integration before required options are saved,
- disable an integration without checking dependent features,
- use EditUserThirdPartyIntegration for non-native custom integrations,
- use list/retrieval operations as a substitute for explicit confirmation.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Rename integration | Edit `name` only. |
| Update description | Edit `description` only. |
| Enable integration | Verify credentials/options first, then edit `enabled: true`. |
| Disable integration | Confirm dependent workflow impact, then edit `enabled: false`. |
| Update credentials | Create Secure Form, then edit `secure_form_id`. |
| Save options after initial creation | Retrieve options/assets, user selects values, then edit `third_party_options`. |
| Change options/settings later | Retrieve current/available options, get explicit user confirmation, then edit. |
| Only view/check integration | Use `GetUserThirdPartyIntegration`; do not edit. |
| Need account-specific assets | Use `GetUserThirdPartyIntegration` after credentials are saved. |
| No native integration exists | Use Functions/custom integration pattern instead. |

---

## Final AI/MCP Instruction

Use `EditUserThirdPartyIntegration` to modify an existing User Third Party Integration by ID.

This is a partial-edit operation: include only the fields that should change. Use `secure_form_id` only for credential updates. Use `third_party_options` only when saving selected integration options/assets.

The normal lifecycle is: create the user integration, retrieve it with `GetUserThirdPartyIntegration`, review account-specific third-party options/assets, have the user choose the correct settings, then edit the integration to save those options. After editing, retrieve again to verify.

Only update options/assets during initial setup or when the user explicitly wants to change an integration's options/settings. Do not casually alter saved options because they may control live third-party accounts, stores, warehouses, tax profiles, shipping services, AI models, voice settings, payment accounts, or other production behavior.

If a native Site Third Party Integration does not exist for the provider, use RevCent Functions and related tools to build a custom integration instead.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.