Improve UX clarity between "Sync Now" and "Import all Products from Square" buttons

[m-muhsin]

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:

This PR improves clarity between the "Sync Now" and "Import all Products from Square" actions to reduce merchant confusion.

Problem: Merchants were confused because both buttons lead to similar-looking pages, but they do different things:

• "Sync Now" only updates existing linked products
• "Import all Products from Square" brings new products from Square into WooCommerce

This caused support cases where merchants couldn't understand why new products added in Square weren't appearing after using "Sync Now".

Solution: Added descriptive helper text in key locations to clarify the difference:

1. Update tab: Added helper text below the "Sync Now" button and a warning notice in the sync modal explaining it only updates existing synced products (when Square is the system of record)

2. Settings tab (PHP): Added description text below the "Import all Products from Square" button explaining how it differs from "Sync Now"

3. Settings tab (React): Added the same description text and localized the import modal title

Closes #447
Closes https://linear.app/a8c/issue/SQUARE-225/improve-ux-clarity-between-sync-now-and-import-all-products-from.

Steps to test the changes in this Pull Request:

1. Set Square as the System of Record in WooCommerce > Settings > Square
2. Navigate to WooCommerce > Settings > Square > Update tab
3. Verify the "Sync Now" button now shows helper text: "Updates existing synced products only..."
4. Click "Sync Now" and verify the modal includes a yellow warning note about scope
5. Navigate to WooCommerce > Settings > Square > Settings tab
6. Verify the "Import all Products from Square" button has description text below it
7. Test both the React-based settings (new experience) and legacy PHP settings

Changelog entry

Add - Added helper text and notices to clarify that "Sync Now" only updates existing synced products, while "Import all Products from Square" is needed to bring new products into WooCommerce.

[github-actions]

This is linked to GitHub issue #446.

[github-actions]

This is linked to GitHub issue #447.

[m-muhsin]

Thanks for the kind and detailed feedback, @iamdharmesh. Should look okay now.

[iamdharmesh]

Thanks @m-muhsin.

@m-muhsin Could you please check if PR description is accurate about changes we made in the PR. Also, I think sort description of what we are doing in whole PR would be more helpful instead of AI generate summary with file wise changes. Thank you.

[m-muhsin]

@iamdharmesh updated PR description accordingly. Thanks!

[qasumitbagthariya]

QA Update ✅

---

I have verified this PR in the fix/square-225 branch, which has been fixed and is functioning as intended.

I tested the following on this branch:

• The "Sync Now" button now shows helper text: "Updates existing synced products only.

• Sync Now" and verify the modal includes a yellow warning note about scope

• Import all Products from Square" button has description text below it

• Setup Wizard

Testing Environment

Details

• WordPress: 6.9
• Theme: Twenty Twenty-Five 1.4
• WooCommerce - 10.4.0
• PHP: 8.0.30
• Web Server: Nginx 1.20.2
• Browser: Chrome
• OS: macOS 15.2
• Branch: fix/square-225

Steps to Test- As mentioned in the PR description.
Test Results - It is working as expected.
Functional Demo / Screencast -
Special Notes - Ready for UAT
Testing Document status:
Cases related to this Issue/PR are added to the Critical Flow Wiki pages:

• Yes
• Not Required/Applicable for this PR

---