# RevCent MCP Guide: `EditUserShop`

AI/MCP-focused guide for editing a RevCent User Shop, also called a Third-Party Shop.

This guide is focused on the most important post-creation User Shop workflows:

1. Retrieving and adding/mapping shipping methods.
2. Retrieving and adding/mapping alternate/offline payment methods.
3. Retrieving and importing/updating products.

These three areas are vital for a WooCommerce or other third-party shop to work correctly inside RevCent.

---

## Reference Links

Use these overview and operation-specific files alongside this guide:

| Document | Link | Why It Matters |
|---|---|---|
| User Shop / Third-Party Shop Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewUserShop.md` | Explains the broader concept of Shops, WooCommerce as storefront, RevCent as backend, shop context, payment handling, shipping, products, subscriptions, emails, AI, tracking, and reporting. |
| CreateUserShop Guide | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserShop.md` | Explains requirements and the initial shop creation flow before editing/mapping post-creation objects. |
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` | Explains shipments, fulfillment, shipping method behavior, provider/method mapping, shipment status, tracking, and shipping automation. |
| Offline / Alternate Payment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md` | Explains how RevCent treats alternate payment processors such as Sezzle, Klarna, Afterpay, Affirm, Amazon Pay, and other non-credit-card / non-PayPal payment methods. |
| Product Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md` | Explains product setup, product import, shippable products, subscriptions, trials, product groups, and `third_party_shop` / `internal_id` mapping. |

---

## Source Operations

This guide is based on these RevCent MCP operations:

| Operation | Purpose |
|---|---|
| `EditUserShop` | Edits an existing User Shop. Used for shop settings, credentials, mapped shipping methods, and mapped alternate/offline payment methods. |
| `GetUserShop` | Retrieves a User Shop and can retrieve remote WooCommerce data using `remote_data`. |
| `CreateProduct` | Creates RevCent Products from remote shop products that do not already exist in RevCent. |
| `EditProduct` | Updates RevCent Products that already exist and are mapped to remote shop products. |

Related operations may also be needed:

| Related Operation | Purpose |
|---|---|
| `GetUserShops` | Find the User Shop ID if unknown. |
| `ValidateUserShop` | Confirm shop/plugin configuration before import/mapping. |
| `FixUserShop` | Attempt to fix RevCent plugin settings after validation errors. |
| `GetSiteShop` | Review required fields for the selected Site Shop. |
| `CreateSecureForm` | Securely collect new credentials when editing credentials. |
| Shipping provider lookup operation(s) | Retrieve valid provider/provider method IDs for shipping-method mapping. |
| Third-party integration operations | Retrieve/create RevCent integrations for alternate/offline payment mapping. |

---

## Operation Summary

Operation:

```text
EditUserShop
```

Purpose:

```text
Edit a user shop in RevCent.
```

Schema behavior:

```text
Only provide the properties you wish to modify.
Properties not provided will remain unchanged.
```

This means simple fields can be edited safely by sending only the intended fields.

Example:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Main WooCommerce Store"
}
```

However, array fields require special care.

Important array fields:

```text
shipping_methods
offline_payment_methods
```

When either array is included, it replaces the entire saved array.

Critical rule:

```text
shipping_methods and offline_payment_methods are replacement arrays, not patch arrays.
```

If the shop currently has three shipping methods and the edit request includes only one, the shop will end up with only that one saved shipping method.

---

## Why This Operation Is Important

`EditUserShop` is central to making a connected WooCommerce/third-party shop operational after creation.

`CreateUserShop` creates the connection, but `EditUserShop` completes key configuration:

- mapped shipping methods,
- mapped alternate/offline payment methods,
- updated credentials via Secure Form,
- updated Campaign,
- updated Payment Profile,
- updated shop URL,
- updated shop version,
- updated shop description.

For WooCommerce stores, this is especially important because RevCent should be treated as the backend commerce engine and WooCommerce should be treated as the storefront.

Correct architecture:

```text
WooCommerce = storefront / cart / checkout surface
RevCent = backend commerce engine
```

The User Shop must be configured correctly so RevCent can understand and manage:

