# Service Label Designer WHMCS Addon # Description ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) ## PUQ Service Label Designer — WHMCS Addon **PUQ Service Label Designer** is an addon module for WHMCS that allows you to fully customize how service names and labels are displayed in the client area services list and on invoices. Using per-group templates with dynamic variables, you can create rich, informative service labels that include product names, domains, IPs, client info, custom fields, and more — with full HTML support. - - - - - - ## Key Features - **Per-Group Templates** — configure label templates for each product group separately - **Client Area Overwrite** — replace default service names in the client area "My Products & Services" list - **Invoice Text** — add, replace, or prepend custom text to invoice line item descriptions - **Invoice Modes** — choose per group how invoice text is applied: Append, Replace, or Prepend - **Dynamic Variables** — use template variables that are replaced with real service data: - `{product-name}`, `{group-name}` — product and group names - `{service-domain}`, `{service-username}`, `{service-dedicatedip}`, `{service-assignedips}` — service details - `{service-id}`, `{service-status}`, `{service-regdate}`, `{service-nextduedate}` — service info - `{client-name}`, `{client-email}` — client details - `{service-customField-[name]}`, `{service-configOption-[name]}` — custom fields and config options - **HTML Support** — templates support full HTML for rich formatting (bold, colors, tables, icons, etc.) - **Default Values** — configure fallback values for empty fields (domain, username, IP, etc.) - **Live Preview** — preview how your template renders with real service data before saving - **Export / Import** — export all settings and templates to a JSON file, import on another WHMCS instance - **Bulk Operations** — enable/disable all groups for List or Invoice in one click - **Dashboard** — overview with key metrics, enabled groups summary, and live preview of recent services - **License system** — online/offline license verification with graceful degradation (dashboard remains accessible without a license) - **English language interface** - - - - - - ## System Requirements

Requirement	Minimum
WHMCS	8.x, 9.x
PHP	8.1, 8.2+
ionCube Loader	v13 or newer (v14, v15)

- - - - - - ## Links - **Product page:** [https://puqcloud.com/](https://puqcloud.com/) - **Documentation:** [https://doc.puq.info/books/service-label-designer-whmcs-addon](https://doc.puq.info/books/service-label-designer-whmcs-addon) - **Support:** [https://puqcloud.com/submitticket.php](https://puqcloud.com/submitticket.php?step=2&deptid=1) - **Community:** [https://community.puqcloud.com/](https://community.puqcloud.com/)# Changelog ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) ## v1.0 — 2026-02-15 First release. ### New Features - Per-group label templates for client area services list - Per-group invoice text templates with three modes: Append, Replace, Prepend - Dynamic template variables: `{product-name}`, `{group-name}`, `{service-domain}`, `{service-username}`, `{service-dedicatedip}`, `{service-assignedips}`, `{service-id}`, `{service-status}`, `{service-regdate}`, `{service-nextduedate}`, `{client-name}`, `{client-email}`, `{service-customField-[name]}`, `{service-configOption-[name]}` - Full HTML support in templates - Default fallback values configuration for empty service fields - Live template preview with real service data - Export / Import of all settings and templates as JSON - Bulk operations: Enable All / Disable All for List and Invoice checkboxes - Dashboard with key metrics, enabled groups overview, and recent services preview - AJAX-based save/load for all pages - ClientAreaPage hook for overwriting service names in client area - InvoiceCreation hook for modifying invoice line item descriptions - License verification system with online/offline modes - Dashboard accessible without active license, other pages restricted - English language interface# Installation and Update ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) ## System Requirements

Requirement	Minimum
PHP	8.1, 8.2 or newer
WHMCS	8.x, 9.x or newer
ionCube Loader	v13 or newer (v14, v15)

