WooCommerce Square

WooCommerce Square provides seamless integration between your Square account and WooCommerce store, allowing you to synchronize inventory on both, and offer Square as a payment option.

The Square Payment Gateway requires an SSL certificate installed on your site, and it takes payments inside of an iFrame. All the customer payment data is stored on the Square servers.

WooCommerce Square requires that you have a Square account based in the U.S., Canada, Australia, Japan or the UK.

Requirements ↑ Back to top

  • WooCommerce 2.6.0+
  • PHP version 5.3+
  • WordPress 4.4+
  • cURL installed on your server
  • Square account
  • An SSL Certificate
  • A business location set in your Square account

Syncing products with WooCommerce Square requires that you have SKUs assigned to all products, including each product variation (if applicable). The product must also be published.

Sign up for a Square account ↑ Back to top

  1. Go to: squareup.com/signup
  2. Sign up for your free Square account.
  3. Enter a Business Location when prompted.
  4. Stay logged into Square during setup of your WooCommerce Square plugin.

If you already have a Square account, sign into your account and stay logged in during setup of the plugin.

Installation ↑ Back to top

  1. Download the .zip file from your WooCommerce account.
  2. Go to: WordPress Admin > Plugins > Add New to upload the file you downloaded with Choose File.
  3. Activate the extension.

Setup and Configuration ↑ Back to top

General Settings ↑ Back to top

Your Store Address needs to be set up, if not already. If set and no edits are necessary, skip to the next section.

1/ Go to: WooCommerce > Settings > General.

2/ Enter your Address. Must be in the U.S., Canada, Australia, Japan or the UK.

3/ Save changes.

Connecting WooCommerce Square ↑ Back to top

  1. Go to: WooCommerce > Settings > Integration > Square.
  2. Connect with Square.
  3. Log into your Square account, if not already:
  4. Verify identity of your site/store with That’s My Site – Redirect Me.

Once verified, you are returned to the Square settings.

Square Settings ↑ Back to top

Square Settings at WooCommerce > Settings > Integration.

  1. Select the button to Disconnect/Connect Square.
  2. Select a Business Location from the dropdown. These locations are entered in and pulled from your Square account.
  3. Enter your Notification Email(s): Use one or several email addresses to be notified when a sync is complete.
  4. Tick the Log Debug Messages checkbox: Useful for troubleshooting issues with the sync process. View logs at: WooCommerce > Status > Logs and select the log that starts with woocommerce_square_sync.

Synchronization Settings ↑ Back to top

  1. Select Enabled: This is the master switch for product syncing. If disabled, no items will sync.
  2. Include Categories: Enabling will sync your product categories.
  3. Include Inventory: Enabling will sync your product inventory.
  4. Include Images: Enabling will sync your product images.
  5. Square Inventory Sync: Enabling will auto-sync Square to WooCommerce.
  6. Click the button of your choice to Initiate a Manual Sync.
  7. Save changes.

For syncing to function correctly, you must do a one-time initial bulk sync — from WooCommerce (WC) to Square or Square to WooCommerce. This provides the initial “link up” between the two platforms.

Per Product Sync Settings

You may disable syncing for any product. Go to WooCommerce > Products, select a product and then tick the Disable Sync checkbox. This disables all syncing functionalities both ways.

Square Payment Gateway Settings ↑ Back to top

Should you wish to use and offer Square as a payment option, it needs to be set up.

  1. Go to: WooCommerce > Settings > Payments.
    Note: ‘Payments’ formerly called ‘Checkout’ prior to WooCommerce 3.4.
  2. Use the toggle under Enabled to select Square.
  3. Select Set Up. You are taken to the Square settings.
  4. Enable/Disable: Tick the checkbox if you wish to use Square as a payment option.
  5. Enter a Title: Displayed to customers during checkout.
  6. Enter a Description.
  7. Delay Capture (optional) Allows you to pre-authorize a charge and not capture it until later. This is useful if you wish to take payment only when shipping goods. On WooCommerce, choose to: a) Capture an authorization by marking the order Processing or Completed; or b) void the authorization by canceling the order. Captures must be completed within six days.
  8. Create Customer (optional): Create a customer profile on Square when a customer checks out on your WooCommerce store.
  9. Tick the Log Debug Messages checkbox: Useful for troubleshooting issues with the sync process. View logs at: WooCommerce > System Status > Logs and select the log that starts with woocommerce_square_sync.
  10. Save changes.

Here’s what the payment option looks like for customers:



WooCommerce Square does not currently have a sandbox mode for testing purposes. A regular product can be purchased to test the payment gateway (minimum amount is $1)

Troubleshooting ↑ Back to top

Why is it taking so long to sync? ↑ Back to top

If you have many products on Square, it needs to loop through all of them and process each one separately. This takes time. If you set up the notification email, you can step away and come back when it’s done.

