# RevCent Products Overview This version also incorporates product-management and bundle guidance from the RevCent Knowledge Base: ```text https://kb.revcent.com/en/product https://kb.revcent.com/product/product-bundle ``` This document explains Products in RevCent for MCP/AI clients. It is based on the refreshed `CreateProduct` and `EditProduct` operation details. Products are core catalog records. They define what a business sells, how the item is priced, whether it ships, how it is fulfilled, whether it is a subscription or trial product, whether it is a bundle, how it maps to third-party shops, how product images are hosted, and how the product can be used in customer-facing, AI, automation, and reporting workflows. --- # Product Concept A Product can represent: ```text A physical product. A digital product. A subscription product. A trial product. A bundle product. A product from a third-party shop. A parent product or child/variant product. A product prepared for product listings or agentic commerce. ``` Products are used throughout RevCent: ```text Sales Product Sales Shipping Fulfillment Accounts Subscription Profiles Trials Product Groups Bundles Third-Party Shops Email Templates Customer support AI Assistants AI Voice Agents Functions BigQuery reporting ``` A Product should be treated as important ecommerce configuration, not just a name and price. --- --- # Product Management Concepts From the RevCent KB The RevCent Product KB should be treated as the broad conceptual source for how Products are created, edited, viewed, imported, and organized in RevCent: ```text https://kb.revcent.com/en/product ``` The KB organizes Product management around these practical areas: ```text View Products. Create or Edit a Product. Basic Details. Type Options. Trial Options. Subscription Options. Additional Options. Shipping Options. Bundle Options. Import Products. CSV File Import. Third-Party Shop Download. Import Table. Import Success / Import Error / Import Complete. ``` For MCP/AI, this means Product work should not be reduced to only the required API fields. When a user asks to create or edit a Product, MCP/AI should think through the same operational categories: ```text Basic catalog identity. Product type and behavior. Trial behavior. Subscription behavior. Additional identifiers. Shipping and fulfillment. Bundle configuration. Third-party shop mapping. Product image. Import/source of truth. ``` --- ## Basic Details Basic Product details include the core catalog identity and customer-facing information. MCP/AI should collect or verify: ```text Product name. SKU. Actual Product price. Description. HTML description, if needed. Product page URL. Product image URL. Enabled/disabled status. ``` The Product should remain disabled when key configuration is incomplete. Examples of incomplete configuration: ```text Missing fulfillment account for a shippable Product. Missing subscription profile for a subscription Product. Missing bundle settings for a bundle Product. Missing third-party shop internal_id for an external shop Product. Unconfirmed price or SKU. Missing direct Product image URL for a customer-facing listing. ``` --- ## Type Options Product type and behavior determine how RevCent should treat the Product. MCP/AI should identify whether the Product is: ```text Physical/shippable. Digital/non-shippable. Subscription-based. Trial-based. A bundle. A third-party shop Product. A parent/child variant Product. ``` These choices affect required fields and downstream business behavior. Examples: ```text A physical Product requires fulfillment planning. A subscription Product requires a subscription profile. A trial Product requires trial-day and trial-price decisions. A bundle Product requires bundled Product selection and unbundle method decisions. A third-party shop Product requires external ID mapping. ``` --- ## Additional Options Additional Product options are useful for mapping and reporting. MCP/AI should consider: ```text internal_id for third-party shop mapping. additional_id values for warehouse, supplier, ERP, marketplace, or legacy IDs. cost for margin/profit reporting. Product Groups for organization, filtering, and reporting. Parent Product when creating variants. Display/listing identifiers such as UPC, EAN, MPN, ISBN, ASIN, brand, material, condition, and category. ``` Do not invent identifiers. Use only verified IDs from the business, source shop, warehouse, supplier, or external system. --- ## Product Import Concepts The Product KB includes Product import workflows. MCP/AI should understand the difference between: ```text Creating one Product manually with CreateProduct. Editing one Product with EditProduct. Importing many Products through a CSV file import. Downloading/importing Products from a third-party shop. ``` When a user wants to add many Products, an import workflow may be more appropriate than repeatedly calling `CreateProduct`. Common Product import considerations: ```text CSV fields must map to Product fields. Third-party shop downloads require correct shop/source configuration. Imported Products may still need fulfillment accounts. Imported subscription Products may still need subscription profiles. Imported bundle Products may still need bundle settings. Imported third-party shop Products still need correct internal_id mapping. Imported Products may need direct image URLs if images should be hosted by RevCent. Import success and import error states should be reviewed before assuming all Products were created correctly. ``` MCP/AI should not treat import completion as proof every Product is fully ready to sell. Imported Products may still need review. # Product vs Product Sale A Product is the catalog definition. A Product Sale is a purchased instance of that Product inside a Sale. | Object | Meaning | |---|---| | Product | Catalog record: name, SKU, price, image, fulfillment, subscription profile, trial settings, bundle settings, listing fields. | | Product Sale | Purchase record: customer, sale, campaign, payment type, quantity, amount, refunds, and purchase context. | Example: ```text Product: Organic Coffee Beans - 2 lb Bag Product Sale: Customer purchased 2 units of Organic Coffee Beans on June 1. ``` Use Product operations to manage catalog configuration. Use Product Sale operations or BigQuery to analyze purchases, revenue, refunds, and performance. --- # CreateProduct `CreateProduct` creates a new Product and returns a `product_id`. Required fields: ```text name price sku ``` Minimum request: ```json { "name": "Organic Coffee Beans - 2 lb Bag", "price": 29.99, "sku": "COFFEE-2LB" } ``` Use `CreateProduct` only when the Product does not already exist. If there is a chance the Product already exists, MCP/AI should search or list Products first to avoid duplicates. --- # EditProduct `EditProduct` edits an existing Product. Required field: ```text product_id ``` All other fields are optional. Important: ```text EditProduct is a partial update operation. Only include fields that should be changed. ``` Example: ```json { "product_id": "XXXXXXXXXXXXXXXXXXXX", "price": 34.99 } ``` That request changes only the Product price. MCP/AI should not resend every Product property unless the user intentionally wants to update every included value. --- # No Unknown Fields Both `CreateProduct` and `EditProduct` use: ```text additionalProperties = false ``` Only send fields supported by the operation schema. Do not send unsupported fields such as: ```text image images image_file metadata inventory_policy warehouse_id category_name random custom fields ``` If Product metadata is needed and the Product operation does not support a `metadata` input field, create or edit the Product first, then use the appropriate metadata operation if supported for Product items. --- # Product Images: `image_url` Both `CreateProduct` and `EditProduct` support: ```text image_url ``` `image_url` is the Product image URL. When provided, RevCent will: ```text Download the image. Compress the image. Host the image within the RevCent CDN for optimal delivery. Make the Product image accessible through a RevCent CDN URL. Allow the Product image to be used in Email Templates. ``` This lets MCP/AI give RevCent a source image URL while RevCent handles optimized image hosting. --- # `image_url` Requirements `image_url` must be: ```text A direct URL to an image file. A JPG, JPEG, or PNG image. ``` Supported: ```text .jpg .jpeg .png ``` Not supported: ```text .webp .svg .gif .pdf HTML product pages Gallery pages Any webpage URL that is not the image file itself ``` Good examples: ```text https://cdn.example.com/products/coffee-2lb.jpg https://example.com/images/product-main.jpeg https://images.example.com/products/starter-kit.png ``` Bad examples: ```text https://example.com/products/coffee-2lb https://example.com/product-page.html https://example.com/images/product.webp https://example.com/images/product.svg ``` --- # `image_url` and Third-Party Shops If a Product is associated with a third-party shop, it is recommended to set `image_url` to the Product image from that third-party shop. Recommended third-party shop mapping: ```text third_party_shop = RevCent third-party shop ID internal_id = external shop Product ID url = external shop Product page URL image_url = direct external Product image URL sku = stable Product SKU ``` Do not use the product page URL as `image_url`. Use the direct image file URL. --- # Important EditProduct Image Behavior When using `EditProduct`, only provide `image_url` if the user wants to replace the existing Product image. Important: ```text If image_url is provided to EditProduct, RevCent removes previous versions of the Product image and replaces them with the new one. ``` Therefore: ```text Do not include image_url in EditProduct unless replacing the Product image is intentional. ``` Correct: ```json { "product_id": "XXXXXXXXXXXXXXXXXXXX", "image_url": "https://cdn.example.com/products/new-product-image.jpg" } ``` Incorrect: ```text Including image_url in every edit request just because the Product already has an image. ``` --- # Core Product Fields ## `name` The Product name. Good examples: ```text Organic Coffee Beans - 2 lb Bag Monthly Coffee Subscription Starter Supplement Bundle Premium Skincare Trial Kit ``` Poor examples: ```text Product 1 Test New Product Item ``` Product names affect support, reports, Product Sales, fulfillment, bundles, product listings, Email Templates, and AI workflows. --- ## `sku` The Product SKU. Use a stable SKU that can work across fulfillment, inventory, third-party shops, support, reporting, and external systems. Examples: ```text COFFEE-2LB SUPP-STARTER-KIT SUB-COFFEE-MONTHLY ``` --- ## `price` The actual transaction price used when the Product is sold. Example: ```json { "price": 29.99 } ``` Important: ```text price is the actual transaction price. price_sale is display-only and does not change the transaction price. ``` --- ## `description` and `description_html` Use `description` for a short plain-text description. Use `description_html` for richer customer-facing HTML display. Example: ```json { "description": "Organic medium roast coffee beans in a 2 lb bag.", "description_html": "

