How to Set up a Square Integration in the GRUBBRR Portal

Last updated: August 5, 2026

GRUBBRR supports integration with the Square POS and payment device. Square-integrated clients typically already have a Square account and menu configured at squareup.com It's important to note that we use two separate portals for Square clients. Clients using our Square Enterprise integration use the enterprise.grubbrr.com portal, while clients using our Square Merged integration will sign in to portal.grubbrr.com.

Prerequisites:

  1. In the US, GRUBBRR's integration works with the Gen 1 or 2 Square Reader; outside the US, we work with Square Terminal payment devices. 
    • Note: The Terminal payment device does not itemize orders outside the US. This means that the client may see a $25 transaction on the POS but not what was ordered. In this scenario, we should offer clients the GRUBBRR KDS or have them use networked kitchen printers.
  2. All Square customers must have a SquareAppDetailID selected during company creation. If we do not specify an ID, then the Square integration configuration settings will not be available.
  3. Before attempting to pair the Square Reader with their Kiosk, the client should connect the reader to either their POS or the Square App on their phone, and make sure that the device has been updated to the most recent firmware
    1. The Square Reader may not be able to link with the Kiosk if its firmware isn't up to date. 
  4. We also need to make sure that the client is using the latest version of the GRUBBRR application available at build.grubbrr.com; Square regularly updates their SDK, and older versions of the Kiosk won't be able to communicate with the newest versions of the Reader. 
  5. Recommended: We strongly recommend that clients add GRUBBRR as a user in Square Sync. Giving GRUBBRR access to the client’s Square Portal helps to facilitate the initial setup and troubleshooting in the future.

Creating a Company

Most of the Company Creation process is identical to creating a company for a non-Square client. However, to connect the client's GRUBBRR Portal to Square, we must do the following: 

  1. After filling in the Client's Company, User, Address, and Subscription information, you'll see a dropdown menu in the right column labeled SquareAppDetailID. You must assign an ID from this list to the client for the integration to function.

     
     
    • For SMB clients, you can generally assign them to the General GRUBRR ID
    • For larger clients or clients using a GRUBBRR KDS, you may need to give them a unique ID from the list. 
      • This step helps to prevent the client’s business from being impacted by API Rate limits imposed by Square
      • If additional App IDs are needed, please contact the Portal team
  2. Once you have configured the client's account, click save

Company-Level Configuration

  1. Connecting to Square
  2. Settings Configuration

Connecting to Square

Note: This document assumes that the client has added GRUBBRR as an administrative user in their Square Portal. If this isn't the case, please model this process for the client over video meeting.  

In Square, all menus are managed at the Company level. To perform an initial sync with your client's menu, do the following: 

  1. Log in to the GRUBBRR Portal using company credentials
  2. Select Configure from the left sidebar menu
  3. Select Square Integration from the dropdown
  4. Select Square Onboarding from the dropdown to open the Squareup Sign-in Screen

  5. Sign in with the appropriate squareup.com credentials

     
      • If the client has chosen to add GRUBBRR as an admin, use the james@grubbrr.com account
        • If using GRUBBRR as an admin, you will need to select the appropriate Square Portal for the client to proceed. If using the client's credentials, you should proceed directly to step 6. 
  6. Select Allow on the Permissions Authorization page

  7. Select Sync to Square to finalize the initial connection.

What Do We Pull from Square? 

When the initial sync to Square completes, the GRUBBRR Portal will automatically populate with:

  • Menu Items (w/ Images)
  • Categories (w/o Images)
  • Modifiers and Modifier Groups (w/o Images)
  • Variations (w/o Images)
  • Prices
  • Taxes
  • Discounts
  • Locations
  • Modifier and Modifier Groups display order
    • This is pulled from the client's Square Online Ordering menu, not the POS
  • Item and Category display order
    • This is pulled from the client's Square Online Ordering menu, not the POS
  • Store Timing
    • Note: We pull this information from Square by default, but it can be overridden through the GRUBBRR portal; if we do, the system will no longer update store timing automatically when we perform a sync

