# RevCent MCP Guide: `CreateUserShop`

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

This document explains the `CreateUserShop` operation, its requirements, the correct setup process, and the required post-creation workflows for validation, fixing, shipping method retrieval/import, third-party/offline payment method retrieval/import, and product retrieval/import.

---

## Related Overview Files

AI/MCP clients should use these related overview files when creating and configuring a User Shop:

| Overview | Link | Why It Matters |
|---|---|---|
| Shop Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShop.md` | Explains Shops / Third-Party Shops, WooCommerce as the storefront, RevCent as the backend commerce engine, shop lifecycle, setup, tracking, payments, shipping, fulfillment, products, subscriptions, AI, emails, Sentinel, Customer Portal, and reporting. |
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` | Explains shipments, fulfillment, shipping method behavior, shipment status, tracking, and how RevCent handles order shipments. |
| 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, third-party shop product mapping, shippable products, subscriptions, trials, product groups, and product configuration. |
| Tracking Domain Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrackingDomain.md` | Explains DNS-based first-party tracking, SSL/DNS setup, visitor IDs, URL parameter metadata, conversion attribution, and why a shop domain should be DNS complete before the shop is treated as ready. |

---

## Source Operations

This guide is based on the following RevCent MCP operations:

| Operation | Purpose |
|---|---|
| `CreateUserShop` | Creates the user's connected third-party shop in RevCent. |
| `GetSiteShops` | Lists RevCent-supported shop integrations, such as WooCommerce. |
| `GetSiteShop` | Retrieves required fields and details for a specific Site Shop. |
| `CreateSecureForm` | Creates a secure credential form so shop credentials are not entered into AI/chat. |
| `ValidateUserShop` | Validates a created User Shop and checks RevCent plugin settings. |
| `FixUserShop` | Attempts to fix RevCent plugin settings after validation errors. |
| `GetUserShop` | Retrieves the User Shop and remote data such as shipping methods, offline payment methods, and products. |
| `EditUserShop` | Updates the User Shop, including mapped shipping methods and offline payment methods. |
| `CreateProduct` | Creates RevCent Products from remote shop products. |
| `EditProduct` | Updates existing RevCent Products mapped from remote shop products. |
| `GetTrackingDomains` | Lists Tracking Domains so the AI/MCP client can verify whether the shop domain already exists and whether DNS is complete. |
| `CreateTrackingDomain` | Creates a Tracking Domain for the shop/root domain if one does not exist. |
| `GetTrackingDomain` | Retrieves Tracking Domain details, DNS records, SSL status, DNS status, and URL parameter configuration. |
| `InitializeTrackingDomainSSL` | Starts SSL setup after A records are added to DNS and returns CNAME records for SSL validation. |
| `InitializeTrackingDomainDNS` | Completes DNS tracking setup after A records, SSL, and CNAME validation are ready. |

---

## Core Concept

A User Shop is the user's connected external shopping cart/store inside RevCent.

For WooCommerce:

```text
WooCommerce = storefront
RevCent = backend commerce engine
User Shop = the connected WooCommerce store inside RevCent
```

The User Shop lets RevCent connect to the external store and manage shop-originated commerce through RevCent's backend systems:

- Sales,
- Product Sales,
- customers,
- credit-card payments,
- PayPal transactions,
- Offline Payments / alternate payment methods,
- shipping methods,
- products,
- subscriptions,
- trials,
- fulfillment,
- Sentinel anti-fraud,
- Email Templates,
- AI Assistants,
- AI Voice Agents,
- BigQuery reporting.

Objects containing:

```text
third_party_shop
```

are referencing a RevCent User Shop.

For WooCommerce products, the RevCent Product should be created with:

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

---

## Operation Summary

Operation:

```text
CreateUserShop
```

Purpose:

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

The operation requires:

- a selected Site Shop,
- a Campaign,
- a Payment Profile,
- shop software version,
- required credentials/configuration for the selected Site Shop,
- completed Secure Form if credentials are needed.

For WooCommerce, the user must already have:

- the RevCent Payment plugin installed in WordPress,
- WooCommerce API key/secret created,
- required credentials ready to enter into a RevCent Secure Form.

Important:

```text
CreateUserShop only creates the User Shop.
It does not complete the full shop setup.
```

After creation, the AI/MCP client must run post-creation setup:

```text
ValidateUserShop
    ↓
FixUserShop if validation errors occur
    ↓
GetUserShop remote_data: ["shipping_methods"]
    ↓
EditUserShop shipping_methods
    ↓
GetUserShop remote_data: ["offline_payment_methods"]
    ↓
EditUserShop offline_payment_methods
    ↓
GetUserShop remote_data: ["products"]
    ↓
Create/Edit RevCent Products with third_party_shop + internal_id
```

---

## Site Shop vs User Shop

| Concept | Meaning |
|---|---|
| Site Shop | RevCent-supported shop integration type, such as WooCommerce. |
| User Shop | The user's actual connected shop/store instance. |

Examples:

```text
Site Shop = WooCommerce integration definition
User Shop = John's WooCommerce Store connected to RevCent
```

Use `GetSiteShops` to list available Site Shops.

Use `GetSiteShop` to inspect required fields for a selected Site Shop.

Use `CreateUserShop` to create the user's connected shop.

---

## DNS Tracking Domain Requirement Before Creating a Shop

Before creating a WooCommerce / third-party User Shop, the shop's root domain should already be configured as a RevCent Tracking Domain and have DNS setup complete.

This is vital.

A User Shop connects the external storefront to RevCent, but the Tracking Domain connects the visitor, URL parameters, attribution metadata, and conversion context to RevCent.

Recommended rule:

```text
Before CreateUserShop:
    Verify the shop's domain has a RevCent Tracking Domain
    Verify SSL is issued
    Verify DNS status is COMPLETE