> **Note:** The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server. - - - - - - ## Download The module can be ordered and downloaded from PUQ Cloud: - **Order / Download:** [https://puqcloud.com/store/whmcs-addon-modules](https://puqcloud.com/store/whmcs-addon-modules) - **FAQ:** [https://community.puqcloud.com/](https://community.puqcloud.com/) - **Direct download links:** PHP 8.1: ``` wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/php81/PUQ_WHMCS-Service-Label-Designer-latest.zip ``` PHP 8.2+: ``` wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/php82/PUQ_WHMCS-Service-Label-Designer-latest.zip ``` > All versions are available at: [https://download.puqcloud.com/WHMCS/addons/PUQ\_WHMCS-Service-Label-Designer/](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) After downloading, extract the archive: ``` unzip PUQ_WHMCS-Service-Label-Designer-latest.zip ``` - - - - - - ## Installation ### Step 1: Upload Files Extract the module archive and upload the `puq_service_label_designer` directory to the WHMCS addons directory: ``` /your-whmcs/modules/addons/puq_service_label_designer/ ``` Directory structure after upload: ``` modules/addons/puq_service_label_designer/ puq_service_label_designer.php hooks.php whmcs.json version logo.png lib/ puqServiceLabelDesigner.php lang/ english.php templates/ ... ``` ### Step 2: Activate the Module 1. Log in to the WHMCS admin panel 2. Go to **Setup** > **Addon Modules** 3. Find **PUQ Service Label Designer** in the list 4. Click **Activate** > On activation, the module creates two database tables: `puq_service_label_designer_config` and `puq_service_label_designer_overwrite`. ### Step 3: Configure the License Key 1. After activation, click **Configure** next to the module 2. Enter your license key in the **License key** field 3. Select admin role groups that should have access to the module 4. Click **Save Changes** After saving, a verification status will appear below the license key field (e.g., `success: 2027-02-16T01:32:13+01:00`). ![Module configuration with license key and access control](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-l5yswh9r.png)*01-addon-config-license.png* ### Step 4: Access the Module Go to **Addons** > **PUQ Service Label Designer** to access the dashboard. - - - - - - ## Update ### Step 1: Backup Before updating, we recommend backing up: - Your WHMCS database - Module files in `modules/addons/puq_service_label_designer/` ### Step 2: Upload New Files Extract the new version and overwrite all files in: ``` /your-whmcs/modules/addons/puq_service_label_designer/ ``` ### Step 3: Re-activate (if needed) If the update adds new database columns, deactivate and re-activate the module: 1. Go to **Setup** > **Addon Modules** 2. Click **Deactivate**, then **Activate** again > This is safe — the module only creates tables/columns if they don't already exist. Your settings and templates are preserved. ### Step 4: Verify 1. Go to **Addons** > **PUQ Service Label Designer** 2. Check the version number in the top-right corner of the navigation bar (e.g., `v1.0`) - - - - - - ## Deactivation 1. Go to **Setup** > **Addon Modules** 2. Click **Deactivate** next to PUQ Service Label Designer 3. Confirm the deactivation > **Warning:** Deactivation drops the module's database tables (`puq_service_label_designer_config` and `puq_service_label_designer_overwrite`). All your templates and settings will be lost. Export your settings before deactivating if you want to preserve them. - - - - - - ## License The module requires an active license for full functionality. The license is verified through the PUQ Cloud license server. ### How License Verification Works - The module periodically checks license validity at `https://license.puqcloud.com/` - Verification results are cached in the database for 5 days - If the license server is temporarily unreachable, the module uses the last cached result ### Without an Active License - **Dashboard** (Home page) remains fully accessible - **All other pages** (Config, Designer) display a license required page - **All AJAX controllers** (except Dashboard) return a 403 error ### After Activating a License 1. The warning banner disappears 2. All pages and features become accessible 3. Enter your license key in **Setup** > **Addon Modules** > **PUQ Service Label Designer** > **Configure** ### Purchase a License **[https://puqcloud.com/store/whmcs-addon-modules](https://puqcloud.com/store/whmcs-addon-modules)** For license-related questions, please contact us via the ticket system: **[https://puqcloud.com/submitticket.php](https://puqcloud.com/submitticket.php?step=2&deptid=1)**# Dashboard ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) The Dashboard is the home page of the module, available at: **Addons** > **PUQ Service Label Designer** > **Home** It provides a complete overview of your label configuration — key metrics, enabled groups, and a live preview of how labels look on recent services. ![Dashboard — metrics, enabled groups, and recent services preview](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-dw0qbzw3.png)*02-dashboard.png* - - - - - - ## Key Metrics The top section displays summary cards:

Metric	Description
Total Groups	Number of product groups configured in WHMCS
Total Products	Number of products across all groups
Active Services	Services with Active status
Groups List Enabled	Number of groups with the client area list overwrite enabled
Groups Invoice Enabled	Number of groups with invoice text enabled

- - - - - - ## Enabled Groups A table showing all product groups that have either List or Invoice overwrite enabled:

Column	Description
ID	Product group ID in WHMCS
Group Name	Name of the product group
Active Services	Number of active services in this group
Status	Badges indicating which features are enabled: List (blue), Invoice (orange), and the invoice mode (append/replace/prepend)
List Template	Preview of the overwrite list template (truncated)
Invoice Template	Preview of the invoice text template (truncated)

