Developer notes
How the fee is applied
Section titled “How the fee is applied”The fee is an order surcharge, like the core payment surcharge. In the calculate_cart hook (priority 150, before gift certificates) the add-on adds the fee to cart.total, taxes it with fn_calculate_tax_rates() and merges the tax into cart.taxes under the applies key KVSHP_fee. The result is in cart.kv_shp_calc (offered, selected, fee, tax, display_fee, base, country, prechecked).
The customer’s choice is in cart.kv_shp: explicit (Y/N, only after the customer touched the box), shown (the checkout page with the box was opened).
Multi-Vendor sub-orders: core recalculates every vendor cart with parent_order_id set. The add-on reads the parent order’s stored fee and gives each vendor order the share of its product value.
Hooks used
Section titled “Hooks used”calculate_cart, place_order, get_order_info, form_cart, delete_order, template_document_order_context_init. Same signatures in 4.17.2 and 4.21.2.
Template hooks (storefront): checkout:final_section_customer_notes (box), checkout:checkout_totals, checkout:summary, orders:order_total, orders:tabs. Admin: orders:totals_content, order_management:totals.
Tables
Section titled “Tables”?:kv_shp_orders: one row per order that was offered protection (protectedY/N,fee,tax,display_fee,base,tax_ids,mode,country,prechecked).?:kv_shp_claims: claims (type,statusO/R/F/D,itemsJSON,description,photosJSON,reply,internal_note,refund_amount,replacement_order_id, timestamps).
Photos: var/kv_shipping_protection/claims/<claim_id>/, with .htaccess deny rules; streamed by admin.php?dispatch=kv_shipping_protection.photo.
Order data
Section titled “Order data”fn_get_order_info() returns kv_shp for protected orders (also in the REST API). Twig documents get an extra product row kv_shp.
Full page cache
Section titled “Full page cache”Nothing is printed on cacheable pages (home, categories, products, pages). The box lives on the checkout page and the claims on the customer order page, which are never cached.