# RevCent MCP Operation: `EditProduct`

This document explains how MCP/AI clients should use the `EditProduct` operation in RevCent.

`EditProduct` edits an existing Product using a 20-character `product_id`.

Before editing Products, MCP/AI should read the Products overview:

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

MCP/AI should also understand the Product and Product Bundle KB pages:

```text
https://kb.revcent.com/en/product
https://kb.revcent.com/product/product-bundle
```

Sources:
- Refreshed RevCent operation schema for `EditProduct`
- Refreshed RevCent operation schema for `CreateProduct`
- Products overview: `https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md`
- Product KB: `https://kb.revcent.com/en/product`
- Product Bundle KB: `https://kb.revcent.com/product/product-bundle`

---

## Operation Summary

Use `EditProduct` when the Product already exists and the user wants to update one or more Product fields.

Required field:

```text
product_id
```

All other fields are optional.

Critical rule:

```text
EditProduct is a partial update operation.
Only include fields that should be changed.
```

Do not send every field from the existing Product unless the user intentionally wants all included values updated.

---

# Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `product_id` | string | Yes | 20-character Product ID. |

Example:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "price": 34.99
}
```

This request changes only the Product price.

---

# Schema Rule: No Unknown Fields

`EditProduct` uses:

```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 `EditProduct` does not include a `metadata` input field, use the appropriate metadata operation if supported for Product items.

---

# Safe Partial Update Workflow

Recommended workflow:

```text
1. Identify the Product ID.
2. Retrieve the current Product if current settings matter.
3. Decide exactly which fields should change.
4. Build an EditProduct request with product_id plus only changed fields.
5. Call EditProduct.
6. Optionally retrieve the Product again to verify changes.
```

This is important because Product edits can affect:

```text
Checkout price.
Product image.
Fulfillment.
Shipping.
Subscription renewals.
Trial behavior.
Bundle behavior.
Third-party shop mapping.
Product group membership.
Customer-facing displays.
AI workflows.
Reporting.
```

---

# Supported Input Fields

| Field | Type | Required | Purpose |
|---|---:|---:|---|
| `product_id` | string | Yes | 20-character Product ID. |
| `name` | string | No | Product name. |
| `description` | string | No | Plain text Product description. |
| `description_html` | string | No | Product description in HTML format. |
| `enabled` | boolean | No | Whether Product is enabled. |
| `sku` | string | No | Product SKU. |
| `url` | string | No | Product URL at a third-party shop or storefront. |
| `image_url` | string | No | Direct JPG/JPEG/PNG image URL. Replaces existing Product image if provided. |
| `internal_id` | string | No | Internal/external Product ID, critical for third-party shop Products. |
| `price` | number | No | Actual Product transaction price. |
| `price_trial` | number | No | Trial expiration price. Defaults to Product price. |
| `price_subscription` | number | No | Subscription renewal price. Defaults to Product price. |
| `trial_shipping_setting` | enum string | No | `trial_expiration`, `trial_creation`, or `both_trial_expiration_creation`. |
| `trial_days` | integer | No | Number of days a trial lasts. |
| `cost` | number | No | Estimated Product cost for reporting. |
| `is_shippable` | boolean | No | Whether Product is shippable. |
| `shipping_attributes` | object | Conditionally | Shipping details. Required when Product is shippable. |
| `additional_id` | array<object> | No | Additional Product identifiers. |
| `third_party_shop` | string | Conditionally | 20-character third-party shop ID. Required if Product is associated with a third-party shop. |
| `subscription_profile` | string | Conditionally | 20-character Subscription Profile ID. Required if Product is a subscription Product. |
| `parent_product` | string | No | Parent Product ID or internal ID. |
| `is_bundle_product` | boolean | No | Whether Product is a bundle. |
| `bundle_settings` | object | Conditionally | Bundle composition and unbundle method. |
| `product_group` | array<string> | No | Product Group IDs. |
| `google_product_category` | string | No | Google Product category ID for listings/agentic commerce. |
| `msrp` | number | No | Display-only MSRP. |
| `is_price_sale` | boolean | No | Display-only sale indicator. |
| `price_sale` | number | No | Display-only sale price. Does not affect transaction price. |
| `is_discount` | boolean | No | Display-only discount indicator. |
| `discount_rate` | number | No | Display-only discount rate. |
| `in_stock` | boolean | No | Display/listing stock indicator. |
| `stock` | integer | No | Display/listing stock quantity. |
| `brand` | string | No | Product brand. |
| `material` | string | No | Product material. |
| `age_group` | enum string | No | `adult`, `kids`, `toddler`, `infant`, or `newborn`. |
| `condition` | enum string | No | `new`, `used`, or `refurbished`. |
| `rating_value` | string | No | Rating value from 0 to 5. |
| `rating_count` | integer | No | Rating count. |
| `upc` | string | No | UPC. Recommended for agentic commerce where applicable. |
| `isbn` | string | No | ISBN. |
| `asin` | string | No | ASIN. |
| `mpn` | string | No | MPN. |
| `ean` | string | No | EAN. |

---

# Product Image Replacement: `image_url`