- shop-originated Sales,
- Product Sales,
- credit-card payments,
- PayPal transactions,
- alternate/offline payments,
- shipping methods,
- shipments,
- products,
- fulfillment,
- subscriptions,
- trials,
- refunds,
- emails,
- AI workflows,
- BigQuery reporting.

---

## `EditUserShop` Input Schema

Top-level schema behavior:

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

Supported fields:

| Field | Type | Required | Purpose |
|---|---:|---:|---|
| `user_shop_id` | string | Yes | 20-character User Shop ID to edit. |
| `name` | string | No | Rename the User Shop. |
| `description` | string | No | Update User Shop description. |
| `url` | string | No | Update the shop URL. Confirm exact URL with user. |
| `payment_profile_id` | string | No | Change the Payment Profile used for credit-card transactions. |
| `campaign_id` | string | No | Change the Campaign associated with the shop. |
| `site_shop_id` | string | No | Change the Site Shop association. |
| `site_shop_version` | string | No | Change shop software version. WooCommerce should be `"3"`. |
| `secure_form_id` | string | No | Use only if changing credentials and/or site third-party shop. |
| `shipping_methods` | array | No | Full array of mapped remote shop shipping methods. Replaces saved array. |
| `offline_payment_methods` | array | No | Full array of mapped remote shop offline/alternate payment methods. Replaces saved array. |

---

## 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. |
| `user_shop_id` | string | 20-character User Shop ID. |
| `result` | string | Result message. |

---

## Simple Edit Examples

### Rename User Shop

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Main WooCommerce Store"
}
```

### Update Description

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Main WooCommerce storefront connected to RevCent as backend commerce engine."
}
```

### Update URL

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "url": "https://example.com"
}
```

### Change Payment Profile

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "payment_profile_id": "PPPPPPPPPPPPPPPPPPPP"
}
```

Use this only after confirming the new Payment Profile with the user.

### Update Credentials

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Use `secure_form_id` only after creating a Secure Form and the user completing it.

Never ask the user to paste credentials into chat.

---

## Why the Three Post-Creation Areas Should Often Be Separate

It may be easier and safer to handle the following in separate edit/import operations:

1. Shipping method mapping.
2. Alternate/offline payment method mapping.
3. Product import/update.

Reason:

```text
Each area requires different decisions, different IDs, different mapping rules, and different business context.
```

Shipping methods require mapping remote shop shipping IDs to RevCent shipping providers/provider methods.

Alternate/offline payment methods require deciding whether each remote method maps to a RevCent third-party integration.

Products require deciding whether to create or edit each product, preserving `internal_id`, assigning `third_party_shop`, configuring shippable behavior, subscriptions, trials, product groups, and fulfillment.

Recommended approach:

```text
Edit 1: shipping_methods
Edit 2: offline_payment_methods
Import/update products separately using CreateProduct/EditProduct
```

This reduces mistakes and makes each step easier to review with the user.

---

# Part 1: Retrieving and Adding Shipping Methods

## When to Retrieve Shipping Methods

After a User Shop has been created and validated, retrieve remote shipping methods from WooCommerce or the supported third-party shop.

Use `GetUserShop`:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "remote_data": [
    "shipping_methods"
  ]
}
```

This retrieves shipping methods from the remote shop.

Important:

```text
remote_data applies to WooCommerce stores.
```

Use this before editing `shipping_methods`.

---

## Why Shipping Method Mapping Is Vital

Shipping method mapping connects the customer's selected WooCommerce shipping method to a RevCent shipping provider/provider method.

Without correct mapping:

- RevCent may not understand the selected remote shop shipping method,
- shipments may not use the correct carrier/provider method,
- fulfillment may receive incomplete or wrong shipping method context,
- support may not have reliable shipment/provider details,
- tracking/reporting may be weaker,
- WooCommerce initial Sale shipments may be configured incorrectly.

Conceptual flow:

```text
Customer selects shipping method in WooCommerce checkout
    ↓
WooCommerce sends order/shipping context to RevCent
    ↓
RevCent looks at User Shop shipping_methods mapping
    ↓
Remote method maps to RevCent provider/provider_method
    ↓
