# RevCent Product Groups Overview for AI/MCP Clients Generated for AI and MCP clients that need to understand, create, edit, or use Product Groups in RevCent. This guide is based on the Product Group operations exposed by the RevCent MCP, plus related Product, Email Template, Payment Profile, and Project operations where Product Groups are commonly used. --- ## 1. What Product Groups Are A **Product Group** is a named collection of RevCent product IDs. Product Groups are useful when the user wants to treat multiple products as one logical segment for automation, routing, filtering, organization, or reporting. Use Product Groups when the user says things like: - “Group these products together.” - “Only send this email for this set of products.” - “Use a different gateway/payment flow for these products.” - “Show me products in this collection/category.” - “Organize these products under a project or business line.” A Product Group contains references to individual products, not copies of products. Deleting a Product Group disassociates its products from the group, but does **not** delete the products themselves. **Best practice for User Shops:** Always place the products belonging to a specific User Shop into a dedicated Product Group, often called a **shop group**. This makes the account easier to organize and gives AI/MCP clients a clean Product Group ID to use for filtering Email Templates, Payment Profiles, product lookups, reporting, and project organization. For example, if a user has a WooCommerce shop named `Main Store`, create or maintain a Product Group such as `Shop Group - Main Store` that contains the RevCent products associated with that shop. A shop group should be treated as an organizational layer around products from the same shop. It does not replace `third_party_shop` filters where those filters are explicitly needed, but it gives the user and AI/MCP clients a reusable product-level grouping that can be applied across more RevCent features. --- ## 2. Core Product Group Operations Always discover operations first with `GetOperationsList`, then retrieve the details for the exact operations needed with `GetOperationDetails` before calling `RunOperation`. ### `GetProductGroups` Returns a paginated list of Product Groups. **Use when:** - The user asks what Product Groups exist. - The user provides a Product Group name and you need to find its 20-character ID. - You need to avoid creating a duplicate Product Group. **Input fields:** | Field | Type | Required | Notes | |---|---:|---:|---| | `limit` | integer | Yes | Limit can range from 1 to 25. | | `page` | integer | Yes | Used for pagination. | **Returned group summary fields include:** - `id` - `name` - `description` - `enabled` - `created_date_unix` - `updated_date_unix` **AI/MCP behavior:** - If matching by name, paginate as needed. - Prefer exact name matches first. - If multiple close matches exist, present the options instead of guessing. --- ### `CreateProductGroup` Creates a new Product Group and returns a new `product_group_id`. **Use when:** - The user wants a new named group of products. - The user wants to create a reusable segment for filters, payment routing, email templates, reporting, or project organization. **Input fields:** | Field | Type | Required | Notes | |---|---:|---:|---| | `name` | string | Yes | Product Group name. | | `description` | string | No | Internal description. | | `enabled` | boolean | No | Whether the Product Group is enabled. | | `products` | array | No | 20-character Product IDs to associate immediately. | **Important:** If `products` is provided during creation, every Product ID in the array is automatically associated with the new Product Group. **Example request:** ```json { "name": "Trial Products", "description": "Products that start as a trial before converting to a paid subscription.", "enabled": true, "products": [ "XXXXXXXXXXXXXXXXXXXX", "YYYYYYYYYYYYYYYYYYYY" ] } ``` --- ### `GetProductGroup` Retrieves the full details of one Product Group. **Use when:** - You need the current membership before editing. - You need to confirm whether a product is already in the group. - You need to display the current Product IDs in a group. - You are about to edit membership and must avoid accidental disassociation. **Input fields:** | Field | Type | Required | Notes | |---|---:|---:|---| | `product_group_id` | string | Yes | 20-character Product Group ID. | **Returned fields include:** - `id` - `name` - `description` - `enabled` - `products` — array of Product IDs currently in the group - `created_date_unix` - `updated_date_unix` --- ### `EditProductGroup` Edits a Product Group. Only include fields the user wants to modify. **Use when:** - Renaming a Product Group. - Updating the description. - Enabling or disabling a group. - Replacing the Product Group’s full product membership. **Input fields:** | Field | Type | Required | Notes | |---|---:|---:|---| | `product_group_id` | string | Yes | 20-character Product Group ID. | | `name` | string | No | New Product Group name. | | `description` | string | No | New description. | | `enabled` | boolean | No | Whether the group is enabled. | | `products` | array | No | Full replacement list of Product IDs. | ## Critical Membership Rule When editing a Product Group, the `products` array is **authoritative**. If `products` is provided: - Product IDs included in the array will be associated with the group. - Any products previously in the group but **not** included in the array will be disassociated. - If `products` is provided as an empty array, all products will be disassociated from the group. If you are only changing `name`, `description`, or `enabled`, omit `products` entirely. **Safe add-product workflow:** 1. Run `GetProductGroup` for the target group. 2. Read the existing `products` array. 3. Add the new Product ID(s) to that array. 4. Run `EditProductGroup` with the complete updated `products` array. **Safe remove-product workflow:** 1. Run `GetProductGroup` for the target group. 2. Read the existing `products` array. 3. Remove only the Product ID(s) the user wants removed. 4. Run `EditProductGroup` with the complete remaining `products` array. **Dangerous example — do not do this unless the user truly wants only one product left in the group:** ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "products": ["NEWPRODUCTIDXXXXXXXX"] } ``` That request will disassociate every existing product not included in the array. **Safe rename example:** ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "name": "Updated Product Group Name" } ``` --- ### `DeleteProductGroup` Deletes a Product Group. **Use when:** - The user explicitly wants the group removed. - The group is no longer needed for filtering, payment routing, or organization. **Input fields:** | Field | Type | Required | Notes | |---|---:|---:|---| | `product_group_id` | string | Yes | 20-character Product Group ID. | **Important:** Deleting a Product Group disassociates any products in that group. It does not delete the products. **AI/MCP behavior:** - Before deletion, consider checking related configuration where the group may be referenced, especially Email Templates and Payment Profiles. - Do not delete a Product Group based only on a vague phrase like “remove the old group” if multiple possible matches exist. --- ## 3. Product Operations Related to Product Groups Product Groups are collections of product IDs, so AI/MCP clients often need to retrieve product details before creating or editing groups. ### `GetProducts` Returns products and supports `product_group_filter`. Useful inputs include: | Field | Type | Notes | |---|---:|---| | `date_start` | integer | Unix timestamp start date. Required by schema. | | `date_end` | integer | Unix timestamp end date. Required by schema. | | `limit` | integer | 1 to 25. Required by schema. | | `page` | integer | Pagination. Required by schema. | | `product_group_filter` | array | Filter products by one or more Product Group IDs. | | `shop_filter` | array | Filter products by one or more shop IDs. | | `subscription_profile_filter` | array | Filter by subscription profile. | | `metadata_filter` | array | Filter by metadata. | Product results include a `product_group` array containing Product Group IDs the product belongs to. **Use cases:** - Show all products in a Product Group. - Verify Product Group membership from the product side. - Find products to add to a group. - Audit which products are not grouped correctly. ### `GetProduct` Returns a single product and includes the product’s `product_group` array. **Use when:** - The user provides a Product ID and wants to know what Product Groups it belongs to. - You need to verify a product before associating it with a group. --- ## 4. Product Group Use Cases ### A. Email Template Filtering Email Templates support `filters.product_group`. Use this when the user wants an email to trigger only for events involving products in one or more Product Groups. **Relevant operations:** - `GetEmailTemplates` - `GetEmailTemplate` - `CreateEmailTemplate` - `EditEmailTemplate` **Filter shape for create/edit:** ```json { "filters": { "product_group": [ "XXXXXXXXXXXXXXXXXXXX" ] } } ``` `filters.product_group` is an array of 20-character Product Group IDs. Email Template filters can also include: ```json { "filters": { "campaign": ["XXXXXXXXXXXXXXXXXXXX"], "product": ["XXXXXXXXXXXXXXXXXXXX"], "product_group": ["XXXXXXXXXXXXXXXXXXXX"], "third_party_shop": ["XXXXXXXXXXXXXXXXXXXX"] } } ``` **Common examples:** - Send a different post-purchase email for “Subscription Products.” - Trigger a specific abandoned-cart email only for “High Ticket Products.” - Send warehouse or fulfillment emails only for “Physical Products.” - Send renewal notices only for “Trial Products” or “Continuity Products.” - Send support follow-up emails only for products in a specific brand, store, or funnel. **AI/MCP behavior for Email Template filters:** - Use `GetProductGroups` to resolve Product Group names to IDs. - Use `GetEmailTemplate` before editing an existing template. - When editing `filters`, provide only the filter arrays that should be modified. - Use an empty array only when intentionally removing that filter. - Do not confuse `filters.product` with `filters.product_group`. --- ### B. Payment Profile Filtering and Gateway Routing Payment Profiles support a payment-flow node type named `filter_product_group`. Use this when the user wants payment-routing logic to branch based on whether products in the payment request are in or not in certain Product Groups. **Relevant operations:** - `GetPaymentProfiles` - `GetPaymentProfile` - `CreatePaymentProfile` - `EditPaymentProfile` **Payment flow node type:** ```text filter_product_group ``` **Relevant `node_settings` fields:** | Field | Type | Meaning | |---|---:|---| | `in_product_group` | array | Checks whether all products related to the payment request are in the specified Product Group(s). | | `nin_product_group` | array | Checks whether any products related to the payment request are not in the specified Product Group(s). | | `filter_priority` | string | Optional priority used when multiple filters are evaluated at the same point. Lower values are checked earlier. | | `node_note` | string | Optional internal note for human readability in the flow UI. | **Simplified node example:** ```json { "id": "filter_product_group_1", "type": "filter_product_group", "node_settings": { "in_product_group": ["XXXXXXXXXXXXXXXXXXXX"], "filter_priority": "0", "node_note": "Route products in the High Ticket group to the high-risk gateway branch." } } ``` This is only a partial node example. A valid Payment Profile flow must still include valid `inputs`, `outputs`, `position`, and connected action nodes according to the Payment Profile schema. **Typical routing patterns:** - Route “High Ticket Products” to a gateway group with higher approval limits. - Route “Subscription Products” to gateways optimized for recurring transactions. - Abort or redirect payment flow when a product is not in an approved group. - Combine `filter_product_group` with `filter_campaign`, `filter_currency`, `filter_bin_profile`, or `filter_metadata` using `filter_merge_filters`. - Use different gateway selection rules for physical vs. digital products. **AI/MCP behavior for Payment Profiles:** - Payment Profile changes are high-impact because they control credit-card processing. - Always retrieve the existing Payment Profile with `GetPaymentProfile` before editing. - Preserve existing flow nodes unless the user explicitly wants them changed. - Never create or edit a Payment Profile from a partial mental model. The flow must be internally consistent. - When adding a `filter_product_group` node, ensure it is connected correctly through `inputs` and `outputs`. - Make sure the success branch and failure branch both lead to intentional next steps. --- ### C. Product Organization and Discovery Product Groups are useful for organizing products into business-friendly collections. Examples: - “Supplements” - “Digital Products” - “Physical Products” - “Trial Offers” - “Subscription Products” - “High Ticket Products” - “Shopify Imported Products” - “WooCommerce Product Line A” - “Products requiring special fulfillment” Use `GetProducts` with `product_group_filter` to list products that belong to one or more groups. --- ### D. Project Organization Projects can be used to organize associated entities, including Product Groups and Products. Relevant operations from the MCP operation list include: - `GetProjects` - `GetProject` - `ProjectAssociateEntity` - `ProjectDisassociateEntity` Use Product Groups with Projects when the user wants to organize a business line, product line, funnel, brand, or store setup. Example intent: > “Create a project for my supplement funnel and associate all supplement product groups with it.” AI/MCP behavior: - Retrieve the Project first if the project already exists. - Retrieve or create the Product Group first. - Associate the existing Product Group entity with the Project only when the user intends project-level organization. --- ### E. Reporting and Auditing Product Groups can support internal reporting workflows by acting as a stable segmentation layer. Examples: - Products in a group. - Products missing from expected groups. - Products grouped by fulfillment type. - Products grouped by payment-routing strategy. - Products grouped by campaign/funnel/offer type. For simple product listing, use `GetProducts` with `product_group_filter`. For analytics, aggregates, revenue reporting, counts, or large data mining across sales/transactions, use the appropriate analytics/data-query operation instead of paginating transactional list operations. --- ## 5. Recommended AI/MCP Workflows ### Workflow: Create a Product Group from product names 1. Use `GetProducts` or `SearchProducts` to identify the Product IDs. 2. Confirm the exact products if the names are ambiguous. 3. Use `GetProductGroups` to check whether a similar group already exists. 4. Use `CreateProductGroup` with `name`, optional `description`, optional `enabled`, and the selected `products` array. 5. Return the new `product_group_id` and a short summary of included products. ### Workflow: Add products to an existing Product Group 1. Use `GetProductGroups` to resolve the group name to `product_group_id`. 2. Use `GetProductGroup` to retrieve the current `products` array. 3. Use `GetProducts` or `SearchProducts` to resolve new products to Product IDs. 4. Merge existing and new Product IDs. 5. Use `EditProductGroup` with the complete merged `products` array. 6. Clearly state that the group membership was updated. ### Workflow: Remove products from an existing Product Group 1. Use `GetProductGroups` to resolve the group. 2. Use `GetProductGroup` to retrieve the current `products` array. 3. Remove only the user-requested Product IDs. 4. Use `EditProductGroup` with the complete remaining `products` array. 5. Confirm which products remain in the group. ### Workflow: Create or maintain a shop group for a User Shop 1. Use `GetUserShops` or `GetUserShop` when the user references a specific connected shop. 2. Use `GetProducts` with `shop_filter` when available, or otherwise resolve the products associated with that User Shop. 3. Use `GetProductGroups` to check whether a shop group already exists for that shop. 4. If no shop group exists, use `CreateProductGroup` with a clear name such as `Shop Group - {Shop Name}` and include the shop's product IDs in the `products` array. 5. If a shop group already exists, use `GetProductGroup` to retrieve the current `products` array, merge in any missing shop products, and use `EditProductGroup` with the complete final `products` array. 6. Use this shop group for Email Template filtering, Payment Profile `filter_product_group` nodes, project organization, and future product discovery. ### Workflow: Apply a Product Group filter to an Email Template 1. Use `GetProductGroups` to resolve Product Group name(s) to IDs. 2. Use `GetEmailTemplates` or `GetEmailTemplate` to resolve the target Email Template. 3. Use `EditEmailTemplate` and include: ```json { "email_template_id": "XXXXXXXXXXXXXXXXXXXX", "filters": { "product_group": ["YYYYYYYYYYYYYYYYYYYY"] } } ``` 4. Preserve unrelated filters unless the user explicitly wants them changed. 5. If removing the Product Group filter, pass an empty `product_group` array only when that is the explicit intent: ```json { "email_template_id": "XXXXXXXXXXXXXXXXXXXX", "filters": { "product_group": [] } } ``` ### Workflow: Use Product Groups in a Payment Profile 1. Use `GetProductGroups` to resolve Product Group name(s) to IDs. 2. Use `GetPaymentProfiles` or `GetPaymentProfile` to retrieve the target Payment Profile. 3. Review the current `payment_flow` before editing. 4. Add or modify a `filter_product_group` node. 5. Connect the filter node’s outputs intentionally: - `output_1`: condition met. - `output_2`: condition not met. 6. Ensure both branches lead to valid actions or intentional termination. 7. Use `EditPaymentProfile` only with a complete, valid flow update. --- ## 6. Common Mistakes to Avoid ### Mistake: Editing `products` with only the new product Bad: ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "products": ["NEWPRODUCTIDXXXXXXXX"] } ``` This removes any previous members not included. Good: ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "products": [ "EXISTINGPRODUCTIDXXX", "NEWPRODUCTIDXXXXXXXX" ] } ``` ### Mistake: Passing an empty `products` array unintentionally Bad unless the user explicitly wants to empty the group: ```json { "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "products": [] } ``` This disassociates all products from the group. ### Mistake: Confusing Product IDs and Product Group IDs - Product IDs identify individual products. - Product Group IDs identify the group. - `CreateProductGroup.products` and `EditProductGroup.products` expect Product IDs. - `filters.product_group` expects Product Group IDs. - `filter_product_group.node_settings.in_product_group` expects Product Group IDs. ### Mistake: Editing an Email Template filter without preserving intent When editing Email Template filters, only include filter arrays the user wants to modify. Empty arrays remove those filters. ### Mistake: Leaving User Shop products ungrouped If products belong to a User Shop, do not leave them only as individual products when the account needs automation or filtering. Create or maintain a dedicated shop group so AI/MCP clients can use one Product Group ID for shop-level Email Template filters, Payment Profile filters, reporting, and organization. ### Mistake: Treating a Payment Profile change as low-risk Payment Profiles control payment routing and processing. Product Group filters inside Payment Profiles can affect approvals, declines, retries, gateway selection, and flow termination. --- ## 7. Decision Guide | User intent | Best operation(s) | |---|---| | “Show me product groups” | `GetProductGroups` | | “Create a product group” | `CreateProductGroup` | | “What products are in this group?” | `GetProductGroup`; optionally `GetProducts` for product detail | | “Add products to this group” | `GetProductGroup` then `EditProductGroup` with full `products` array | | “Remove products from this group” | `GetProductGroup` then `EditProductGroup` with full remaining `products` array | | “Rename this group” | `EditProductGroup` with `name` only | | “Disable this group” | `EditProductGroup` with `enabled: false` | | “Delete this group” | `DeleteProductGroup` | | “Only send this email for this group” | `GetProductGroups`, `GetEmailTemplate`, `EditEmailTemplate` with `filters.product_group` | | “Route payments differently for this group” | `GetProductGroups`, `GetPaymentProfile`, `EditPaymentProfile` with `filter_product_group` in `payment_flow` | | “List products in this group” | `GetProducts` with `product_group_filter` | | “Organize products from this shop” | `GetUserShops` or `GetUserShop`, `GetProducts` with `shop_filter`, then `CreateProductGroup` or `EditProductGroup` | | “Associate this group with a project” | `GetProject`, `ProjectAssociateEntity` | --- ## 8. Minimal Operation Reference ### Product Group operations ```text GetProductGroups CreateProductGroup GetProductGroup EditProductGroup DeleteProductGroup ``` ### Frequently related operations ```text GetProducts GetProduct SearchProducts GetUserShops GetUserShop GetEmailTemplates GetEmailTemplate CreateEmailTemplate EditEmailTemplate GetPaymentProfiles GetPaymentProfile CreatePaymentProfile EditPaymentProfile GetProjects GetProject ProjectAssociateEntity ProjectDisassociateEntity ``` --- ## 9. AI/MCP Checklist Before Running a Product Group Mutation Before `CreateProductGroup`, `EditProductGroup`, or `DeleteProductGroup`: - Resolve names to IDs using list/get/search operations. - Verify every Product ID is a product, not a Product Group. - Verify every Product Group ID is a group, not a product. - If products are associated with a User Shop, prefer creating or updating a dedicated shop group for those shop products. - For `EditProductGroup`, omit `products` unless changing membership. - If changing membership, retrieve the current group first and send the full intended membership. - Treat empty arrays as destructive when editing membership or filters. - For Email Template filters, preserve unrelated filters unless the user asked to change them. - For Payment Profiles, retrieve and understand the full `payment_flow` before editing. - Return the affected ID and a concise summary of what changed. --- 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.