Organic medium roast coffee beans with notes of chocolate and citrus.

" } ``` --- ## `enabled` Whether the Product is active. Use: ```text enabled = true ``` only when the Product is ready. Use: ```text enabled = false ``` when the Product is a draft or is missing required setup such as fulfillment, subscription profile, bundle settings, shop mapping, confirmed pricing, or image/content review. --- ## `url` The Product URL at a third-party shop or storefront. This is not the image URL. ```text url = Product page URL image_url = direct image file URL ``` --- ## `internal_id` The Product internal ID. If the Product is associated with a third-party shop, it is extremely important to set `internal_id` to the ID of the Product from the third-party shop. Examples: ```text WooCommerce product ID Shopify-style product ID External catalog product ID Marketplace listing ID ``` Do not invent `internal_id`. Use the external Product ID from the source shop/system. --- # Pricing Fields | Field | Purpose | |---|---| | `price` | Actual transaction price. | | `price_trial` | Trial expiration price. Defaults to Product price. | | `price_subscription` | Subscription renewal price. Defaults to Product price. | | `cost` | Internal estimated cost for tracking/reporting. | | `msrp` | Display-only MSRP. | | `is_price_sale` | Display-only sale flag. | | `price_sale` | Display-only sale price. Does not affect transaction price. | | `is_discount` | Display-only discount flag. | | `discount_rate` | Display-only discount rate. | MCP/AI must not confuse display pricing with transaction pricing. --- # Trial Products A trial Product can use: ```text trial_days price_trial trial_shipping_setting ``` Allowed `trial_shipping_setting` values: ```text trial_expiration trial_creation both_trial_expiration_creation ``` Default: ```text trial_expiration ``` Meanings: | Value | Meaning | |---|---| | `trial_expiration` | Shipping is tied to trial expiration. | | `trial_creation` | Shipping is tied to trial creation. | | `both_trial_expiration_creation` | Shipping can apply to both trial creation and trial expiration. | Before configuring a trial Product, MCP/AI should confirm: ```text Trial length. Initial Product price. Trial expiration price. When shipping should happen. Whether the Product is shippable. Which Fulfillment Account should be used. ``` --- # Subscription Products A subscription Product requires: ```text subscription_profile ``` `subscription_profile` is the 20-character ID of the Subscription Profile associated with the Product. The schema states this is required if the Product is a subscription Product. Use: ```text GetSubscriptionProfiles ``` to list available Subscription Profiles and assign the appropriate one. Use `price_subscription` when the renewal price differs from the initial Product price. Example: ```json { "name": "Monthly Coffee Subscription", "price": 19.99, "price_subscription": 29.99, "sku": "COFFEE-SUB-MONTHLY", "subscription_profile": "PPPPPPPPPPPPPPPPPPPP" } ``` --- # Shippable Products A Product is shippable when: ```text is_shippable = true ``` Shippable Products use: ```text shipping_attributes ``` Shipping attributes include: | Field | Unit | Purpose | |---|---:|---| | `weight` | pounds | Product weight. | | `length` | inches | Product length. | | `width` | inches | Product width. | | `height` | inches | Product height. | | `fulfillment_account` | 20-character ID | Fulfillment Account used for this Product. | The schema states: ```text fulfillment_account is required if the Product is shippable. ``` Example: ```json { "is_shippable": true, "shipping_attributes": { "weight": "2", "length": "10", "width": "7", "height": "4", "fulfillment_account": "FFFFFFFFFFFFFFFFFFFF" } } ``` --- # Fulfillment Account Requirement All shippable Products should be associated with the correct Fulfillment Account. MCP/AI should use: ```text GetFulfillmentAccounts ``` to retrieve available Fulfillment Accounts and assign the correct one. Before enabling a shippable Product, verify: ```text Fulfillment Account exists. Fulfillment Account is enabled. Fulfillment Account is configured correctly. Fulfillment Account is tied to the correct Fulfillment Center. Product is assigned to the correct Fulfillment Account. ``` Important: ```text If a Product is shippable and the attached Fulfillment Account is disabled, the Product may not ship. ``` --- # Third-Party Shop Products If the Product is associated with a third-party shop, the schema says: ```text third_party_shop is required. ``` Use: ```text third_party_shop internal_id url image_url sku ``` Recommended mapping: ```text third_party_shop = RevCent third-party shop ID internal_id = external shop Product ID url = external Product page URL image_url = direct external Product image URL sku = stable Product SKU ``` Third-party shop Products should not be created or edited with guessed external IDs. --- # Parent and Child Products Use: ```text parent_product ``` when the Product is a child/variant Product. `parent_product` can be: ```text The internal_id of an existing Product. A 20-character RevCent Product ID. ``` Example: ```text Parent Product: T-Shirt Child Products: T-Shirt - Blue - Medium T-Shirt - Black - Large ``` Only use parent-child relationships when the business catalog actually needs them. --- # Additional IDs Use: ```text additional_id ``` for alternate Product identifiers. Each entry has: ```text name value ``` Example: ```json { "additional_id": [ { "name": "warehouse_sku", "value": "WH-12345" }, { "name": "supplier_id", "value": "SUP-9988" } ] } ``` Use cases: ```text Warehouse SKU. ERP ID. Supplier Product ID. Marketplace listing ID. Legacy Product ID. External fulfillment item ID. ``` --- --- # Product Bundle Concepts From the RevCent KB The Product Bundle KB should be read before MCP/AI creates or edits bundle Products: ```text https://kb.revcent.com/product/product-bundle ``` The KB explains that a Product can be configured as a bundle when one sellable Product represents multiple bundled Products. Conceptual terminology: ```text Bundle Product = the Product being sold as the bundle. Bundled Products = the component Products inside the bundle. ``` Example: ```text Bundle Product: Starter Supplement Bundle Bundled Products: Vitamin A Vitamin B Protein Powder ``` Bundle Products are useful when the business wants to sell a kit, pack, set, or grouped offer while still preserving the underlying component Products for fulfillment, reporting, or operational logic. --- ## Why Set a Product as a Bundle? A Product should be configured as a bundle when the customer buys one Product, but the business needs RevCent to understand that the sale includes multiple component Products. Examples: ```text Starter kit. Supplement stack. Skincare set. Multi-product sample kit. Subscription box. Trial kit. Buy-together offer. Physical kit that warehouse must pick as separate components. ``` Bundle Products are useful because they can help connect the customer-facing offer to the operational reality of the items being sold, shipped, reported on, or refunded. --- ## Selecting Bundled Products When configuring `bundle_settings.products`, MCP/AI must select the actual component Product IDs and specify: ```text id quantity price ``` Each component `id` must be a 20-character Product ID. Each component `quantity` should represent how many units of that component are included in one bundle. Each component `price` should represent the amount allocated to that component inside the bundle. Example: ```json { "is_bundle_product": true, "bundle_settings": { "products": [ { "id": "AAAAAAAAAAAAAAAAAAAA", "quantity": 1, "price": 25.00 }, { "id": "BBBBBBBBBBBBBBBBBBBB", "quantity": 2, "price": 25.00 } ], "unbundle_method": "unbundle_at_fulfillment" } } ``` In this example: ```text Product A: 1 × $25 = $25 Product B: 2 × $25 = $50 Total component allocation = $75 ``` --- ## Why Bundled Product Totals Should Equal Bundle Price The bundle Product price should generally equal the total allocated price of its bundled Products. Formula: ```text Bundle Product price = sum(component price × component quantity) ``` Example: ```text Bundle Product price = $75 Component A: 1 × $25 = $25 Component B: 2 × $25 = $50 Total bundled Product allocation = $75 ``` This matters because mismatched totals can create confusion for: ```text Product Sales. Revenue reporting. Refund allocation. Customer communication. Fulfillment. Bundle decomposition. AI analysis. BigQuery reporting. ``` MCP/AI should verify bundle totals before calling `CreateProduct` or `EditProduct`. --- ## Unbundle Methods The Product Bundle KB explains two unbundle methods: ```text unbundle_at_fulfillment unbundle_at_sale ``` These methods determine when the bundle is decomposed into its component Products. --- ### `unbundle_at_fulfillment` Use `unbundle_at_fulfillment` when the business wants the customer/sale to preserve the bundle concept, but fulfillment needs the component Products. This is often best for: ```text Physical kits. Warehouse picking. Customer-facing bundle offers. Bundles where fulfillment needs individual component SKUs. ``` Conceptual behavior: ```text Customer buys bundle Product. Sale can preserve the bundle Product. Fulfillment receives or uses bundled component Products. ``` --- ### `unbundle_at_sale` Use `unbundle_at_sale` when the business wants the bundle decomposed into component Product Sales immediately when the sale is created. This is often best for: ```text Immediate component-level Product Sales. Component-level reporting at sale time. Component-level refunds. Automation that needs component Product records right away. ``` Conceptual behavior: ```text Customer buys bundle Product. RevCent unbundles the bundle during sale creation. Sale/Product Sale records can expose component Products immediately. ``` --- ## Which Unbundle Method Should MCP/AI Choose? MCP/AI should not guess the unbundle method. Ask or infer only when the business workflow is explicit. Use decision guidance: ```text If warehouse/fulfillment needs component SKUs but customer-facing sale should remain a bundle, prefer unbundle_at_fulfillment. If reports/refunds/automation need component Product Sales immediately, prefer unbundle_at_sale. ``` Questions MCP/AI should consider: ```text Should the customer see the bundle Product or component Products? Should Email Templates show the bundle or components? Should the warehouse receive component SKUs? Should refunds happen at bundle level or component level? Should BigQuery reports see component Products at sale time? Should Functions or AI Assistants receive bundle or component Product data in events? ``` --- ## Viewing Bundle Products and Bundled Products The Product Bundle KB distinguishes between viewing: ```text Bundle Products. Bundled Products. ``` MCP/AI should preserve this distinction. ```text Bundle Product = the parent sellable bundle. Bundled Products = the components inside that bundle. ``` When debugging or explaining a bundle sale, MCP/AI should clearly state whether it is referring to the bundle Product itself or its component Products. --- ## Subscription and Trial Bundle Products The Product Bundle KB includes subscription and trial bundle concepts. A bundle Product can be combined with subscription or trial behavior when the business model requires it. Examples: ```text Subscription bundle: Monthly supplement kit containing multiple Products. Trial bundle: Starter kit trial that later bills at trial expiration. Shippable trial bundle: Trial kit ships at creation, expiration, or both. Shippable subscription bundle: Recurring kit that ships component Products on renewal. ``` Before creating or editing a subscription/trial bundle, MCP/AI should verify: ```text is_bundle_product bundle_settings.products bundle_settings.unbundle_method price component price allocation subscription_profile, if subscription Product price_subscription, if renewal price differs trial_days, if trial Product price_trial, if trial expiration price differs trial_shipping_setting, if trial shipping matters is_shippable shipping_attributes.fulfillment_account component Product fulfillment requirements image_url, if customer-facing ``` Do not configure subscription/trial bundles by assumption. --- ## Multiple Bundle Products in a Single Sale The Product Bundle KB indicates bundle Products can be used in sales alongside other Products, including other bundle Products. MCP/AI should be careful when a sale includes multiple bundle Products because event data, Product Sale records, fulfillment data, and reporting can include multiple bundle/component relationships. For automation and reporting: ```text Do not assume there is only one bundle. Do not assume every Product Sale is a component. Do not assume every component belongs to the same bundle. Use Product IDs and related sale/Product Sale data carefully. ``` --- ## Bundle Event Data Awareness Bundle behavior can affect event data. The Product Bundle KB includes event data concepts for: ```text Unbundle at fulfillment. Unbundle at sale. ``` MCP/AI should understand that Functions, AI Assistants, AI Voice Agents, Email Templates, and other event-driven workflows may receive different Product/Product Sale structures depending on the chosen unbundle method. Before writing automation that depends on bundle data, MCP/AI should inspect the relevant event data examples or current item data structure. Important: ```text The unbundle method affects what downstream automation sees. ``` # Bundle Products A Product can be a bundle of other Products. Use: ```text is_bundle_product = true bundle_settings ``` `bundle_settings` includes: ```text products unbundle_method ``` Each bundled Product has: ```text id quantity price ``` `id` must be a 20-character Product ID. Allowed `unbundle_method` values: ```text unbundle_at_fulfillment unbundle_at_sale ``` --- # Bundle Price Allocation For bundle Products, MCP/AI should verify: ```text Sum of component allocated prices equals bundle Product price. ``` Example: ```text Bundle Product price = $75 Component A: 1 × $25 = $25 Component B: 2 × $25 = $50 Allocated total = $75 ``` This matters for Product Sales, revenue reporting, refund allocation, fulfillment, and customer communication. --- # Bundle Unbundle Method ## `unbundle_at_sale` Use when the bundle should be decomposed into component Product Sales at sale time. Useful for: ```text Component-level reporting immediately. Component-level refunds. Downstream automation that needs component Products right away. ``` ## `unbundle_at_fulfillment` Use when the bundle should be decomposed for fulfillment. Useful for: ```text Physical kits. Warehouse picking. Customer-facing bundles where fulfillment still needs component SKUs. ``` MCP/AI should not guess the unbundle method. Ask how the business wants sale records, customer communication, and fulfillment to behave. --- # Product Groups Products can belong to Product Groups using: ```text product_group ``` This is an array of 20-character Product Group IDs. Product Groups are useful for: ```text Reporting. Filters. Payment routing. Promotions. Shipping logic. Product organization. AI analysis. Customer support segmentation. ``` MCP/AI should retrieve or confirm Product Group IDs before assigning them. --- # Display and Listing Fields Products include optional display/listing fields: ```text google_product_category msrp is_price_sale price_sale is_discount discount_rate in_stock stock brand material age_group condition rating_value rating_count upc isbn asin mpn ean image_url ``` These fields are useful for: ```text Product listings. Customer-facing displays. Agentic commerce. Email Templates. Customer Portals. AI product summaries. ``` --- # Google Product Category `google_product_category` is the Google Product category ID. It is used for Product listings including agentic commerce such as ChatGPT Instant Checkout. The category should be: ```text The most specific category possible that accurately describes the Product. ``` MCP/AI should not guess category IDs when confidence is low. --- # Agentic Commerce Readiness If the user wants the Product to be suitable for product listings or agentic commerce, MCP/AI should help collect: ```text Clear Product name. Accurate Product description. Actual Product price. Direct jpg/jpeg/png image_url. Product URL. Brand. Condition. Availability/in_stock. Stock quantity, if available. UPC/EAN/MPN/ISBN/ASIN when applicable. Google Product category. Accurate shipping and fulfillment configuration. ``` Do not invent identifiers. --- --- # ChatGPT Instant Checkout and ACP Product Readiness RevCent can make Products available for ChatGPT Instant Checkout through ACP, the Agentic Commerce Protocol. MCP/AI should understand this as an important product-listing use case: ```text RevCent Product data becomes the source used to list eligible Products for ChatGPT Instant Checkout through ACP. ACP allows Products to be exposed to agentic commerce experiences. ChatGPT Instant Checkout requires Products to have enough structured Product data to be safely discovered, displayed, and purchased. ``` A Product existing in RevCent does not automatically mean the Product is ready for ChatGPT Instant Checkout. MCP/AI should treat ChatGPT Instant Checkout readiness as a Product data-quality and configuration checklist. --- ## Fields Important for ChatGPT Instant Checkout Several RevCent Product fields are required or strongly important for ChatGPT Instant Checkout / ACP listing readiness. MCP/AI should ensure the Product has accurate values for: ```text name description or description_html price sku url image_url enabled in_stock stock, if available google_product_category brand, when applicable condition upc, ean, mpn, isbn, or asin when applicable shipping_attributes, if the Product is shippable fulfillment_account, if the Product is shippable ``` In ACP/listing terms, these fields help provide: ```text Product title. Product description. Product detail page URL. Main Product image. Current price. Availability. Stable identifier. Product category. Brand/manufacturer identity. Product condition. Merchant-side fulfillment readiness. ``` Do not assume optional display/listing fields are unimportant. For ChatGPT Instant Checkout, fields that may be optional for normal RevCent checkout can be important or effectively required for product discovery, listing quality, and checkout eligibility. --- ## RevCent Field Mapping for ChatGPT Instant Checkout MCP/AI should map RevCent Product fields to Instant Checkout / ACP concepts as follows: | RevCent Field | Instant Checkout / ACP Meaning | |---|---| | `name` | Product title/name shown to shoppers. | | `description` / `description_html` | Product description used for discovery and product understanding. | | `url` | Product detail page URL. | | `image_url` | Main Product image. Must be a direct JPG/JPEG/PNG image URL. | | `price` | Actual transaction price. | | `sku` | Stable merchant/product identifier. | | `internal_id` | External shop Product ID when imported from WooCommerce or another third-party shop. | | `third_party_shop` | RevCent user third-party shop ID associated with the Product. | | `enabled` | Product should generally be enabled to be actively listed/sold. | | `in_stock` | Product availability signal. | | `stock` | Product inventory quantity signal, if available. | | `google_product_category` | Product taxonomy/category for listings and agentic commerce. | | `brand` | Brand/manufacturer value, when applicable. | | `condition` | Product condition: `new`, `used`, or `refurbished`. | | `upc`, `ean`, `mpn`, `isbn`, `asin` | Product identifiers that improve matching and product trust. | | `is_shippable` | Whether the Product requires shipping. | | `shipping_attributes` | Weight/dimensions and fulfillment-account data for physical Products. | | `shipping_attributes.fulfillment_account` | Fulfillment Account required for shippable Products. | --- ## ChatGPT Instant Checkout Readiness Checklist Before MCP/AI treats a Product as ready for ChatGPT Instant Checkout, it should verify: 1. Product is intended to be available for ChatGPT Instant Checkout. 2. Product is enabled. 3. Product has a clear `name`. 4. Product has a stable `sku`. 5. Product has an accurate `price`. 6. Product has a useful `description` or `description_html`. 7. Product has a valid Product page `url`. 8. Product has a direct JPG/JPEG/PNG `image_url`. 9. Product image has been downloaded/compressed/hosted by RevCent through the Product image workflow. 10. Product has `in_stock` set accurately. 11. Product has `stock` set when inventory quantity is known. 12. Product has the most specific accurate `google_product_category`. 13. Product has `brand` when applicable. 14. Product has `condition`. 15. Product has UPC/EAN/MPN/ISBN/ASIN when applicable and known. 16. If the Product is shippable, it has `is_shippable = true`. 17. If the Product is shippable, it has `shipping_attributes.fulfillment_account`. 18. If the Product is shippable, the Fulfillment Account is enabled and correctly configured. 19. If the Product came from WooCommerce or another third-party shop, `third_party_shop` and `internal_id` are correctly mapped. 20. Product data is not guessed or invented. --- ## ChatGPT Instant Checkout and Product Images For ChatGPT Instant Checkout, Product images are especially important. Use: ```text image_url ``` Rules: ```text image_url must be a direct URL to a JPG/JPEG/PNG file. image_url must not be a Product page URL. RevCent downloads, compresses, and hosts the image on the RevCent CDN. The hosted image can be used in Email Templates and other RevCent contexts. ``` For WooCommerce Products, use the direct WooCommerce Product image URL when possible. Do not use: ```text A WooCommerce Product page URL. A gallery page URL. A WebP image URL. An SVG image URL. A temporary signed URL likely to expire. ``` --- ## ChatGPT Instant Checkout and Category Data `google_product_category` is important for Product listings and agentic commerce. The Product category should be: ```text The most specific accurate Google Product category ID. ``` MCP/AI should not guess category IDs when uncertain. If the category is unknown, MCP/AI should help the user choose the correct category or leave it for user review rather than inventing an inaccurate category. --- ## ChatGPT Instant Checkout and Availability For ChatGPT Instant Checkout, availability matters. MCP/AI should keep these fields accurate: ```text enabled in_stock stock ``` Do not mark Products as available if they are not actually sellable. A Product should generally not be considered ready for ChatGPT Instant Checkout if: ```text enabled = false in_stock = false stock = 0, when stock is tracked fulfillment_account is missing for a shippable Product fulfillment_account is disabled for a shippable Product price is missing or unconfirmed image_url is missing or invalid ``` --- ## RevCent Lists Available Products Through ACP RevCent will list Products available for ChatGPT Instant Checkout through ACP, the Agentic Commerce Protocol. MCP/AI should understand: ```text CreateProduct and EditProduct populate the Product fields RevCent uses for listing readiness. RevCent controls the ACP listing layer. MCP/AI should focus on making the Product data complete, accurate, and eligible. Incorrect Product data can result in poor listings, incorrect discovery, or ineligibility. ``` MCP/AI should not claim that a Product is definitely visible in ChatGPT merely because it was created. The Product must also satisfy RevCent's Instant Checkout / ACP eligibility and listing requirements. --- # WooCommerce Product Import Through User Third-Party Shops WooCommerce Products can be imported into RevCent through a user third-party shop. The intended workflow is: ```text 1. User links WooCommerce store with RevCent. 2. RevCent creates or exposes the WooCommerce store as a user third-party shop. 3. MCP retrieves the user shop with GetUserShop. 4. MCP includes remote_data = ["products"] when running GetUserShop. 5. GetUserShop returns remote WooCommerce Product data. 6. MCP creates or updates RevCent Products using CreateProduct or EditProduct. ``` This allows MCP/AI to import WooCommerce Products individually instead of requiring the user to manually re-enter product data. --- ## GetUserShop With `remote_data` After the WooCommerce store is linked with RevCent, MCP can retrieve remote WooCommerce Products by calling: ```text GetUserShop ``` with: ```json { "user_shop_id": "XXXXXXXXXXXXXXXXXXXX", "remote_data": ["products"] } ``` In URL/query-parameter style transports, this may be represented as a `remote_data` URL parameter. The important concept is: ```text remote_data must include products. ``` The `remote_data` option applies to WooCommerce stores and can retrieve remote items from the connected store that may not have been created in RevCent yet, or items that were updated remotely and need to be updated in RevCent. Known `remote_data` options include: ```text products shipping_methods offline_payment_methods ``` For Product importing, use: ```text products ``` --- ## WooCommerce Product to RevCent Product Mapping When importing a WooCommerce Product, MCP/AI should map WooCommerce data into `CreateProduct` fields. Recommended mapping: | WooCommerce Data | RevCent Product Field | |---|---| | WooCommerce Product ID | `internal_id` | | WooCommerce Product name | `name` | | WooCommerce SKU | `sku` | | WooCommerce price | `price` | | WooCommerce short/long description | `description` / `description_html` | | WooCommerce Product permalink | `url` | | WooCommerce main image URL | `image_url` | | WooCommerce stock status | `in_stock` | | WooCommerce stock quantity | `stock` | | WooCommerce brand/category attributes | `brand`, `google_product_category`, `product_group`, or metadata when appropriate | | WooCommerce weight/dimensions | `shipping_attributes.weight`, `length`, `width`, `height` | | RevCent user shop ID | `third_party_shop` | | Fulfillment routing | `shipping_attributes.fulfillment_account` | Important: ```text For WooCommerce Products, internal_id should be the WooCommerce Product ID. For WooCommerce Products, third_party_shop should be the RevCent user shop ID. For WooCommerce Products, image_url should be the direct WooCommerce Product image URL. ``` --- ## Create vs Update During WooCommerce Import Before creating a new RevCent Product from WooCommerce remote data, MCP/AI should check whether the Product already exists. Best matching fields: ```text third_party_shop internal_id sku ``` Correct behavior: ```text If no matching Product exists, use CreateProduct. If a matching Product exists, use EditProduct. ``` Do not create duplicates for the same WooCommerce Product. --- ## WooCommerce Import Example Example `CreateProduct` request from WooCommerce remote data: ```json { "name": "Organic Coffee Beans - 2 lb Bag", "sku": "COFFEE-2LB", "price": 29.99, "description": "Organic medium roast coffee beans.", "description_html": "