Shipment has correct shipping context
```

---

## Shipping Method Schema

`EditUserShop.shipping_methods` is an array of objects.

Each object requires:

| Field | Required | Description |
|---|---:|---|
| `third_party_shipping_id` | Yes | Remote shop ID for the shipping method. Use the ID returned by `remote_data.shipping_methods`. |
| `third_party_shipping_name` | Yes | Remote shop shipping method name returned by `remote_data.shipping_methods`. |
| `provider` | Yes | 20-character RevCent shipping provider ID. |
| `provider_method` | Yes | 20-character RevCent provider method ID associated with the provider. |

Example:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "shipping_methods": [
    {
      "third_party_shipping_id": "flat_rate:1",
      "third_party_shipping_name": "Flat Rate",
      "provider": "PPPPPPPPPPPPPPPPPPPP",
      "provider_method": "MMMMMMMMMMMMMMMMMMMM"
    }
  ]
}
```

---

## Shipping Methods Are a Full Replacement Array

Important:

```text
When editing shipping_methods, include all shipping methods that should remain.
```

The array is replaced in its entirety.

Unsafe example:

```text
Current saved methods:
- Flat Rate
- Free Shipping
- Local Pickup

Edit request includes:
- Flat Rate

Result:
- Free Shipping and Local Pickup are removed.
```

Safe workflow:

```text
1. GetUserShop to retrieve current saved shipping_methods.
2. GetUserShop remote_data: ["shipping_methods"] to retrieve remote methods.
3. Compare current saved methods vs remote methods.
4. Build the full final shipping_methods array.
5. Include every method that should remain.
6. Send EditUserShop with the full shipping_methods array.
7. Verify with GetUserShop.
```

---

## Shipping Method Mapping Workflow

Recommended AI/MCP workflow:

```text
1. Confirm User Shop is valid.
2. Call GetUserShop with remote_data: ["shipping_methods"].
3. Review remote_data.shipping_methods.
4. Review existing saved shipping_methods.
5. Identify each active remote shipping method.
6. Ask/confirm which RevCent provider/provider method each remote method maps to.
7. Build full final shipping_methods array.
8. Call EditUserShop with shipping_methods only.
9. Call GetUserShop to verify saved mappings.
```

Use a separate `EditUserShop` call for shipping methods.

Do not combine this with alternate payment mapping unless the mappings are already confirmed and low-risk.

---

## Shipping Method Mapping Example

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "shipping_methods": [
    {
      "third_party_shipping_id": "flat_rate:1",
      "third_party_shipping_name": "Flat Rate",
      "provider": "AAAAAAAAAAAAAAAAAAAA",
      "provider_method": "BBBBBBBBBBBBBBBBBBBB"
    },
    {
      "third_party_shipping_id": "free_shipping:2",
      "third_party_shipping_name": "Free Shipping",
      "provider": "AAAAAAAAAAAAAAAAAAAA",
      "provider_method": "CCCCCCCCCCCCCCCCCCCC"
    }
  ]
}
```

Only send this after confirming the provider and provider method IDs.

Do not guess these IDs.

---

## Shipping Methods vs Shipping Profiles

Shipping methods and Shipping Profiles are different.

| Concept | Purpose |
|---|---|
| User Shop shipping methods | Map customer-selected remote shop shipping method IDs to RevCent provider/provider method IDs. |
| Shipping Profiles | Define how RevCent calculates shipping rates for automated shippable-product events. |

Initial WooCommerce Sales can have shipping calculated by WooCommerce and sent to RevCent.

But:

```text
Subscription renewals and trial expirations involving shippable products require RevCent Shipping Profiles.
```

RevCent will not use the initial Sale shipping amount as the rate source for future subscription renewals or trial expirations.

---

# Part 2: Retrieving and Adding Alternate / Offline Payment Methods

## When to Retrieve Offline Payment Methods

After the User Shop is validated, retrieve remote offline/alternate payment methods.

Use `GetUserShop`:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "remote_data": [
    "offline_payment_methods"
  ]
}
```

This retrieves payment methods from the remote shop that are not processed as RevCent credit-card payments or PayPal.

---

## What Offline / Alternate Payment Methods Are

Offline/alternate payment methods include payment methods such as:

- Sezzle,
- Klarna,
- Afterpay,
- Affirm,
- Amazon Pay,
- manual/external payments,
- other Buy Now Pay Later providers,
- other payment methods that are not RevCent credit-card or PayPal payments.

