Fix: Clear stale Square category ID from all associated WooCommerce categories

[faisal-alvi]

All Submissions:

• Does your code follow the WooCommerce Sniffs variant of WordPress coding standards?
• Have you written new tests for your changes, as applicable?
• Have you successfully run tests with your changes locally?
• Will this change require new documentation or changes to existing documentation?

---

Changes proposed in this Pull Request:

When multiple WooCommerce product categories were mapped to the same Square category ID and that Square category was deleted or missing, refresh_category_mappings() only cleared the stale mapping for one WC category. The rest kept the invalid Square ID, causing manual sync to fail at upsert_categories().

This change:

• Builds the category audit so all WC term IDs are stored per Square ID (array per key instead of a single value), so no mapping is overwritten.
• When a Square category is found in the API response, updates square_version in the map for every associated WC category.
• When a Square category is missing (stale), flattens the remaining audit entries and removes the stale mapping from every associated WC category, marking them unmapped so sync can create new Square categories and continue.

Note

The plugin does not intentionally allow multiple WC categories per Square ID; this can occur when two WC categories share the same name and are matched to the same Square category across syncs, or from manual/DB edits. The fix makes cleanup resilient to that state.

Closes https://linear.app/a8c/issue/SQUARE-261/stale-category-mapping-not-fully-cleaned-up-when-two-woocommerce.

Steps to test the changes in this Pull Request:

1. Set WooCommerce Square to use WooCommerce as the system of record and ensure at least two product categories exist and are mapped to Square (run a successful manual sync first if needed).
2. Simulate the bug: manually edit the wc_square_category_map option so two WC category IDs point to the same square_id.
3. Run manual sync (WooCommerce → Settings → Square → Sync).
4. Confirm sync completes without failing at category upsert, and that both WC categories no longer have the stale Square ID (check the map or Tools → Square category map test); both should be unmapped and eligible for new Square category creation on the next sync.

Changelog entry

Fix - Stale category mapping not fully cleaned when two WooCommerce categories share the same Square category ID; all associated WC categories are now unmapped and sync continues.

[github-actions]

🔍 WordPress Plugin Check Report

❌ Status: Failed

📊 Report

🎯 Total Issues	❌ Errors	⚠️ Warnings
8	8	0

---

❌ Errors (8)

📁 includes/Framework/PaymentGateway/Admin/views/html-admin-gateway-status.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/Framework/PaymentGateway/Admin/views/html-user-profile-section.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/Framework/PaymentGateway/Admin/views/html-user-payment-token-editor.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/Framework/PaymentGateway/Admin/views/html-user-profile-field-customer-id.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/Framework/PaymentGateway/Admin/views/html-order-partial-capture.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/Framework/PaymentGateway/Admin/views/html-user-payment-token-editor-token.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/WC_Payments_Compatibility.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

📁 includes/Admin/Product_Editor_Compatibility.php (1 error)

📍 Line	🔖 Check	💬 Message
0	missing_direct_file_access_protection	PHP file should prevent direct access. Add a check like: if ( ! defined( 'ABSPATH' ) ) exit;

---

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

[faisal-alvi]

@iamdharmesh Could you give this a code review when you get a chance?

[iamdharmesh]

Thanks @faisal-alvi. Code looks good.