Getting started

Overview

Product Addons lets you attach extra options to any WooCommerce product — from a simple "add gift wrapping?" toggle to a multi-step product configurator with live price calculation.

Everything is organised into addon groups. A group is a reusable bundle of fields with its own pricing, conditional logic and assignment rules. You build a group once, then assign it to as many products, categories or customer roles as you like. A single product can show several groups at once.

Getting started

Requirements & installation

1. Install the plugin. In WordPress go to Plugins → Add New → Upload Plugin, choose the phox-product-addons.zip file and click Install Now.
2. Activate it. A new Product Addons item appears in the main admin menu (look for the layout icon).
3. Confirm WooCommerce is active. Product Addons extends WooCommerce, so WooCommerce must be installed and active first.

Getting started

Quick start — your first addon

Let's add an optional gift-wrapping fee to a product in under a minute.

1. Open Product Addons from the admin menu, then click New Addon Group (or pick a ready-made template — see Starter templates).
2. Name the group at the top, e.g. "Gift options".
3. Add a field. On the Fields tab click Add field and choose Toggle Switch. Label it "Add gift wrapping" and set its price to a fixed 3.95.
4. Assign the group. On the Assignments tab add a target — choose Entire store, or search for specific products or categories.
5. Set it live. On the Settings tab set Status to Active, then click Save.
6. Check the product page. The toggle now appears below the product, and ticking it adds £3.95 to the live total and the cart.

Getting started

The admin interface

The plugin opens on the groups list, where every addon group is shown with its field count, priority and status. From here you can create, duplicate, export, import or delete groups, and toggle the global itemised totals setting.

Opening a group reveals the group editor, organised into four tabs:

Building addons

Field types

Product Addons ships with twenty-one field types across five categories. Add as many as you like to a group and drag them into any order.

Basic Basic

Selection Selection

Visual Visual

Products Products

Advanced Advanced

Common field settings

Every field shares a few settings: a label, an optional description shown beneath it, and a Required toggle. Text-style fields add a placeholder and maximum length; option fields add an options editor; visual fields add image and badge controls.

Building addons

Options, images & badges

Selection and visual fields are built from a list of options. For each option you can set:

• Label — what the shopper sees.
• Value — the stored identifier used in logic and on the order.
• Price & price type — a per-option add-on (fixed amount or percentage).
• Image or colour — for image dropdowns, visual cards and swatches (colour swatches accept a second colour for a two-tone chip).
• Badge — a small label such as "Popular" or "Bestseller" shown on cards and image dropdowns.
• Description — extra copy on cards and image dropdowns.

Images are chosen through the standard WordPress media library, so anything already in your media library is available instantly.

Building addons

Pricing

Pricing is set per field (or per option). Every priced selection is added to the product price, multiplied by quantity, and shown in the live total and the cart. All prices are recalculated authoritatively on the server when the item is added to the cart, so totals can never be tampered with from the browser.

Building addons

Formulas & calculator groups

Formula pricing turns Product Addons into a made-to-measure calculator. Set a field's price type to Formula and enter an expression such as:

(width * height) * 15

Formulas support +, -, *, / and parentheses. The available variables are:

• product_price — the current product (or variation) price.
• quantity — the chosen quantity.
• Any Number field's formula variable name. For example, set a Number field's variable name to width and another to height, and both become usable in formulas.

Calculator groups

Set a group's type to Calculator and give the group itself a formula. The result is added as a single priced line labelled with the group title — ideal for area- or volume-based pricing where the charge comes from the whole configuration rather than one field.

Building addons

Conditional logic

The Logic tab lets fields react to what the shopper does. A rule reads as: when these conditions are met, perform these actions.

Actions

Conditions

Conditions can test much more than other fields. Each rule holds one or more condition groups; within a group you choose whether all or any conditions must pass, and you choose whether all or any groups must pass. This lets you build sophisticated AND/OR logic.

Building addons

Assignments

The Assignments tab decides where a group appears. Add one or more targets; they are combined with OR, so the group shows whenever any target matches.

Combining groups

When several groups match the same product, the group's mode and priority decide how they interact:

Priority is a number; higher-priority groups load first and win in Override mode.

Building addons

Display modes & layouts

A group's display mode (on the Settings tab) controls how its fields are laid out on the product page.

Modal popup New

Instead of showing a group's fields inline, you can tuck them behind a button that opens a popup. Tick Open options in a modal popup on the group's Settings tab — it wraps whichever display mode you've chosen (Cards, Grid, Tabs, Steps and so on), so it works over any layout.

On the product page the shopper then sees:

• A trigger button in place of the inline fields, with text you set via Modal button text (default "Customise Product").
• A popup containing all the group's fields plus a live total, opened by the button and dismissed with the close icon, the backdrop or the Esc key.
• A confirm button — text set via Confirm button text (default "Save options") — which validates the group's required fields before closing. If something's missing the popup stays open and highlights it.
• Once confirmed, the trigger turns into a summary: a "Customised" tick, the added price, and an Edit link that reopens the popup.

