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, which is 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