```

Related overview:

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

The Tracking Domain overview explains that RevCent Tracking Domains use custom DNS and SSL for first-party visitor and conversion tracking. This helps RevCent connect:

```text
Visitor → Tracking activity → URL parameters / metadata → Sale / conversion
```

For WooCommerce and other storefronts, this is especially important because RevCent should be the backend commerce engine and the shop should be the storefront.

If the shop domain is not DNS complete before the User Shop is created and tested, the shop may still process commerce, but RevCent may not have complete visitor attribution, URL parameter metadata, visitor validation, or conversion context.

---

## Why DNS Tracking Must Be Complete First

A WooCommerce shop should not be treated as ready for full RevCent operation until the store domain's Tracking Domain DNS setup is complete.

DNS Tracking Domain completion helps RevCent:

- track visitors on the WooCommerce/storefront domain,
- persist visitor identity using first-party tracking,
- preserve attribution through checkout,
- capture URL parameters such as `utm_source`, `utm_campaign`, `gclid`, `fbclid`, `affiliate_id`, and `sub_id`,
- save tracked URL parameters as RevCent metadata,
- associate purchases with the correct visitor and marketing source,
- improve BigQuery reporting and conversion analysis,
- improve customer lifecycle analytics,
- improve chargeback/refund/fraud analysis,
- support stronger Sentinel visitor validation when enabled,
- give AI Assistants better metadata and attribution context,
- support more accurate ecommerce business decisions.

Important:

```text
Tracking the visit alone is not enough.
The conversion/Sale must be tied back to the visitor.
```

For WooCommerce, the RevCent plugin and Tracking Domain setup should work together so visitor identity is preserved through checkout and Sale creation.

---

## Tracking Domain Setup Lifecycle

The Tracking Domain overview describes this setup lifecycle:

```text
1. Create Tracking Domain for the shop's root domain.
2. Add returned A records to the domain's DNS provider.
3. Initialize SSL.
4. Add returned CNAME records to DNS for SSL validation.
5. Initialize DNS.
6. Confirm DNS status is COMPLETE.
7. Install/configure Track.js or the appropriate platform/plugin integration.
8. Confirm visitor IDs are passed into conversion/Sale flows.
9. Confirm URL parameters are saved as metadata.
```

For WooCommerce shop creation, the AI/MCP client should verify this lifecycle before calling `CreateUserShop` whenever possible.

The desired readiness state is:

```text
tracking_domain.dns.status = COMPLETE
tracking_domain.ssl.status = ISSUED
```

---

## Domain Choice for Tracking

A Tracking Domain should be created for the shop's root domain.

Example:

```text
example.com
```

not:

```text
www.example.com
```

The Tracking Domain overview explains that the root domain is used and the domain cannot be modified after creation.

Before creating a Tracking Domain, verify:

- the user owns the domain,
- the domain is the correct store/root domain,
- the user can modify DNS records,
- the user understands DNS propagation may take time,
- the domain should not be a temporary/staging domain unless the shop is intentionally a staging/test shop.

For a WooCommerce store at:

```text
https://www.example.com
```

the root tracking domain should usually be:

```text
example.com
```

unless RevCent/domain setup indicates otherwise.

---

## Tracking Domain Pre-Creation Workflow

Before calling `CreateUserShop`, AI/MCP clients should do the following:

```text
1. Confirm the shop URL/root domain.
2. Use GetTrackingDomains to check whether a Tracking Domain already exists for the domain.
3. If no Tracking Domain exists, create one with CreateTrackingDomain.
4. Have the user add the returned A records to DNS.
5. Initialize SSL with InitializeTrackingDomainSSL.
6. Have the user add the returned CNAME records to DNS.
7. Initialize DNS with InitializeTrackingDomainDNS.
8. Use GetTrackingDomain to confirm:
       ssl.status = ISSUED
       dns.status = COMPLETE
9. Confirm Track.js / plugin visitor tracking is configured.
10. Only then proceed to CreateUserShop when possible.
```

If the user must create the shop before DNS is complete, the AI/MCP client should clearly mark the setup as incomplete and return to DNS completion before treating the shop as production-ready.

---

## Tracking Domain and Sentinel

DNS Tracking Domain completion also matters for Sentinel.

Sentinel visitor validation is strongest when RevCent can associate visitor/session data with the payment attempt.

Do not enable aggressive visitor validation settings until DNS tracking is complete and visitor IDs are properly preserved through checkout.

Correct order:

```text
Tracking Domain DNS COMPLETE
    ↓
WooCommerce plugin / visitor tracking configured
    ↓
Create/validate User Shop
    ↓
Enable Sentinel baseline
    ↓
Carefully enable visitor validation if appropriate
```

If visitor validation is enabled before DNS tracking is complete, legitimate purchases without visitor IDs may be incorrectly treated as suspicious.

---

## Tracking Domain Pre-Creation Checklist

Before `CreateUserShop`, verify:

- Shop root domain is known.
- Tracking Domain exists for the shop root domain.
- User has added required A records.
- SSL has been initialized.
- User has added required CNAME records.
- SSL status is `ISSUED`.
- DNS has been initialized.
- DNS status is `COMPLETE`.
- Track.js / supported plugin visitor tracking is configured.
- Visitor IDs are expected to be preserved into checkout/Sale creation.
- URL parameters that should become metadata are configured or planned.
- User understands that incomplete DNS tracking can reduce attribution, metadata, reporting, and Sentinel visitor-validation quality.

---

## WooCommerce Requirements

For WooCommerce, the user must complete external setup before `CreateUserShop` is called.

Required prerequisites:

1. WooCommerce store exists.
2. User has WordPress admin access.
3. Shop root domain is configured as a RevCent Tracking Domain.
4. Tracking Domain SSL status is `ISSUED`.
5. Tracking Domain DNS status is `COMPLETE`.
6. RevCent Payment plugin is installed in WordPress.
7. WooCommerce REST API key and secret are created.
8. User has the correct shop URL.
9. RevCent Campaign exists.
10. RevCent Payment Profile exists.
11. Site Shop ID for WooCommerce is known.
12. Secure Form is created and completed for WooCommerce credentials.

WooCommerce should generally use:

```json
{
  "site_shop_version": "3"
}
```

The schema states that for WooCommerce stores, the default/value should be `"3"`.

---

## Credential Safety Requirement

Do not ask the user to paste WooCommerce API secrets or shop credentials into chat.

Shop credentials are sensitive.

Use `CreateSecureForm`.

Correct credential flow:

```text
GetSiteShops
    ↓
Choose WooCommerce Site Shop
    ↓
GetSiteShop
    ↓
Read required fields
    ↓
CreateSecureForm for the selected Site Shop
    ↓
User opens secure form link
    ↓
User enters WooCommerce credentials securely
    ↓
User confirms completion
    ↓