Why are some/all products not syncing? ↑ Back to top

Be sure you have SKUs set on both your products on WooCommerce site and your Square POS and that you have done an initial bulk sync.

The Square extension only supports one location. If some of the products aren’t syncing then make sure they are available in Square for the correct location. Otherwise they will be considered as “Not Found”. Which could result in creating duplicate products if they are synced from WooCommerce to Square or the products are updated in WooCommerce

Why are my product categories not syncing correctly? ↑ Back to top

Because WooCommerce and Square handle product categories very differently.

  • WooCommerce allows multiple categories to be assigned to one product while Square only allows one.

So if you’re syncing from Square to WooCommerce, that product will be updated to just one that is set in Square. If you have multiple categories and you’re syncing from WooCommerce to Square, it will pick the parent/and or the top most category to use. Because of this limitation on Square, our plugin has to follow suit.

Because Square has a flat category structure, it is not possible to have subcategories in WooCommerce and keep them in sync with Square. If you have subcategories, you can disable category sync entirely.

My product description is not syncing to my WooCommerce store. ↑ Back to top

This is by design.

  • Because WooCommerce accepts/allows rich HTML content and Square does not.

So if you sync’d from Square to WooCommerce and your WooCommerce product had HTML content, all HTML would be stripped away leaving only plain text. This is not the result you would want. However, you can sync from WooCommerce to Square and any HTML content will be stripped before saving to Square as they don’t allow HTML content. But if you are only using plain text product description and you would still like to sync both ways, there is a filter you can use. Place the following code into your child theme’s functions.php file. Please take care when editing code. Always make a backup of your site first.

add_filter( 'woocommerce_square_sync_from_square_description', '__return_true' );

My variations are not syncing properly. ↑ Back to top

Because WooCommerce and Square handles product variations very differently.

  • Square has single level variations where WooCommerce can have multilevel variations.

So if you only have single level variations on the WooCommerce side (only one attribute) everything will sync to Square just fine. However, if you need to use multiple attributes there are two syncing methods you can use.

The preferred method is using a workaround. For example, if you have Color and Size (two attributes). You’ll want to combine them into one attribute, for example, Black Small, Black Medium and Black Large as the three variations. This way when syncing over to Square, it will generate the variations correctly.

The second method does not require you to combine your attributes, Square will merge these attributes on their end. Inventory syncing should still function both ways in these cases, however you will not be able to ever initiate a manual Square > WooCommerce in the future. If you do Square will overwrite all of your product variations in WooCommerce with their merged variations. We recommend not using the forced manual sync option after initially setting up the plugin, so most users should not have a problem with using this second method.

Nothing is Syncing and I am seeing this error “PHP Deprecated: Automatically populating $HTTP_RAW_POST_DATA is deprecated and will be removed in a future version.” in my PHP error log. ↑ Back to top

Add the following into your PHP.ini file. “always_populate_raw_post_data = -1” ( no quotes ). You can ask your host to do this for you.

Why do I not see the Square payment on the checkout page? ↑ Back to top

Make sure you have SSL installed on your site and is active on the checkout page.

I am testing a purchase with Square Payment but it failed! Why? ↑ Back to top

Make sure you’re testing with a dollar amount that is greater than $1.00.

Why do my Square reports not show order information? ↑ Back to top

Currently, Square’s API does not support sending detailed transaction information. At this time, they are only able to capture the order number and the order total on transactions sent to them. Because of this, transactions will show up in your Square account as an uncategorized “Custom Amount.”

Why are my product images in WooCommerce not updating after I change them in Square? ↑ Back to top

This is intentional and due to the way Square handles product images. Once a product image has been imported from Square, any changes to that image in Square will need to be manually recreated in WooCommerce. You can do this by editing the item within WooCommerce and uploading your new product image. Please note that if you update your product images from within WooCommerce, instead of Square, you don’t have to worry about this – as WooCommerce will automatically update the new product image to your Square account.

The reason for this is because Square saves all product images with the same filename. This means even though you may have updated the product image in Square, that image file will have the same name as it did before. Because of this, there is no way for your WooCommerce site to know if the product image is different when a sync is performed. If we were to import the image with every sync, it would cause file duplications in your media library.

Why do my products not have SKUs after importing from Square? ↑ Back to top

If your products do not have SKU’s or are not showing as for sale on your site, check the product in Square to ensure it does not have extra blank variations. Log into your Square dashboard and click on the item that is causing the problem. Make sure that the only blank variation line is the very last line. If there are any other blank variation lines, you will need to delete them using the “X” symbol to the right. Once you are done removing any blank variations, save your changes. Now go back to your WooCommerce site and manually edit the product to remove any blank variations that were brought in with your sync. The next time that your Square account syncs to WooCommerce, the issue will be corrected.