In RevCent, these can be represented as Offline Payments so they are visible in the backend commerce lifecycle.

Related overview:

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

---

## Why Alternate Payment Mapping Is Vital

Alternate payment mapping ensures that payments completed through external/alternate WooCommerce payment methods are properly recorded and understood by RevCent.

Correct mapping helps RevCent:

- associate the payment with the correct Sale,
- associate payment with the correct Customer,
- associate payment with the correct third-party shop,
- associate payment with the correct provider/integration,
- retrieve payment details where supported,
- issue refunds where supported,
- improve customer support visibility,
- improve reporting,
- avoid forcing support teams to use provider dashboards for basic context.

If a payment method corresponds to a RevCent-supported third-party integration, map it.

Examples:

```text
Sezzle remote method → RevCent Sezzle integration
Klarna remote method → RevCent Klarna integration
Afterpay remote method → RevCent Afterpay integration
Affirm remote method → RevCent Affirm integration
Amazon Pay remote method → RevCent Amazon Pay integration
```

---

## Offline Payment Method Schema

`EditUserShop.offline_payment_methods` is an array of objects.

Each object supports:

| Field | Required | Description |
|---|---:|---|
| `id` | Yes | Remote shop ID for the offline payment method. |
| `name` | Yes | Remote shop payment method name. |
| `description` | No | Description returned by the remote shop. |
| `method_title` | No | Method title returned by the remote shop. |
| `method_description` | No | Method description returned by the remote shop. |
| `third_party_integration` | No | RevCent user third-party integration ID, or `null`. The site integration should be type `offline_payment` when applicable. |

Example:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "offline_payment_methods": [
    {
      "id": "sezzle",
      "name": "Sezzle",
      "description": "Sezzle Buy Now Pay Later",
      "method_title": "Pay with Sezzle",
      "method_description": "Split your payment with Sezzle.",
      "third_party_integration": "TTTTTTTTTTTTTTTTTTTT"
    }
  ]
}
```

If no RevCent integration should be associated:

```json
{
  "id": "manual_invoice",
  "name": "Manual Invoice",
  "third_party_integration": null
}
```

---

## Offline Payment Methods Are a Full Replacement Array

Important:

```text
When editing offline_payment_methods, include all methods that should remain.
```

The array is replaced in its entirety.

Unsafe example:

```text
Current saved methods:
- Sezzle
- Klarna
- Manual Invoice

Edit request includes:
- Sezzle

Result:
- Klarna and Manual Invoice are removed.
```

Safe workflow:

```text
1. GetUserShop to retrieve current saved offline_payment_methods.
2. GetUserShop remote_data: ["offline_payment_methods"] to retrieve remote methods.
3. Compare current saved methods vs remote methods.
4. Identify third-party integrations for supported methods.
5. Build full final offline_payment_methods array.
6. Include every method that should remain.
7. Send EditUserShop with offline_payment_methods only.
8. Verify with GetUserShop.
```

---

## Offline Payment Mapping Workflow

Recommended AI/MCP workflow:

```text
1. Confirm User Shop is valid.
2. Call GetUserShop with remote_data: ["offline_payment_methods"].
3. Review remote_data.offline_payment_methods.
4. Review existing saved offline_payment_methods.
5. Identify which methods are active/used by the store.
6. Identify matching RevCent third-party integrations.
7. Create or request creation of integrations where necessary.
8. Build full final offline_payment_methods array.
9. Call EditUserShop with offline_payment_methods only.
10. Call GetUserShop to verify saved mappings.
```

Use a separate `EditUserShop` call for offline/alternate payment methods.

Reason:

```text
Alternate payment mapping often requires separate business decisions and integration setup.
```

---

## Offline Payment Mapping Example

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "offline_payment_methods": [
    {
      "id": "sezzle",
      "name": "Sezzle",
      "description": "Buy now, pay later with Sezzle.",
      "method_title": "Sezzle",
      "method_description": "Split your purchase into installments.",
      "third_party_integration": "SSSSSSSSSSSSSSSSSSSS"
    },
    {
      "id": "klarna",
      "name": "Klarna",
      "description": "Klarna payment method.",
      "method_title": "Klarna",
      "method_description": "Pay with Klarna.",
      "third_party_integration": "KKKKKKKKKKKKKKKKKKKK"
    },
    {
      "id": "cod",
      "name": "Cash on Delivery",
      "description": "Manual payment method.",
      "method_title": "Cash on Delivery",
      "method_description": "Pay upon delivery.",
      "third_party_integration": null
    }
  ]
}
```