Use secure_form_id in CreateUserShop
```

Credentials that should never be pasted into chat include:

- WooCommerce consumer key,
- WooCommerce consumer secret,
- passwords,
- API keys,
- tokens,
- plugin secrets,
- any authentication secret.

---

## `CreateUserShop` Input Schema

Schema behavior:

```text
type: object
additionalProperties: false
```

Only send supported fields.

### Required Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | User Shop name. Must be unique. |
| `campaign_id` | string | Yes | 20-character Campaign ID associated with the shop. |
| `payment_profile_id` | string | Yes | 20-character Payment Profile ID used to process credit-card transactions. |
| `site_shop_id` | string | Yes | 20-character Site Shop ID, such as the WooCommerce Site Shop ID. |
| `site_shop_version` | string | Yes | Shop software version. For WooCommerce, use `"3"` unless the user has a specific confirmed reason otherwise. |

### Optional Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `description` | string | No | Description of the User Shop. |
| `url` | string | No | Shop URL. Confirm exact URL with the user. |
| `secure_form_id` | string | No / usually needed | 20-character Secure Form ID containing credentials/configuration. |

---

## Field Details

### `name`

The User Shop name must be unique.

Good examples:

```text
Main WooCommerce Store
Brand A WooCommerce Store
Example.com WooCommerce
US Store WooCommerce
```

Avoid names like:

```text
Shop
Test
WooCommerce
Store
```

unless that is truly sufficient and unique.

---

### `description`

Use the description to explain:

- brand,
- store purpose,
- domain,
- environment,
- payment profile,
- campaign,
- whether it is production or testing.

Example:

```text
Main WooCommerce storefront for Brand A. Uses RevCent as backend commerce system for payments, PayPal, alternate payments, subscriptions, shipping, fulfillment, Sentinel, emails, AI automation, and reporting.
```

---

### `url`

The shop URL should be the correct WooCommerce storefront URL.

Confirm the exact URL with the user.

Example:

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

Do not guess whether the domain should include:

- `www`,
- subdomain,
- trailing slash,
- staging domain,
- production domain.

Ask/confirm before creation when necessary.

---

### `campaign_id`

The Campaign associates shop activity with a RevCent Campaign.

If the user does not provide a valid Campaign ID:

```text
Use GetCampaigns to retrieve available campaigns.
Confirm the selected campaign with the user.
```

Do not guess.

---

### `payment_profile_id`

The Payment Profile determines how credit-card transactions from the shop are processed.

If the user does not provide a valid Payment Profile ID:

```text
Use GetPaymentProfiles to retrieve available payment profiles.
Confirm the selected payment profile with the user.
```

This is critical because WooCommerce credit-card payments will be processed through the Payment Profile associated with the User Shop.

---

### `site_shop_id`

The Site Shop ID identifies the supported shop integration type.

For WooCommerce, retrieve and confirm the WooCommerce Site Shop ID using:

```text
GetSiteShops
GetSiteShop
```

Do not guess the Site Shop ID.

---

### `site_shop_version`

Required.

For WooCommerce stores:

```json
{
  "site_shop_version": "3"
}
```

The schema states that WooCommerce stores should use version `"3"`.

Confirm the version with the user if they are using a special or non-standard WooCommerce setup.

---

### `secure_form_id`

Optional in schema, but generally required when credentials/configuration must be supplied.

Use a Secure Form when creating the shop so credentials are handled securely.

Example:

```json
{
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

---

## Example `CreateUserShop` Request

```json
{
  "name": "Main WooCommerce Store",
  "description": "Main WooCommerce storefront connected to RevCent.",
  "url": "https://example.com",
  "campaign_id": "CCCCCCCCCCCCCCCCCCCC",
  "payment_profile_id": "PPPPPPPPPPPPPPPPPPPP",
  "site_shop_id": "SSSSSSSSSSSSSSSSSSSS",
  "site_shop_version": "3",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

---

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

The returned `id` is the new User Shop ID.

Use this value as:

```text
user_shop_id
```

in post-creation operations.

It is also the value used as:

```text
third_party_shop
```

when creating or editing RevCent Products that originated from the remote shop.

---

## Required Process Before Calling `CreateUserShop`

### 0. Verify Tracking Domain DNS Completion

Before creating the User Shop, confirm the shop's root domain is DNS complete in RevCent.

Use the Tracking Domain workflow to verify:

```text
ssl.status = ISSUED
dns.status = COMPLETE
```

If the domain is not DNS complete, the AI/MCP client should guide the user through Tracking Domain setup first.

Do not treat the shop as production-ready until DNS tracking is complete.

---

### 1. Identify the Shop Type

Use:

```json
{}
```

with:

```text
GetSiteShops
```

Find the WooCommerce Site Shop if the user is connecting WooCommerce.

Then use:

```json
{
  "site_shop_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

with:

```text
GetSiteShop
```

to inspect required fields.

---

### 2. Confirm WooCommerce Plugin and API Key

Before creating a WooCommerce User Shop, confirm the user has:

```text
RevCent Payment plugin installed in WordPress
WooCommerce API key/secret created
```

Do not proceed if these do not exist.

The `CreateUserShop` operation description explicitly states that the appropriate RevCent plugin must be installed and credentials must be acquired before creating the User Shop.

---

### 3. Confirm Campaign and Payment Profile

Confirm:

```text
campaign_id
payment_profile_id
```

These are required.

The Payment Profile is especially important because it determines how WooCommerce credit-card transactions are processed.

---

### 4. Create and Complete Secure Form

Create a Secure Form using the selected Site Shop and required credential fields.

Then wait until the user indicates the form has been completed.

Use the resulting:

```text
secure_form_id
```

in the `CreateUserShop` request.

---

### 5. Confirm Final Details

Before calling `CreateUserShop`, confirm:

- shop name,
- shop URL,
- Tracking Domain DNS complete for the shop root domain,
- Campaign,
- Payment Profile,
- Site Shop,
- Site Shop Version,
- Secure Form completed,
- whether this is live or test setup,
- user understands post-creation validation and mapping are required.

---

## Post-Creation Process Is Required

Creating the User Shop is not the end of setup. Shipping methods, alternate/offline payment methods, and products must be retrieved/imported and mapped correctly before the shop should be treated as fully operational.

After `CreateUserShop`, the AI/MCP client should continue with:

1. `ValidateUserShop`
2. `FixUserShop` if validation returns errors
3. Shipping method retrieval/import
4. Offline/alternate payment method retrieval/import
5. Product retrieval/import
6. Product setup for shippable/subscription/trial products
7. Testing

Recommended full flow:

```text
CreateUserShop
    ↓
ValidateUserShop
    ↓
FixUserShop if validation errors occur
    ↓
ValidateUserShop again if needed
    ↓
GetUserShop remote_data: ["shipping_methods"]
    ↓
EditUserShop shipping_methods
    ↓
GetUserShop remote_data: ["offline_payment_methods"]
    ↓
EditUserShop offline_payment_methods
    ↓
GetUserShop remote_data: ["products"]
    ↓
CreateProduct / EditProduct for remote products
    ↓
Configure Fulfillment Accounts, Shipping Profiles, Product Groups, subscriptions/trials
    ↓
Test checkout/payment/shipping/refund/reporting flows
```
Recommended safety note:

```text
It is usually best to complete shipping method mapping, alternate/offline payment mapping, and product import as separate focused workflows.
```

This allows each mapping area to receive the attention it needs.

---

## Detailed Post-Creation Import Workflows

Creating the User Shop is only the first step.

A newly created WooCommerce / third-party User Shop is not fully operational until the following import and mapping workflows are completed:

1. Retrieve and map shipping methods.
2. Retrieve and map alternate/offline payment methods.
3. Retrieve and import/update products.

These workflows are vital.

If shipping methods, alternate payments, or products are imported incorrectly, RevCent may not correctly understand the shop's orders, payment methods, shippable products, fulfillment requirements, refunds, reporting, or automation.

Recommended principle:

```text
Do the three import workflows separately.
```

It is usually safer to handle each workflow in its own focused step:

```text
Workflow 1: Shipping method retrieval and EditUserShop.shipping_methods
Workflow 2: Alternate payment retrieval and EditUserShop.offline_payment_methods
Workflow 3: Product retrieval and CreateProduct/EditProduct
```

Reason:

```text
Shipping mapping, alternate payment + third-party integration mapping, and product import each require individual review and business decisions.
```

Do not rush these steps or combine them into a single broad operation unless all mappings are already known, verified, and approved.

---

## Why Separate Import Workflows Are Recommended

Although it may be technically possible to edit multiple shop configuration areas in one broader process, AI/MCP clients should usually keep them separate.

| Workflow | Why It Needs Individual Attention |
|---|---|
| Shipping methods | Each remote shipping method must be mapped to the correct RevCent shipping provider and provider method. Incorrect mapping can affect shipments and fulfillment. |
| Alternate/offline payments | Each remote alternate payment method must be mapped to a RevCent third-party integration where applicable. Incorrect mapping can affect payment details, refunds, support, and reporting. |
| Products | Each remote product must be created or updated correctly with `third_party_shop` and `internal_id`. Products also require shippable, fulfillment, subscription, trial, and Product Group decisions. |

Recommended structure:

```text
Complete shipping methods first.
Then complete alternate/offline payment methods.
Then import/update products.
Then configure product-specific fulfillment, shipping profiles, subscriptions, trials, and Product Groups.
```

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

---

# Import Workflow 1: Retrieve and Add Shipping Methods

## Purpose

Shipping method import/mapping connects the remote shop's shipping methods to RevCent shipping provider/provider method IDs.

This is required so RevCent understands how the remote shop's shipping methods relate to RevCent shipment and fulfillment behavior.

For WooCommerce:

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

This is especially important because initial WooCommerce Sales may already have shipping selected/calculated at checkout, but RevCent still needs the method mapping so the shipping context is meaningful inside RevCent.

Related overview:

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

---

## Step 1A: Retrieve Remote Shipping Methods

Use `GetUserShop` with:

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

The response may include remote shop shipping methods that need to be saved/mapped in RevCent.

AI/MCP clients should compare:

```text
remote_data.shipping_methods
```

against existing saved:

```text
shipping_methods
```

on the User Shop.

---

## Step 1B: Map Remote Shipping Methods

Each saved shipping method must include:

| Field | Required | Meaning |
|---|---:|---|
| `third_party_shipping_id` | Yes | Remote shop shipping method ID. |
| `third_party_shipping_name` | Yes | Remote shop shipping method name. |
| `provider` | Yes | RevCent shipping provider ID. |
| `provider_method` | Yes | RevCent shipping 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"
    },
    {
      "third_party_shipping_id": "free_shipping:2",
      "third_party_shipping_name": "Free Shipping",
      "provider": "PPPPPPPPPPPPPPPPPPPP",
      "provider_method": "NNNNNNNNNNNNNNNNNNNN"
    }
  ]
}
```

Do not guess provider or provider method IDs.

The provider/provider method mapping should be reviewed carefully because it affects shipping context and fulfillment behavior.

---

## Step 1C: Save Shipping Methods With `EditUserShop`

Use `EditUserShop` with the full final `shipping_methods` array.

Important:

```text
shipping_methods is a full replacement array.
```

When editing `shipping_methods`, include every method that should remain.

Unsafe pattern:

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

Request includes:
- Flat Rate only

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

Safe pattern:

```text
Retrieve current saved methods
    ↓
