Margin Reveal for WooCommerce — User Documentation
Version 1.0.0
Publisher: GlezByte

1. PURPOSE
Margin Reveal is an administrative WooCommerce utility for Simple products. It adds a Product Cost field and calculates Gross Profit, Margin, and Markup from the product's current WooCommerce selling price. It also adds a Margin Reveal column to the Products screen and supports updating Product Cost through WooCommerce Quick Edit.

2. REQUIREMENTS
- WordPress 6.0 or later
- PHP 8.0 or later
- WooCommerce 10.0 or later

3. SUPPORTED PRODUCT TYPES
Margin Reveal 1.0.0 supports WooCommerce Simple products.

The following product types are not supported in this release:
- Variable products
- Grouped products
- External/Affiliate products
- Other non-Simple custom product types

Unsupported product types do not receive editable Margin Reveal calculation fields. On the Products screen, unsupported products display no Margin Reveal calculation.

4. CALCULATION DEFINITIONS AND FORMULAS
Margin Reveal uses two inputs:
- Selling Price: the WooCommerce price that is currently effective for the product.
- Product Cost: the store administrator's entered cost for the product.

Gross Profit
Gross Profit = Selling Price - Product Cost

Example:
Selling Price = $100.00
Product Cost = $60.00
Gross Profit = $100.00 - $60.00 = $40.00

Margin
Margin measures gross profit as a percentage of the selling price.
Margin % = (Gross Profit / Selling Price) x 100

Using the example above:
Margin % = ($40.00 / $100.00) x 100 = 40%

Markup
Markup measures gross profit as a percentage of product cost.
Markup % = (Gross Profit / Product Cost) x 100

Using the example above:
Markup % = ($40.00 / $60.00) x 100 = 66.67%

Margin and Markup are different measurements. Margin uses Selling Price as the denominator; Markup uses Product Cost as the denominator.

5. ZERO-COST AND ZERO-PRICE BEHAVIOR
If Product Cost is 0:
- Gross Profit is still calculated as Selling Price - 0.
- Margin is calculated normally when Selling Price is non-zero.
- Markup displays N/A because division by zero is undefined.

If Selling Price is 0:
- Gross Profit is still calculated as 0 - Product Cost.
- Margin displays N/A because division by zero is undefined.
- Markup is calculated normally when Product Cost is non-zero.

If Product Cost is blank, Margin Reveal leaves the calculated fields blank and the Products-list column does not show a profitability calculation for that product.

6. REGULAR PRICE, SALE PRICE, AND SCHEDULED SALES
Margin Reveal follows the WooCommerce effective selling price.

No sale price:
- Calculations use the Regular Price.

Sale price without a schedule:
- Calculations use the Sale Price.

Scheduled sale with a future start date:
- Until the configured start date is reached, calculations use the Regular Price.
- When the sale becomes active, calculations use the Sale Price.

Scheduled sale with an end date:
- While the sale is active, calculations use the Sale Price.
- After the configured end date has passed, calculations return to the Regular Price.

Scheduled sale with both start and end dates:
- Before the start date: Regular Price is used.
- During the active sale period: Sale Price is used.
- After the end date: Regular Price is used.

The product-editor live calculation watches Regular Price, Sale Price, Sale start, Sale end, and Product Cost so the displayed Gross Profit, Margin, and Markup update when those values change. After saving, WooCommerce's effective product price is used for stored/admin display calculations.

7. WOOCOMMERCE PRICE FORMATTING
Live monetary results follow the store's WooCommerce price-format settings, including:
- Currency symbol
- Currency position
- Decimal separator
- Thousands separator
- Configured number of decimal places

Examples of supported WooCommerce-style output include formats such as $1,234.56, 1.234,56 €, 25.00 $, and other combinations configured by the store.

8. USING PRODUCT COST IN THE PRODUCT EDITOR
1. In WordPress admin, go to Products.
2. Open a WooCommerce Simple product for editing.
3. Locate the product pricing area.
4. Enter the store's cost in Product Cost.
5. Margin Reveal calculates Gross Profit, Margin, and Markup immediately.
6. Adjust Regular Price, Sale Price, or scheduled-sale dates as needed; the live values update accordingly.
7. Click Update or Publish to save the product.

9. USING PRODUCT COST THROUGH QUICK EDIT
1. In WordPress admin, go to Products.
2. Find a supported Simple product.
3. Hover over the product row and click Quick Edit.
4. Locate the Product cost field added by Margin Reveal.
5. Enter a new cost or change the existing cost.
6. Click Update.
7. WooCommerce saves the Product Cost for that product.
8. The Margin Reveal column on the Products screen uses the saved Product Cost and the product's effective WooCommerce price to display the updated profitability values.

If the Product cost field is left blank and the product is updated, the saved Margin Reveal cost is removed.

10. PRODUCTS SCREEN COLUMN
Margin Reveal adds a Margin Reveal column to the WooCommerce Products screen for supported Simple products.

When Product Cost is available, the column displays:
- Cost
- Profit
- Margin

Products without a saved Product Cost and unsupported product types display no calculation.

11. INTERNATIONALIZATION
Margin Reveal uses the WordPress text domain margin-reveal. User-facing PHP strings and the live JavaScript N/A output use translatable/localized strings. A translation template is included at:

languages/margin-reveal.pot

The POT template can be used by standard WordPress translation tools to create language-specific PO/MO files.

12. SCOPE AND LIMITATIONS
Margin Reveal does not replace WooCommerce pricing, tax, shipping, accounting, inventory, or reporting systems. It is an administrative profitability utility. Calculations are based on WooCommerce's effective product price and the Product Cost entered by an authorized store administrator.

Version 1.0.0 does not provide variation-level costing or calculations for Variable products.
