WooCommerce Square

Overview ↑ Back to top

WooCommerce Square combines SAQ-A PCI compliant payment processing with product and inventory synchronization, letting you sell via multiple sales channels and accept secure online payments.

Requirements ↑ Back to top

Installation ↑ Back to top

  1. Ensure your store meets the plugin requirements.
  2. Download the extension from your WooCommerce dashboard.
  3. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
  4. Click Install Now and then Activate.
  5. Click Configure and read the next section to learn how to setup the plugin.
Note: To uninstall the plugin, go to Plugins, find the WooCommerce Square plugin, click Deactivate, and then click Delete.

Getting Started ↑ Back to top

To begin using WooCommerce Square, you first need to connect your site to Square by following the steps below:

  1. Go to WooCommerce > Settings > Square.
  2. Click Connect with Square.
  3. Login to your Square account. You must be the owner of the Square account to authorize WooCommerce to connect.
  4. Click That’s My Site – Redirect Me to return to your site.

That’s it! You’re connected to Square. You can now adjust the other plugin settings and gateway settings as needed.

Square Settings ↑ Back to top

From WooCommerce > Settings > Square, you can configure the following settings to determine how data sync between Square and WooCommerce:

  • Business location: Select the location to link to this site.
  • Product system of record: Choose where you will update data for synced products. Click here to learn more about product syncing.
  • Sync inventory: Enable to sync inventory between WooCommerce and Square. When WooCommerce is your system of record, inventory changes in Woo overwrite Square inventory. When Square is your system of record, inventory cannot be changed in WooCommerce, and will always be pulled from Square. Regardless of your system of record, inventory is pulled from Square every hour to account for POS sales.
  • Handle missing products: When the Product system of record is set to “Square”, enable to hide products in your WooCommerce Products list that aren’t found in Square. If disabled, no action will be taken against missing products beyond a notification in the Sync records area.
  • Import Products: Run a one-time import to create new products in WooCommerce for every product in Square, if the SKU doesn’t already exist in WooCommerce.
  • Connection: Connect or disconnect your site from Square. Click here for instructions on connecting to Square.
  • Enable logging: Enable to save debug messages to the WooCommerce > Status > Logs page. Please do not enable this setting unless there are issues with the plugin.

WooCommerce Square sync settings

Payment Gateway Settings ↑ Back to top

From WooCommerce > Settings > Payment > Square, you can configure the following settings for the Square payment gateway:

  • Enable / Disable: Enable to allow customers to use this gateway at checkout.
  • Title: Determine how the gateway should be labeled for customers at checkout and on the Order Received page.
  • Description: The text shown under the Title during checkout. Limited HTML is allowed.
  • Transaction Type: Controls how transactions are submitted to Square. Select “Charge” to automatically capture payments. If you select “Authorization”, you must manually capture and settle payments on the WooCommerce orders screen or from your Square account after the transaction has been submitted (and Authorizations do not display under Square transactions). This defaults to “Charge”.
    Note that Square authorizations are only valid for 6 days, so they cannot be captured after this time.
  • Charge Virtual-Only Orders: If Transaction Type is set to “Authorization”, enable to automatically capture charges for orders with only Virtual products. For downloadable products, this will grant immediate access to downloads.
  • Capture Paid Orders: If Transaction Type is set to “Authorization”, enable to automatically capture charges when orders move to a paid status (i.e. Processing or Completed).
  • Accepted Card Logos: Determines which card logos are displayed during checkout. This has no impact on which cards are accepted by your merchant account.
  • Customer Profiles: Let customers save their payment methods for future use at checkout. This is required for Subscriptions and Pre-Orders.
  • Detailed Decline Messages: Display detailed messages to customers to provide reasoning for declines instead of a generic error message when possible.
  • Debug Mode: Enable when there are problems processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both. Please do not enable this setting unless there are issues with the plugin.

Note: WooCommerce Square does not currently include a sandbox mode for testing the payment gateway. To test the gateway, we recommend using a live credit card to purchase a $1 test product, which is the minimum allowed amount. You can then refund the order if it is successful.

Product and Inventory Sync ↑ Back to top

You can share product and inventory information between Square and WooCommerce, which ensures that each system is up-to-date whether you process a transaction via Square or your online store. In the plugin settings, you can decide whether Square or WooCommerce should be the system of record for your store. This will determine how product data is shared between these platforms.

  • If you sell via multiple channels (e.g. in-person with Square POS and online), we recommend setting Square as your system of record. Using Square as the system of record is especially helpful if inventory is shared for a Square location.
  • If you sell online only, we recommend setting WooCommerce as your system of record. This will ensure basic WooCommerce product data are pushed to Square as they change on your site.
Note: Inventory is always pulled from Square to WooCommerce, regardless of the Product system of record setting.

To share information between Square and WooCommerce, you must enable syncing for that product by following the steps below:

  1. Go to Products.
  2. Select the product in question.
  3. Enable the Sync with Square setting. This is only available for products with no more than one attribute and a populated SKU, which is how products are matched between Square and WooCommerce.
  4. Click Update.

To update syncing for multiple products at the same time:

  1. Go to Products.
  2. Check the products you want to update.
  3. From the Bulk Actions menu, select “Edit”.
  4. Update the Sync with Square? field to “Yes”.
  5. Click Update.

Square as System of Record ↑ Back to top

When Square is the system of record, the WooCommerce Products list will be overwritten with data from the Square product catalog for the following fields:

  • Product name
  • Product price
  • Inventory count (if inventory sync is enabled)
  • Product image, if a featured image is not set in WooCommerce

The plugin will update WooCommerce with information from Square approximately every 60 minutes. You can also run a manual sync any time. In both cases, Square will:

  • Update synced WooCommerce products to reflect changes made to Square products with matching SKUs.
  • Hide synced WooCommerce products when the SKUs are missing or were deleted from Square, if the Handle missing products setting is enabled. If this setting is disabled, no action will be taken against missing products beyond a notification in the Sync records section.

When Square is the system of record, you should avoid changing product data in WooCommerce (manually or via import / API) as these updates could be overwritten by the data in Square during the next automatic update.

WooCommerce as System of Record ↑ Back to top

When WooCommerce is designated as the system of record, the Square product catalog will be overwritten with data from the WooCommerce Products list for the following fields:

  • Product name
  • Product price
  • Inventory count (if inventory sync is enabled)
  • Product category (see note below)
  • Product image
Note: Square allows one category per product, so if your synced product has multiple categories and sub-categories in WooCommerce, only the first or parent category will be sent to Square.

The plugin will send updated information from WooCommerce to Square whenever you make a change to a synced product via manual edit in WooCommerce, import, or API. You can also run a manual sync any time. In both cases, WooCommerce will:

  • Update Square products to reflect changes made to synced WooCommerce products with matching SKUs.
  • Create a new Square product when a synced WooCommerce product doesn’t have a matching SKU in Square.
  • Remove the location from the Square product when a synced WooCommerce product with a matching SKU is deleted from WooCommerce.

Manually Sync Products and Inventory ↑ Back to top

You can run a manual sync any time to ensure records match between Square and WooCommerce. To run a manual sync:

  1. Go to WooCommerce > Settings > Square.
  2. Go to the Update tab.
  3. Click Sync Now.

The sync results will appear in the Sync records section. If you have enabled the Square sync completed email, any listed recipients will receive an email once the manual sync is complete. Alerts identify any issues with the sync that require your review. You can take the following actions against Alerts:

  • Delete: Remove the alert from the list.
  • Ignore: Ignore the alert without removing it from the list.
  • Unlink: Disable syncing for this product.

Sync Email

For businesses with many products, syncing can take some time. You can enable the Square sync completed email to notify you when a manual sync is complete. Follow the steps below to setup this email:

  1. Go to WooCommerce > Settings > Emails.
  2. Select Square sync completed.
  3. Check the Enable box.
  4. Enter one or more recipients for this email. By default, it will be delivered to the WordPress admin email as defined in Settings > General.
  5. Click Save changes.

Gateway Features ↑ Back to top

You and your customers can take advantage of the following features when your site uses WooCommerce Square.

Capture Charges ↑ Back to top

If the gateway’s Transaction Type setting is set to “Authorization”, you can manually capture these payments from the WooCommerce > Orders page. An authorized transaction can be captured for up to 6 days; after 6 days, you must ask the customer to re-authorize the transaction to capture payment. This is a restriction for all Square transactions.

Click here to read more about capturing charges.

Automatic Refunds ↑ Back to top

You can process refunds directly in WooCommerce without going through your Square account. Click here to learn more about issuing automatic refunds in WooCommerce.

Void Transactions ↑ Back to top

You can void transactions directly in WooCommerce in following circumstances:

  • If your Transaction Type setting is set to “Authorization”, you can void when the transaction has been authorized but not yet captured.
  • If your Transaction Type setting is set to “Capture”, you can void when the transaction has not yet been settled.

We recommend voiding / revoking authorizations within WooCommerce for WooCommerce orders rather than revoking an authorization in Square. Otherwise, WooCommerce will continue to consider this transaction as valid for capture.

If a transaction can no longer be voided, you should refund the order instead. Click here to read more about voiding transactions.