Special fields

File uploads

The File Upload field lets shoppers attach artwork, proofs or documents to their order. You can allow a single file or several, and cap the number of files.

Allowed files & limits

By default the field accepts JPG, JPEG, PNG, SVG, PDF, DOC and DOCX files up to 10 MB each. Both limits can be changed by a developer (see Hooks & filters).

Security

Uploads are validated defensively, so executable files such as .php cannot be uploaded or run:

• Every file is checked against an allow-list of types — and the file's real contents are inspected, not just its extension, so a renamed script is rejected.
• Files are stored with randomised names in a dedicated uploads/phox-addons/ folder.
• SVGs are sanitised to strip scripts and event handlers.
• The upload folder is hardened with rules that block execution of .php, .phtml, .cgi and similar files and disable directory listing.

Special fields

Date & time

The Date, Time and Date & Time fields collect scheduling information — delivery dates, appointment slots, event times and so on. Each offers an optional Allowed range with an Earliest and Latest limit shown side by side.

When a range is set, a value outside it is rejected both in the browser (the shopper sees an error and can't add to cart) and again on the server, so an out-of-range date can never reach an order.

Special fields

Visual cards & swatches

Visual Cards, Image Swatches and Colour Swatches turn flat option lists into a polished, tactile picker. Each supports:

• Single or multiple selection. Tick Allow multiple selections on the field to let shoppers choose several options at once (they render as checkboxes); leave it off for a one-of-many picker (radio behaviour).
• Per-option pricing and badges, so a "Premium" card can carry both an upcharge and a label.
• For Visual Cards, a 1–4 column layout.
• For Image Swatches, a zoom lightbox so shoppers can preview the full image.
• Replace the product image — optionally swap the main product photo for the selected option's image (see below).

Replace the product image New

Image Dropdown, Visual Cards and Image Swatches each have a "Replace product image with selected option" checkbox in the field's settings. Turn it on and, when a shopper picks an option that has an image, the product page's main image swaps to that option's image; clearing the choice (or selecting an option without an image) restores the original.

It works with the standard WooCommerce product gallery and with the Phox Elements / Phox Oxygen Product Display element, both detected automatically — so shoppers see the exact variant they're configuring. The original image and its responsive srcset are restored intact when the selection is cleared.

Special fields

Product options New

The Product Options field lets you offer other products as selectable options — bundles, cross-sells or an "add a matching item" upsell. Each option points at a real WooCommerce product (or a specific variation), so its price, name and image come straight from that product and stay in sync.

Configuring options

• Product — search for and pick the product each option represents.
• Discount — an optional percentage off that product's live price, just for this option.
• Quantity — how many of the product a single selection adds (defaults to one).
• Label & badge — override the displayed name and add a small label such as "Popular"; leave the label blank to use the product's own name.
• Single or multiple selection, rendered as cards with the product thumbnail (choose 1–4 columns).

Pricing & stock

Options are priced from the product's live, sale-aware price (with any per-option discount applied) and multiplied by the option quantity. Because the price is read from the product itself, a later price change or sale on the linked product is reflected automatically. Out-of-stock products are shown as disabled and can't be selected, and any option whose product no longer exists or can't be purchased is skipped everywhere.

Workflow

Starter templates

From the groups list you can create a group from a ready-made template — a fast way to learn the plugin or stand up common patterns. Each is created as a draft so you can review and adjust before going live.

Workflow

Import & export

Any group can be exported to a JSON file from the groups list, and imported on another site (or the same one). This makes it easy to move configurations between staging and production, or to keep a backup of a complex configurator.

Workflow

Settings & totals

Per-group settings

Itemised totals

A global toggle on the groups list controls how add-ons appear in the totals box. With itemised totals on, each priced selection gets its own line; with it off, all add-ons are summed into a single "Options" row.

Workflow

The storefront & cart

On the product page, add-ons appear below the product with a live totals box that updates as the shopper configures. Required fields are validated before the item can be added to the cart. If an image field has Replace product image enabled, the product's main photo also updates as the shopper chooses.

From there, selections flow through the whole order:

• The shopper's choices and their prices are shown under the item in the cart and at checkout.
• Add-on charges are added to the line item's price.
• Selections are saved to the order and appear in admin order details and in order emails.
• Product Options add the chosen product to the order as its own line item, at the discounted price where set.
• Uploaded files are linked from the order so you can download exactly what the customer sent.

---

Developer reference

Data model

Addon groups are stored as a hidden custom post type, phox_addon_group. The entire configuration — fields, options, assignments, logic and settings — is serialised as JSON in the _phox_config post meta.

Developer reference

REST API

The React admin is powered by a REST API under the phox-addons/v1 namespace. All group endpoints require the manage_woocommerce capability.

Developer reference

Hooks & filters

Actions

// Render a product's addon groups inside a custom template / page builder.
// Fires the same renderer WooCommerce's product page uses.
do_action( 'phox_addons_product_display', $product );

Filters

// Change which groups apply to a product.
add_filter( 'phox_addons_groups_for_product', function ( $groups, $product ) {
    return $groups;
}, 10, 2 );
// Change the maximum upload size (bytes). Default 10 MB.
add_filter( 'phox_addons_max_upload_size', fn() => 20 * MB_IN_BYTES );
// Change the allowed upload types (extension => mime).
add_filter( 'phox_addons_allowed_upload_types', function ( $types ) {
    $types['ai'] = 'application/postscript';
    return $types;
} );

Developer reference

Front-end JS API

Each rendered addon block exposes a small API on its root element, so custom add-to-cart implementations can validate and read the live total. The block also dispatches a bubbling phox-addons:change event whenever a selection changes.

const root = document.querySelector('[data-phox-addons]');
// Validate required fields before submitting. Returns true if valid.
if ( ! root.phoxAddons.validate() ) return;
root.phoxAddons.refresh();           // recompute visibility & totals
root.phoxAddons.total;               // current per-unit addon total
root.phoxAddons.setProductPrice(p); // override price (variation-aware hosts)
// React to configuration changes.
root.addEventListener('phox-addons:change', (e) => {
    console.log(e.detail.total);
});

Developer reference

Page-builder integration

Product Addons integrates with custom product templates — including the Phox Elements and Phox Oxygen "Product Display" elements — that don't use WooCommerce's default form.cart.

To render add-ons inside a custom template, fire the action where you want them to appear:

do_action( 'phox_addons_product_display', $product );

Then, in your add-to-cart handler:

• Call root.phoxAddons.validate() and stop if it returns false.
• Append the serialised phox_addons[...] fields to the POST body so they reach the cart.
• For variation-aware layouts, call setProductPrice() when the selected variation changes so percentage and formula pricing follow the live price.

The renderer guards against rendering twice for the same product on a page, so it's safe whether it fires via the standard WooCommerce hook or your custom template.

---

Help

Troubleshooting

Breakdance or the site shows "Constant PHOX_ADDONS_VERSION already defined"

Two copies of the plugin are active at once — usually the original phox-product-addons folder plus a second upload such as phox-product-addons-latest. WordPress loads both, and the second defines the same constant, which triggers a fatal error. Deactivate and remove one copy so only a single phox-product-addons folder remains, then update in place rather than adding a parallel folder.

The group doesn't appear on the product

Check that its Status is Active (not Draft), that it has at least one Assignment target matching the product, and that its mode isn't set to Exclude. If another matching group uses Override at a higher priority, it may be replacing this one.

A product option isn't showing

Product Options skip anything that can't be sold: a product that's out of stock appears but is disabled, and an option whose product has been trashed, set to draft, or changed to a variable/grouped/external type is dropped entirely. Point the option at a purchasable simple product or a specific variation.

The product image doesn't swap

Confirm the field has Replace product image with selected option ticked and that the chosen option actually has an image. The swap targets the standard WooCommerce gallery and the Phox Product Display element; a heavily customised or third-party gallery may use different markup (see Front-end JS API).

A file upload says "Session expired. Please reload the page"

This means the upload's security nonce didn't validate. It most often happens when a product page is served from a cache for a long time, or when a custom add-to-cart calls the upload endpoint without forwarding the logged-in session. Reload the page to refresh the nonce; for custom integrations, send the X-WP-Nonce header (see REST API).

The live total looks wrong

The cart price is always recalculated on the server, so the cart is the source of truth. If the browser total disagrees, it's usually a stale cached copy of the plugin's script — clear any page/CDN cache. Hidden fields (via logic) are never charged.

New features or styles aren't showing

Clear your site and browser caches. The plugin versions its assets automatically, but aggressive CDNs sometimes hold an old copy.

Help

FAQ

Can one product show several addon groups?

Yes. Every group whose assignment matches the product is shown (in Merge mode), and logic can even reference fields across those groups.

Are add-on prices charged per item?

Yes — add-on prices are per unit and are multiplied by the quantity, just like the base product price.

Can I offer other products as add-ons?

Yes — use the Product Options field. Each option links to a real product or variation, is priced from its live price (with an optional discount), respects stock, and is added to the order as its own line item. See Product options.

Can an option change the product image?

Yes. On image fields, enable Replace product image with selected option and the main product photo swaps to the chosen option's image, restoring when the choice is cleared. See Visual cards & swatches.

Can shoppers select more than one visual card or swatch?

Yes. Enable Allow multiple selections on the field and it behaves like a checkbox group while keeping the visual styling.

Is it safe to let customers upload files?

Yes. Uploads are restricted to an allow-list of document and image types, validated by real content rather than extension, stored with randomised names, and the folder is hardened against script execution. SVGs are sanitised. See File uploads.

Can I move a configuration between sites?

Yes — export the group to JSON and import it elsewhere. It arrives as a draft with assignments cleared, ready to review and re-assign. Re-pick any Product Options, since they reference products by ID.

---

Phox Product Addons Pro · v1.1.0 · by Phox Elements · Built for WooCommerce. For the latest information visit phoxelements.com.