Documentation

WooCommerce to Square Object Mappings

Overview

The WooCommerce to Square integration ensures that product information is consistent and up-to-date across online and in-store platforms, and it synchronizes product data between platforms based on a configured System of Record (SOR). The System of Record setting wc_square_system_of_record determines which platform is authoritative for product data. This setting defaults to ‘square’. System of Record behavior:

When Square is SOR

↑ Back to top

Square data overwrites WooCommerce data ONLY when
- Square is set as System of Record (controlled by wc_square_system_of_record option)
- Square data is not empty
- The field has a corresponding mapping in WooCommerce
- The sync operation succeeds
Specific field sync behavior
- Product name: Only updated if Square name is not empty
- Description: Only updated if Square description is not empty
- Categories: Only synced if Square category_id exists
- Prices: Only updated from valid Square variation data
- Stock: Only synced for products with inventory tracking enabled
Stock status (in_stock/out_of_stock) is also synced from Square, conditional on inventory tracking settings
Inventory tracking settings are respected from Square
Images are only imported from Square if no featured image exists in WooCommerce

When WooCommerce is SOR

↑ Back to top

WooCommerce data overwrites Square data
New products are created in Square if no match found
Product variations are created in Square if they don’t exist
For initial sync only, stock levels are still pulled from Square even when WooCommerce is SOR
Product images in WooCommerce sync to Square only when WooCommerce is the SOR.
Inventory tracking settings from WooCommerce are respected
Product status (active/inactive) and inventory tracking settings from WooCommerce are pushed to Square.

Here’s how WooCommerce objects align with Square’s catalog system to streamline its operations:

Inventory synchronization

↑ Back to top

Feature	Behavior
Stock Fetch	Products can fetch current stock levels from Square via “Fetch stock from Square” button.
Manual Sync	“Sync Inventory” option available for products with inventory tracking enabled.
Auto Sync	Inventory updates automatically sync when orders are processed and stock is reduced, or when product/variation stock is manually updated. A sync process also runs periodically in the background to keep WooCommerce inventory in sync with Square without requiring manual intervention. Inventory counts syncFetches current inventory counts from SquareUpdates WooCommerce product stock levelsHandles pagination through cursorsUpdates products in batches to avoid timeouts Key featuresUses cursors for paginationTracks last sync timestamp to only fetch recent changesHandles both inventory tracking status and actual countsUpdates products in batchesMaintains sync history and processed product IDsHandles errors and invalid responses
Batch Processing	Inventory sync processes up to 1000 items per batch to optimize performance

WooCommerce to Square: Entities Overview

↑ Back to top

WooCommerce	Square	Description
Products	Catalog	Square’s catalog holds all items synced from WooCommerce, ensuring listings and availability are aligned.
Product	Item	Each WooCommerce product syncs directly to a Square item, maintaining consistency in name, SKU, and price.
Product Variations	Item Variations	WooCommerce variations (such as size, color) map to Square item variations, syncing variant-specific SKUs and stock levels.
Product Categories	Category	WooCommerce categories link to Square categories, organizing products consistently on both platforms.

Field Mappings: WooCommerce Product to Square Item

↑ Back to top

WooCommerce Field	Square Field	Description
Product Name	Item Name	Maps WooCommerce product names to Square item names. Can be filtered via `wc_square_update_product_set_name`
Product Description	Item Description	Syncs WooCommerce product descriptions to Square. HTML support can be toggled via `wc_square_enable_html_description` filter
Product Type	Item Type	Syncs WooCommerce product types (e.g., simple, variable) with Square item types. Note that product sync is disabled for unsupported product types.
Product Category	Category	Links WooCommerce categories to Square categories.
SKU	Item Variation SKU	SKUs are used as unique identifiers for synchronization. For simple products, the product SKU maps directly to Square’s item variation SKU. For variable products, each variation must have a unique SKU that maps to a corresponding Square variation SKU. Empty SKUs will prevent sync for that product/variation.
Regular Price	Item Price	Syncs the WooCommerce regular price to Square’s item price.
Sale Price	Discounted Item Price	Syncs the sale price, if available, from WooCommerce to Square’s discounted price.
Stock Quantity	Inventory Count	Maps stock quantities for managing inventory levels between WooCommerce and Square.
Product Image	Item Image	Downloads the primary product image from Square to WooCommerce, ensuring consistent visual representation across both platforms. Note that images set in WooCommerce are uploaded to Square only when WooCommerce is SOR.
Attributes	Item Attributes	Maps WooCommerce product attributes (e.g., color, size) to attributes in Square.
Soft Deletes	Soft Deletes	When Square is the system of record (SOR), products missing from Square are optionally hidden (not deleted) in WooCommerce based on the `hide_missing_products` setting. This is handled in three scenarios:When a product is deleted in SquareWhen a product doesn’t exist in Square catalogWhen variations are missing from Square
Location-Based Availability	Location-Based Availability	WooCommerce Square extension manages product availability at specific Square locations, ignoring items that are absent at the WooCommerce store location.
Custom Attributes	Custom Attributes	WooCommerce custom attributes are synced to Square’s custom attributes for products, providing additional descriptive fields that extend beyond basic product data.
Stock Threshold	Low Stock Alert	Syncs low stock threshold settings between platforms.

Field Mappings: WooCommerce Category to Square Category

↑ Back to top

The WooCommerce Square extension syncs categories by mapping WooCommerce categories to their Square counterparts based on Square’s unique category ID. If a matching category exists in WooCommerce, it’s updated for consistency; if not, a new category is created using the Square category name. This process keeps product organization consistent across both platforms.

WooCommerce Field	Square Field	Description
Category Name	Category Name	Maps WooCommerce category names to Square’s category names.
Category Description	Category Description	Syncs category descriptions, if available.
Category Image	Category Image	Syncs WooCommerce category images to Square categories where possible.

Field Mappings: WooCommerce Product Variations to Square Item Variations

↑ Back to top

WooCommerce Field	Square Field	Description
Attributes	Item Options	Links WooCommerce variation attributes with Square’s attributes (aka Options).
Attribute values list	Item Option Data Values	The value of the attribute at WooCommerce links with Options Data Values at Square.
Variation Name	Variation Name	Links WooCommerce variation names with Square’s variation names. Can be filtered via `wc_square_update_product_set_variation_name`
Variation SKU	Variation SKU	Syncs each WooCommerce variation SKU to Square’s variation SKU for identification.
Variation Price	Variation Price	Syncs price information for each variation from WooCommerce to Square.
Stock Status	Inventory Status	Maps variation stock status (in stock, out of stock) with Square’s inventory status.

Best Practices for Handling Attributes

When syncing attributes between WooCommerce and Square, adhering to these guidelines can help avoid sync issues and ensure smooth operation:

1. Avoid Changing Taxonomy Attribute Slugs or Names

Changing the slugs or names of taxonomy attributes in WooCommerce can disrupt the synchronization process.
Similarly, renaming dynamic options in Square can lead to mismatched data, as these changes are not automatically reflected during the sync.
Best Practice: Once set, keep taxonomy attribute slugs and names consistent in WooCommerce and Square.

2. Avoid Creating Custom Attributes with Identical Names to Existing Taxonomy Attributes

Custom attributes with names identical to taxonomy attributes can cause issues during import or synchronization.
For example, products using custom attributes with duplicate names may have their data replaced incorrectly with taxonomy attributes.
Best Practice: Use unique and descriptive names for custom attributes to prevent conflicts.