Developer notes

Technical reference for developers who customize Serial Numbers & Warranty Tracker.

Add-on identity

Item	Value
Add-on id	kv_serial_warranty
Function prefix	fn_kv_serial_warranty_
Language variables	kv_serial_warranty.*
CSS scope	.kv-snw, .kv-snw-*
PHP namespace	Tygh\Addons\KvSerialWarranty
Database tables	?:kv_snw_*

Database tables

Table	Contents
kv_snw_receipts	Goods receipts: company, product, lot, mfg_ym (YYYYMM), quantity, reference, notes, source (G generated, L scanned/typed, I import)
kv_snw_serials	One row per unit: company, product, receipt, serial (unique per company), status (A in stock, S sold, R returned, X replaced, V void), order_id, item_id (order line), user_id, email, sold_at, w_start, w_end, notes
kv_snw_products	Per-product settings: track, w_months (-1 = default), w_basis, pattern
kv_snw_claims	Warranty claims: serial, order, customer, type, status, in_warranty, fault, resolution, replacement_id, rma_return_id, withdrawal_ref
kv_snw_events	History of every unit (type + JSON data, user, time)
kv_snw_seq	Running numbers per company and pattern (reserved atomically)
kv_snw_attempts	Rate limit of the public warranty check (hashed IP, time)

company_id is the owner of the product: the vendor on Multi-Vendor, the owning storefront on CS-Cart Ultimate.

Hooks used

Hook	Purpose
create_shipment_post	Assign serial numbers to shipped units (setting When a shipment is created)
change_order_status_post	Assign on the chosen statuses; release on the release statuses
delete_order	Release the serial numbers of a deleted order
update_product_post	Save the product tab (product_data[kv_snw])
clone_product	Copy the product settings to a cloned product
delete_product_post	Remove the product settings (serial records stay)
delete_company	Remove the data of a deleted vendor or storefront
init_templater_post	Upgrade synchronizer, registered only while an in-place upgrade is pending

All hooks exist with identical arguments in CS-Cart 4.17.2 – 4.21.x. Template hooks: admin products:tabs_content, orders:tabs_extra; storefront orders:product_info, profiles:my_account_menu.

PHP API

use Tygh\Addons\KvSerialWarranty\Serials;
use Tygh\Addons\KvSerialWarranty\Orders;
use Tygh\Addons\KvSerialWarranty\Receipts;

// Find a unit (company_id null = any company)
$unit = Serials::find('UV27-4K-2609-00001', null);

// Serial numbers of an order, grouped by order line (item id)
$by_line = Orders::serialsByItem($order_id);

// Receive 10 generated units
$result = Receipts::create(['product_id' => 123, 'mode' => 'generate', 'qty' => 10, 'mfg' => '2026-09'], 0);

// Fill the missing serial numbers of an order from stock
Orders::autoFill(fn_get_order_info($order_id));

Labels

Pdf::labels(array $labels, $layout = 'roll62', $skip = 0) returns the PDF bytes. Each label is ['title' => ..., 'serial' => ..., 'meta' => ...]. The PDF uses the base fonts Helvetica and Courier (WinAnsi), so characters outside Western European text are replaced. Barcodes are Code 128 subset B (Barcode::bars(), Barcode::svg()). The admin URL kv_serial_warranty.labels accepts serial_ids, receipt_id or order_id, plus layout and skip (empty positions on the first A4 sheet).

Cache

Customer data is printed only on orders.details, kv_serial_warranty.my and kv_serial_warranty.check, which the 4.21 full page cache never caches. The account menu link is the same for every signed-in customer.

Template customization

Storefront templates are in var/themes_repository/responsive/templates/addons/kv_serial_warranty/ (copied to every theme on install). Override them in your theme like any add-on template; styles are scoped under .kv-snw.

File map

app/addons/kv_serial_warranty/
  addon.xml, init.php, func.php
  controllers/backend/kv_serial_warranty.php   register, unit, receipts, claims, import/export, labels, order actions
  controllers/backend/products.post.php        product tab data
  controllers/backend/orders.post.php          order tab data
  controllers/frontend/kv_serial_warranty.php  account page, warranty check
  controllers/frontend/orders.post.php         serials on the customer's order page
  controllers/frontend/init.post.php           account menu flag
  schemas/ menu, permissions, settings
  Tygh/Addons/KvSerialWarranty/
    Config, Pattern, Warranty, Barcode, Pdf, Products, Serials, Receipts, Orders, Claims, Csv, Lookup,
    License/*, Upgrade/Synchronizer
design/backend/templates/addons/kv_serial_warranty/ views, components, hooks, license
design/backend/css/addons/kv_serial_warranty/styles.less
js/addons/kv_serial_warranty/backend.js
var/themes_repository/responsive/templates/addons/kv_serial_warranty/ views, components, hooks
var/themes_repository/responsive/css/addons/kv_serial_warranty/styles.less
var/langs/en/addons/kv_serial_warranty.po