Product Companion

Product Companion is a WHMCS addon that automatically bundles companion products into the cart when their parent product is selected, and removes them when the parent is removed. Configurable parent → child links replace one-off cart hooks for common bundling scenarios.

Overview

The module adds a single hook to WHMCS that runs on every cart total recalculation. When a parent product is in the cart, its linked companion is auto-added with the same billing cycle and domain. When the parent is removed, the companion is stripped. Multiple parents can share the same companion - it stays as long as any linked parent remains.

The module only modifies the cart session. It does not write to tblhosting, tblorders, tblinvoices, or any other WHMCS table. Disabling the module immediately stops auto-bundling.

Requirements

• WHMCS 8.9 or later
• PHP 8.1 or later
• ionCube Loader matching your PHP version
• Valid license from ArkHost

Installation

1. Download the module from your ArkHost client area
2. Upload the modules folder to your WHMCS root, preserving the directory structure
3. Navigate to System Settings → Addon Modules
4. Click Activate next to Product Companion
5. Click Configure, paste your license key, and save
6. Set admin role permissions as needed
7. Open Addons → Product Companion to start adding links

Configuration

The module configuration page accepts the following settings:

License Key

Your ArkHost license key for the module. Required for the module to operate.

Fallback Billing Cycle

Used only when a cart row has no billing cycle set, which is rare. Default: quarterly.

Clear Data on Deactivation

When enabled, drops the link table on module deactivation. Default: off (data preserved across deactivate/reactivate cycles).

Adding Links

1. Open Addons → Product Companion
2. In the Add Companion Link panel, select one or more parent products. Hold Ctrl (or Cmd on macOS) to select multiple.
3. Select the companion (child) product from the right-hand dropdown
4. Click Add Link(s)

Each parent gets its own row in the link table. The same child can be linked from any number of parents and will remain in the cart as long as any of its linked parents is present.

Managing Links

The Configured Links table provides per-row actions:

Disable

Keeps the link configuration but stops the cart hook from acting on it. Useful for temporarily pausing a bundle without losing the configuration.

Delete

Removes the link permanently.

Panel-level actions:

Search

Filters the link table in real time by parent or companion product name, product ID, or shared-with badge text.

Test

Opens a modal where you select a parent product. The module simulates the cart hook and shows what would auto-add. No real cart is touched.

Export

Downloads all configured links as CSV with full product names and metadata.

How It Works

The module installs one hook:

On every cart total recalculation:

1. For every parent product in the cart, the linked child is added if not already present, inheriting billingcycle and domain from the parent
2. Any companion product whose linked parents are all absent from the cart is stripped

Loop and Chain Detection

At save time, the module performs two checks:

Reverse loop

If you try to create a link B → A while A → B already exists, the save is rejected with a hard error. This prevents infinite cart-mutation loops.

Chain warning

If the new link's parent is itself a child elsewhere, or its child is itself a parent elsewhere, the save proceeds but a warning is shown. This flags multi-tier chains, which v1 does not propagate through (see Limitations).

Limitations

v1 has the following intentional boundaries:

• No chain propagation. If A → B and B → C are both configured, adding A only auto-adds B, not C. Save-time warnings flag this.
• No service cancellation cascade. Cancelling a parent service in WHMCS admin after checkout does not affect the child service. This is on the v1.1 roadmap.
• Product-to-product linking only. The module does not link configurable options, addons, promo codes, or quantities.

Troubleshooting

Companion is not being added to the cart

• Verify the link is enabled in the Configured Links table
• Confirm the parent product is actually being added to the cart (not just visited on a product page)
• Use the Test tool to confirm the link configuration
• Check the WHMCS Activity Log for entries from Product Companion

Companion stays in cart after parent is removed

• Reload the cart page - the strip happens on cart total recalculation
• Check whether another parent linked to the same companion is still in the cart (this is intended behaviour)

Save fails with reverse loop error

• You are attempting to create a circular link. Either delete the existing reverse link or pick a different parent/child pairing.

Module activation fails

• Confirm ionCube Loader is installed and matches your PHP version
• Verify the database user has CREATE TABLE privileges
• Check the WHMCS Activity Log for the specific activation error

FAQ

Can the same product be both a parent and a child of different links?

Yes. The module supports this configuration but flags it with a chain warning at save time, since v1 does not propagate through chains.

What happens if the companion product is deleted from WHMCS while a link exists?

The link remains in the database but the cart hook silently skips it. You should delete or update the affected link manually.

Does the module work with MarketConnect products?

Yes. MarketConnect products appear as standard products in WHMCS and can be used as either parent or child.

Does the companion inherit configurable options or addons from the parent?

No. v1 only inherits billing cycle and domain. Configurable option propagation is not in scope.

Will the companion be charged?

That depends on your companion product's pricing configuration. Set the companion to free (paytype: free, or zero price across all cycles) if it should not be billed.

Can I prevent customers from ordering the companion product directly?

Mark the companion product as Hidden in WHMCS. The module will still add it via cart hook even though it does not appear in the storefront.

Support

For documentation and support tickets, visit arkhost.com/submitticket.php.