WooCommerce Square: Troubleshooting

Not able to connect your site to Square? You must be the owner of the Square account to do so. This integration needs access to much of the data in your Square account, and Square only grants these permissions to owners.

If you get an “Unauthorized” error when attempting to connect with Square, please check with Square if you are the owner of the account you’re connecting to.

If there are problems with the product/inventory sync, please check the following:

• Are SKUs set for your Square and WooCommerce products? This is how the plugin will match products between these systems.
• Is the Square product assigned to the Location that’s configured in the plugin settings? This plugin only supports one Square Location, so if some products aren’t syncing as expected, double-check to ensure they are in the same Square Location as defined in the plugin settings.
• Does your site support background processing? Background processing is required to successfully sync product data between Square and WooCommerce. Square and many other WooCommerce features/plugins require background processing. 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.

WPEngine runs a script that terminates processes taking longer than 60 seconds, which might stop the wc_square_background_sync process. This only impacts clients on shared hosting. A temporary workaround is to reach out to WPEngine and ask to have it turned off for the duration of the import.

Alternatively, wait for the process to get stuck, use the Clear Square Sync option under WooCommerce > Status > Tools, and start the import again. Repeat the process until no further products are imported. The log will be marked with Completed step cycle: update_inventory_counts.

Square for WooCommerce v3.0 and newer uses the official Square SDK for API communication with the Square platform. Some API responses are cached to improve performance.

• Ensure opcache.save_comments is enabled. This is required for the plugin and product sync to work correctly.

If this setting is disabled and you’re experiencing issues, you may need to contact your hosting provider to change the setting.

Credit card fields are not translating? To translate Square we need to take the .pot language files from wp-content/plugins/woocommerce-square/i18n/languages and use this to generate 2 new language files. Following that you should end up with language files like the following, replacing the {locale} placeholder with the appropriate one.

• woocommerce-square-{locale}.mo
• woocommerce-square-{locale}.po

Place the two translation files under /wp-content/languages/plugins/

If you see issues when importing items from Square, please check the following:

• Is the Square product assigned to the Location that’s configured in the plugin settings? This plugin only supports one Square Location, so if some products aren’t syncing as expected, double-check to ensure they’re in the Square Location defined in the plugin settings.
• Are SKUs set in Square for items you want to import? Items must have a SKU to match items between systems when syncing product data.
• Does your site support background processing? Background processing is required to successfully sync product data between Square and WooCommerce. Square and many other WooCommerce features/plugins require background processing. 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.

If you’re unable to process payments with the Square gateway, please check the following:

• Does your site have an SSL certificate? To use the Square payment gateway, you must have an SSL certificate installed on your site. Click here to learn more about SSL certificates.
• Does your site currency match your Square account currency? Square and WooCommerce must be set to the same currency to use the gateway. You can set your WooCommerce store currency from WooCommerce > Settings > General. Your Square location currency is based on the country selected when creating your account.
• Is your shop located in a supported country? Square can only accept transactions from the following countries: US, CA, UK, AU, IR, ES, FR and JP. If your shop base address is in a different country, you can’t process transactions with Square. You can view and modify your shop location from WooCommerce > Settings > General.
• Is your transaction type set to “Authorization”? Authorizations will not display in the Square “Transactions” list until you capture the charge within WooCommerce.
• 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.
• Are your payment methods, such as the credit card field, not loading correctly? Many site optimization plugins minify the code of extensions, which may introduce breaking changes to Square. Please exclude the extension from any optimization and minification rules.

Seeing issues with authorizations? Please note the following:

• Square authorizations are only valid for 6 days. After this time frame, the authorization can no longer be captured, so the capture action is disabled. You must obtain a new authorization from the customer if you have not captured the charge in this time frame.
• You should revoke authorizations within WooCommerce when possible. 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.

If you’ve enabled Digital Wallets but the Apple Pay button isn’t being displayed, please check the following:

• Are there any admin notices related to Apple Pay when viewing the Square settings page?
• Has your domain been verified with Square/Apple? To verify your domain has been verified in Square, please following the steps found in our Digital Wallet Apple Pay Setup section. To help with troubleshooting any errors, enabling Square logging (found in WooCommerce > Settings > Square) will log the response that was received when attempting to register your domain.
• Are you viewing your store from a support browser or device? Apple Pay is only available on Safari and supported Apple device.
• Do you have a valid card in your Apple Wallet?

Legacy sandbox mode can still be enabled via the constant below but it is advised that you use the setting above as the constant will likely be removed in the future.

define( 'WC_SQUARE_SANDBOX', true );

Add the above constant in your preferred method. If using wp-config.php add it before the line that says /* That's all, stop editing! Happy blogging. */

Please refer to the Frequently Asked Questions guide.