Configuration

Settings: Add-ons → Manage add-ons → Image Optimizer (WebP/AVIF & Lazy Load) → Settings. The Settings button on Website → Image optimizer opens the same page. All settings apply to the whole installation: the image files are shared by every storefront (CS-Cart Ultimate) and every vendor (Multi-Vendor).

General

Setting	Default	Description
Enable	On	Switches the whole add-on off without uninstalling it. The storefront then shows the original images.
Server support	–	Shows whether this server can write WebP and AVIF, and with which library (see Server support).
Serve optimised images	Picture element	Picture element: the image gets AVIF and WebP sources; browsers that support a format load the smaller copy, all others the original. Safe with the full page cache and any CDN. Replace with WebP: the image address points straight to the WebP copy (also the zoom/lightbox link); no AVIF and no fallback for very old browsers. Use it only if a theme script changes image addresses and the picture element gets in the way. Off: copies are created but not used yet (for example while you test).
Native lazy loading	On	Adds loading="lazy" and decoding="async" to images further down the page, so the browser loads them only when they come close to the screen. The logo, the first banner of the home page and the main product image are never lazy.
Images loaded at once at the top of a page	4	The first images CS-Cart renders on a page are never lazy.
High priority for the main product image	On	Adds fetchpriority="high" to the main image of product pages and to the first banner of the home page. These are usually the largest element on the page (Largest Contentful Paint).

Conversion

