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 Companions panel

  • Enable add-on products for this product — master toggle
  • Add-on Products Label — section heading on the frontend
  • Add-on Products — search-and-add list, drag to reorder
  • Conflict Group Key per add-on — short string. Two add-ons sharing the same key cannot both be selected.

    • Pricing display

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

    • 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.

    Global Settings — Tools

    WooCommerce → Settings → Companion Products → Tools

  • Export Configuration — downloads a JSON file containing per-product settings, global settings, and conflict-group keys, all keyed by SKU
  • Import Configuration — uploads a previously-exported JSON file. Matches products by SKU on this site and reports per-product success or skip in an admin notice
  • 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
  • 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