Product Personalizer for WooCommerce

Overview

Plugin: kv-product-personalizer · Version: 1.0.0 · Compatibility: WordPress 6.7+, WooCommerce 10.1+ (tested 11.2.1), PHP 7.4+, HPOS, Cart and Checkout blocks, block and classic themes

Customers type a name, a date or their initials, pick a font and a position and see the result on the product image before they add the item to the cart. You set the rules once in a template: which fields, how many characters, which fonts, what it costs. Every value is checked again on the server, the fee is added to the item price, and the personalization follows the item to the cart, the checkout, the order, the e-mails and the production sheet.

Installation

Requirements

WordPress 6.7 or later, WooCommerce 10.1 or later (tested up to 11.2.1), PHP 7.4 or later.

Install

1. Plugins > Add New Plugin > Upload Plugin: choose kv-product-personalizer-kv.zip (from My licenses) and click Install Now, then Activate.
2. WooCommerce > Settings > Product Personalizer > Licence: paste your licence key. You have 14 days to do it; staging and local sites (localhost, *.test, *.local, private IPs) are included.

Update

Upload the new zip the same way and choose "Replace current with uploaded". Templates, settings and orders are kept.

Uninstall

Deactivate and delete the plugin. Orders always keep their personalization texts. Templates, settings and the template choices of products and categories are removed only when Remove data on uninstall is on (WooCommerce > Settings > Product Personalizer).

Configuration

Settings

WooCommerce > Settings > Product Personalizer.

Templates

Products > Personalization. A template is the form customers fill in. Template options: name (admin only), title on the product page, optional (customers tick the title to open the form; otherwise the form is always open), block offensive words, live preview, active. Use Copy to start a new template from an existing one.

Field options:

The positions are areas of the product image (center: the middle 56 % x 20 %; top and bottom: the upper and lower bands; upper and lower third). Use product photos where the engraving area sits in one of them.

Prices

Amounts are entered like product prices (with or without tax, as in WooCommerce > Settings > Tax). The fee of one item is added to the product price after sale prices and taxed with the product's tax class. Spaces and line breaks are never charged. Example: per character $0.50 with 3 free characters, "Happy Birthday" = 13 characters - 3 = 10 x $0.50 = $5.00. Products with measured quantities (decimal quantities such as 2.5 m) pay the fee once per cart line.

Products and categories

• Product: Product data > Personalization: use the category template, a template of its own, or "Not personalized". The note below the field shows which template applies now. Variations use the template of the product.
• Category: Products > Categories > edit (or add): Personalization template. Products use the template of their categories first, then of the parent categories (nearest first). The category list shows a Personalization column.
• Simple and variable products can be personalized (filter kv_pp_product_types for more). Category templates never apply to virtual products; choose a template on the product to personalize one.

Usage

Shopper flow

1. On the product page the customer ticks the template title (optional templates) and fills in the fields.
2. The text appears on the product image in the chosen font and position; the character counter and the fee update while they type. Wrong input is explained next to the field (too long, characters that cannot be engraved, a word that is not allowed...).
3. Add to cart checks everything again on the server and adds the item with its personalization. Different personalizations of the same product become separate cart lines; the same personalization adds to the quantity.
4. Products with a required template cannot be added from product lists; the list shows a Personalize button that opens the product page.

Cart, checkout and orders

The cart (block and classic), mini cart and checkout show each field ("Engraving: Happy Birthday (Great Vibes, Top)") and the fee per item; the line price includes the fee. Quantities can be changed in the cart. The order confirmation, My Account, the order e-mails and the admin order screen show the same rows (order item meta). "Order again" keeps the personalization.

Production sheet

WooCommerce > Personalization sheet lists the personalized lines of open orders (Processing, On hold) with the full specification: text in its font, monogram as engraved and as typed, font, style, position and finish.

• Filter by date, order number or all statuses; include lines already produced.
• Select lines and Mark selected as done when they are produced; they leave the open list.
• Print prints a clean sheet without the admin menus.

The order screen has a Personalization box with the same data and a link to the sheet of that order.

Developers

Data

• Templates: option kv_pp_templates. Product choice: product meta _kv_pp_template (empty = category, none, or a template id). Category template: term meta kv_pp_template.
• Cart line: kv_pp = set_id, set (template snapshot), values (field id => t, fo, st, p), fee (one item), hash.
• Order item: visible meta per field (label => text) and "Personalization fee"; hidden _kv_pp (same structure as the cart line plus per_line) and _kv_pp_done (timestamp). Order meta _kv_pp_has = yes. All through the order CRUD (HPOS).

Store API

Each cart item has extensions["kv-product-personalizer"]: personalized, template, fields (id, label, text, font, style, position), fee, fee_per_line. Add a personalized item:

POST /wp-json/wc/store/v1/cart/add-item
{ "id": 123, "quantity": 1,
  "kv_product_personalizer": { "on": true, "values": { "name": { "t": "Robin", "fo": "playfair", "p": 0 } } } }

Field ids come from the template; fo = font key, st = monogram style key, p = position index. A product with a required template is refused (HTTP 400) without this data.

Hooks

FAQ

Can customers change the price in the browser?

No. The fee is computed on the server from the template and the text; every add to cart (product form, AJAX, Store API) is checked again.

Which fonts are included?

Playfair Display, Cormorant Garamond, Cinzel, Montserrat, Great Vibes, Alex Brush, Pinyon Script and Dancing Script (SIL Open Font License 1.1; files and licences in assets/fonts), plus Georgia, Times New Roman, Arial and Courier New. Fonts download only on products that use them.

Are fees discounted by coupons?

Coupons apply to the whole line price, which includes the fee. Sale prices apply to the product price only; the fee is added afterwards.

What happens when I edit a template later?

Carts and orders keep the template as it was when the item was added.

Does it work with my theme?

It is tested with Twenty Twenty-Five (block theme) and the classic shortcode cart and checkout. Any theme that uses the WooCommerce add-to-cart form and product gallery works.

Does it add checkout fields?

No. Nothing changes in the checkout form.

Can I use it with Sell by Measure for WooCommerce?

Yes. A measured line (for example 2.5 m) carries the personalization and pays the fee once per line.

Why are "<" and ">" refused?

They are never accepted, so no markup can reach e-mails or documents.

What if I switch the plugin off?

The form disappears and products are sold without personalization. Lines already in carts keep their personalization and fee; orders are never changed.