Setting	Default	Description
Create WebP copies	On	WebP is supported by all current browsers.
WebP quality (1-100)	80	80 keeps product photos visually identical to the original. Lower values give smaller files.
Lossless WebP for PNG images	Off	Keeps PNG graphics pixel-exact. Lossless files are larger than lossy ones; a copy is only kept when it is smaller than the PNG.
Create AVIF copies	On	AVIF is usually another 20–40 % smaller than WebP. Browsers that support AVIF prefer it. Needs PHP 8.1+ with AVIF in GD, or Imagick with AVIF.
AVIF quality (1-100)	50	AVIF needs a lower number than WebP for the same visual quality.
Minimum saving (%)	5	A copy is kept only if it is at least this much smaller than the source. Otherwise the original is served.
Images to optimise	all	Thumbnails (the resized images on product lists and pages), Product and category images (the full-size originals shown in zoom and lightbox), Banners, Other images (logos, feature variants, blog, promotions). Turning a group off deletes its copies on the next scan (daily, or at once with Scan for new images). Files uploaded in the text editor (images/companies/) are not touched: they are not shown through the CS-Cart image template.
Exclude files	–	One pattern per line, * matches any characters. A pattern without a slash matches a file or folder name (logo*.png), a pattern with a slash matches the path inside the images folder (detailed/12/*). Excluded files lose their copies on the next scan.
Image library	Auto	Auto uses Imagick when it supports the format and GD otherwise. Choose GD or Imagick to force one.
Largest image (megapixels)	30	Larger images are skipped to protect the server memory. Images that would not fit into the PHP memory limit are skipped too.

Original images

Setting	Default	Description
Compress original images	Off	Re-saves JPEG originals at the quality below and PNG originals losslessly, but only if the result is at least the minimum saving smaller. Every original is copied to var/kv_image_optimizer_webp/originals/ first. Restore originals on the image optimizer page and uninstalling the add-on put them back. Thumbnails are not compressed (CS-Cart creates them from the originals; their quality is the core setting Settings → Thumbnails). JPEG images that are rotated by EXIF data are left as they are.
JPEG quality for originals (40-100)	82	82 is visually lossless for product photos.
Remove metadata (EXIF, comments)	On	Camera data and comments are removed from compressed originals. Colour profiles are kept with Imagick. With GD, metadata cannot be kept: when this is off, JPEG originals with metadata are not compressed.

Processing

Setting	Default	Description
Process while an administrator works in the admin panel	On	Without a cron job, new and changed images are optimised in short batches (5 seconds, at most every 2 minutes) while an administrator uses the admin panel.
Seconds per run	20	Time limit of one cron run. The Optimise now button works in batches of up to 8 seconds.
Automation	–	The cron command for this store, for example every 15 minutes: php /path/to/store/admin.php --dispatch=kv_image_optimizer_webp.cron. Optional arguments: --seconds=120 (longer run), --rescan=Y (scan the whole images folder now).

Server support

The add-on only uses PHP extensions. What it finds is shown on the General tab and on the image optimizer page:

Server	WebP	AVIF
GD with WebP support (most hosts)	yes	–
GD on PHP 8.1+ built with AVIF	yes	yes
Imagick with WebP / AVIF delegates	yes	yes
Neither	The page says so; nothing is converted and nothing changes on the storefront. Ask your host to enable WebP in the PHP GD extension.

If AVIF is not available, the add-on creates WebP copies only and adds AVIF later when the server supports it (click Create all copies again).

What happens with special images:

Image	Result
Animated GIF / PNG / WebP	Kept as it is (a converted copy would lose the animation).
JPEG with EXIF rotation	The copy is rotated the way browsers show the original.
Images with a colour profile other than sRGB (for example Adobe RGB)	Converted with Imagick, which keeps the profile. GD would change the colours, so with GD these images are skipped.
CMYK JPEG	Converted with Imagick (to sRGB); skipped with GD.
Transparent PNG	Transparency is kept in WebP and AVIF.
WebP thumbnails of the core setting Thumbnails → Format: WebP	Get an AVIF copy only.
A copy that would not be smaller	Not kept; the original is served.

The reason for every skipped image is shown in the files list.

CDN and image storage

• Images on this server (the CS-Cart default): fully supported.
• CloudFront CDN (Administration → Storage → CDN settings): supported. The copies live in the same images storage, so the CDN loads them from your server like any other image, with the CDN’s cache-busting time stamp.
• Amazon S3 storage ($config['storage']['images'] with the Amazon backend): not supported. The add-on detects it, shows a notice and changes nothing on the storefront.
• Web server: the copies are plain .webp and .avif files. Apache, nginx, LiteSpeed and Caddy serve them as images; the add-on adds an .htaccess with the AVIF/WebP MIME types for older Apache versions.

License

The license status is shown in a License card at the top of the add-on page, above the tabs, so you see it on every tab. The License tab holds the key itself. The key is stored once for the whole installation.

The License card shows:

• the status in color: green when valid, blue for a development host or the 14-day period before a key is required (with the days left), amber when the license server could not be reached (with the days left) or a Marketplace number is still being verified, red when the add-on is switched off;
• in plain words what the status means and, when the add-on is (or will be) switched off, what stops: no new images are converted or compressed, and the storefront shows the original images without WebP/AVIF or lazy-loading changes; all images keep working: compressed originals stay valid, and Restore originals and Delete optimised copies stay available;
• the licensed domain, every storefront with its result (covered, development host, not covered), the end of the updates and support period, the last and the next check, and the key in use (masked);
• the actions Enter license key / Change license key (opens the License tab), Check now (verifies at once and stays on the page), Manage license (your licenses on cs-cart.kaviolabs.com) and, without a valid license, Buy a license.

In Add-ons → Manage add-ons the add-on’s row shows a small license badge next to its name, for example License: Valid or License: Pending · 9 days left.

The image optimizer page shows the license status in a bar at the top: a small green chip when the license is valid, or a banner with the status, what is switched off and the same actions as the card. Vendors never see license information.

Setting	Description
License key	Your Kavio Labs license key (KAVIO-XXXX-XXXX-XXXX-XXXX, from My licenses on cs-cart.kaviolabs.com) or your CS-Cart Marketplace license number. If you entered the Marketplace license number in Add-ons → Manage add-ons (the add-on’s license field), leave this empty: the add-on uses that number.
License status	Points to the License card and explains what the check sends.

What the license covers. A license is bound to the base domain you entered at purchase (for example example.com) and covers every subdomain of it (www.example.com, shop.example.com, staging.example.com). Local development hosts are always allowed: localhost, 127.0.0.1 and other private IP addresses, and host names ending in .localhost, .test, .local, .example or .invalid. A store on a different base domain needs its own license. If you move your store to a new domain, contact support.

When the add-on checks. When you save the key, and then once a day. The check runs only in the admin panel (on a page you open) or from cron, never while customers browse the storefront, and takes a few seconds at most. A cron job keeps the license verified even when nobody opens the admin panel:

php /path/to/store/admin.php --dispatch=kv_image_optimizer_webp_license.check

What is sent. The check sends this to https://cs-cart.kaviolabs.com and nothing else: the license key, the add-on ID and version, the host names of your storefronts, your CS-Cart version and edition, and a random one-time value. No images, customer, vendor, order or personal data are sent. The server answers with a digitally signed result, so a forged answer is ignored.

Statuses.

Status (card)	Color	What happens
Valid	Green	The license is valid for this domain. Everything works.
Development host	Blue	The store runs on a local development host, which every license covers. Everything works.
Pending verification	Amber	A CS-Cart Marketplace license number was accepted, but the Marketplace has not confirmed it yet. Everything works.
Pending · N days left	Blue	No verified key yet (a new installation). Everything works for 14 days.
Grace period · N days left	Amber	The last checks failed (for example a network problem). The add-on keeps working for 14 days after the first failed check.
Not activated, Invalid key, Revoked, Domain mismatch, Not verified	Red	No new images are converted or compressed (cron, Optimise now and the background batches stop), and the storefront shows the original images without the picture element or lazy-loading changes. Nothing is deleted: the copies stay on disk and are used again when the license is valid, compressed originals stay valid images, and the statistics, Restore originals and Delete optimised copies keep working. Domain mismatch shows the licensed domain next to the domain your store runs on.

When your updates and support period ends, the add-on keeps working. Only updates and support stop.

License information appears in the admin panel only, and only for administrators who may manage add-ons; vendors and customers never see it. When the add-on is switched off, other admin pages also show a notice once per session with a link to the add-on page; the add-on page and the image optimizer page show the card or the status bar instead.