Square Modifiers

Square modifiers let customers customise a product before adding it to the cart — sizes, extras, add-ons, preparation preferences. With modifier syncing enabled, the modifier sets you've built in Square appear on your WooCommerce product pages automatically, selections adjust the price in the cart, and completed orders send the chosen modifiers back to Square as real Square modifiers, so POS receipts, kitchen displays, and Square reporting all stay intact.

No extra plugins are needed — this is built in.

Modifiers are not variations

This is the most common point of confusion, so it's worth stating first:

A WooCommerce attribute drives variations — every choice is a separate product with its own SKU, price, and stock. A Square modifier is an add-on applied to the order line item ("Extra shot +$1.00"). Modifiers don't create product variations; they adjust the line-item price and travel with the order.

The plugin deliberately does not convert modifiers into attributes. If it did, every modifier combination would need to become a real variation, which would break stock and order sync back to Square. Square item options/variations sync as WooCommerce variations; Square modifiers sync as modifier sets. Both can exist on the same product.

If you want a single-choice modifier set to look like a variation dropdown, you can — see Storefront display below.

Requirements

• SquareSync for Woo Pro with an active licence and a connected Square account.
• Modifier sets configured in Square and enabled on your items (Square Dashboard → Items → Modifiers).
• Products linked/imported through the plugin.

Enabling modifier syncing

1. Go to SWS Pro → Settings → Modifiers
2. Toggle on Modifier syncing
3. Import (or re-import) the products that carry modifiers — or let real-time sync pick them up

With the master switch on, modifiers sync on products and orders. To keep modifier sets updated automatically when they change in Square, make sure the Modifiers data point is enabled in your Square → WooCommerce real-time sync settings (Settings → Products).

What syncs across

Storefront display

New in 9.10.1. How modifier sets render is controlled globally under SWS Pro → Settings → Modifiers → Storefront Display. This demo is wired the same way the plugin is — flip the settings on the left and watch the product page react:

Three settings, matching the panel above:

Multi-choice sets always render as checkboxes — a dropdown can't represent "pick several, up to X".

Required modifier sets

New in 9.10.1. When a modifier set has a minimum selection count of 1 or more in Square, the plugin treats it as required:

• The set is marked with a red asterisk, like any required WooCommerce field.
• Add to Cart stays disabled until every required set has a selection — the same behaviour WooCommerce uses for variable products.
• The requirement is also enforced server-side, so AJAX add-to-cart and express-checkout flows can't bypass it.
• On shop and category pages, the product's button becomes a "Select options" link to the product page instead of an instant add-to-cart, so a required choice can never be skipped.

Auto-detection can be switched off globally (the Require sets marked required in Square toggle), and any individual set can be forced Required or Optional per product — see the next section.

Per-product overrides

Every synced product gets a Modifiers tab under Product data on its edit screen. Each set shows its synced values plus two override controls:

• Display — Default (plugin setting), Radio buttons, or Dropdown (single-choice sets only)
• Required — Auto (follow Square), Required, or Optional

The per-set value always wins over the plugin setting; Default / Auto fall through to it. Try the resolution below — the demo set has a Square minimum of 1:

Your overrides are safe: when Square re-syncs a product, set names, options, and prices refresh from Square, but per-set Display and Required choices are preserved.

Editing sets and options

The same tab lets you edit sets directly — or build sets from scratch on products that don't come from Square:

Heads up: on products that sync from Square, option names and prices are overwritten by the next product sync — make those edits in Square. Manual edits are only permanent on sets/products that don't sync.

Custom sets without Square IDs still work on the storefront and in the cart, but their selections can't be attached to the Square order as real modifiers (they'll still appear in the order item details). Fill in the Square Mod List ID and Modifier IDs if you want them on the Square side.

Cart, checkout, and orders

• Selected modifiers are listed under the item in the cart and at checkout, and each selection's price is added to the line-item total.
• On the WooCommerce order, the item shows a Modifiers summary of what was chosen.
• When the order syncs to Square, selections are attached as real Square modifiers (by their catalog IDs) — so they appear on POS receipts and kitchen displays, and Square's modifier reporting stays accurate.

Sold-out and stock behaviour

• If a modifier is marked sold out at your location in Square, the synced option renders disabled ("sold out") until Square says otherwise.
• Options with a plugin-side stock count decrement as orders come in and grey out at zero.
• Modifier stock is per-option and optional — most stores leave it blank (unlimited).

For developers

The heading above the modifier sets can also be changed (or removed) in code:

// Rename the heading for everything:
add_filter( 'sws_modifiers_heading', function ( $heading, $product ) {
    return 'Customise your order';
}, 10, 2 );
 
// Or remove it entirely:
add_filter( 'sws_modifiers_heading', '__return_empty_string' );

The storefront markup uses stable CSS classes you can target: .pws-modifier-sets (wrapper), .pws-modifier-set-frontend (each set), .pws-modifier-option-label (radio/checkbox rows), and .pws-modifier-select (dropdowns).

Using an external modifier plugin instead?

If you build product options with a third-party add-ons plugin (Advanced Product Fields, Orderable, and similar) rather than syncing Square's own modifiers, use Order Modifier Mapping to map that plugin's order data onto Square modifiers so POS orders still show the right choices. You don't need it for the built-in modifier sync described on this page.

Troubleshooting

Modifiers don't appear on a product

• Confirm Modifier syncing is on under Settings → Modifiers.
• Re-import or re-sync the product — modifier sets attach during product sync.
• In Square, check the modifier list is actually enabled on that item, isn't disabled, and isn't hidden from customers — hidden and disabled lists are skipped on purpose.
• If every option in a set is marked Hide Online, the whole set stays hidden.

A single-choice set still shows radio buttons after switching to Dropdown

Check the product's Product data → Modifiers tab — a per-set Display override of Radio buttons beats the global setting. Set it back to Default (plugin setting).

Add to Cart is disabled and I don't know why

A required set has no selection. If you don't want the set to be required, either lower its minimum selections in Square, set the per-set Required override to Optional, or switch off Require sets marked required in Square globally.

Selections don't show on the Square order

• Confirm order syncing to Square is enabled and the order actually synced.
• Custom (non-synced) sets need a Square Mod List ID and per-option Square Modifier IDs to be attached to the Square order as modifiers.

My option price/name edits keep reverting

You edited a synced set — Square is the source of truth for names, options, and prices, and each product sync refreshes them. Make the change in Square instead. (Display and Required overrides are never reverted.)