Subscribing to Webhooks

GRUBBRR can subscribe to Webhooks to receive automatic menu updates from the client's Square POS. This is not a mandatory step, but it is highly recommended;many Square-related support requests are in response to menu changes not syncing to a client’s GRUBBRR Portal. You can enable the settings by following these steps:

  1. Select Configure from the left sidebar menu
  2. Select Square Integration from the dropdown
  3. Select Square Settings

  4. Enable Process Webhook for Auto-Sync Menu

Note: There are two important notes for Square webhooks:

  1. Even with webhooks enabled, there is the possibility that the client's Square POS will not properly send updates to the GRUBBRR Portal. Please use the manual menu sync process outlined below if you are ever concerned that your GRUBBRR Portal is not aligned with your POS
  2. While the GRUBBRR Portal will update automatically, clients will still need to manually sync the Portal with their GRUBBRR Kiosk to apply these changes

What Updates do we Receive through Webhooks?

If webhooks are enabled, the GRUBBRR Portal should automatically update whenever the client: 

  • Creates a new menu item
  • Changes a menu item's price
  • 86'es a menu item
  • Adds a new category to their menu
  • Adds a new item to their menu
  • Adds a new discount to their menu
    • These will still need to be manually activated in the GRUBBRR Portal!
  • Adds new modifiers to an Item
  • Removes modifiers from an item

Managing the Menu

Performing Manual Menu Syncs

Almost all menu management takes place through Square. To manually sync menu changes from Square with GRUBBRR, follow the steps below: 

  1. Sign in to the Client's GRUBBRR Portal at the Company level
  2. Click on Configure
  3. Click on Square Sync

  4. The Portal will then pull up a Wizard-style sync page and will perform the sync in six parts:



    1. Locations Updates
    2. Category Updates (Does not overwrite images uploaded to the GRUBBRR Portal)
    3. Modifier Updates (Does not overwrite images uploaded to the GRUBBRR Portal)
    4. Items Updates (Does not overwrite images uploaded to the GRUBBRR Portal)
    5. Item Variations Updates (Does not overwrite images uploaded to the GRUBBRR Portal)
    6. Discount Updates

 

This process can take some time for large menus. If the process times out, simply restart the sync process from the beginning. If timeout errors persist after 3 or more attempts, contact GRUBBRR’s Portal team for assistance. 

Configuring The Menu

After we've pulled a client's menu, there are very few things that we'll be able to configure in the GRUBBRR Backend. Our system will always treat Square as the source of truth when updating a client's menu; however, we do have the ability to manage the following elements of the GRUBBRR Kiosk interface:

  • Category Images
  • Modifier Images
  • Item Display Names
  • Item-Level Upsells
  • Order-Level Upsells

Everything else- category mapping, modifiers, etc- must be imported from Square.

Hiding Items from the Kiosk Menu

When we sync with Square, we pull the entirety of the client's catalog into the GRUBBRR Portal. We can not remove or archive items from the Square POS; however, we can control whether an item is displayed on the client's kiosks. To hide an item on a client's kiosk menus: 

  1. Sign in to the client's portal at the Company level
  2. Click on Menu in the left sidebar
  3. Click on Catalog Management in the dropdown
  4. Select Items

  5. Find the item you wish to hide on the kiosk, and click the Edit button in the action column

  6. Underneath the item details, find the flag labeled Show on Kiosk, and turn it Off

  7. Click Save to apply your changes

You can follow a similar process for categories or modifiers that the client does not want on their kiosk. 

Pushing Menu Updates to GRUBBRR Devices

After pulling a client’s menu from their Square Portal, we need to push the updates to their devices. We do so by clicking the Sync button at the top right of the page in the GRUBBRR Portal. 

Pushing the menu behaves differently if we do so at the Company or the Location level. 

  • If we push the menu from the Company level, then the updates will be pushed to all GRUBBRR devices linked to the client’s account
  • If we push from the Location level, then the updates will only be pushed to devices registered to that specific location


Procedure Warnings: