Metafields & Attributes

Square Custom Attributes allow you to store additional product information beyond standard fields. SquareSync can sync these attributes to WooCommerce metafields automatically.

Overview

With metafield syncing enabled:

• Square Custom Attributes import as WooCommerce metafields
• Extended product data stays synchronized
• Map Square attributes to existing WooCommerce metafields
• No manual data entry required

Enable Metafield Syncing

When importing products, include metafields in your sync:

1. Go to SquareSync for Woo > Products
2. Select the products you want to import
3. Click Import All
4. Check the Metafields option in import settings
5. Run the import

Square Custom Attributes will automatically sync to WooCommerce metafields with matching keys.

Metafield Mapping

For more control, map Square attributes to specific WooCommerce metafields:

Step 1: Access Mapping Settings

1. Go to SWS Pro > Settings > Products
2. Scroll to the Metafield Mapping section

Step 2: Configure Mappings

1. Enter the Square attribute key in the left field
2. Enter the WooCommerce metafield key in the right field
3. Add additional mappings as needed
4. Click Save Changes

Example Mappings

WooCommerce Fields (Weight)

Some WooCommerce fields are not metafields at all — weight is a product field of its own, so it cannot be mapped through the table above. Instead, pick the Square custom field that holds it.

Set it up

1. In Square, create a custom attribute for weight. A Number type is best; text works too.
2. Go to SWS Pro > Settings > Metafields.
3. In WooCommerce Fields → Square Custom Fields, choose that attribute next to Weight.
4. Click Save Field Bindings.

Weight then syncs in both directions on every product sync that includes metafields: the Square value is written to the WooCommerce weight field on import, and the WooCommerce weight is sent back to Square on export.

Units and formats

Square custom fields hold plain text, so whatever a merchant has typed can end up in there. SquareSync reads all of it and converts to your store's weight unit (WooCommerce > Settings > Products):

Grams, kilograms, milligrams, tonnes, pounds, ounces and stone are all recognised, in long or short form. A value that holds no number at all — about a kilo — is ignored, leaving the WooCommerce weight untouched.

Going the other way, a Number attribute in Square receives the bare figure, and a Text attribute receives the figure with your store's unit (2.5 kg) so it stays unambiguous and reads back the same.

Things worth knowing

• The binding wins over any metafield mapping row for the same Square attribute, and that attribute's meta key box is disabled while it is bound — one value, one home.
• A variation only sends a weight it has of its own. A variation left blank in WooCommerce inherits the parent's weight for shipping but sends nothing to Square, so an import cannot silently pin the parent's weight onto it.
• A product with no weight sends nothing rather than zero.
• A Square value that is not a number is ignored, leaving the existing WooCommerce weight untouched.

WooCommerce Fields (Brand and Tags)

Since 10.5.20. WooCommerce keeps brands in its own Brands list (Products > Brands, WooCommerce 9.6 or later), not in a metafield, so a Square "Brand" attribute mapped through the table above lands in post meta where WooCommerce never shows it. Bind it to Brand instead.

1. In Square, create a custom attribute for the brand. Text or Selection both work.
2. Go to SWS Pro > Settings > Metafields.
3. In WooCommerce Fields, choose that attribute next to Brand.
4. Click Save Field Bindings, then sync a product to check it.

On import the product is given that brand, and a brand that doesn't exist in WooCommerce yet is created. On export the product's WooCommerce brand is sent to the Square attribute.

• Separate several brands with commas (Acme, Bolt). With a Selection attribute, each brand must match one of its options by name, and Square's limit on how many options can be chosen applies. A brand whose own name contains a comma can't be synced.
• Each import replaces the product's brands with what Square holds. An empty Square value leaves the WooCommerce brand alone.
• Brands belong to the parent product. Variations neither send nor receive one.
• Brand values already stored as post meta by an older mapping aren't removed. They're harmless.

Tags

Since 10.5.24. Square has no product tags of its own, so a Square custom attribute stands in for them. The natural fit is a Selection attribute with multiple choices allowed, one option per tag; a Text attribute with tags separated by commas works too.

1. In Square, create the attribute (for example "Tags") and give it one option per tag you use.
2. Go to SWS Pro > Settings > Metafields and, in WooCommerce Fields, choose that attribute next to Tags.
3. Click Save Field Bindings.

On import the product's WooCommerce tags (Products > Tags) are set to the options chosen in Square, and a tag that doesn't exist yet is created. On export the product's tags are sent back to the attribute. The same rules as Brand apply: each import replaces the tag set with what Square holds, an empty Square value leaves the WooCommerce tags alone, tags belong to the parent product, and with a Selection attribute each tag must match an option by name.

If you had the attribute in the mapping table above before binding it, the binding wins. The old meta values are harmless.

Developers can add other fields — length, width, height — with the squarewoosync_product_field_attributes filter. See the Filters Reference.

Use Cases

Extended Product Information

Store additional specs like dimensions, materials, or manufacturer details that sync between platforms.

Custom Specifications

Technical products can include detailed specifications that display on product pages via custom themes or plugins.

Inventory Tracking Data

Internal tracking codes, supplier references, or warehouse locations can sync as hidden metafields.

Troubleshooting

Metafields not syncing

• Verify Metafields is checked in import options
• Confirm the product has Custom Attributes in Square
• Re-import the affected products

Mapping not applying

• Check that attribute keys match exactly (case-sensitive)
• Verify mappings are saved in settings
• Ensure the WooCommerce metafield key is valid

Missing attribute data

• Review the product in Square Dashboard
• Confirm Custom Attributes are properly configured
• Check that attribute values are not empty