Retrieve remote methods
    ↓
Build final full shipping_methods array
    ↓
Include all methods that should remain
    ↓
EditUserShop with shipping_methods only
```

If there are no shipping methods, provide an empty array:

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

---

## Shipping Method Import Checklist

Before saving shipping methods, verify:

- User Shop ID is correct.
- User Shop has been validated.
- Remote shipping methods were retrieved.
- Current saved shipping methods were reviewed.
- Every active remote shipping method is represented.
- RevCent provider IDs are correct.
- RevCent provider method IDs are correct.
- All existing methods that should remain are included.
- Any removed methods are intentionally omitted.
- User confirmed the final mapping.

---

# Import Workflow 2: Retrieve and Add Alternate / Offline Payment Methods

## Purpose

Alternate/offline payment method import/mapping connects payment methods from the remote shop to RevCent Offline Payment handling and, where applicable, RevCent third-party integrations.

Offline/alternate payment methods include payment methods that are not processed as RevCent credit-card payments or PayPal.

Examples:

- Sezzle,
- Klarna,
- Afterpay,
- Affirm,
- Amazon Pay,
- manual/external payments,
- other Buy Now Pay Later providers,
- other non-credit-card / non-PayPal payment methods.

Related overview:

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

---

## Why Alternate Payment Mapping Is Vital

Alternate payment mapping is important because RevCent should still understand shop payments that were completed outside the normal RevCent credit-card flow.

Correct mapping helps RevCent:

- associate alternate payments with the correct Sale,
- associate payment details with the correct customer,
- associate payments with the correct third-party shop,
- connect payment provider context to reporting,
- retrieve payment details where supported,
- issue refunds through supported integrations where available,
- improve support workflows,
- reduce the need to search separate provider dashboards.

If an alternate payment method corresponds to a RevCent-supported third-party integration, it should be mapped.

Examples:

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

---

## Step 2A: Retrieve Remote Offline Payment Methods

Use `GetUserShop` with:

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

The response may include remote shop payment methods that need to be saved/mapped in RevCent.

AI/MCP clients should compare:

```text
remote_data.offline_payment_methods
```

against existing saved:

```text
offline_payment_methods
```

on the User Shop.

---

## Step 2B: Map Offline Payment Methods

Each saved offline payment method can include:

| Field | Required | Meaning |
|---|---:|---|
| `id` | Yes | Remote shop ID for the offline/alternate payment method. |
| `name` | Yes | Remote shop payment method name. |
| `description` | No | Remote method description. |
| `method_title` | No | Remote method title. |
| `method_description` | No | Remote method description/details. |
| `third_party_integration` | No | RevCent User Third Party Integration ID, or `null`. |

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 purchase with Sezzle.",
      "third_party_integration": "SSSSSSSSSSSSSSSSSSSS"
    },
    {
      "id": "manual_invoice",
      "name": "Manual Invoice",
      "description": "Manual invoice payment",
      "method_title": "Manual Invoice",
      "method_description": "Customer pays through manual invoice process.",
      "third_party_integration": null
    }
  ]
}
```