`EditProduct` supports `image_url`.

When `image_url` is 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.
```

Requirements:

```text
image_url must be a direct URL to an image file.
image_url must not be a webpage URL.
Only jpg, jpeg, and png are supported.
```

Critical edit behavior:

```text
Only provide image_url if you wish to update the existing Product image.
RevCent will remove previous versions of the Product image and replace them with the new one.
```

Therefore:

```text
Do not include image_url unless image replacement is intentional.
```

Good:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "image_url": "https://cdn.example.com/products/new-image.jpg"
}
```

Bad:

```text
Including image_url in every EditProduct request just because the Product already has an image.
```

If the Product is associated with a third-party shop, use the direct Product image URL from that shop only when replacing the image is desired.

---

# Basic Edit Scenarios

## Rename Product

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Organic Coffee Beans - 2 lb Bag"
}
```

## Update Product Description

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Organic medium roast coffee beans in a 2 lb bag."
}
```

## Update HTML Description

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "description_html": "<p>Organic medium roast coffee beans with notes of chocolate and citrus.</p>"
}
```

## Update Actual Price

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "price": 34.99
}
```

Remember:

```text
price is the actual transaction price.
```

## Update Display Sale Price

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "is_price_sale": true,
  "price_sale": 29.99
}
```

This changes display fields only. It does not change the actual transaction price.

## Disable Product

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

## Enable Product

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": true
}
```

Only enable a Product when required configuration is complete.

---

# Third-Party Shop Edit Guidance

If editing third-party shop mapping:

```text
third_party_shop is required if Product is associated with a third-party shop.
internal_id should be the external shop Product ID.
url should be the external Product page URL.
image_url should be the direct external Product image URL only if replacing the Product image.
```

Example:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "third_party_shop": "SSSSSSSSSSSSSSSSSSSS",
  "internal_id": "woocommerce_product_12345",
  "url": "https://example.com/products/coffee-2lb"
}
```

If replacing image too:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "image_url": "https://example.com/wp-content/uploads/coffee-2lb.jpg"
}
```

Do not guess `internal_id`.

---

# Shipping Edit Guidance

If editing a Product to become shippable:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "is_shippable": true,
  "shipping_attributes": {
    "weight": "2",
    "length": "10",
    "width": "7",
    "height": "4",
    "fulfillment_account": "FFFFFFFFFFFFFFFFFFFF"
  }
}
```

The schema states `shipping_attributes.fulfillment_account` is required if the Product is shippable.

Before editing, confirm:

```text
Fulfillment Account exists.
Fulfillment Account is enabled.
Fulfillment Account is correct for this Product.
Weight/dimensions are accurate if provided.
```

Important:

```text
If a Product is shippable and the attached Fulfillment Account is disabled, the Product may not ship.
```

---

# Subscription Edit Guidance

If editing a Product to become subscription-based:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "subscription_profile": "PPPPPPPPPPPPPPPPPPPP",
  "price_subscription": 29.99
}
```

`subscription_profile` is required if the Product is a subscription Product.

Use `GetSubscriptionProfiles` to find the correct profile.

---

# Trial Edit Guidance

Trial fields:

```text
trial_days
price_trial
trial_shipping_setting
```

Allowed `trial_shipping_setting` values:

```text
trial_expiration
trial_creation
both_trial_expiration_creation
```

Example:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "trial_days": 14,
  "price_trial": 49.99,
  "trial_shipping_setting": "trial_creation"
}
```

Confirm whether shipping should happen at trial creation, trial expiration, or both.

---

# Bundle Edit Guidance

A bundle Product uses:

```text
is_bundle_product = true
bundle_settings
```

The Product Bundle KB distinguishes:

```text
Bundle Product = the Product being sold as the bundle.
Bundled Products = the component Products inside the bundle.
```

When editing `bundle_settings`, treat the submitted value as the intended bundle configuration.

Verify:

```text
Every component Product ID is valid.
Every quantity is correct.
Every allocated price is correct.
Unbundle method is intentional.
Allocated component total equals Product price.
```

Allowed `unbundle_method` values:

```text
unbundle_at_fulfillment
unbundle_at_sale
```

Example:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "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"
  }
}
```

Do not guess the unbundle method.

---

# Bundle Unbundle Method

## `unbundle_at_sale`

Use when the bundle should decompose into component Product Sales at sale time.

Good for:

```text
Immediate component-level reporting.
Component-level refunds.
Automation that needs component Product Sales immediately.
```

## `unbundle_at_fulfillment`

Use when the bundle should decompose for fulfillment.

Good for:

```text
Physical kits.
Warehouse picking.
Customer-facing bundle with component fulfillment.
```

The unbundle method affects sale data, fulfillment data, event data, reporting, and customer communication.

---

# Product Groups

`product_group` is an array of 20-character Product Group IDs.

Only include it when changing Product Group membership.

Example:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "product_group": [
    "GGGGGGGGGGGGGGGGGGGG"
  ]
}
```

Product Groups can support:

```text
Reporting.
Filters.
Payment routing.
Promotions.
Shipping logic.
Product organization.
AI analysis.
Customer support segmentation.
```

---

# Parent Product and Additional IDs

## `parent_product`

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

## `additional_id`

Use for alternate identifiers.

Example:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX",
  "additional_id": [
    {
      "name": "warehouse_sku",
      "value": "WH-12345"
    }
  ]
}
```

---

# Display and Listing Fields

Display/listing fields include:

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

Important:

```text
price_sale is display-only.
price determines the actual transaction price.
```

`google_product_category` is used for Product listings including agentic commerce such as ChatGPT Instant Checkout. Use the most specific accurate category ID.

Allowed `age_group` values:

```text
adult
kids
toddler
infant
newborn
```

Allowed `condition` values:

```text
new
used
refurbished
```

Do not invent UPC/EAN/MPN/ISBN/ASIN/category/rating values.

---

# Import Product Awareness

If a user imported Products through CSV or third-party shop download, Product records may still need editing afterward.

Common post-import edits:

```text
Add or replace image_url.
Attach Fulfillment Account.
Attach Subscription Profile.
Configure bundle_settings.
Correct internal_id mapping.
Assign Product Groups.
Review enabled status.
Fix prices/SKUs/descriptions.
```

Do not assume imported Products are fully ready to sell without review.

---

# Output Schema

Successful response can include:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1770000000,
  "code": 1,
  "product_id": "YYYYYYYYYYYYYYYYYYYY",
  "result": "..."
}
```

MCP/AI should return the edited `product_id` and summarize changed fields.

---

# Validation Checklist

Before calling `EditProduct`:

1. `product_id` is known.
2. The Product exists.
3. Current Product has been retrieved if needed.
4. Request includes only fields being changed.
5. `image_url` is included only if replacing the Product image.
6. If `image_url` is included, it is a direct JPG/JPEG/PNG file URL.
7. Product page `url` is not confused with `image_url`.
8. Price changes are intentional.
9. Display-only price changes are not confused with transaction price changes.
10. Enabled/disabled change is intentional.
11. If Product is shippable, `shipping_attributes.fulfillment_account` is present and valid.
12. Fulfillment Account is enabled and correct.
13. If Product is subscription-based, `subscription_profile` is valid.
14. Trial settings are intentional.
15. Third-party shop mapping is correct if edited.
16. `internal_id` is correct for third-party shop Products.
17. Bundle settings are complete if edited.
18. Bundle component allocated total equals Product price.
19. Product Group changes are intentional.
20. Display/listing identifiers and category values are accurate.
21. No unsupported fields are sent.

---

# Common Mistakes

## Mistake: Editing With Full Stale Object

Wrong:

```text
Retrieve Product and send the entire Product object back through EditProduct.
```

Correct:

```text
Send only product_id plus fields that should change.
```

## Mistake: Replacing Image Accidentally

Wrong:

```text
Include image_url when the Product image should not change.
```

Correct:

```text
Only include image_url when replacing the image.
```

## Mistake: Webpage URL as Image

Wrong:

```text
image_url = https://example.com/products/product-123
```

Correct:

```text
image_url = https://example.com/images/product-123.jpg
```

## Mistake: Setting Sale Price Instead of Actual Price

Wrong:

```text
Set price_sale and assume actual transaction price changed.
```

Correct:

```text
Set price to change the actual transaction price.
```

## Mistake: Removing Fulfillment Accidentally

Wrong:

```text
Mark Product shippable but omit fulfillment_account.
```

Correct:

```text
Include valid shipping_attributes.fulfillment_account.
```

## Mistake: Editing Bundle Settings Without Full Review

Wrong:

```text
Change bundle component prices without verifying total equals Product price.
```

Correct:

```text
Verify component allocated total equals Product price.
```

---

# MCP/AI Decision Guide

Use `EditProduct` when:

```text
The Product already exists.
The user wants to change Product details.
The user wants to replace the Product image.
The user wants to change price, status, fulfillment, subscription, trial, bundle, listing, or shop mapping.
```

Use `CreateProduct` instead when:

```text
The Product does not exist and the user wants a new Product.
```

Use retrieval/search first when:

```text
The user provided only a Product name or SKU.
The Product ID is unknown.
MCP/AI needs to avoid editing the wrong Product.
```

---

# Key Takeaways

```text
EditProduct edits an existing Product.
```

```text
EditProduct requires product_id.
```

```text
Only include fields that should be changed.
```

```text
image_url must be a direct JPG/JPEG/PNG image URL.
```

```text
Providing image_url to EditProduct replaces the existing Product image.
```

```text
Shippable Products require a Fulfillment Account.
```

```text
Subscription Products require a Subscription Profile.
```

```text
Third-party shop Products require correct third_party_shop and internal_id mapping.
```

```text
Bundle Product edits require careful bundle_settings validation.
```

```text
Bundle component totals should equal the bundle Product price.
```

```text
price is the actual transaction price; price_sale is display-only.
```

```text
Read the Products overview and Product KB before making complex Product edits:
https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md
https://kb.revcent.com/en/product
https://kb.revcent.com/product/product-bundle
```


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