- - - - - - ## Recent Services Preview A table showing the 5 most recent active services that belong to groups with List overwrite enabled:

Column	Description
ID	Service ID in WHMCS
Product	Product name and group name
Client	Client full name
Rendered Label	The actual rendered result of applying the template with real service data

This section lets you instantly see how your templates look in practice without navigating to the client area.# Configuration ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) The Configuration page is available at: **Addons** > **PUQ Service Label Designer** > **Config** Here you set default fallback values for template variables. When a service field is empty, the corresponding default value is used instead. ![Configuration — default values and available variables reference](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-iwrbwrfa.png)*03-configuration.png* - - - - - - ## Default Values The left panel contains input fields for each default value:

Setting	Description
Default Product Name	Fallback when a product has no name (rare)
Default Group Name	Fallback when a group has no name
Default Service Domain	Shown when a service has no domain assigned
Default Service Username	Shown when a service has no username
Default Service Dedicated IP	Shown when a service has no dedicated IP
Default Service Assigned IPs	Shown when a service has no assigned IPs
Default Custom Field	Shown when a custom field value is empty
Default Config Option	Shown when a config option value is empty

> **Tip:** Set all defaults to `-` or `N/A` to avoid blank spaces in your rendered labels when service data is missing. - - - - - - ## Available Variables The right panel displays a reference table of all template variables you can use in the Designer:

Variable	Description
`{product-name}`	Product name
`{group-name}`	Product group name
`{service-domain}`	Service domain
`{service-username}`	Service username
`{service-dedicatedip}`	Service dedicated IP address
`{service-assignedips}`	Service assigned IPs
`{service-id}`	Service ID
`{service-status}`	Service status (Active, Suspended, etc.)
`{service-regdate}`	Service registration date
`{service-nextduedate}`	Service next due date
`{client-name}`	Client full name
`{client-email}`	Client email address
`{service-customField-[name]}`	Custom field value (replace `[name]` with the field name)
`{service-configOption-[name]}`	Config option value (replace `[name]` with the option name)

- - - - - - ## How Defaults Work When a template is rendered, each variable is replaced with the actual service data. If the data is empty, the default value from this page is used instead. **Example:** Template: `{product-name} / {service-domain}` - Service has domain `example.com` → **VPS Basic / example.com** - Service has no domain, default is `N/A` → **VPS Basic / N/A** - Service has no domain, default is empty → **VPS Basic /**# Label Designer ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) The Label Designer page is available at: **Addons** > **PUQ Service Label Designer** > **Designer** This is the main page of the module where you configure label templates for each product group. ![Label Designer — template editor with per-group configuration](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-1g9rxibl.png)*04-designer.png* - - - - - - ## Page Layout The page consists of several sections: ### Top Bar - **Import** — import settings and templates from a JSON file - **Export** — export all settings and templates to a JSON file - **Save** — save all changes ### Available Variables A reference panel listing all template variables you can use. See [Configuration](05-configuration.md) for a detailed description of each variable. ### Bulk Operations A toolbar with quick actions: - **Enable All List** / **Disable All List** — check or uncheck all "Enable in List" checkboxes - **Enable All Invoice** / **Disable All Invoice** — check or uncheck all "Enable in Invoice" checkboxes - - - - - - ## Groups Table The main table lists all product groups from WHMCS with the following columns:

Column	Description
ID	Product group ID
Group Name	Name of the product group
Products count (cube icon)	Number of products in this group
Enable in List (list icon)	Checkbox — enable overwriting service names in client area
Overwrite List Text	Template for the client area services list. Supports HTML and template variables
Enable in Invoice (invoice icon)	Checkbox — enable adding custom text to invoice descriptions
Invoice Text	Invoice mode selector and template. Supports HTML and template variables

- - - - - - ## Overwrite List Text When the **Enable in List** checkbox is checked for a group, all services belonging to products in that group will have their names replaced in the client area "My Products & Services" page. The template supports: - All template variables (e.g., `{product-name}`, `{service-domain}`) - Full HTML (e.g., ``, ``, `
`, ``) - Any combination of text and HTML **Example template:** ```html {product-name}({group-name})
{service-domain} — {service-dedicatedip} | {service-assignedips} ``` - - - - - - ## Invoice Text When the **Enable in Invoice** checkbox is checked, the module modifies invoice line item descriptions for services in that group. ### Invoice Mode Each group has a mode selector above the invoice template textarea:

Mode Behavior
**Append** Adds the template text **after** the original invoice description (on a new line)
**Replace** **Replaces** the original invoice description entirely with the template text
**Prepend** Adds the template text **before** the original invoice description (on a new line)
**Example (Append mode):** Original: `Mikrotik VPN 10M/10M/10GB (01/03/2026 - 31/03/2026)`Template: `{product-name} ({group-name}) — | User: {service-username} | IP: {service-dedicatedip}` Result: ``` Mikrotik VPN 10M/10M/10GB (01/03/2026 - 31/03/2026) Mikrotik VPN 10M/10M/10GB (Mikrotik VPN) — | User: 1-5525 | IP: 192.168.222.2 ``` - - - - - - ## Preview Each template textarea has a preview button (eye icon). Click it to see how the template renders with real service data from that group. ![Preview modal — rendered template with real service data](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-cd2kbp3m.png)*05-preview.png* The preview modal shows: - **Service ID** — which service was used for the preview - **Rendered result** — the template with all variables replaced by actual data > **Note:** The preview uses the current textarea content (not saved data), so you can test your template before saving. - - - - - - ## Export / Import ### Export Click the **Export** button to download a JSON file containing: - All configuration settings (default values) - All group templates and settings (enable flags, modes, template text) ### Import Click the **Import** button and select a previously exported JSON file. The import will: - Overwrite all configuration settings - Replace all group templates and settings > **Warning:** Import replaces all existing settings. Export your current settings first if you want to keep them as a backup. This feature is useful for: - Migrating settings between WHMCS instances - Backing up your configuration before making changes - Sharing templates between environments (dev/staging/production)# Client Area and Invoices ### Service Label Designer addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/store/whmcs-addon-modules) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Service-Label-Designer/) | [FAQ](https://community.puqcloud.com/) This page shows how the module affects the client-facing pages — the services list in the client area and invoice descriptions. - - - - - - ## Client Area — Services List When a group has **Enable in List** checked, all services in that group display the rendered template instead of the default product name + domain format. ![Client area — services list with custom labels](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-xdstih4j.png)*06-client-area.png* The module hooks into the **ClientAreaPage** event (priority 1000) and replaces the service display data for the "My Products & Services" page. ### What Gets Replaced - **Product name** — replaced with the rendered template - **Domain** — set to a space (hidden) since the template typically includes domain info ### Example With the template: ```html {product-name} / {group-name}
Domain: {service-domain} | User: {service-username}
IP: {service-dedicatedip} | Assigned: {service-assignedips}
Client: {client-name} ({client-email})
Registered: {service-regdate} | Next Due: {service-nextduedate} | Status: {service-status} ``` Each service in the client area shows a rich, multi-line label with all relevant information instead of just the product name. - - - - - - ## Invoices When a group has **Enable in Invoice** checked, the module modifies invoice line item descriptions when a new invoice is created. ![Invoice — modified line item descriptions](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-e2dw3ntd.png)*07-invoice.png* The module hooks into the **InvoiceCreation** event (priority 1) and processes each invoice line item that has a related service (relid). ### Invoice Modes The behavior depends on the mode selected for each group:
Mode Result
**Append** Original description + newline + rendered template
**Replace** Only the rendered template (original description removed)
**Prepend** Rendered template + newline + original description
### Example (Append mode) Original invoice line: ``` Mikrotik VPN 10M/10M/10GB (01/03/2026 - 31/03/2026) ``` With template: `{product-name} ({group-name}) — | User: {service-username} | IP: {service-dedicatedip}` Result: ``` Mikrotik VPN 10M/10M/10GB (01/03/2026 - 31/03/2026) Mikrotik VPN 10M/10M/10GB (Mikrotik VPN) — | User: 1-5525 | IP: 192.168.222.2 ``` ### Important Notes - Invoice text modification happens **only when the invoice is created**. Existing invoices are not affected. - Only line items with a related service (`relid != 0`) are processed. - If an error occurs during processing, it is logged via `logModuleCall` and the original description is preserved.

Mode	Behavior
Append	Adds the template text after the original invoice description (on a new line)
Replace	Replaces the original invoice description entirely with the template text
Prepend	Adds the template text before the original invoice description (on a new line)

Mode	Result
Append	Original description + newline + rendered template
Replace	Only the rendered template (original description removed)
Prepend	Rendered template + newline + original description