MaxtDesign

Configuration

Two Levels of Configuration

Companion Products has two configuration surfaces:

  • Per-product — every simple product has a Companion Products meta box on its edit screen. This is where you choose the required list, the add-on list, display style, pricing, and out-of-stock behavior.
  • Global — under WooCommerce → Settings → Companion Products, with three sections: General, Tools, System Status.

    • Per-Product Meta Box

    Located on every simple product edit screen.

    Required Companions panel

  • Enable required product selection for this product — master toggle
  • Selection Label — the heading customers see (e.g. "Select Required Product")
  • Required Products — search-and-add list, drag to reorder
  • Display Style — Radio Buttons (best for ≤5 options) or Dropdown (best for many options)
  • Out-of-stock behavior per companion — Block, Allow Backorders, or Hide

    • Add-on Sections panel

  • Enable add-on products for this product — master toggle
  • Sections — create one or more named sections (for example "Wall Panels", "Mounting Hardware"), drag to reorder
  • Section mode — each section is checkbox (pick any) or radio (pick at most one, including none)
  • Add-on Products — search-and-add list per section, drag to reorder within the section
  • "Display as" override per companion — a shorter label shown on the product widget only; cart, checkout, emails, and orders keep the real product name
  • "Incompatible with" per companion — tick the add-ons (or required options) that conflict with it. Incompatible items dim with an explanation on the product page, and the rule is enforced again server side at add-to-cart

    • Pricing display

  • Per-option price — each companion shows its own price
  • Combined total — the parent page shows a single live running total
  • Both — per-option price and a running total

    • The running total honors your store currency and WooCommerce tax display setting (inclusive or exclusive). You can rename or hide it, and trim long companion titles, under WooCommerce → Settings → Companion Products.

    Global Settings — General

    WooCommerce → Settings → Companion Products → General

    Multi-Select User Roles

    Required companions default to single-select for all users. Tick one or more roles here (e.g. Wholesale, Dealer, Subscriber) to give those roles a multi-select dropdown so they can pick multiple required companions in a single add-to-cart. Regular customers continue to see single-select.

    This is useful when wholesale buyers need to pick from a list of compatible parts in one transaction.

    Running Total and Titles

  • Running total label — rename the live total shown on the product page
  • Running total visibility — show or hide the running total globally
  • Long-title truncation — trim long companion titles to one line on the widget, with the full name on hover

    • Global Settings — Tools

    WooCommerce → Settings → Companion Products → Tools

  • Export Configuration — downloads a JSON file containing the full v2 configuration (sections and modes, "Display as" overrides, incompatibility rules, thumbnail settings, per-product and global settings), all keyed by SKU
  • Import Configuration — uploads a previously-exported JSON file. Matches products by SKU on this site (with a product ID fallback) and reports per-product success or skip in an admin notice. Files exported from version 1 still import fine
  • Clear Cache — flushes the requirements lookup transient cache (1-hour TTL, auto-invalidated on product save and stock change, manual flush rarely needed)

    • The SKU-keyed export format makes config portable between sites with different product IDs — useful for staging → production promotion.

    Global Settings — System Status

    WooCommerce → Settings → Companion Products → System Status

    Shows cache statistics, the number of products with companions configured, the HPOS state, and any environment warnings. Use this for troubleshooting before opening a GitHub issue.

    What's saved where

  • Per-product settings — postmeta table under _mcp_* keys, scoped to the parent product (sections, "Display as" overrides, incompatibility pairs, and thumbnail display are part of this versioned data layer)
  • Global settings — single autoloaded wp_options row at mcp_settings
  • Cart relationship — runtime cart_item_data keys (mcp_required_qty, mcp_extra_qty, mcp_parent_product_id, mcp_parent_cart_key, mcp_is_required, mcp_is_optional)
  • Order item meta — _mcp_is_required, _mcp_is_optional, _mcp_group_id, _mcp_parent_product_id on the line item (visible in admin order detail)
    • InstallationFeatures