Only include third-party integration IDs that are correct and confirmed.

---

# Part 3: Retrieving and Adding Products

## Important: Products Are Not Added With `EditUserShop`

Products are retrieved through `GetUserShop` using `remote_data: ["products"]`.

But products are not added to RevCent through `EditUserShop`.

Correct flow:

```text
GetUserShop remote_data: ["products"]
    ↓
For each remote product:
    - CreateProduct if it does not exist in RevCent
    - EditProduct if it already exists in RevCent and needs updates
```

The `EditUserShop` operation is important to the shop setup process, but product import/update uses Product operations.

Related overview:

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

---

## When to Retrieve Products

After the User Shop is created, validated, and shipping/payment mappings are handled, retrieve products.

Use:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "remote_data": [
    "products"
  ]
}
```

Purpose:

```text
Retrieve products that have been created in the remote shop but not yet created in RevCent, or products updated in the remote shop that need to be updated in RevCent.
```

---

## Why Product Import Is Vital

Products are the foundation of RevCent ecommerce analysis and automation.

Correct product import lets RevCent connect WooCommerce purchases to:

- Sales,
- Product Sales,
- subscriptions,
- trials,
- shipments,
- fulfillment,
- product groups,
- refunds,
- PayPal transactions,
- Offline Payments,
- Email Templates,
- AI Assistants,
- AI Voice Agents,
- BigQuery reporting.

If products are not imported correctly, RevCent may not properly understand the line-item purchase context.

Critical mapping:

```text
third_party_shop = RevCent User Shop ID
internal_id = remote shop product ID
```

The remote product ID must be preserved as `internal_id`.

---

## Remote Product Fields

Remote products returned through `GetUserShop remote_data: ["products"]` can include fields needed for Product create/edit.

Important fields include:

| Field | Meaning |
|---|---|
| `exists_in_revcent` | Whether the product already exists in RevCent. |
| `id` | RevCent Product ID when the product already exists. |
| `internal_id` | Remote shop product ID. Must be preserved. |
| `sku` | Remote product SKU. |
| `name` | Product name. |
| `image_url` | Product image URL. |
| `url` | Product URL on remote shop. |
| `description` | Product description, if available. |
| `is_shippable` | Whether the product requires shipping. |
| Product pricing/status fields | Used to configure RevCent Product behavior where applicable. |

The exact fields depend on the remote shop and Product schema.

---

## Product Import Decision Rule

Use the remote product field:

```text
exists_in_revcent
```

Decision table:

| `exists_in_revcent` | Correct Action |
|---:|---|
| `false` | Use `CreateProduct`. |
| `true` | Use `EditProduct` if changes are needed. Do not create a duplicate. |

If `exists_in_revcent = true`, use the returned RevCent Product `id` for `EditProduct`.

If `exists_in_revcent = false`, create a new Product with:

```text
third_party_shop = user_shop_id
internal_id = remote product ID
```

---

## Product Create Example

```json
{
  "name": "Example WooCommerce Product",
  "sku": "EXAMPLE-SKU",
  "internal_id": "12345",
  "third_party_shop": "XXXXXXXXXXXXXXXXXXXX",
  "is_shippable": true
}
```

The exact fields should follow the live `CreateProduct` schema and the product's business purpose.

Do not omit `internal_id`.

Do not omit `third_party_shop`.

---

## Product Edit Example

```json
{
  "product_id": "PPPPPPPPPPPPPPPPPPPP",
  "name": "Updated Product Name",
  "sku": "UPDATED-SKU",
  "internal_id": "12345",
  "third_party_shop": "XXXXXXXXXXXXXXXXXXXX"
}
```

The exact `EditProduct` shape depends on the product fields being updated.

Only update fields that are intentionally being changed.

---

## Product Import Workflow

Recommended AI/MCP workflow:

```text
1. Call GetUserShop with remote_data: ["products"].
2. Review remote_data.products.
3. For each product:
       If exists_in_revcent = false:
           prepare CreateProduct
       If exists_in_revcent = true:
           compare remote values to RevCent values
           prepare EditProduct only if updates are needed
