Sync products between Square and WooCommerce

WooCommerce Square keeps your product catalog and inventory counts aligned between WooCommerce and Square. You choose which platform the Sync Setting applies to; your choice determines which platform’s data overwrites the other during sync.

Before You Start

↑ Back to top

For sync to work correctly:

• Every product must have a SKU. SKUs are how the plugin matches products between WooCommerce and Square.
• Products must be assigned to the correct Square Location. Check WooCommerce > Settings > Square > Business Location.
• Background processing must be enabled on your server. This is required for automatic sync to run. Check WooCommerce > Status for any background processing errors.

Step 1: Choose Your Sync Setting

↑ Back to top

Go to WooCommerce > Settings > Square, and choose the platform that serves as the source of truth under Sync Settings.

Step 2: Enable Sync Per Product

↑ Back to top

Sync must be enabled individually for each product you want to sync.

Enable sync for a single product:

1. Go to Products > All Products.
2. Edit the product.
3. Check the Sync with Square checkbox.
4. Click Update.

Enable sync for multiple products (bulk edit):

1. Navigate to Products > All Products.
2. Select the products you want to update.
3. From the Bulk Actions menu, select “Edit” and click ‘Apply‘
4. Update the Sync with Square? field to “Yes”.
5. Click Update.

Variable Products

↑ Back to top

Variable products are supported, but Square has limits on attributes and variations. For more information about these limits, refer to the Square documentation for CatalogItem and CatalogItemVariation objects.

Setting	Description
Max attributes per product	6
Max terms per attribute	250
Max character length of attribute name	65
Max variations per product	250

When Sync with Square is enabled on a variable product, WooCommerce displays a validation error when saving if any attribute or variation exceeds these limits. Only attributes used for variations are synced — unused attributes are excluded.

Manual Sync

↑ Back to top

You can manually sync products between WooCommerce and Square at any time to keep product data up to date. Before syncing, make sure the product is set to Sync with Square. Follow the steps below to manually sync your products:

1. In your WordPress dashboard, go to WooCommerce > Settings > Square.
2. Click the Update tab.
3. Click Sync Now to start a manual sync.

Track progress in the Sync Records section. You can also set up email notifications for sync completion under WooCommerce > Settings > Emails > Square Sync Completed.

When Sync with Square is enabled on a variable product, WooCommerce will display a validation error when saving if any attribute or variation exceeds these limits.

Receive Sync Email Notifications

↑ Back to top

If you have a large inventory, synchronizing your products between WooCommerce and Square may take a while. To keep you informed when a manual sync is completed, you can opt to receive a notification email.

1. Go to WooCommerce > Settings > Emails.
2. Click Square Sync Completed.
3. Check the Enable checkbox.
4. Enter the recipient email addresses, separated by commas.
5. Click Save Changes.

Bulk manage synced products via CSV

↑ Back to top

The column headers below map to the Square-specific fields the plugin stores on each product. You’ll work with these when bulk-managing products via CSV, either through WooCommerce’s built-in importer/exporter or a plugin like Product CSV Import Suite for WooCommerce.

Column header	Applies to	Description
tax:wc_square_synced	Parent product	Sync eligibility. yes enables sync, no disables.
meta:_square_item_id	Parent product	Linked Square catalog item ID. Populated by the plugin. Leave blank for new products.
meta:_square_item_version	Parent product	Square version stamp. Managed by the plugin.
meta:_square_item_variation_id	Simple products, variations	Linked Square variation ID. Populated by the plugin.
meta:_square_item_variation_version	Simple products, variations	Square version stamp. Populated by the plugin.
meta:_square_item_image_id	Parent product	Linked Square image ID. Populated by the plugin.
meta:_square_gift_card	Parent product	Marks the product as a Square gift card.

Best practices for bulk managing products via CSV

↑ Back to top

1. Give every product and variation a unique, non-empty SKU. SKUs are how the plugin matches to Square. No SKU means no sync.
2. Import parents before variations, and don’t sync variable products until their variations exist. A single CSV containing both is handled correctly by the importer. If you split into two files, import parents first, and note that a variable product with zero variations will not sync to Square at all.
3. Enable “Sync with Square” after the import completes, using Bulk Edit. This prevents half-imported rows from being pushed to Square.
4. Don’t carry Square catalog IDs across Square accounts when migrating to another site. If the destination site is connected to a different Square account or sandbox than the source, those IDs will point at items that don’t exist, and sync will fail. Leave meta:_square_item_id and meta:_square_item_variation_id blank, and the plugin will populate them on the first sync.