# RevCent MCP Guide: `EditProductGroup` Audience: AI agents and MCP clients working with RevCent Product Groups. Purpose: This guide explains how to safely use the `EditProductGroup` operation, with special emphasis on the `products` array behavior. The `products` array is a full replacement list. It is not an append, merge, or partial patch. --- ## Operation Summary `EditProductGroup` edits an existing Product Group in RevCent using the Product Group ID. Use this operation to change one or more of the following: - Product Group name - Product Group description - Product Group enabled status - The complete set of products associated with the Product Group Only include properties that should be modified. If you only want to rename a group, only send `product_group_id` and `name`. Do not include `products` unless you are intentionally replacing the group membership. --- ## Critical Rule: `products` Is Overwritten The `products` array in `EditProductGroup` is a complete replacement of the Product Group membership. If `products` is provided: - Every Product ID in the array will be associated with the Product Group. - Any previously associated product that is not included in the array will be disassociated from the Product Group. - If `products` is provided as an empty array, all products will be removed from the Product Group. Never send a partial `products` array unless the desired result is for the Product Group to contain only those products. --- ## Required Best Practice Before Modifying `products` Before modifying the `products` array, always run `GetProductGroup` first. Reason: `GetProductGroup` returns the existing Product Group details, including the current `products` array. The MCP client should use those existing Product IDs as the starting point, then add or remove IDs locally, and finally submit the complete intended product list to `EditProductGroup`. Safe workflow: 1. Use `GetProductGroups` if the Product Group ID is not known. 2. Use `GetProductGroup` with the target `product_group_id`. 3. Read the returned `products` array. 4. Build the full desired final list of Product IDs. 5. Confirm that the final list contains every product that should remain in the group. 6. Call `EditProductGroup` with `product_group_id` and the complete `products` array. Do not skip step 2 when adding or removing products. --- ## Input Schema ```json { "type": "object", "additionalProperties": false, "required": ["product_group_id"], "properties": { "product_group_id": { "type": "string", "description": "A 20 character product group ID." }, "name": { "type": "string", "description": "The Product Group name." }, "description": { "type": "string", "description": "The Product Group description." }, "enabled": { "type": "boolean", "description": "Whether the Product Group is enabled." }, "products": { "type": "array", "description": "All product(s) to associate with the Product Group. This is a full replacement list.", "items": { "type": "string", "description": "A 20 character product ID.", "minLength": 20, "maxLength": 20 } } } } ``` --- ## Output Schema A successful response includes the edited `product_group_id` and a result string. ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1710000000, "code": 1, "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "result": "success" } ``` --- ## Safe Edit Patterns ### Rename Only Do not include `products`. ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "name": "WooCommerce Store Products" } ``` ### Update Description Only Do not include `products`. ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "description": "All products imported from the WooCommerce store. Used for filtering email templates and payment profiles." } ``` ### Disable a Product Group Do not include `products` unless membership must also change. ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "enabled": false } ``` ### Add Products Safely First call `GetProductGroup`. Assume `GetProductGroup` returns: ```json { "id": "GROUPXXXXXXXXXXXXXXXX", "products": [ "PRODUCTAAAAAAAAAAAAA", "PRODUCTBBBBBBBBBBBBB" ] } ``` To add `PRODUCTCCCCCCCCCCCCC`, send the full final membership: ```json { "product_group_id": "GROUPXXXXXXXXXXXXXXXX", "products": [ "PRODUCTAAAAAAAAAAAAA", "PRODUCTBBBBBBBBBBBBB", "PRODUCTCCCCCCCCCCCCC" ] } ``` Do not send only the new product ID. Incorrect: ```json { "product_group_id": "GROUPXXXXXXXXXXXXXXXX", "products": [ "PRODUCTCCCCCCCCCCCCC" ] } ``` The incorrect request would remove `PRODUCTAAAAAAAAAAAAA` and `PRODUCTBBBBBBBBBBBBB` from the group. ### Remove Products Safely First call `GetProductGroup`. Assume `GetProductGroup` returns: ```json { "id": "GROUPXXXXXXXXXXXXXXXX", "products": [ "PRODUCTAAAAAAAAAAAAA", "PRODUCTBBBBBBBBBBBBB", "PRODUCTCCCCCCCCCCCCC" ] } ``` To remove `PRODUCTBBBBBBBBBBBBB`, send the full remaining list: ```json { "product_group_id": "GROUPXXXXXXXXXXXXXXXX", "products": [ "PRODUCTAAAAAAAAAAAAA", "PRODUCTCCCCCCCCCCCCC" ] } ``` ### Clear All Products Only send an empty `products` array when the user explicitly wants to remove every product association from the Product Group. ```json { "product_group_id": "GROUPXXXXXXXXXXXXXXXX", "products": [] } ``` This will disassociate all products from the Product Group. --- ## Best Practices for Shop Product Groups It is best practice for every connected user shop to have its products organized into a dedicated Product Group, often called a shop group. Examples: - `WooCommerce - Main Store Products` - `Shopify - Skin Care Store Products` - `WooCommerce - Test Store Products` - `Amazon Store - Imported Products` A shop group makes RevCent easier to operate because it gives AI/MCP clients and human operators a stable way to reference all products from a specific storefront. Shop groups are especially useful for: - Organizing imported or synchronized products from a user shop. - Filtering Email Templates so a template only triggers for purchases involving products from a specific shop. - Filtering Payment Profiles so routing logic can differ by store or product family. - Segmenting analytics and operational workflows by storefront. - Keeping store-specific products grouped even if individual product names, SKUs, or metadata change. When editing a shop group, always preserve all products that should remain associated with that shop. If a new product is imported from a shop, retrieve the current shop group with `GetProductGroup`, append the new Product ID to the existing `products` array, and submit the full updated array through `EditProductGroup`. --- ## Why Product Groups Matter Product Groups are not only labels. They are reusable operational references across RevCent. They can support: - Email Template filtering by `filters.product_group`. - Payment Profile routing with `filter_product_group` nodes. - Product organization by shop, category, funnel, subscription type, or fulfillment type. - Easier AI reasoning when multiple products belong to the same business concept. For AI/MCP clients, Product Groups reduce ambiguity. Instead of asking the user for a long list of individual Product IDs every time, the MCP can use one Product Group ID to represent a known set of products. --- ## Recommended AI/MCP Behavior When a user asks to modify a Product Group: 1. Determine whether the request changes metadata only or membership. 2. If changing only `name`, `description`, or `enabled`, omit `products`. 3. If changing membership, run `GetProductGroup` first. 4. Build the final full `products` array. 5. Check that every Product ID is 20 characters. 6. Explain that the product list will be replaced by the submitted list if the user is reviewing the action. 7. Call `EditProductGroup` only with the intended fields. When a user asks to add products to a Product Group: - Treat it as a read-modify-write workflow. - Never call `EditProductGroup` with only the new products. When a user asks to remove products from a Product Group: - Retrieve the current group first. - Remove only the requested Product IDs from the local list. - Submit all remaining Product IDs. When maintaining a shop group: - Prefer one dedicated Product Group per user shop. - Keep the group name and description clear enough for future AI/MCP clients to understand its purpose. - Use the shop group for Email Template and Payment Profile filtering when the logic should apply to all products from that shop. --- ## Common Mistakes ### Mistake: Sending only the products to add This causes every existing product not included in the request to be removed from the group. ### Mistake: Sending `products: []` as a placeholder This removes all products from the group. Omit `products` entirely when not changing membership. ### Mistake: Editing a group name and accidentally including stale products If the `products` array is included, it becomes authoritative. If the array is stale or incomplete, associations will be lost. ### Mistake: Treating Product Group membership as additive `EditProductGroup` does not append. It overwrites membership. ### Mistake: Modifying shop groups without checking current membership Shop groups often power filtering for Email Templates and Payment Profiles. Accidentally removing products from a shop group can cause automations or payment routing to stop matching expected products. --- ## Example: Maintain a WooCommerce Shop Group User request: > Add the new RevCent Product ID `PRODUCTCCCCCCCCCCCCC` to the WooCommerce Main Store product group. Correct MCP workflow: 1. Locate the Product Group ID if unknown using `GetProductGroups`. 2. Retrieve the group with `GetProductGroup`. 3. Read the existing `products` array. 4. Add `PRODUCTCCCCCCCCCCCCC` to the array. 5. De-duplicate the final array. 6. Call `EditProductGroup` with all Product IDs that should be in the group. Example final edit request: ```json { "product_group_id": "GROUPXXXXXXXXXXXXXXXX", "products": [ "PRODUCTAAAAAAAAAAAAA", "PRODUCTBBBBBBBBBBBBB", "PRODUCTCCCCCCCCCCCCC" ] } ``` --- ## Minimal Field Rules Use these field rules to avoid unintended changes: - To rename: send `product_group_id` and `name` only. - To update description: send `product_group_id` and `description` only. - To enable/disable: send `product_group_id` and `enabled` only. - To modify membership: send `product_group_id` and the complete final `products` array. - To clear membership: send `product_group_id` and `products: []` only after explicit intent. --- ## Quick Checklist Before Calling `EditProductGroup` - The `product_group_id` is present. - The Product Group ID is the intended target. - Optional fields are included only if they should change. - If `products` is included, it contains the full final membership. - `GetProductGroup` was called first if modifying `products`. - Empty `products` array is used only when intentionally clearing the group. - Product IDs are valid 20-character IDs. - For shop groups, all products that should remain in the shop group are included. --- ## Related Operations ### `GetProductGroups` Use this to list Product Groups when the Product Group ID is unknown. ### `GetProductGroup` Use this before modifying `products`. It returns the existing Product Group details, including the current `products` array. ### `EditProductGroup` Use this to edit Product Group metadata or replace the Product Group's full product membership. --- ## Summary for AI/MCP Clients `EditProductGroup` is safe for simple metadata edits when only the intended metadata fields are included. It becomes high-impact when `products` is included because the list is overwritten. The safest rule is: > Never include `products` in `EditProductGroup` unless you have first retrieved the current group with `GetProductGroup` and built the complete final list of products that should be associated with the group. For user shop products, maintain a dedicated shop group and update it carefully using the read-modify-write workflow. This improves organization and enables reliable filtering for Email Templates, Payment Profiles, and other RevCent workflows. --- 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.