Connecting Square POS

Square is a recommended POS for SMBs using Stash. Connection takes about 2 minutes and uses Square's standard OAuth flow — Stash never sees or stores your Square password.

Who can do this

Only Admins can connect Square. You'll also need to sign in to Square as the account owner (a regular employee account won't have permission to authorize integrations).

Before you start

You need at least one Stash shop set up. See How to add your first location.
You need your Square account owner login.
Allow popups for app.getstash.io in your browser — Square's authorization opens in a popup window.

How to connect Square

From the sidebar, open Integrations.
Find the Stash shop you want to connect Square to.
Click Connect POS.
Choose Square from the provider list.
Sign in to Square with your owner account.
Review the permissions Stash is requesting (read-only access to products, locations, and sales) and click Allow.
You'll be redirected back to Stash. The connection appears in seconds.

Once connected, Stash automatically pulls in your Square locations and starts a product catalog sync.

After connecting — finish the setup

The Setup card on the Integrations page walks you through the remaining steps:

Locations imported — happens automatically right after connecting
Map locations — tell Stash which Square location is which Stash shop. See Mapping POS locations to Stash shops.
Sync products — pull in your Square catalog (run automatically the first time, manual after)
Link Blueprints — connect each Square product to a Blueprint (or Modifier Blueprint, for modifiers) so sales deduct components. See Linking a Blueprint to a POS product.

How sales reach Stash

Stash pulls in Square sales every 15 minutes. Only orders that are closed in Square are processed — open tickets and parked orders don't deduct stock until they close. Historical Square orders placed before you connected are not imported. For the full breakdown, see How POS sales deduct stock automatically.

Good to know

Multi-location Square accounts

If your Square account has multiple locations, all of them are pulled in. You then map each one to the right Stash shop. One Square account can serve as the data source for multiple Stash shops.

Square modifiers — important limitation

Square supports modifiers (oat milk, extra shot, no onions, sauce on the side, etc.) as nested data inside each order line item. This modifier data is currently not exposed in the order feed Stash receives from Square. Stash sees the parent line item (e.g., "Latte") but not the modifier attached to it (e.g., "Oat Milk").

What this means in practice:

A "Latte with Oat Milk" sale is processed as a Latte only. Your Latte Blueprint fires and deducts cow milk (the default).
Any Modifier Blueprint you've set up for Oat Milk in Stash won't fire — Square never sends the Oat Milk line.
Stock for oat milk is not automatically deducted, and the cow milk that wasn't actually used is not added back.
Over time this creates drift: your cow milk inventory is over-deducted and your oat milk is under-deducted.

Workarounds:

Use Square variants instead of modifiers when possible. If you set up "Latte (Oat)" as its own variation in Square (rather than a modifier on Latte), it comes through as a distinct POS product. You then create a Blueprint for it that deducts oat milk directly. This works perfectly with Stash today.
For modifiers you can't avoid, do a periodic stock count on the affected items (typically your milks) and adjust manually. See Adjusting stock quantity manually.

Sizes are usually fine. If your Square setup has Small / Medium / Large as variations of a product (the standard Square pattern), each one is a distinct POS product that can have its own Blueprint with the correct quantities. If sizes are configured as modifiers instead, they hit the same limitation.

First-class Square modifier support is on our roadmap. The Modifier Blueprint pattern Stash already supports works out of the box for any POS that exposes modifiers as separate line items (e.g., Odoo POS) — see What is a Modifier Blueprint?.

Refunds and voided sales

Square refunds and voids do not automatically reverse the stock deduction in Stash. If you refund a sale and need the stock to come back, do a manual stock adjustment with a note referencing the refunded order. See Adjusting stock quantity manually. Automatic refund reversal is on our roadmap.

What Stash doesn't access

Even though Square handles a lot of data, Stash only reads what's needed: products, locations, and sale events. It doesn't read customer info, card numbers, employee details, payouts, or invoices.

Troubleshooting

"The popup didn't open"

Your browser blocked it. Allow popups for app.getstash.io and try again. On Chrome: click the popup-blocked icon in the address bar and choose "Always allow."

"Square is asking me to log in to a specific business"

If you have multiple Square businesses, log in to the one whose data you want in Stash. You can connect a different one to a different Stash shop later.

"I see locations imported but no products"

The product sync runs after locations are mapped. Map your locations first, then click Sync now to pull products.

"I authorized but the connection doesn't show in Stash"

Refresh the Integrations page. If still missing, the popup may have closed too quickly — try connecting again.

"Sales aren't appearing in Stash yet"

Sales are pulled in every 15 minutes. Wait for the next sync cycle. If sales still don't appear after that, see Why my Blueprint isn't deducting stock.