The hourly “Square Inventory Sync” isn’t updating my products or adding new ones? ↑ Back to top

The automated hourly “Square Inventory Sync” will only update the inventory of items that have already been synced between Square and your WooCommerce site. It is not able to add new items to WooCommerce, nor is it able to update the price or description of existing items. If you have new items in Square that are not in WooCommerce, or if you want the price, item name, or image in WooCommerce to be updated using Square; you will need to perform a manual Square to WooCommerce sync. This can be done by using the “Square > WC” button on the WooCommerce > Settings > Integration tab.

Because of this, we recommend using WooCommerce to manage all of your product changes or additions, as changes made in WooCommerce are automatically sent to Square and do not require a manual sync.

FAQ ↑ Back to top

Why do I need an SSL certificate? ↑ Back to top

Because you are taking payments on your website/store, and for security reasons and privacy laws, you need an SSL certificate. More at: WooCommerce Site and Data Security FAQ and the GDPR in effect from May 25, 2018.

Should you not have one, a message at the top will appear after enabling Square: “Square is enabled, but the force SSL option is disabled; your checkout is not secured. Please enable SSL and ensure your server has a valid certificate.”

Where do I get an SSL certificate and how much does it cost? ↑ Back to top

You can get an SSL certificate from Let’s Encrypt, and it’s free of charge. More at: SSL and HTTPS.

Do I need to set SKUs for all products? ↑ Back to top

Yes, you must set SKUs for syncing to work properly. The SKU is a unique value in both WooCommerce and Square, so it is used to ‘match’ items between the two platforms.

How does Square automatically sync inventory to my WooCommerce store? ↑ Back to top

From the time you activate the plugin, a scheduled event automatically polls the inventory from Square and updates your WooCommerce on an hourly basis.

I have multiple Square locations. Why am I only able to use one location per WooCommerce store? ↑ Back to top

This is typical with integrations. However, in discussion with Square, this may be added in the future.

Does Square payments work in countries other than the U.S., Canada, Australia, Japan and the UK? ↑ Back to top

Not at this time. Options for other countries can be found at: WooCommerce Payment Gateways.

Does this support Subscriptions? ↑ Back to top

Not at this time but you can add your votes to the idea on our Ideas Board. These gateways do: Subscription Payment Methods and Gateways.


Does this support ApplePay? ↑ Back to top

Currently, this plugin does not support ApplePay. You can add your votes to the idea on our Ideas Board to hopefully add this functionality in the future.


Does this support Shipping Multiple Addresses? ↑ Back to top

Not at this time, although support for Shipping Multiple Addresses is on our road map.

Does this support Composite Products? ↑ Back to top

No, currently Square only supports simple and variable product types.

How are Sale prices handled? ↑ Back to top

Square does not support having a regular and sale price for items. When you set a sale price for an item in WooCommerce, the price will also be updated in your Square account. Once the sale price is removed from the item in WooCommerce, your Square item will be updated with the regular price again.

Sync process passes the current product prices. Therefore, when syncing products, make sure there are no active discounts (via WooCommerce Memberships or any other discount plugin) for the logged-in user otherwise discounted prices will be synced and used for all users. To avoid this, login using a normal admin user which has no discount rules applied to it.

Is there a maximum length for my product descriptions? ↑ Back to top

Square has an undocumented 4095 character limit on item descriptions. If someone is having trouble with items syncing and the descriptions are very long, double-check this.

Why is my sync frozen/stuck? ↑ Back to top

If you are trying to perform a manual sync and finding that the sync is stuck or frozen, it may be caused by caching from a plugin or your web host.

Try disabling any caching plugins that you have installed. As well, check to ensure your host hasn’t forced the installation of any cache plugins. These would show up under the “Drop-ins” or “Must-Use” tabs on your Plugins screen.

Does syncing include Square modifiers? ↑ Back to top

WooCommerce does not have such modifiers so therefore Square modifiers are not sync’d.

Can I connect the same Square account to multiple WooCommerce sites?

As long as each WooCommerce site is using a different Square Location, you can connect the same Square account to multiple WooCommerce sites.

How does Square handle syncing products with tax inclusive pricing? ↑ Back to top

Currently Square does not support syncing products with an inclusive tax rate. Their suggestion is to create Tax Rules in Square to mark items that should not have taxes applied to them. Because of this, once your WooCommerce item is synced to Square it will be the pre-tax price. You will need to either adjust the product price once it is synced to Square or use their Tax settings to apply tax to the product.

Does Square sync my orders? ↑ Back to top

Our Square integration syncs payments and inventory only because of the API limitation. If you want orders sync to be added to the extension, make sure to vote this idea up on our Ideas Board.

Questions and Feedback ↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.

Already purchased and need some assistance? Get in touch with a Happiness Engineer via the Help Desk.

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

Back to the top