Use `third_party_integration: null` only when there is no applicable RevCent integration or the user explicitly chooses not to map the method.

---

## Step 2C: Save Offline Payment Methods With `EditUserShop`

Use `EditUserShop` with the full final `offline_payment_methods` array.

Important:

```text
offline_payment_methods is a full replacement array.
```

When editing `offline_payment_methods`, include every method that should remain.

Unsafe pattern:

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

Request includes:
- Sezzle only

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

Safe pattern:

```text
Retrieve current saved methods
    ↓
Retrieve remote methods
    ↓
Identify third-party integrations where applicable
    ↓
Build final full offline_payment_methods array
    ↓
Include all methods that should remain
    ↓
EditUserShop with offline_payment_methods only
```

If there are no offline payment methods, provide an empty array:

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

---

## Alternate Payment Import Checklist

Before saving offline/alternate payment methods, verify:

- User Shop ID is correct.
- User Shop has been validated.
- Remote offline payment methods were retrieved.
- Current saved offline payment methods were reviewed.
- Every active remote alternate payment method is represented.
- Supported methods are mapped to RevCent third-party integrations where applicable.
- `third_party_integration` is `null` only when intentional.
- All existing methods that should remain are included.
- Any removed methods are intentionally omitted.
- User confirmed the final mapping.

---

# Import Workflow 3: Retrieve and Add Products

## Purpose

Product import connects remote shop products to RevCent Products.

Products are essential because RevCent uses product context for:

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

Related overview:

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

---

## Products Are Retrieved Through `GetUserShop`, Not Added Through `EditUserShop`

Important:

```text
Products are not added to RevCent with EditUserShop.
```

Correct product import flow:

```text
GetUserShop remote_data: ["products"]
    ↓
For each remote product:
        if exists_in_revcent = false → CreateProduct
        if exists_in_revcent = true  → EditProduct if updates are needed
```

Use `EditUserShop` for shop settings, shipping methods, and offline payment methods.

Use Product operations for product import and updates.

---

## Step 3A: Retrieve Remote Products

Use `GetUserShop` with:

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

The response may include products that:

- exist in the remote shop but not in RevCent,
- already exist in RevCent,
- have changed in the remote shop and need updates in RevCent.

---

## Step 3B: Preserve Product Mapping

For every remote product, preserve the mapping:

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

This is critical.

Do not create remote shop products in RevCent without `third_party_shop`.

Do not create remote shop products in RevCent without `internal_id`.

The `internal_id` should be the remote shop product ID.

The `third_party_shop` should be the RevCent User Shop ID.

---

## Step 3C: Create or Edit Products

Use the remote product's existence status to decide what to do.

| Remote Product State | Correct Action |
|---|---|
| `exists_in_revcent = false` | Use `CreateProduct`. |
| `exists_in_revcent = true` | Use `EditProduct` only if updates are needed. |
| Product has a RevCent `id` | Use that ID for `EditProduct`. |
| Product is shippable | Configure shippable settings and Fulfillment Account. |
| Product is subscription-based | Configure RevCent subscription settings only. |
| Product has trial behavior | Configure RevCent trial settings. |

Example conceptual `CreateProduct` request:

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

The exact Product schema depends on the product's business purpose and the live Product operation schema.

---

## Product Import Requires Business Decisions

Product import often requires more attention than simple copying.

For each product, decide whether it needs:

- shippable configuration,
- Fulfillment Account,
- Shipping Profile support for subscription renewals or trial expirations,
- subscription settings,
- trial settings,
- Product Group assignment,
- pricing review,
- image URL,
- product URL,
- SKU preservation,
- metadata,
- tax or discount context,
- shop-specific filtering.

This is why product import should usually be handled separately from shipping method and alternate payment mapping.

---

## Shippable Product Requirements

If a remote shop product is shippable, configure the RevCent Product accordingly.

At minimum:

```text
is_shippable = true
Fulfillment Account assigned
shipping attributes configured
```

A shippable product should also have:

- mapped User Shop shipping methods,
- an enabled Fulfillment Account,
- Shipping Profiles for subscription renewals and trial expirations where needed,
- Product Group assignment for filtering and rate rules.

Do not rely on WooCommerce shipping settings alone.

RevCent must have its own product/fulfillment/shipping configuration for backend shipping and fulfillment to work correctly.

---

## Subscription Product Requirements

WordPress/WooCommerce should not be used for subscriptions 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 lifecycle.
```

Do not use WordPress/WooCommerce subscription plugins for:

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

For shippable subscription products:

```text
RevCent Shipping Profiles are required for renewal shipping calculation.
```

---

## Trial Product Requirements

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

For shippable trial products, also confirm:

- trial shipping behavior,
- Fulfillment Account,
- Shipping Profile for trial expiration if shipping is required,
- Email Templates for trial lifecycle,
- Customer Portal support where needed,
- AI Assistant / AI Voice Agent recovery workflows where useful.

---

## Product Group Best Practice

It is best practice to organize shop products into Product Groups.

Example Product Groups:

```text
Main WooCommerce Store Products
Brand A WooCommerce Products
WooCommerce Subscription Products
WooCommerce Trial Products
WooCommerce Shippable Products
```

Product Groups help with:

- organization,
- Shipping Profile qualifiers,
- Email Template filters,
- AI Assistant filters,
- reporting,
- shop-specific workflows,
- product maintenance.

---

## Product Import Checklist

Before creating/updating products, verify:

- User Shop ID is correct.
- Remote products were retrieved.
- `exists_in_revcent` was reviewed for every product.
- Existing products are updated, not duplicated.
- New products use `CreateProduct`.
- Existing products use `EditProduct` only when changes are needed.
- `third_party_shop` is set to the User Shop ID.
- `internal_id` is preserved from the remote shop product ID.
- SKU/name/image/url are preserved where useful.
- Shippable products have Fulfillment Accounts.
- Subscription products use RevCent-only subscription settings.
- Trial products use RevCent trial settings.
- Product Groups are assigned.
- User confirmed product import/update plan.

---

## Recommended Separate Operation Plan

Because the three import areas are all important and all require careful mapping, AI/MCP clients should usually proceed like this:

### 1. Shipping Methods

```text
GetUserShop remote_data: ["shipping_methods"]
    ↓
