Developer notes

How the rules are applied

Point	Hook / controller	What happens
Add to cart, cart update, every cart calculation	check_amount_in_stock_before_check	The product row core checks gets the effective min_qty, max_qty, qty_step (core settings combined with the first matching product rule). Core corrects the quantity with its own messages.
Same	post_check_amount_in_stock	Customer purchase limits: the quantity is lowered to the remaining allowance, or set to 0 (item not added) with a message.
Add to cart	pre_add_to_cart, post_add_to_cart	An add that breaks a maximum of a cart or group rule is undone (cart restored) with a message.
Product pages and lists	gather_additional_product_data_before_discounts	Effective quantity fields for the quantity selector; $product.kv_oqr_notes on product pages.
Cart lines	get_cart_product_data	Effective quantity fields for the cart quantity inputs.
Cart page	checkout.post.php (mode cart)	$kv_oqr_cart (violations, lines) for the panel and the line notes.
Checkout entry	checkout.pre.php (mode checkout)	Unmet rules: notifications and redirect to the cart.
Place order	allow_place_order_post	Parent order only: unmet rules set $result = false (admin orders in warn mode: warnings only).
REST API	api_orders_create_after_add_product_to_cart	403 with the messages.
Admin order editor	order_management.post.php	Warnings.
Vendor minimum	update_company, delete_company, companies.post.php	Fields on the vendor page.

All hooks exist with the same arguments in CS-Cart 4.17.2 and 4.21.2. Quantity corrections are skipped when ORDER_MANAGEMENT or API is defined: those carts are checked as a whole when the order is placed.

Template hooks

Hook	Template
products:qty_description (post)	addons/kv_order_quantity_rules/hooks/products/qty_description.post.tpl: product page notes
checkout:product_info (post)	per-line notes in the cart
checkout:extra_list (post)	the “Before you check out” panel (a table row at the end of the cart items, inside the AJAX-reloaded #cart_items)
companies:general_information (post, admin)	vendor minimum order fields

Styles are scoped under .kv-order-quantity-rules (storefront) and .kv-oqr (admin).

Data

Table	Content
?:kv_oqr_rules	rules: type product / total / customer, priority, scope (applies_to, object_ids, subcats, exclude_ids, usergroup_ids, storefront_ids) and the limits of each type
?:kv_oqr_rule_descriptions	the optional shopper message per language
?:kv_oqr_vendor_minimums	vendor minimum order (amount, quantity)

Customer purchase history is read from ?:orders / ?:order_details (statuses except N, F, D, I; Multi-Vendor parent orders skipped), only in the cart, at checkout and when products are added.

Full page cache and block cache

Product page notes depend only on the product, the customer group and the storefront, never on the visitor’s history, so cached pages are the same for every guest. The block cache of product lists, category pages and the product page is refreshed when the rule tables change (update_handlers) and keyed by the add-on state (callable_handlers: license, enabled, notes setting). Storefront GET requests write nothing.

Evaluating a cart in your code

use Tygh\Addons\KvOrderQuantityRules\Context;
use Tygh\Addons\KvOrderQuantityRules\Evaluator;

$result = Evaluator::evaluateCart($cart, Context::build($cart, $auth));
// $result['violations']: [['code' => 'min_amount', 'kind' => 'min', 'rule_id' => 4, 'company_id' => 0,
//                          'limit' => 75, 'current' => 40, 'missing' => 35, 'cart_ids' => [...], 'message' => '...'], ...]
// $result['lines']: [cart_id => ['Sold in packs of 12', ...]]

Violation codes: line_min, line_max, line_step, customer_limit, min_amount, max_amount, min_qty_total, max_qty_total, qty_multiple, min_items, max_items.

File map

app/addons/kv_order_quantity_rules/
  addon.xml  init.php  func.php
  controllers/backend/kv_order_quantity_rules.php      rule list and editor
  controllers/backend/order_management.post.php        warnings in the order editor
  controllers/backend/companies.post.php               vendor minimum fields
  controllers/frontend/checkout.pre.php                checkout entry check
  controllers/frontend/checkout.post.php               cart panel data
  schemas/menu/menu.post.php  schemas/permissions/admin.post.php  schemas/block_manager/blocks.post.php
  Tygh/Addons/KvOrderQuantityRules/
    Config.php  Context.php  Rules.php  Evaluator.php  History.php  Messages.php  VendorMinimums.php  Enforcer.php  Admin.php
    License/  Upgrade/Synchronizer.php
design/backend/templates/addons/kv_order_quantity_rules/
  views/kv_order_quantity_rules/{manage,update}.tpl  hooks/companies/general_information.post.tpl  license/  hooks/index/
design/backend/css/addons/kv_order_quantity_rules/  js/addons/kv_order_quantity_rules/backend.js
var/themes_repository/responsive/templates/addons/kv_order_quantity_rules/hooks/{products,checkout,index}/
var/themes_repository/responsive/css/addons/kv_order_quantity_rules/styles.less
var/langs/en/addons/kv_order_quantity_rules.po

License

The license client (License\Client) gates every enforcement hook, the product page notes, the cart panel and the API check (Config::isActive() = add-on enabled and licensed). Without a valid license the store behaves as without the add-on: CS-Cart’s own quantity settings and minimum order amount still apply. The admin pages are not gated. See License.