4. Preserve internal_id from the remote shop.
5. Assign third_party_shop as the User Shop ID.
6. Configure shippable settings.
7. Assign Fulfillment Account for shippable products.
8. Configure RevCent-only subscription settings if needed.
9. Configure RevCent trial settings if needed.
10. Add products to Product Groups where appropriate.
11. Confirm with the user before creating/updating products.
12. Run Product operations.
13. Verify products after import/update.
```

---

## Shippable Product Import Requirements

If a remote product is shippable, RevCent Product setup must include shipping/fulfillment configuration.

At minimum:

```text
is_shippable = true
fulfillment account assigned
shipping attributes configured
```

Do not rely only on WooCommerce shipping settings.

RevCent needs Product/Fulfillment configuration to manage backend shipment workflows.

Shippable products also need:

- User Shop shipping method mapping,
- Fulfillment Account,
- Shipping Profiles for subscription renewals or trial expirations,
- Product Groups for filtering/rules where appropriate.

---

## Subscription Product Import Requirements

WooCommerce/WordPress should not be used for subscriptions at all when RevCent is connected.

Subscriptions should be handled only by RevCent.

For subscription products:

```text
WooCommerce sells/displays the product.
RevCent creates and manages the subscription.
RevCent bills renewals.
RevCent manages subscription status/lifecycle.
```

Do not use WordPress/WooCommerce subscription plugins for:

- subscription creation,
- subscription billing,
- renewals,
- cancellations,
- lifecycle management.

When importing subscription products, configure RevCent subscription settings and Subscription Profiles.

For shippable subscription products, configure Shipping Profiles for renewal shipping calculation.

---

## Trial Product Import Requirements

If a remote product has trial behavior, configure trial behavior in RevCent.

For shippable trial products:

- configure trial shipping behavior,
- assign Fulfillment Account,
- configure Shipping Profile for trial expiration when shipping is required,
- configure Email Templates for trial lifecycle where needed,
- configure Customer Portal support where needed.

---

## Product Group Best Practice

It is best practice to place a shop's products into a Product Group.

Example:

```text
Main WooCommerce Store Products
```

or:

```text
Brand A WooCommerce Products
```

This helps with:

- organization,
- filtering,
- Shipping Profiles,
- Email Templates,
- AI Assistants,
- reporting,
- shop-specific workflows,
- product management.

---

## Recommended Separate Operation Plan

Because shipping methods, alternate payment methods, and products each require careful mapping, do them separately.

Recommended plan:

### Edit 1: Shipping Methods

```text
GetUserShop remote_data: ["shipping_methods"]
    ↓
Build full final shipping_methods array
    ↓
EditUserShop with shipping_methods only
```

### Edit 2: Alternate / Offline Payment Methods

```text
GetUserShop remote_data: ["offline_payment_methods"]
    ↓
Build full final offline_payment_methods array
    ↓
EditUserShop with offline_payment_methods only
```

### Product Import / Update

```text
GetUserShop remote_data: ["products"]
    ↓
CreateProduct / EditProduct per product
```

This approach makes review easier and reduces the risk of accidentally overwriting arrays or creating incorrect product mappings.

---

## Full Post-Creation / Edit Workflow

After `CreateUserShop` and validation, use:

```text
1. GetUserShop
2. Validate shop status / review saved fields
3. GetUserShop remote_data: ["shipping_methods"]
4. EditUserShop shipping_methods only
5. GetUserShop remote_data: ["offline_payment_methods"]
6. EditUserShop offline_payment_methods only
7. GetUserShop remote_data: ["products"]
8. CreateProduct or EditProduct for remote products
9. Configure shippable products, fulfillment, Shipping Profiles, subscriptions, trials, Product Groups
10. Test WooCommerce checkout/payment/shipping/refund/reporting flow
```

---

## Validation Checklist Before Editing Shipping Methods

Before sending `EditUserShop.shipping_methods`, verify:

- User Shop ID is correct.
- Remote shipping methods were retrieved.
- Current saved shipping methods were reviewed.
- Every active remote shipping method is included.
- Provider IDs are valid RevCent IDs.
- Provider method IDs are valid RevCent IDs.
- All existing methods that should remain are preserved.
- Removed methods are intentionally omitted.
- User confirmed final mapping.
- The edit request contains only `user_shop_id` and `shipping_methods` unless another change is intentionally included.

---

## Validation Checklist Before Editing Offline Payment Methods

Before sending `EditUserShop.offline_payment_methods`, verify:

- User Shop ID is correct.
- Remote offline payment methods were retrieved.
- Current saved offline payment methods were reviewed.
- Every active remote offline payment method is included.
- Supported providers are mapped to RevCent third-party integrations where applicable.
- `third_party_integration` is `null` only when no integration is needed or available.
- All existing methods that should remain are preserved.
- Removed methods are intentionally omitted.
- User confirmed final mapping.
- The edit request contains only `user_shop_id` and `offline_payment_methods` unless another change is intentionally included.

---

## Validation Checklist Before Importing Products

Before creating/updating products:

- User Shop ID is correct.
- Remote products were retrieved with `GetUserShop remote_data: ["products"]`.
- Each product's `exists_in_revcent` value was reviewed.
- Existing products are updated with `EditProduct`, not duplicated.
- New products use `CreateProduct`.
- `internal_id` is preserved from the remote shop.
- `third_party_shop` is set to the User Shop ID.
- SKU/name/image/URL are preserved where appropriate.
- Shippable products have Fulfillment Account configuration.
- Subscription products use only RevCent subscription settings.
- Trial products use RevCent trial settings.
- Product Groups are used for organization/filtering.
- User confirmed the import/update plan.

---

## Common Mistakes to Avoid

Do not:

- treat `shipping_methods` as a patch array,
- send only one shipping method when other saved methods should remain,
- treat `offline_payment_methods` as a patch array,
- send only one alternate payment method when others should remain,
- skip remote shipping method retrieval before mapping,
- skip remote offline payment method retrieval before mapping,
- skip remote product retrieval before product import,
- guess RevCent provider/provider method IDs,
- leave supported alternate payment methods unmapped to RevCent integrations,
- create duplicate products when `exists_in_revcent = true`,
- create Products without `third_party_shop`,
- create Products without `internal_id`,
- create shippable Products without Fulfillment Account configuration,
- use WordPress/WooCommerce for subscriptions instead of RevCent,
- rely on WooCommerce initial Sale shipping for subscription renewals/trial expirations,
- combine shipping, alternate payment, and product workflows into one step when each needs separate review,
- use operational endpoints for reporting instead of BigQuery.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Rename or update basic shop field | `EditUserShop` with only the specific field(s). |
| Update credentials | Create Secure Form, then `EditUserShop` with `secure_form_id`. |
| Retrieve remote shipping methods | `GetUserShop` with `remote_data: ["shipping_methods"]`. |
| Save shipping method mappings | `EditUserShop.shipping_methods` with full final array. |
| Retrieve alternate payment methods | `GetUserShop` with `remote_data: ["offline_payment_methods"]`. |
| Save alternate payment mappings | `EditUserShop.offline_payment_methods` with full final array. |
| Retrieve remote products | `GetUserShop` with `remote_data: ["products"]`. |
| Add new remote product to RevCent | `CreateProduct` with `third_party_shop` and `internal_id`. |
| Update existing remote product in RevCent | `EditProduct` using returned RevCent Product ID. |
| Report on shop/shipping/payment/product metrics | `BigQueryRunQuery`. |

---

## Final AI/MCP Instruction

Use `EditUserShop` carefully.

Simple top-level fields are partial edits, but `shipping_methods` and `offline_payment_methods` are full replacement arrays. Always retrieve current and remote methods first, build the complete final array, and include every method that should remain.

It is often safer to perform shipping method mapping and alternate payment mapping in separate `EditUserShop` calls because each requires individual review and mapping decisions.

Product retrieval/import is related to User Shop setup, but products are not added with `EditUserShop`. Retrieve products with `GetUserShop remote_data: ["products"]`, then use `CreateProduct` for products that do not exist and `EditProduct` for products that already exist.

Shipping methods, alternate payment methods, and products must be imported and mapped correctly for the shop to operate properly inside RevCent.


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