Developer notes

Technical reference for developers who customize Stock Statuses & Lead Times.

Add-on identity

Item	Value
Add-on id	`kv_stock_status_manager`
Function prefix	`fn_kv_stock_status_manager_`
Language variables	`kv_stock_status_manager.*`
CSS scope	`.kv-ssm`, `.kv-ssm-*`
PHP namespace	`Tygh\Addons\KvStockStatusManager`
Database tables	`?:kv_ssm_*`
Product filter field type	`K`

Resolution

Resolver::resolveMany($products, $lang_code, $storefront_company_id = null) returns product_id => status|null for a batch. Order: Pre-Orders & Deposits pre-order item (null) → product setting for the stock state → first matching active rule (the owner’s rules before shared rules, then by position) → default setting. Stock state: in stock when stock > 0 or the product (or the store) does not track stock. The stock shown to the shopper (inventory_amount, amount of list and product rows) is used; for cart and order lines the stored stock.

The resolved status (also on storefront products as $product.kv_ssm):

Key	Meaning
`status_id`, `name`, `note`	Status and its texts with `[days]`, `[qty]`, `[date]` filled in
`date`	Dispatch date for the product page (when “Show dispatch date” is on)
`color`, `bg`, `icon`, `svg`	Colour, 12% tint, icon key and inline SVG
`feed`, `feed_date`	Feed availability value and ISO 8601 dispatch date
`lead_min`, `lead_max`, `days`	Lead time used
`source`	`product`, `rule:<id>` or `default`
`replace`, `product_page`, `in_lists`, `in_cart`	Display settings

Feed API

if (class_exists('\Tygh\Addons\KvStockStatusManager\Feed')) {
    \Tygh\Addons\KvStockStatusManager\Feed::prefetch($products);            // optional, one batch
    $availability = \Tygh\Addons\KvStockStatusManager\Feed::availability($product);
    if ($availability !== null) {
        list($value, $date) = $availability; // in_stock | out_of_stock | backorder | preorder, ISO date or ''
    }
}

availability() returns null when the add-on is off or unlicensed, the product has no status, or the status leaves the value to the feed (“Automatic”).

Lead time API

if (class_exists('\Tygh\Addons\KvStockStatusManager\Lead')) {
    $days = \Tygh\Addons\KvStockStatusManager\Lead::days([$product_id]); // [product_id => days until dispatch]
}

days() returns the upper lead time of the status each product shows now (the value the dispatch date uses), from the stored stock. Products without a status or a lead time are left out; the result is empty when the add-on is off or unlicensed. Shipping Estimator on Product Page uses it as the least handling time.

Display API

if (class_exists('\Tygh\Addons\KvStockStatusManager\Display')) {
    $ids = \Tygh\Addons\KvStockStatusManager\Display::inCart($product_ids); // products whose cart line shows a status
}

Urgency & Social Proof uses it to leave out its low stock cart note where a status is already shown.

Database tables

Table	Contents
`kv_ssm_statuses`	status_id, company_id (0 = shared; MV vendor; Ultimate storefront), color, icon, lead_min, lead_max, feed, show_date, position, status
`kv_ssm_status_descriptions`	status_id, lang_code, name, note, filter_name
`kv_ssm_rules`	rule_id, company_id, name, stock_cond (any/in/out/range), qty_min, qty_max, warehouse_id, category_ids, product_ids, vendor_ids (CSV), supplier_lead, status_id, position, status
`kv_ssm_products`	product_id, status_in, status_out, lead_min, lead_max
`kv_ssm_index`	product_id, status_id: the index of the storefront filter
`kv_ssm_order_items`	order_id, item_id, product_id, status_id, name, color, icon: the status of each order line when it was placed

Hooks used

PHP: gather_additional_products_data_post (storefront status data), update_product_post, clone_product, delete_product_post, update_product_amount_post, import_post, delete_company, place_order, get_order_info, delete_order, get_product_filter_fields, generate_filter_field_params, get_products. All exist with the same arguments in 4.17.2 and 4.21.2.

Templates (storefront): products:product_amount (override in replace mode, post in “below” mode; core skips the pre/post templates of other add-ons when an override renders, so the override includes them itself and their lines, such as the exact stock of Sell by Weight & Length, stay), products:list_price_block (post), checkout:product_info (post), index:styles. Admin: products:update_product_amount (post), index:styles, index:scripts.

Cache

The status is static per product (no visitor data). Storefront reads of the add-on tables are tagged by the 4.21 full page cache, so admin changes invalidate cached pages; stock changes update products, which pages already depend on. The block cache of the product, category, vendor and search pages and of product blocks gets the add-on tables as update handlers and fn_kv_stock_status_manager_cache_key() (on/off, licence, display settings, date) as a key.

Template customization

The status chip is addons/kv_stock_status_manager/components/status.tpl ($kv_status, $kv_compact). Copy it to your theme’s templates/addons/kv_stock_status_manager/components/ to change the markup; do not edit the add-on’s files, they are replaced on update. Colours come from the CSS variables --kv-ssm-color and --kv-ssm-bg.

File map

app/addons/kv_stock_status_manager/
  addon.xml, init.php, func.php
  controllers/backend/kv_stock_status_manager.php   statuses and rules pages (admin + vendor)
  controllers/backend/products.post.php             product editor data
  schemas/ block_manager, menu, permissions, settings
  Tygh/Addons/KvStockStatusManager/
    Config, Statuses, Rules, Products, Resolver, Index, Filter, Orders, Feed, Install, License/*, Upgrade/Synchronizer
design/backend/templates/addons/kv_stock_status_manager/ views, components, hooks, license
design/backend/css/addons/kv_stock_status_manager/styles.less
js/addons/kv_stock_status_manager/backend.js
var/themes_repository/responsive/templates/addons/kv_stock_status_manager/ components/status.tpl, hooks
var/themes_repository/responsive/css/addons/kv_stock_status_manager/styles.less
var/langs/en/addons/kv_stock_status_manager.po