Review remote methods
    ↓
Map to RevCent provider/provider_method
    ↓
EditUserShop with shipping_methods only
    ↓
Verify saved mappings
```

### 2. Alternate / Offline Payment Methods

```text
GetUserShop remote_data: ["offline_payment_methods"]
    ↓
Review remote methods
    ↓
Map supported methods to RevCent third-party integrations
    ↓
EditUserShop with offline_payment_methods only
    ↓
Verify saved mappings
```

### 3. Products

```text
GetUserShop remote_data: ["products"]
    ↓
Review exists_in_revcent for every product
    ↓
CreateProduct for new products
    ↓
EditProduct for existing products that need updates
    ↓
Configure shippable/subscription/trial/product group details
    ↓
Verify imported products
```

This separate workflow is strongly recommended because the cost of incorrect mapping can be high.

---

## Import Failure / Mistake Impact

Incorrect import or mapping can cause serious downstream issues.

| Incorrect Setup | Possible Impact |
|---|---|
| Shipping methods not mapped | Shipment provider/method context may be missing or wrong. |
| Wrong shipping provider/method | Fulfillment/shipping behavior may be incorrect. |
| Alternate payments not mapped | Payment details/refunds/reporting may be incomplete. |
| Wrong third-party integration | Refunds/details may route incorrectly or fail. |
| Products missing `internal_id` | Remote product cannot be reliably matched to RevCent Product. |
| Products missing `third_party_shop` | Product loses shop-origin context. |
| Duplicate products | Reporting, filters, Product Sales, subscriptions, and fulfillment may become inconsistent. |
| Shippable product missing Fulfillment Account | Product may not fulfill correctly. |
| Subscription product handled by WooCommerce plugin | Duplicate/conflicting subscription billing can occur. |
| Missing Shipping Profile for subscription/trial products | Renewal/trial shipment shipping rate may not calculate correctly. |

AI/MCP clients should treat these import workflows as required setup, not optional cleanup.

---

## Step 1 After Creation: `ValidateUserShop`

Immediately after creation, run:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

with:

```text
ValidateUserShop
```

Purpose:

```text
RevCent connects to the shop and checks the RevCent plugin settings.
```

If validation succeeds, continue setup.

If validation returns an error, read the result and consider `FixUserShop`.

Do not assume that a newly created shop is operational until validation passes.

---

## Step 2 If Needed: `FixUserShop`

If `ValidateUserShop` returns an error, run:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

with:

```text
FixUserShop
```

Purpose:

```text
RevCent attempts to fix required RevCent plugin settings.
```

Important limitations:

- `FixUserShop` is only intended to fix required RevCent plugin settings.
- It does not fix unrelated WooCommerce plugin issues.
- It does not fix custom store code.
- It does not fix unrelated WordPress/WooCommerce problems.
- If errors remain after running `FixUserShop`, notify the user that support/manual resolution may be required.

Recommended:

```text
Run FixUserShop once after validation error.
Then run ValidateUserShop again.
```

---

## Step 3: Retrieve Remote Shipping Methods

After validation succeeds, retrieve remote shop shipping methods.

Use `GetUserShop`:

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

This applies to WooCommerce stores.

Purpose:

```text
Get the remote shop's shipping methods so they can be mapped correctly to RevCent User Shop shipping methods.
```

Related overview:

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

---

## Why Shipping Method Mapping Matters

WooCommerce initial Sales may already include the shipping method and amount selected by the customer at checkout.

However, RevCent still needs the remote shipping method mapped to the correct RevCent provider and provider method so shipments can be understood and fulfilled correctly.

Without mapping:

- customer-selected WooCommerce shipping method may not be understood by RevCent,
- provider/method context may be missing,
- shipments may route incorrectly,
- fulfillment may be incomplete,
- tracking/provider details may be less reliable,
- support/reporting context may be weaker.

Conceptual flow:

```text
Customer chooses shipping method in WooCommerce
    ↓
WooCommerce sends order/payment/shipping context to RevCent
    ↓
RevCent uses saved User Shop shipping method mapping
    ↓
Shipment uses correct RevCent provider/provider method context
```

---

## Shipping Method Import / Mapping

After retrieving remote shipping methods, map them with `EditUserShop.shipping_methods`.

Schema for each `shipping_methods` item:

| Field | Required | Description |
|---|---:|---|
| `third_party_shipping_id` | Yes | Remote shop shipping method ID. |
| `third_party_shipping_name` | Yes | Remote shop shipping method name. |
| `provider` | Yes | 20-character RevCent shipping provider ID. |
| `provider_method` | Yes | 20-character RevCent shipping 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"
    }
  ]
}
```

Important:

```text
When editing shipping_methods, include all methods that should remain.
The array is replaced in its entirety.
```

If there are no shipping methods, provide:

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

Do not guess `provider` or `provider_method`.

Use:

```text
GetShippingProviders
GetShippingProvider
```

to identify valid provider/provider method IDs.

---

## Important Shipping Profile Distinction

Shipping method mapping is not the same as Shipping Profiles.

| Concept | Purpose |
|---|---|
| User Shop shipping method mapping | Maps remote WooCommerce shipping method IDs to RevCent provider/provider method IDs for shop-originated shipping context. |
| Shipping Profiles | Define how RevCent calculates shipping rates for shippable products when RevCent must calculate shipping. |

Initial WooCommerce Sales may have shipping determined by WooCommerce checkout.

But:

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

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

---

## Step 4: Retrieve Remote Offline / Alternate Payment Methods

After shipping methods are handled, retrieve remote offline/alternate payment methods.

Use `GetUserShop`:

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

Purpose:

```text
Get the remote shop's payment methods and map them correctly to RevCent User Shop offline payment methods with possible third-party integration.
```

Related overview:

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

---

## What Offline / Alternate Payment Methods Are

Offline Payment methods are payment methods not processed as RevCent credit-card payments or PayPal.

Examples:

- Sezzle,
- Klarna,
- Afterpay,
- Affirm,
- Amazon Pay,
- manual/external payments,
- other Buy Now Pay Later providers,
- other alternate payment methods.

RevCent represents these through Offline Payments so they can be associated with:

