Use this guide to diagnose and resolve the most common issues with WooCommerce Square. For each issue, follow the steps in order before contacting support.
Connection Issues
↑ Back to topCannot connect WooCommerce to Square
↑ Back to top- You must be the owner of the Square account. This integration requires permissions that Square only grants to account owners.
- If you receive an ‘Unauthorized’ error, contact Square to verify your account ownership before retrying.
Business location not showing in settings
↑ Back to topIn your Square account, confirm that you are the owner of the location in question and that you have completed Square onboarding.
Business location is greyed out
↑ Back to top- This usually indicates a communication issue between servers. Check whether a security or firewall plugin is blocking external requests.
- Under WooCommerce > System Status, confirm that cURL is installed.
- Verify your site’s SSL certificate is valid.
- Run a conflict test to rule out interference from a plugin or theme.
Product Sync Issues
↑ Back to topProducts are not syncing
↑ Back to top- Check that all synced products have a SKU set in both WooCommerce and Square. SKUs are how the plugin matches products between systems.
- Verify the Square product is assigned to the same Location configured in WooCommerce > Settings > Square.
- Confirm your server supports background processing. Background processing is required to successfully sync product data between Square and WooCommerce. If your site fails, please contact your host to enable background processing/loopback connections. While some hosts may identify this as a security issue, there’s no security threat to using a loopback connection and, if done correctly, it won’t increase server usage. Quality hosts will mitigate increased server usage with rate limiting.
Stock remains unchanged or stale
↑ Back to topA failed inventory read is not the same as a confirmed stock count of zero. If WooCommerce cannot confirm the count from Square, it leaves the current quantity unchanged instead of replacing it with zero.
If a quantity is not changing, confirm that the product is assigned to the correct Square location and that Sync with Square is enabled. Check WooCommerce > Status > Logs and the sync record for an inventory error, then run a new sync after correcting the issue.
Sync is stuck
↑ Back to topSometimes the syncing process could get stuck. When this happens, neither automatic nor manual sync will work. In cases like these, try the following troubleshooting steps:
- Go to WooCommerce > Status > Tools.
- Use Clear Square Sync to stop the current sync process.
- Wait a moment, then try syncing again.
If clearing sync does not resolve the issue:
- Go to WooCommerce > Status > Scheduled Actions.
- Filter by Pending and In Progress.
- Delete any stuck Square sync actions.
- New actions will be created automatically.
Note: WPEngine’s shared hosting terminates processes running longer than 60 seconds, which can interrupt wc_square_background_sync. Contact WPEngine support to temporarily disable this, or restart the import repeatedly using Clear Square Sync under WooCommerce > Status > Tools, until all products are imported (look for Completed step cycle: update_inventory_counts in logs).
Automatic Recovery
WooCommerce detects a sync that has stopped responding and stops it automatically, which releases the queue so later syncs can run. A long sync on a large catalogue is not affected. Each step reports progress, so only a sync that has genuinely gone quiet is stopped.
When this happens, a notice appears in the WordPress admin. It explains that a stuck sync was stopped, warns that product data may be out of date, and links to the page where you can start a new sync. The sync records show a matching failed entry. The notice clears as soon as you start a new sync.
Sync completes but some products are skipped
↑ Back to topA sync can finish even when an individual product is not updated in Square. WooCommerce continues with the other products and records the skipped product’s name, SKU, and reason in the sync records or logs.
- Open the sync record or WooCommerce > Status > Logs and note the product name, SKU, and reason.
- Correct the reported issue, such as a missing SKU, an invalid variation, or a stale Square ID.
- Run the sync again and confirm that the product is included.
Blank product variations in Square
↑ Back to topIf a Square product has blank variation lines between populated ones (e.g., Small, [blank], Medium, Large), this can cause sync issues. Move any blank lines to the end of the variation list in Square.
Sync fails for products with stale Square IDs
↑ Back to topIf a product was once linked to a different Square account, a deleted item in Square, or a staging site, WooCommerce still remembers the old Square ID. That old ID no longer resolves to the intended item, so the product can fail to sync until you remove the stale link and run a new sync.
If one product has a stale Square mapping, WooCommerce can skip that product while continuing with other products in the same sync. Review the sync record for the product name, SKU, and reason, fix the product or stale mapping, and run the sync again.
Symptoms of the issue:
- WooCommerce > Status > Logs shows Square errors mentioning an ID you don’t see in your current Square catalog.
- A product looks synced in WooCommerce but never changes in Square.
- After connecting a new Square account, previously synced products stop matching.
Here are the steps to fix this issue:
- Find the product with the stale mapping.
Open WooCommerce > Status > Logs and note the product name, SKU, and reason. If no product is named, review products that are still linked to the old account or item and address them one at a time. You can temporarily set suspect products to Draft so other products can continue syncing.
- Clean up the stale linkage on both Square and WooCommerce.
To reset the connection, remove the broken link in both Square and WooCommerce:
In Square: Open your Square Dashboard and delete (or archive) the item so the next sync creates a fresh record instead of colliding with the old one.
In WooCommerce: If you migrated to a different Square account or sandbox, reconnect the site to the intended account and run a sync so WooCommerce Square can create new mappings. Do not copy or manually edit Square catalog IDs between accounts. If the stale link still points to a deleted item, contact support with the product name, SKU, and relevant sync log details.
After reconnecting to the intended Square account, confirm Sync with Square is still enabled on the product.
- Republish and re-sync.
If you found the product to Draft in step 2, switch it back to Published. Then go to WooCommerce > Settings > Square > Update > Sync Now. The plugin will match the product to Square by SKU and create a fresh connection.
Still not working?
Confirm the SKU exists in your current Square catalog and that the correct location is selected in WooCommerce > Settings > Square.
Order Sync Issues
↑ Back to topOrders not syncing to Square:
↑ Back to top- Confirm your Square account is connected via WooCommerce > Settings > Square.
- Verify that the order sync feature is enabled in Square settings.
- Check that the order used the Square payment gateway.
WooCommerce status not updating:
↑ Back to top- Confirm Action Scheduler is running. Go to WooCommerce > Status > Action Scheduler and look for
wc_square_sync_orders. - In Square, verify the order status is either Completed or Cancelled — only these statuses trigger a sync back to WooCommerce.
- Check WooCommerce > Status > Logs for sync errors.
Manually trigger an order sync
↑ Back to top- Go to WooCommerce → Status → Action Scheduler
- Navigate to the Pending tab
- Find the
wc_square_sync_ordersevent - Click Run.
Fulfillment button not visible in Square:
↑ Back to top- Confirm order was created through WooCommerce (not manually in Square)
- Verify order has proper fulfillment details
- Check Square Dashboard permissions
Payment Gateway Issues
↑ Back to topCannot process payments
↑ Back to top- Confirm your site has an SSL certificate installed. Click here to learn more about SSL certificates.
- Confirm your WooCommerce store currency and Square account currency match (store currency is set in WooCommerce > Settings > General).
- Confirm your shop location set in WooCommerce > Settings > General is in a supported country: US, CA, UK, AU, IE, ES, FR, JP.
- If you’re using a code optimization or minification plugin, exclude WooCommerce Square from it. Minification can break the Square payment fields.
- Did the payment fail with an error code in the order notes or in the logs? Refer to the common error codes returned by Square in this document.
Order fails with “[VALUE_TOO_LONG] Field must not be greater than 50 length” error
↑ Back to topWhen Order Fulfillment Sync is enabled, the plugin sends the WooCommerce shipping method name to Square as the shipping carrier. Square only accepts up to 50 characters for this field, so any shipping method with a longer title causes the order to fail with VALUE_TOO_LONG – Field must not be greater than 50 length.
Try one of the following:
- Shorten the shipping method title to 50 characters or fewer. Go to WooCommerce > Settings > Shipping, open the relevant shipping zone, and edit the method name.
- Disable Order Fulfillment Sync if you don’t need fulfillment details to appear in Square. Go to WooCommerce > Settings > Square and uncheck the Order Fulfillment Sync option.
After making the change, place a new test order to confirm it processes successfully.
Authorized payments not showing in Square Transactions
↑ Back to topAuthorized (but not yet captured) payments do not appear in Square’s Transactions list until they are captured in WooCommerce. This is expected behavior.
If you see issues with authorization, please note the following:
- Square authorizations are only valid for 6 days and can’t be captured after that. You’ll need a new authorization from the customer if you miss the window.
- Always void authorizations and process refunds in WooCommerce, not Square. While Square is aware of changes in WooCommerce, WooCommerce is not aware of changes within Square. For any transaction that originates in WooCommerce, you should make additional changes (such as voiding / revoking authorizations and processing refunds) within WooCommerce.
- Square doesn’t support staging sites on subdomains (e.g.,
staging.yourdomain.com) — the auth token won’t match the redirect domain, and the connection will fail. Use a subfolder instead (e.g.,yourdomain.com/staging/).
“Payment nonce is missing” error at Checkout
↑ Back to topWhen payment doesn’t go through with the error “Payment nonce is missing” at Checkout, it usually indicates that the Square Web Payments SDK was unable to generate or pass the required token to WooCommerce during checkout. This is usually either due to a JavaScript conflict that prevents Square scripts from collecting all required information from the checkout page; or a required billing address field is hidden on a customized Checkout page.
Try disabling all caching and optimization plugins first, then run a full conflict test if that doesn’t resolve the issue.
Order is held for review
↑ Back to topWhen an order is at the On hold status with this note: Square Transaction Held for Review () Order status changed from Pending payment to On hold, this is usually related to Square holding transactions for account-level reasons. The following steps can be applied to confirm this:
- Confirm that Transaction Type is set to Charge via WooCommerce > Settings > Payments > Square
- If the settings are correct, contact Square to investigate why transactions are on hold for review, which can occur when the account isn’t fully set up.
Apple Pay Not Displaying
↑ Back to topIf you’ve enabled Digital Wallets but the Apple Pay button isn’t being displayed, check the following:
- Check for admin notices about Apple Pay on WooCommerce > Settings > Payments > Square.
- Enable Square logging (WooCommerce > Settings > Square) and visit the Square settings page to trigger domain verification. Check logs for errors when verifying the domain.
- Ensure you are viewing your store from a supported browser or device. Apple Pay is only available on Safari on supported Apple devices with a valid card in Apple Wallet.
Gift Card payment failure with an error “Invalid payment method.”
↑ Back to topWhen a Gift Card is entered, the amount is correctly deducted from the Gift Card at Checkout. However, when the customer proceeds to pay with the Gift Card, an error appears: Invalid payment method.
This is usually a sign of a conflict issue. Test with a default Checkout page using the [woocommerce_checkout] shortcode and perform a conflict test as needed.
Import issues
↑ Back to topItems are not importing from Square
↑ Back to top- Verify Square products are assigned to the same Location set in WooCommerce > Settings > Square.
- Confirm products have SKUs set in Square.
- Confirm your server supports background processing.
Frequently Asked Questions
↑ Back to topPlease refer to the Frequently Asked Questions guide.
