WooCommerce to Square Object Mappings

Overview

↑ Back to top

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 the Sync Settings (known as System of Record in versions before 3.4.0). The Sync settings determine which platform is authoritative for product data. The following sections describe how each choice affects synchronization.

When Square is the Sync Settings

↑ Back to top
  • Square is the source for synced WooCommerce product data when:
    • Square is set as the Sync Settings
    • The field has a corresponding mapping in WooCommerce
    • The sync operation succeeds
  • Specific field sync behavior:
    • Product name: The Square item name updates the WooCommerce product name.
    • Description: The Square item description updates the WooCommerce product description.
    • Categories: Categories assigned to a Square item sync to its WooCommerce product. An item can sync multiple categories.
    • Prices: Only updated from valid Square variation data
    • Stock: Inventory sync follows the inventory tracking and Sync Inventory settings.
  • Stock status is also synced from Square, depending on inventory settings.
  • Inventory tracking settings are respected from Square
  • New products imported from Square receive their Square image. Existing product images are updated from Square when Override Product Images is enabled.

When WooCommerce is the Sync Settings

↑ Back to top
  • WooCommerce data overwrites Square data
  • New products are created in Square if no match is found
  • Product variations are created in Square if they don’t exist
  • Stock levels are still pulled from Square during the initial sync (for products matched to a Square item by SKU) and at the configured sync interval after that if inventory sync is enabled, even when WooCommerce is set as the Sync Settings
  • Product images in WooCommerce sync to Square only when WooCommerce is set as the Sync Settings
  • For new Square variations, inventory tracking follows the WooCommerce product. Existing Square variation tracking settings are preserved.
  • WooCommerce product availability is reflected at the configured Square location.

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

Inventory synchronization

↑ Back to top
FeatureBehavior
Stock FetchProducts can fetch current stock levels from Square via “Fetch stock from Square” button.
Manual SyncUse Sync inventory on a product to fetch stock from Square.
Auto SyncWhen inventory sync is enabled, WooCommerce sends stock changes to Square and checks Square periodically for stock changes, including in-person sales. The scheduled check applies to products with Sync with Square enabled. A direct product inventory sync or product import can also fetch inventory from Square.
Batch ProcessingInventory sync processes items in batches.

WooCommerce to Square: Entities Overview

↑ Back to top
WooCommerceSquareDescription
ProductsCatalogSquare’s catalog holds all items synced from WooCommerce, ensuring listings and availability are aligned.
ProductItemEach WooCommerce product syncs directly to a Square item, maintaining consistency in name, SKU, and price.
Product VariationsItem VariationsWooCommerce variations (such as size, color) map to Square item variations, syncing variant-specific SKUs and stock levels.
Product CategoriesCategoryWooCommerce categories link to Square categories, organizing products consistently on both platforms.

Field Mappings: WooCommerce Product to Square Item

↑ Back to top
WooCommerce FieldSquare FieldDescription
Product NameItem NameMaps WooCommerce product names to Square item names.
Product DescriptionItem DescriptionSyncs WooCommerce product descriptions to Square.
Product TypeItem TypeOnly supported product types are included in product sync.
Product CategoryCategory NameSyncs WooCommerce categories that have an existing Square mapping.
SKUItem Variation SKUSKUs 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 PriceItem PriceWhen no sale price is set, the WooCommerce regular price is sent as the Square item price.
Sale PriceItem PriceIf a WooCommerce sale price is set, it is sent as the Square item price rather than a separate discount.
Stock QuantityInventory CountMaps stock quantities for managing inventory levels between WooCommerce and Square.
Product ImageItem ImageWhen WooCommerce is the Sync Setting, the WooCommerce product image syncs to Square.
AttributesItem AttributesAttributes used for WooCommerce variations can map to Square item options.
Soft DeletesSoft DeletesWhen Square is the Sync Setting, Handle Missing Products can hide synced WooCommerce products that have been deleted in Square. Hidden products remain accessible by direct link.
Location-Based AvailabilityLocation-Based AvailabilityWooCommerce Square extension manages product availability at specific Square locations, ignoring items that are absent at the WooCommerce store location. 

Developers can customize product names received from Square or import Square descriptions as plain text.

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 FieldSquare FieldDescription
Category NameCategory NameMaps WooCommerce category names to Square’s category names.

Field Mappings: WooCommerce Product Variations to Square Item Variations

↑ Back to top
WooCommerce FieldSquare FieldDescription
AttributesItem OptionsLinks WooCommerce variation attributes with Square’s attributes (aka Options).
Attribute values listItem Option Data ValuesThe value of the attribute at WooCommerce links with the Options Data Values at Square.
Variation NameVariation NameWooCommerce variation attributes are used to construct the Square variation name.
Variation SKUVariation SKUSyncs each WooCommerce variation SKU to Square’s variation SKU for identification.
Variation PriceVariation PriceSyncs price information for each variation from WooCommerce to Square.
Stock StatusInventory StatusMaps variation stock status (in stock, out of stock) with Square’s inventory status.

Best Practices for Handling Attributes

↑ Back to top


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

↑ Back to top
  • 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

↑ Back to top
  • 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.

Questions and support

↑ Back to top

Do you still have questions and need assistance? 

  • Get in touch with a Happiness Engineer via our Help Desk. We provide support for extensions developed by and/or sold on WooCommerce.com, and Jetpack/WordPress.com customers.
  • If you are not a customer, we recommend finding help in the WooCommerce support forum or hiring a Woo Agency Partner. These are trusted agencies with a proven track record of building highly customized, scalable online stores. Learn more about Woo Agency Partners.

Related Products

WooCommerce Subscriptions is a WooCommerce extension that lets customers subscribe to your products or...

Offer Royal Mail shipping rates to your customers.

Use of your personal data
We and our partners process your personal data (such as browsing data, IP Addresses, cookie information, and other unique identifiers) based on your consent and/or our legitimate interest to optimize our website, marketing activities, and your user experience.