- customer,
- Sale,
- campaign,
- third-party shop,
- products,
- shipping,
- metadata,
- third-party integration,
- refunds,
- support,
- reporting.

---

## Offline Payment Method Import / Mapping

Map remote offline payment methods using `EditUserShop.offline_payment_methods`.

Schema for each `offline_payment_methods` item:

| Field | Required | Description |
|---|---:|---|
| `id` | Yes | Remote shop ID for the offline payment method. |
| `name` | Yes | Name of the offline payment method. |
| `description` | No | Description returned from remote shop. |
| `method_title` | No | Method title returned from remote shop. |
| `method_description` | No | Method description returned from remote shop. |
| `third_party_integration` | No | RevCent User Third Party Integration ID, or `null`. 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"
    },
    {
      "id": "manual_invoice",
      "name": "Manual Invoice",
      "third_party_integration": null
    }
  ]
}
```

Important:

```text
When editing offline_payment_methods, include all methods that should remain.
The array is replaced in its entirety.
```

If there are no offline payment methods, provide:

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

---

## Why Third-Party Integration Mapping Matters

If an offline/alternate payment method corresponds to a RevCent-supported integration, map it to that integration.

Examples:

- Sezzle,
- Klarna,
- Affirm,
- Afterpay,
- Amazon Pay.

Mapping to a RevCent third-party integration allows RevCent to provide stronger support, such as:

- retrieving payment details,
- connecting payment provider context to the Sale,
- supporting refunds where available,
- improving customer support visibility,
- improving BigQuery reporting,
- reducing dependency on provider dashboards.

Do not leave a supported alternate payment method unmapped if the business wants RevCent to retrieve details or issue refunds through the integration.

---

## Step 5: Retrieve Remote Products

After shipping and offline payment methods are handled, retrieve remote products.

Use `GetUserShop`:

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

Purpose:

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

Related overview:

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

---

## Product Import / Creation

Remote shop products should be created or updated as RevCent Products.

Critical mapping:

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

This mapping allows RevCent to understand which remote WooCommerce product corresponds to which RevCent Product.

When creating Products from WooCommerce:

- use the WooCommerce product ID as `internal_id`,
- use the RevCent User Shop ID as `third_party_shop`,
- preserve SKU where available,
- preserve product name,
- preserve image URL where available,
- preserve product URL where available,
- configure shippable settings,
- configure fulfillment account for shippable products,
- configure subscription settings in RevCent only,
- configure trial settings in RevCent only,
- organize shop products into Product Groups.

Example conceptual CreateProduct fields:

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

The exact Product schema depends on the product being created.

---

## Product Import Decision Rules

When remote products are retrieved:

| Situation | Correct Action |
|---|---|
| Remote product does not exist in RevCent | Use `CreateProduct` with `third_party_shop` and `internal_id`. |
| Remote product already exists in RevCent | Use `EditProduct` to update changed fields. |
| Product is shippable | Configure `is_shippable` and fulfillment account/shipping attributes. |
| Product is subscription-based | Configure RevCent subscription profile/settings. |
| Product has trial behavior | Configure RevCent trial settings. |
| Product belongs to a shop's product set | Add it to a Product Group for organization/filtering. |

Do not create duplicates.

Use `third_party_shop` + `internal_id` to identify existing mappings.

---

## Shippable Product Requirements

If a remote WooCommerce product is shippable, the RevCent Product must be configured correctly.

At minimum:

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

Shippable products should also have:

- correct shipping method mapping on the User Shop,
- Fulfillment Account configured and enabled,
- Shipping Profiles for renewals/trial expirations,
- correct product groups for filtering and shipping rules.

Do not assume that WooCommerce shipping settings alone are enough.

RevCent needs Product/Fulfillment/Shipping configuration to handle the backend order shipment lifecycle.

---

## Subscription Product Requirements

WooCommerce should not be used for subscription billing when the store is connected to RevCent.

Subscriptions should be handled only by RevCent.

For subscription products imported from WooCommerce:

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

Do not rely on WordPress/WooCommerce subscription plugins for subscription creation, billing, renewal, cancellation, or lifecycle management.

For shippable subscription products:

```text
RevCent Shipping Profiles are required for renewal shipping calculation.
```

---

## Trial Product Requirements

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

For shippable trial products, also confirm:

- trial shipping behavior,
- Fulfillment Account,
- Shipping Profile for trial expiration if shipping is required at expiration,
- Email Templates for trial upcoming/success/fail,
- Customer Portal support where needed.

---

## Product Group Best Practice

It is best practice to organize a shop's products into Product Groups.

For WooCommerce shops, create a Product Group such as:

```text
Main WooCommerce Store Products
```

or:

```text
Brand A WooCommerce Products
```

Benefits:

- cleaner filtering,
- cleaner Shipping Profile qualifiers,
- easier Email Template filtering,
- easier AI Assistant filtering,
- easier reporting,
- better shop/product organization,
- easier future product maintenance.

---

## Full Recommended `CreateUserShop` Workflow

```text
1. Confirm the user wants to create a third-party shop / WooCommerce User Shop.
2. Confirm the shop root domain.
3. Verify a RevCent Tracking Domain exists for the shop root domain.
4. Verify Tracking Domain SSL status is `ISSUED`.
5. Verify Tracking Domain DNS status is `COMPLETE`.
6. Use GetSiteShops to find supported shop integrations.
7. Select WooCommerce Site Shop if applicable.
8. Use GetSiteShop to inspect required fields.
9. Confirm RevCent Payment plugin is installed in WordPress.
10. Confirm WooCommerce REST API key/secret exists.
11. Confirm shop URL.
12. Confirm Campaign ID.
13. Confirm Payment Profile ID.
14. Create Secure Form for credentials.
15. User completes Secure Form.
16. Call CreateUserShop.
13. Store returned User Shop ID.
14. Run ValidateUserShop.
15. If validation errors occur, run FixUserShop once.
16. Run ValidateUserShop again if needed.
17. Retrieve remote shipping methods with GetUserShop remote_data: ["shipping_methods"].
18. Map shipping methods with a focused EditUserShop operation containing the full final shipping_methods array.
19. Retrieve remote offline payment methods with GetUserShop remote_data: ["offline_payment_methods"].
20. Map offline payment methods with a separate focused EditUserShop operation containing the full final offline_payment_methods array.
21. Retrieve remote products with GetUserShop remote_data: ["products"].
22. Create or update RevCent Products with third_party_shop + internal_id.
23. Configure shippable product fulfillment.
24. Configure Shipping Profiles for subscription renewals/trial expirations.
25. Configure RevCent-only subscription settings.
26. Configure trial settings where needed.
27. Configure Product Groups.
28. Test checkout/payment/shipping/refund/reporting flow.
```

---

## Common Mistakes to Avoid

Do not:

- enable aggressive Sentinel visitor validation before DNS tracking is complete,
- treat a shop as production-ready when Tracking Domain SSL/DNS is incomplete,
- skip Tracking Domain setup for a WooCommerce/storefront domain,
- create a User Shop before the shop root domain is DNS complete in RevCent,
- create a User Shop before the RevCent plugin is installed,
- create a WooCommerce User Shop before WooCommerce API credentials exist,
- ask the user to paste credentials into chat,
- skip Secure Form when credentials are required,
- guess `site_shop_id`,
- guess `campaign_id`,
- guess `payment_profile_id`,
- guess `site_shop_version`,
- skip `ValidateUserShop`,
- repeatedly run `FixUserShop` instead of reading errors,
- assume `CreateUserShop` completes all setup,
- skip shipping method retrieval/mapping,
- skip offline payment method retrieval/mapping,
- skip product retrieval/import,
- edit `shipping_methods` without including all methods that should remain,
- edit `offline_payment_methods` without including all methods that should remain,
- leave supported alternate payment methods unmapped to third-party integrations,
- create duplicate Products instead of using `third_party_shop` + `internal_id`,
- create shippable Products without Fulfillment Accounts,
- rely on WooCommerce initial Sale shipping for subscription renewals or trial expirations,
- use WordPress/WooCommerce for subscriptions instead of RevCent,
- combine shipping method mapping, alternate payment mapping, and product import into one rushed workflow,
- treat `shipping_methods` as a patch array instead of a full replacement array,
- treat `offline_payment_methods` as a patch array instead of a full replacement array,
- import products without reviewing `exists_in_revcent`,
- import products without assigning Product Groups where appropriate,
- use operational list endpoints for reporting instead of BigQuery.

---

## AI/MCP Decision Guide

| User Intent | Correct Operation / Workflow |
|---|---|
| Check shop tracking domain readiness | `GetTrackingDomains` / `GetTrackingDomain`; confirm SSL `ISSUED` and DNS `COMPLETE` |
| Create tracking domain before shop | `CreateTrackingDomain`, then DNS A records, SSL initialization, CNAME records, DNS initialization |
| See available shop integrations | `GetSiteShops` |
| Inspect WooCommerce required fields | `GetSiteShop` |
| Securely collect credentials | `CreateSecureForm` |
| Create connected shop | `CreateUserShop` |
| Check if shop is configured correctly | `ValidateUserShop` |
| Attempt to fix plugin settings | `FixUserShop` after validation error |
| Retrieve remote shipping methods | `GetUserShop` with `remote_data: ["shipping_methods"]` |
| Save mapped shipping methods | `EditUserShop.shipping_methods` with full array |
| Retrieve remote alternate payment methods | `GetUserShop` with `remote_data: ["offline_payment_methods"]` |
| Save mapped alternate payment methods | `EditUserShop.offline_payment_methods` with full array |
| Retrieve remote products | `GetUserShop` with `remote_data: ["products"]` |
| Create RevCent product from remote product | `CreateProduct` with `third_party_shop` and `internal_id` |
| Update existing mapped product | `EditProduct` |
| Report on shop/product/payment metrics | `BigQueryRunQuery` |

---

## Validation Checklist Before Calling `CreateUserShop`

Before calling `CreateUserShop`, verify:

- User explicitly confirmed creation.
- Shop root domain has a RevCent Tracking Domain.
- Tracking Domain SSL status is `ISSUED`.
- Tracking Domain DNS status is `COMPLETE`.
- Track.js / supported plugin visitor tracking is configured or planned.
- Shop type is selected.
- Site Shop ID is known.
- Site Shop required fields were reviewed.
- RevCent plugin is installed in WordPress if WooCommerce.
- WooCommerce API key/secret exists if WooCommerce.
- Secure Form was created.
- User completed Secure Form.
- Campaign ID is valid.
- Payment Profile ID is valid.
- Shop URL is correct.
- `site_shop_version` is correct.
- For WooCommerce, `site_shop_version` is `"3"` unless explicitly confirmed otherwise.
- User understands validation/fix and post-creation import/mapping steps are still required.

---

## Post-Creation Checklist

After `CreateUserShop`, verify:

- `ValidateUserShop` was run.
- `FixUserShop` was run once if validation errors occurred.
- Validation was rechecked if Fix was used.
- Remote shipping methods were retrieved.
- Shipping methods were mapped to provider/provider method IDs.
- Remote offline payment methods were retrieved.
- Offline payment methods were mapped, with third-party integrations where applicable.
- Remote products were retrieved.
- RevCent Products were created/updated with `third_party_shop` and `internal_id`.
- Shippable products have Fulfillment Accounts.
- Subscription products use RevCent subscription settings only.
- Trial products use RevCent trial settings.
- Shipping Profiles exist for shippable subscription renewals/trial expirations.
- Product Groups are configured.
- Test checkout/order/payment/shipping/refund/reporting flows were completed.

---

## Final AI/MCP Instruction

`CreateUserShop` creates a RevCent-connected third-party shop, especially WooCommerce.

Before calling `CreateUserShop`, verify the shop root domain has a RevCent Tracking Domain with SSL `ISSUED` and DNS `COMPLETE`. This is vital for first-party visitor tracking, URL parameter metadata, conversion attribution, BigQuery reporting, Sentinel visitor validation, and tying the storefront visitor to the resulting RevCent Sale/conversion.

For WooCommerce, confirm the RevCent Payment plugin is installed, WooCommerce API credentials exist, a Secure Form is completed, Campaign and Payment Profile IDs are selected, and `site_shop_version` is set to `"3"` unless explicitly confirmed otherwise.

After creation, always run `ValidateUserShop`. If validation returns errors, run `FixUserShop` once, then validate again if needed.

Then complete the required post-creation setup:

```text
remote shipping methods → map with EditUserShop.shipping_methods
remote offline payment methods → map with EditUserShop.offline_payment_methods
remote products → create/edit RevCent Products with third_party_shop + internal_id
```

Shipping methods, alternate payment methods, and products are not optional follow-up concepts; they are part of properly operationalizing the shop inside RevCent. It is usually safer to handle them as three separate workflows because shipping provider mapping, alternate payment integration mapping, and product import each require individual attention.

Use the Shop Overview, Tracking Domain Overview, Shipping Overview, Offline Payment Overview, and Product Overview for deeper context.


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