Developer notes

Overview · Installation · Configuration · Usage · FAQ

Add-on identity

Item	Value
Add-on id	kv_product_cost_profit
Function prefix	fn_kv_product_cost_profit_
Language variables	kv_product_cost_profit.*
CSS scope	.kv-pcp-*
PHP namespace	Tygh\Addons\KvProductCostProfit

Profit formula

Per order (the snapshot is read from the add-on’s tables, nothing is recalculated from current prices):

revenue      = sum(price x amount) - cart discount - included product tax   (tax only when the setting is on)
               - accepted returns (RMA statuses from the settings)
cogs         = sum(unit_cost x amount)                                      (unit cost frozen per order item)
shipping net = shipping charged (net of included tax) - actual shipping     (actual empty = charged)
payment net  = payment surcharge - (total x fee % + fixed fee)
profit       = revenue - cogs + shipping net + payment surcharge - payment fee
               - fixed cost per order - manual cost - marketplace commission
margin       = profit / (revenue + shipping charged + payment surcharge)

Product and category rows show revenue - cost of goods only; order-level costs are not allocated.

How the snapshot is taken

Snapshot::take($order_id, $estimated) runs from the place_order hook after the core has saved the order rows. It also runs for each Multi-Vendor child order and when an administrator edits an order (same order id): existing item ids keep their unit cost, new items take the current cost, and the stored actual shipping, manual cost and fee values are kept. The call is wrapped in try/catch, so a failure never breaks checkout. Snapshot::backfill() creates estimated snapshots for old orders (Tools tab).

Hooks used

Hook	Use
place_order	Take or refresh the order snapshot.
delete_order	Remove the order’s snapshot rows.
update_product_post	Save product_data[kv_pcp_cost] (empty = remove). Also called by the list, bulk edit and imports through fn_update_product.
delete_product_post	Remove the cost row.
clone_product_post	Copy the cost to the clone.

Template hooks (admin): products:product_update_price.post (cost field), products:manage_head.post and manage_body.post (list column), products:bulk_edit_inputs.post, orders:totals.post (profit panel), orders:manage_header and manage_data (orders list column). The exim schema adds the Cost price field to the product export, import and Advanced import (schemas/exim/products.post.php, schemas/advanced_import/products.post.php). All hook signatures are identical in 4.17.2 and 4.21.2.

Hooks provided

None.

Database tables

Table	Content
?:kv_pcp_costs	One cost per product: product_id, cost, updated_at, user_id. A missing row means no cost.
?:kv_pcp_order_items	Per order item: amount, price, net revenue, unit cost, whether a cost existed.
?:kv_pcp_orders	Per order: revenue, cost of goods, shipping charged and actual, surcharge, fee settings, fixed and manual costs, estimated flag, number of items without cost.

No ?:storage_data writes. The commission is read from the core ?:vendor_payouts / vendor plan data and never recalculated. RMA tables are read only when the RMA add-on is installed.

Permissions and scoping

The admin permission schema maps the controller to view_reports (the tools backfill and fill_costs need manage_catalog); the vendor schema allows the report controller when Vendor access is not No access. Every query is limited by runtime.company_id, writes check the ownership of the product, and vendors cannot write order costs.

Full page cache

The add-on has no storefront output. Only the place_order hook runs on the storefront (writes to its own tables).

License check

See License. The gate is fn_kv_product_cost_profit_is_licensed(): reports, CSV export, tools, the order profit panel and the margin columns. Cost fields, import and export, bulk edit and the snapshots keep working.

File map

Path	Purpose
app/addons/kv_product_cost_profit/addon.xml, init.php, func.php	Scheme, settings, tables, hooks, exim handlers
controllers/backend/kv_product_cost_profit.php	Reports, CSV export, tools
controllers/backend/orders.pre.php, orders.post.php	Saving order costs, data for the orders list and the order page
controllers/backend/products.post.php	Data for the product list
Tygh/Addons/KvProductCostProfit/Costs.php	Cost prices
.../Snapshot.php	Order snapshots and backfill
.../Report.php	Report queries and order profit
.../Config.php, Access.php	Settings, scoping, vendor access
.../License/*, controllers/backend/kv_product_cost_profit_license.php	License client and Check now
.../Upgrade/Synchronizer.php	Self-healing upgrades
schemas/exim, schemas/advanced_import, schemas/permissions, schemas/menu	Cost price field, privileges, menu
design/backend/templates/addons/kv_product_cost_profit/	Reports page, hook templates, license UI
design/backend/css/addons/kv_product_cost_profit/	Styles
var/langs/en/addons/kv_product_cost_profit.po	Language variables