Organic medium roast coffee beans with notes of chocolate and citrus.

", "url": "https://example-store.com/product/organic-coffee-beans-2lb", "image_url": "https://example-store.com/wp-content/uploads/coffee-2lb.jpg", "third_party_shop": "SSSSSSSSSSSSSSSSSSSS", "internal_id": "12345", "enabled": true, "in_stock": true, "stock": 48, "brand": "Example Brand", "condition": "new" } ``` If the Product is shippable, add: ```json { "is_shippable": true, "shipping_attributes": { "weight": "2", "length": "10", "width": "7", "height": "4", "fulfillment_account": "FFFFFFFFFFFFFFFFFFFF" } } ``` --- ## WooCommerce Import Review Checklist After importing WooCommerce Products, MCP/AI should review: ```text Product was not duplicated. third_party_shop is set. internal_id equals WooCommerce Product ID. sku is accurate. price is accurate. url points to the WooCommerce Product page. image_url is a direct JPG/JPEG/PNG image URL. enabled is intentional. in_stock and stock are accurate. google_product_category is selected where needed. brand/condition/identifiers are populated where applicable. shippable Products have Fulfillment Accounts. Fulfillment Accounts are enabled. subscription/trial/bundle behavior was not assumed. ``` WooCommerce import does not remove the need to review Product readiness. Imported Products may still need additional configuration before they are ready for normal RevCent checkout, ChatGPT Instant Checkout, fulfillment, subscriptions, trials, bundles, or reporting. # Age Group and Condition Allowed `age_group` values: ```text adult kids toddler infant newborn ``` Allowed `condition` values: ```text new used refurbished ``` Use only allowed values. --- # Rating Fields Rating fields are optional and meant for display purposes. ```text rating_value rating_count ``` `rating_value` should be between 0 and 5. MCP/AI should not invent ratings. --- # Product Reporting Product reporting should use BigQuery, not paginated Product/Product Sale retrieval. Use `BigQueryRunQuery` for: ```text Revenue by Product. Quantity sold by Product. Refund rate by Product. Product Sales by campaign. Product Sales by third-party shop. Subscription revenue by Product. Trial conversion by Product. Bundle sales. Product-level chargebacks. Product-level fulfillment issues. Products missing images. Products missing fulfillment accounts. ``` Use `GetBigQueryTables` before writing production SQL. --- # CreateProduct Best Practices Before calling `CreateProduct`, MCP/AI should confirm: ```text Product does not already exist. name is clear. sku is stable. price is intentional. enabled is intentional. image_url is a direct jpg/jpeg/png if provided. third_party_shop mapping is correct if used. internal_id is correct if third-party shop Product. subscription_profile is provided if subscription Product. shipping_attributes.fulfillment_account is provided if shippable Product. bundle_settings are complete if bundle Product. product_group IDs are valid if provided. display/listing fields are accurate if provided. ``` --- # EditProduct Best Practices Before calling `EditProduct`, MCP/AI should confirm: ```text product_id is known. Only changed fields are included. image_url is included only if replacing the image. price changes are intentional. enabled changes are intentional. shipping_attributes changes are intentional. third_party_shop/internal_id changes are intentional. subscription_profile changes are intentional. bundle_settings changes are intentional. product_group changes are intentional. ``` Safest edit pattern: ```text GetProduct Review current Product Build request with product_id + only changed fields Call EditProduct Optionally GetProduct again to verify ``` --- # Common Mistakes ## Mistake: Using a Webpage as `image_url` Wrong: ```text https://example.com/products/coffee-2lb ``` Correct: ```text https://example.com/images/coffee-2lb.jpg ``` ## Mistake: Using Unsupported Image Format Wrong: ```text https://example.com/images/product.webp ``` Correct: ```text https://example.com/images/product.png ``` ## Mistake: Replacing a Product Image Accidentally Wrong: ```text Include image_url in every EditProduct request. ``` Correct: ```text Only include image_url when the user wants to replace the existing Product image. ``` ## Mistake: Shippable Product Without Fulfillment Account Wrong: ```json { "is_shippable": true } ``` Correct: ```json { "is_shippable": true, "shipping_attributes": { "fulfillment_account": "FFFFFFFFFFFFFFFFFFFF" } } ``` ## Mistake: Subscription Product Without Subscription Profile Wrong: ```text Create a recurring Product but omit subscription_profile. ``` Correct: ```text Use GetSubscriptionProfiles and attach the correct subscription_profile. ``` ## Mistake: Third-Party Shop Product Without Internal ID Wrong: ```json { "third_party_shop": "SSSSSSSSSSSSSSSSSSSS" } ``` Correct: ```json { "third_party_shop": "SSSSSSSSSSSSSSSSSSSS", "internal_id": "external_shop_product_id" } ``` ## Mistake: Confusing `price_sale` With `price` Wrong: ```text Set price_sale and assume checkout amount changed. ``` Correct: ```text Set price for actual transaction price. price_sale is display-only. ``` ## Mistake: Bad Bundle Price Allocation Wrong: ```text Bundle Product price = $100 Component allocated total = $75 ``` Correct: ```text Bundle Product price = $100 Component allocated total = $100 ``` --- # MCP/AI Product Setup Checklist Before creating or deeply editing a Product: 1. Confirm whether the Product already exists. 2. Confirm Product name. 3. Confirm SKU. 4. Confirm actual transaction price. 5. Confirm whether Product should be enabled. 6. Confirm direct jpg/jpeg/png `image_url`, if customer-facing or shop-linked. 7. Confirm Product URL, if third-party shop or storefront Product. 8. Confirm third-party shop ID, if applicable. 9. Confirm `internal_id`, if third-party shop Product. 10. Confirm whether Product is shippable. 11. If shippable, confirm Fulfillment Account. 12. Confirm weight/dimensions if needed. 13. Confirm whether Product is a subscription. 14. If subscription, confirm Subscription Profile. 15. Confirm whether Product is a trial. 16. If trial, confirm trial days, trial price, and trial shipping behavior. 17. Confirm whether Product is a bundle. 18. If bundle, confirm component Products, quantities, allocated prices, and unbundle method. 19. Confirm Product Groups. 20. Confirm display/listing fields. 21. Do not guess product identifiers, prices, images, weights, dimensions, categories, ratings, or bundle allocations. --- Additional KB-informed reminders: ```text Use import workflows for many Products instead of creating Products one by one when appropriate. Imported Products still need review for fulfillment, subscription, bundle, image, and shop-mapping readiness. For bundle Products, distinguish between the Bundle Product and the Bundled Products. Bundle component price allocations should equal the bundle Product price. The unbundle method changes sale, fulfillment, event, and reporting behavior. Subscription and trial Products can also be bundle Products, but require extra validation. ``` Additional ChatGPT Instant Checkout / WooCommerce reminders: ```text RevCent can list eligible Products for ChatGPT Instant Checkout through ACP. ChatGPT Instant Checkout readiness depends on complete Product data, not merely Product existence. Important listing fields include name, description, price, url, image_url, enabled, stock/availability, google_product_category, brand, condition, identifiers, and fulfillment readiness. WooCommerce Products can be retrieved from a linked user third-party shop with GetUserShop using remote_data = ["products"]. WooCommerce Products should map internal_id to the WooCommerce Product ID and third_party_shop to the RevCent user shop ID. MCP/AI should use CreateProduct for new WooCommerce Products and EditProduct for existing mapped Products. ``` # Summary The refreshed `CreateProduct` and `EditProduct` schemas support: ```text Required Product identity and price fields. Product image ingestion through image_url. Third-party shop mapping. Subscription Products. Trial Products. Shippable Products and Fulfillment Accounts. Bundle Products. Product Groups. Parent/child Products. Additional IDs. Display/listing fields. Agentic commerce fields. ``` Most important rules: ```text CreateProduct requires name, price, and sku. EditProduct requires product_id and should only include changed fields. image_url must be a direct jpg/jpeg/png image URL. RevCent downloads, compresses, and hosts image_url images on the RevCent CDN. EditProduct image_url replaces previous Product images. Shippable Products require a Fulfillment Account. Subscription Products require a Subscription Profile. Third-party shop Products require correct internal_id mapping. Bundle Products require valid component Products, quantities, prices, and unbundle method. price is the actual transaction price; price_sale is display-only. ``` Used correctly, Products power RevCent checkout, fulfillment, subscriptions, trials, bundles, reporting, customer support, AI automation, and customer-facing product experiences. --- 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.