Enhanced Checkout Form ↑ Back to top

Square supports an enhanced checkout form to improve your customers’ checkout experience on both desktop and mobile devices. Click here for more information about the enhanced checkout form.

Saved Payment Methods ↑ Back to top

When enabled in the payment gateway settings, customers can save payment methods during checkout or from the My Account area, which supports quicker checkouts and the use of plugins like Subscriptions and Pre-Orders. Click here to learn more about managing saved payment methods.

Detailed Decline Messages ↑ Back to top

When enabled in the payment gateway settings, Square will attempt to provide a more detailed “payment declined” message to help your customers understand why the transaction was declined. Click here to read more about detailed decline messages.

Customer Token Editor ↑ Back to top

When enabled in the payment gateway settings, you can manually add or update the payment method tokens on your site to resolve any synchronization issues. Click here for more information about the customer token editor.

Frequently Asked Questions ↑ Back to top

Q: When I import from Square, some of my products are missing! Where are they?
A: When importing items from Square to WooCommerce, your items must match a couple of criteria:

  1. Items must be available at the location that’s linked to your WooCommerce store.
  2. Items must have a SKU set in Square. The SKU is used to match items between WooCommerce and Square, so we’ll need a SKU to import along with the item.

Q: Why aren’t my product categories syncing correctly?
A: While WooCommerce lets you set multiple categories and sub-categories, Square only accepts one category per product. Because of this limitation, if WooCommerce is your system of record, only the first or parent category will be sent to Square.


Q: Does WooCommerce Square support ApplePay?
A: No – WooCommerce Square does not support ApplePay at this time. However, we are monitoring this idea on our Ideas Board to consider for future development! Click here to vote for this idea.


Q: Can I test the Square payment gateway in a sandbox mode?
A: WooCommerce Square does not currently include a sandbox mode for testing the payment gateway. To test the gateway, we recommend using a live credit card to purchase a $1 test product, which is the minimum allowed amount. You can then refund the order if it is successful.


Q: Can I change how often the automatic sync runs?
A: By customizing the wc_square_sync_interval filter, you can change the automatic sync frequency. This value is stored in seconds, and the default is one hour (which is recommended for most sites, especially those with large product catalogs). Here’s a sample of how you can change the sync interval:

// sync every 15 minutes instead of every hour
add_filter( 'wc_square_sync_interval', function( $interval ) {
    return 15 * MINUTE_IN_SECONDS;
} );

Please note that customizations are not covered under our support policy, so this isn’t something we can help implement on your site.


Q: Why can’t I sync products with multiple attributes?
A: Unlike WooCommerce, Square does not support multiple attributes. If you would like to sync multiple attributes from WooCommerce to Square, consider combining attributes into one product variation – for example, instead of a “color” attribute and a “size” attribute (e.g. black or blue and small or large), combine the two in your product variations (e.g. black-small, black-large, blue-small, blue-large).


Q: Why aren’t my product images importing from Square to WooCommerce?
A: When Square is the system of record, product images are only imported for synced products that do not already have a featured image in place. If you would like to use the Square images in WooCommerce, remove the existing product image from WooCommerce before syncing.


Q: I’ve set Square as the system of record, so why are products missing from WooCommerce that I can see in Square?
A: If a Square product is missing from WooCommerce, check to confirm that the missing product is listed under the same Location as defined in the plugin settings.


Q: Does WooCommerce Square support Subscriptions and Pre-Orders?
A: Yes! If you enable Customer Profiles in the gateway settings, the WooCommerce Square gateway is compatible with Subscriptions and Pre-Orders.


Q: How does WooCommerce Square handle tax-inclusive pricing?
A: WooCommerce Square does not support tax-inclusive pricing. Please ensure that your Square tax rates match your WooCommerce tax rates. If you have set your site to use tax-inclusive pricing (WooCommerce > Settings > Tax), you will see a notification when editing products to this effect.


Q: How are sale prices synced between WooCommerce and Square?
A: When Square is the system of record, the base price in Square will always be imported as the Regular Price in WooCommerce. However, when WooCommerce is the system of record and there is a Sale Price set for a synced product in WooCommerce, that price will be set as the base price in Square for the matching product.

Troubleshooting ↑ Back to top

Connection Issues ↑ Back to top

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.

Sync Issues ↑ Back to top

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’re in the Location 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.

Import issues ↑ Back to top

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

Payment Gateway Issues ↑ Back to top

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

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.

Questions & Support ↑ Back to top

Have a question before you download this plugin? Please fill out this contact form.

Already installed and need some assistance? Please check out our troubleshooting tips and frequently asked questions for common issues or contact support via the help desk if you need more help.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top