Square Integration
Connect Square POS, sync customers and products, map locations, and process payments through Square.
The Square integration is the most common one for OnCloudWine wineries. It covers contacts, products, inventory, and payments — and lets you keep your tasting-room iPad as the in-person source of truth.
What syncs
| Direction | What |
|---|---|
| Square → OnCloudWine | Customers (as contacts), products and variants, stock levels, completed orders. |
| OnCloudWine → Square | Release orders (as Square orders for in-person pickup), payment captures. |
Connect
Open integrations
Settings → Organization → Integrations → Square.
Click Connect Square
You're redirected to Square's OAuth flow. Sign in with your Square merchant account.
Authorize the scopes
OnCloudWine requests: customers (read/write), catalog (read/write), inventory (read), orders (read/write), payments (read/write).
Land back in the dashboard
The integration shows ACTIVE with the Square merchant name and location count.
Map your locations
Square supports multiple locations (tasting rooms, off-site storage). Map each Square location to one or more OnCloudWine signup locations and fulfillment sites:
Square location mapping
Match Square locations to OnCloudWine sites for accurate routing.
| Square location | Role | Maps to |
|---|---|---|
| Main tasting room | Signup + Pickup | Tasting room (default) |
| Storage cellar | Inventory | Warehouse fulfillment |
| Pop-up — SF | Signup only | SF Events |
Sync contacts
To pull existing Square customers into OnCloudWine:
Click Sync contacts
Triggers
SYNC_SQUARE_CONTACTS. Runs as a background job; large catalogs take a few minutes.Review the import
New contacts default to status INACTIVE so you can vet them before moving to ACTIVE.
Match clubs
Square doesn't know about clubs. Use OnCloudWine to assign each new contact to a club — the contact list bulk-actions are ideal for this.
Sync products
Click Sync products
Triggers
SYNC_SQUARE_PRODUCTS. Pulls every catalog item from Square along with variants, prices, and SKUs.Verify variants
Square's "variations" become OnCloudWine variants. Spot-check a few to confirm the SKU and price came across correctly.
Add per-variant weight
Square doesn't always carry weight. Edit each variant in OnCloudWine to add weight before using it in a release (required for shipping).
Stock levels sync continuously via SYNC_SQUARE_STOCK. To force a refresh
click Sync stock at the integration page.
Sync orders
Two-way order sync is supported. When you process payments on a release,
OnCloudWine creates an order in Square (CREATE_SQUARE_ORDERS) so your
tasting-room iPad sees the same order.
After creation, any changes (e.g., a swap or refund in OnCloudWine) push
back to the Square order via UPDATE_SQUARE_ORDERS. The reverse — a
staff change in Square — is not synced back.
Sync statuses
Each synced entity has a status visible on its detail page:
| Status | Meaning |
|---|---|
| PENDING | Queued for sync. Background job will pick it up shortly. |
| SYNCED | Successfully synced; both systems agree on the current state. |
| FAILED | Sync failed. Hover for the Square error message. |
Square environments
OnCloudWine supports both PRODUCTION and SANDBOX. For testing the integration without affecting real data, connect a sandbox merchant account from the Square Developer Dashboard. Switch between them from the integration settings.
Troubleshooting
| Issue | Resolution |
|---|---|
| Sync FAILED | Open the activity log entry. Most failures are due to revoked OAuth — reconnect Square. |
| Duplicate contacts | Square sync is matched on email. If a Square customer changes email, a new contact is created. Use merge on the contact detail page. |
| Missing weights | Square does not require weight on items. Edit variants in OnCloudWine before using them in shipping releases. |
| Order not in Square | Some Square plans don't allow API order creation. Confirm your plan supports it or contact Square Sales. |