# RevCent MCP Guide: `CreateProductGroup` This guide is written for AI/MCP clients that need to create Product Groups in RevCent correctly, safely, and with useful long-term organization. Product Groups are collections of RevCent product IDs. They are especially useful when products share a business context, such as all products from a single connected user shop, products in a brand line, products that should use the same email templates, or products that should follow the same payment-routing logic. --- ## Primary operation ```text CreateProductGroup ``` **Title:** Create A Product Group **Purpose:** Create a Product Group and receive a unique 20-character `product_group_id`. When the request includes the optional `products` array, every product ID in that array is automatically associated with the new Product Group at creation time. --- ## Why create a Product Group? Create a Product Group when products should be managed, filtered, routed, or targeted together. Common reasons include: 1. **Organizing products by shop** - Best practice: every user shop's products should be placed into a dedicated Product Group, often called a "shop group." - This makes it easier for AI/MCP clients and humans to understand which RevCent products belong to which store. - This is especially useful for WooCommerce or other connected shop products, where many products may be synced or created over time. 2. **Filtering Email Templates** - Email Templates can use a `filters.product_group` array. - This allows a template to send only when the event is related to products in one or more Product Groups. - Example: a post-purchase email for only products from a specific shop, brand, collection, or funnel. 3. **Filtering Payment Profiles** - Payment Profiles can include a `filter_product_group` node. - This allows payment-routing logic to branch based on whether the payment request includes products in a Product Group. - Example: route products from a high-risk category, trial funnel, or specific shop to a dedicated gateway path. 4. **Reusable targeting** - Product Groups allow one ID to represent many products. - This reduces repeated configuration across email templates, payment profiles, automations, AI Assistants, functions, and future workflows. 5. **Cleaner product management** - Product Groups reduce the need to repeatedly select or reason about many individual products. - AI/MCP clients can use Product Groups as stable containers when product lists change over time. --- ## Best practice: create a "shop group" for every user shop When a RevCent account has a connected user shop, it is best practice to create a dedicated Product Group for that shop's products. ### Recommended behavior for AI/MCP clients Before creating products for a connected shop, importing products, or configuring shop-specific filters: 1. Run `GetUserShops` to list available user shops if the user has not specified a shop. 2. If needed, run `GetUserShop` for the selected shop. 3. For WooCommerce shops, use `GetUserShop` with `remote_data: ["products"]` when the goal is to inspect products that exist remotely but may not yet exist in RevCent. 4. Run `GetProducts` with `shop_filter` when looking for RevCent products already associated with the selected user shop. 5. Check whether a Product Group already exists for the shop. 6. If no dedicated shop Product Group exists, create one using `CreateProductGroup`. 7. Include all current RevCent product IDs for that shop in the `products` array when creating the group, if the product IDs are known and should be immediately associated. 8. Maintain the group over time whenever shop products are added, removed, imported, or disabled. ### Recommended naming convention Use a clear, shop-specific name. Examples: ```text {Shop Name} - Shop Products {Shop Name} Product Group WooCommerce - {Domain} - Shop Products Shop Group - {Shop Name} ``` ### Recommended description convention Include the shop name, user shop ID if known, and the reason the group exists. Example: ```text Products associated with the {Shop Name} user shop. Use this group for shop-level organization, email template filters, payment profile filters, and AI/MCP workflows that need to target all products from this shop. ``` ### Why this matters A dedicated shop Product Group makes it much easier to: - apply one Email Template filter to all products from the shop; - route payments differently for a shop's products; - query/filter RevCent products by group; - avoid selecting products one-by-one in multiple places; - keep AI/MCP workflows predictable as the shop catalog changes; - distinguish products from multiple shops in one RevCent account. --- ## Input schema `CreateProductGroup` accepts the following request body. ```json { "name": "string", "description": "string", "enabled": true, "products": [ "XXXXXXXXXXXXXXXXXXXX" ] } ``` ### Required fields | Field | Type | Required | Description | |---|---:|---:|---| | `name` | `string` | Yes | The Product Group name. | ### Optional fields | Field | Type | Required | Description | |---|---:|---:|---| | `description` | `string` | No | The Product Group description. | | `enabled` | `boolean` | No | Whether the Product Group is enabled. | | `products` | `array` | No | Product IDs to associate with the Product Group immediately. Each product ID must be a 20-character RevCent product ID. | ### Important schema rules - Do not include unknown properties. - `name` is the only required field. - Each item in `products` must be a 20-character RevCent product ID. - Use the `products` array only when the product IDs are already known and should be associated immediately. - If the shop products have not yet been created in RevCent, create the Product Group first without `products`, then add products later using the appropriate edit workflow. - Creating a Product Group does not create products. It only creates the group container and optionally associates existing products. --- ## Output schema A successful `CreateProductGroup` response includes the new Product Group ID. ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1710000000, "code": 1, "product_group_id": "XXXXXXXXXXXXXXXXXXXX", "result": "string" } ``` ### Output fields | Field | Type | Description | |---|---:|---| | `api_call_id` | `string` | A 20-character API call ID. | | `api_call_unix` | `integer` | Unix timestamp of when the API call was initiated. | | `code` | `integer` | API response code. `1` means success. | | `product_group_id` | `string` | The 20-character Product Group ID that was created. | | `result` | `string` | Human-readable operation result. | --- ## Minimal request example Use this when the user wants to create a group but has not yet chosen products. ```json { "name": "Acme Shop - Shop Products", "description": "Products associated with the Acme Shop user shop. Use this group for shop-level organization, email template filters, payment profile filters, and AI/MCP workflows.", "enabled": true } ``` --- ## Request example with products Use this when the product IDs are already known and should be associated immediately. ```json { "name": "Acme Shop - Shop Products", "description": "Products associated with the Acme Shop user shop. Use this group for shop-level organization, email template filters, payment profile filters, and AI/MCP workflows.", "enabled": true, "products": [ "XXXXXXXXXXXXXXXXXXXX", "YYYYYYYYYYYYYYYYYYYY", "ZZZZZZZZZZZZZZZZZZZZ" ] } ``` --- ## Shop product workflow When creating a Product Group for a user shop's products, follow this workflow. ### 1. Identify the user shop If the user has not clearly identified the shop, list user shops. ```text GetUserShops ``` Use the returned shop names and IDs to identify the correct shop. ### 2. Retrieve shop details if needed ```text GetUserShop ``` For WooCommerce shops, `GetUserShop` can accept `remote_data` to retrieve remote shop data. ```json { "user_shop_id": "XXXXXXXXXXXXXXXXXXXX", "remote_data": ["products"] } ``` Use this when the AI/MCP client needs to inspect remote products that may not yet exist in RevCent. ### 3. Find RevCent products associated with the shop Use `GetProducts` with `shop_filter` to find products already created in RevCent for that user shop. ```json { "date_start": 0, "date_end": 4102444800, "limit": 25, "page": 1, "shop_filter": ["XXXXXXXXXXXXXXXXXXXX"] } ``` The returned product objects include `id`, `name`, and `product_group` data. ### 4. Create the shop Product Group If no existing Product Group represents the shop, create one with `CreateProductGroup`. Include the `products` array if the product IDs are known. ### 5. Store and reuse the Product Group ID After creation, keep the returned `product_group_id` available for related configurations such as: - Email Template filters - Payment Profile filter nodes - product retrieval by `product_group_filter` - Project associations - AI/MCP workflow decisions --- ## Email Template filtering use case Product Groups are useful for Email Templates because they allow one filter to represent many products. Example use cases: - Send a branded post-purchase email only for products from a specific shop. - Send a different abandoned-cart email for a specific shop's products. - Send a warranty, usage, or onboarding email only for products in a specific product line. - Send internal notifications only for products in a fulfillment-sensitive group. Conceptual Email Template filter: ```json { "filters": { "product_group": ["XXXXXXXXXXXXXXXXXXXX"] } } ``` Where `XXXXXXXXXXXXXXXXXXXX` is the Product Group ID returned by `CreateProductGroup`. --- ## Payment Profile filtering use case Product Groups are useful in Payment Profiles because payment flows can branch using `filter_product_group`. Example use cases: - Route products from a specific shop to a specific gateway group. - Route subscription products differently from one-time products. - Apply additional payment attempts only to products in a specific group. - Abort or redirect flows for products in restricted or high-risk categories. - Use different gateway logic for products from different storefronts. Conceptual payment-flow filter node: ```json { "type": "filter_product_group", "node_settings": { "in_product_group": ["XXXXXXXXXXXXXXXXXXXX"], "filter_priority": "0", "node_note": "Check whether the payment request includes products from Acme Shop." } } ``` --- ## Product retrieval use case `GetProducts` supports filtering products by Product Group using `product_group_filter`. Use this after creating a group to verify membership or to retrieve products by group. ```json { "date_start": 0, "date_end": 4102444800, "limit": 25, "page": 1, "product_group_filter": ["XXXXXXXXXXXXXXXXXXXX"] } ``` This is useful for AI/MCP clients because it allows the client to treat the Product Group as a reusable lookup container. --- ## Do not confuse Product Groups with other group types Product Groups are for products. They are different from: - **Customer Groups**: groups of customers. - **Gateway Groups**: groups of payment gateways. - **BIN Profiles**: groups/settings for BIN-based card filtering. - **Projects**: broader organizational containers that can associate multiple entity types. Use `CreateProductGroup` only when the grouping target is products. --- ## AI/MCP decision guide Use `CreateProductGroup` when: - the user asks to organize products into a group; - the user asks for a shop group; - the user is connecting or configuring a user shop and the shop does not already have a Product Group; - the user wants email templates to apply to a set of products; - the user wants payment routing to depend on a set of products; - the user wants to group products for easier future filtering; - the user wants to manage a product collection, brand, funnel, or subscription line. Do not use `CreateProductGroup` when: - the user wants to create an actual product; - the user wants to group customers; - the user wants to group gateways; - the user wants reporting only and does not need a persistent reusable group; - the products are not yet known and the user only asked for a one-time product search. --- ## Safety and correctness checklist before calling `CreateProductGroup` Before creating a Product Group, an AI/MCP client should confirm: - The user wants a new Product Group, not a product, customer group, or gateway group. - The Product Group name is clear and specific. - The group does not already exist under a similar name. - If the group is for a user shop, the correct shop has been identified. - If adding products at creation time, every product ID is a valid 20-character RevCent product ID. - If adding shop products, the products are already created in RevCent. - The description explains why the group exists and how it should be used. - `enabled` is set intentionally. If unsure, use `true` for active organizational groups. --- ## Important behavior of the `products` array In `CreateProductGroup`, the `products` array associates existing products with the new Product Group immediately. This is convenient when creating a shop group for known products. However: - It does not create products. - It should not contain remote shop product IDs unless those IDs are also RevCent product IDs. - It should not contain SKUs, names, URLs, or third-party product IDs. - It should contain only RevCent 20-character product IDs. For remote shop products, first ensure the remote products have corresponding RevCent products. Then use those RevCent product IDs in the `products` array. --- ## Recommended default for shop groups When a user shop exists and no Product Group has been created for it, prefer creating a group like this: ```json { "name": "{Shop Name} - Shop Products", "description": "Products associated with the {Shop Name} user shop. Use this group for shop-level organization, email template filters, payment profile filters, and AI/MCP workflows that need to target this shop's products.", "enabled": true, "products": [ "XXXXXXXXXXXXXXXXXXXX" ] } ``` If no products are available yet, omit `products`: ```json { "name": "{Shop Name} - Shop Products", "description": "Products associated with the {Shop Name} user shop. Use this group for shop-level organization, email template filters, payment profile filters, and AI/MCP workflows that need to target this shop's products.", "enabled": true } ``` --- ## Common mistakes to avoid 1. **Using remote shop product IDs in `products`** - The `products` array requires RevCent product IDs, not WooCommerce or external shop product IDs. 2. **Creating generic group names** - Avoid names like `Products` or `Shop`. - Use names that identify the shop, category, brand, or workflow. 3. **Skipping a shop group** - For connected shops, failing to create a dedicated shop group makes future filtering harder. 4. **Assuming Product Groups create products** - Product Groups only organize existing RevCent products. 5. **Forgetting future maintenance** - When products are later added to a shop, imported into RevCent, or removed, the shop Product Group should be reviewed and updated. 6. **Confusing Product Groups with Project associations** - A Product Group can help organize products, but it is not the same as a Project. Projects are broader organizational entities. --- ## Summary for AI/MCP clients `CreateProductGroup` should be used to create a reusable product container in RevCent. For user shops, it is a best practice to create a dedicated "shop group" containing that shop's RevCent products. This makes product organization clearer and makes future filtering easier for Email Templates, Payment Profiles, product retrieval, and AI/MCP workflows. When creating the group: - choose a clear name; - include a helpful description; - set `enabled` intentionally; - include `products` only when using valid RevCent product IDs; - store the returned `product_group_id` for later filtering and configuration. --- 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.