Using Square Bridge
This is pre-release documentation for an API in public beta and is subject to change.
This topic walks you through the experience of running Square Bridge for the first time and provides a user guide for the application.
When you run Square Bridge, you are prompted to sign in using a Google or Microsoft email address.
Sign up with a Google or Microsoft account. If you want to use a Google account and do not have one, see Create a Google Account.
On successful authentication, you are prompted to agree to the Square terms of service. Accept the terms of service and choose Submit to continue.
For security reasons, following 30 minutes of inactivity, you are automatically signed out of Square Bridge.
You are prompted to create your first Square integration with your ERP system.
In Square Bridge, choose the Create Integration button to run the onboarding wizard that links a Square account with your external system account. The wizard walks you through the integration configuration and setup.
There are several ERP-specific onboarding topics that have additional onboarding steps that you must complete. After you complete an integration configuration, read Sync monitoring to learn about monitoring the health of your integration.
Create a test integration using an alternative Square account (using a different email address from your live Square account) with a non-production version of your external system environment.
Do not create an integration between your live Square account and external production system account until you have validated Square Bridge with test environments.
If you have created an integration, Square Bridge opens to the Overview page, which shows the current status of your selected integration. If you have created other integrations, you can select one from the integration list to view that integration overview.
You can see the status of all synchronization types you have set up in the integration. When a title is selected, it opens a details page under Sync Data. Only sync data types that you have enabled are shown in the overview. In the following example integration, the bank transfer data type is not enabled.
Instead of expanding Sync Data to review a synced data type, you only need to select the title for that type. On selecting the title, you are taken to the Sync Data page for that data type.
Did you know?
Square Bridge is periodically updated with new features and other improvements. You can learn about the version history of Square Bridge by reading the changelog.
The Sync Data section has child pages for each data type that is synced. The child pages show the entities that have synced between Square and your ERP system. Use these pages to verify that you are synchronizing the entities that you expect to sync. You can filter the list by ID, sync state, and item type.
Table filters are additive. Each filter that you set further refines the results that you see in the table. For example, you can set an ID filter for rows whose ID starts with 'S'. If you want to further restrict the results to 'S' items that synced successfully, set the states filter to
Successful. Now, you see only items that start with 'S' and that have been synced successfully.
The ID filter field applies to the Square ID and External ID columns. Rows that pass the ID filter for either the Square or External ID are shown in the list. If you want to filter out more objects, use a longer filter string. For example, the string 'E' includes only objects whose ID first character is 'E' or 'e'. If you filter on 'Ey', the list includes only items whose IDs start with 'Ey'. The filter is not case-sensitive, which means that items starting with 'EY', 'ey', 'eY', or 'Ey' are returned.
The following catalog list has been filtered for IDs that start with 't'. The list includes two rows whose Square ID starts with 'T' and a row whose External ID starts with 'T'.
If a sync data table does not show the items that you expect, where the ERP system is the source of truth, you might need to update the items in your ERP system to correct mapped values. After you have saved those changes, you can choose Run Manual Sync to pull the data set again. You should only sync the latest changes if you have a large data set and only want to see the results of your updates.
If you want to see a synced customer or catalog item in the Square Seller Dashboard, select the entity to open a detail card on the right side of the page. Among the details on the card is a SQUARE ID hyperlink to the item in the Seller Dashboard. When you select the link, you are taken into the appropriate dashboard application where you can see the synced item and all other items of the same type.
You should have created at least two Square accounts: one for testing and one for production. The Square Seller Dashboard opens in whichever account was selected as the Settings → Source Settings, Square Account.
Catalog. Your ERP system is the source of truth for catalog synchronization. This means that any changes to your catalog must be made in your ERP system. Changes are picked up by the next synchronization job, whether it is a “Full Sync”or a "Latest Changes" job.
Customers. The customers sync pulls the complete customer list from your ERP system. Any customer that does not exist in your Square account is added. Existing customers are updated to match their entries in your ERP system.
Inventory levels. Sync the quantity of item variations on hand at a given location.
If an inventory level sync returns no items, verify that catalog sync brought catalog items into your Square account. An inventory sync brings inventory levels into your Square Item Library for only the catalog items that were synced.
Inventory changes. The inventory changes sync writes ERP item ledger entries for adjustments to the inventory level of whatever item+variation was received in your Square account. In addition, the appropriate stock keeping record is updated in your ERP system.
Settings pages hold all the values that you provided to the integration wizard when you created the integration.
Use the Integration Settings pages to update an existing integration configuration. Settings include general setting values that apply globally across the integration and have no location-specific values.
Location Settings are location-specific integration settings and include mappings for individual Square locations. You can set up Square locations based on their geographical location, business function, or their eCommerce channel (in-person or online). Your ERP system can also have general ledger (GL) codes, tax codes, or warehouse or store locations that are organized in the same way.
For example, if you have a Square location in Atlanta, GA, you would map catalog tax settings for the location to the corresponding ERP tax setting value for Atlanta, GA. You might also need to map ERP GL codes for payments by an eCommerce-specific Square location. For example, suppose your Square locations include an online location and an in-person location. If your ERP system has a GL code for cash payments taken online versus payments taken in person, you would define location settings for your online location and different settings for your in-person location. Each location-based sync would map payments to the appropriate GL codes.
Source Settings are the sign-in credentials that Square Bridge needs to get access to your ERP system and your Square account. When you have set your ERP credentials with the Integration Wizard, you must contact the Square Bridge team for any changes to those values.
Square Settings are the sign-in credentials that Square Bridge needs to get access to your ERP system and your Square account. When you have set your ERP credentials with the Integration Wizard and Square Bridge has successfully connected to your ERP system, you must contact the Square Bridge team for any changes to those values.
The Sync Schedules page is used to turn auto-syncing on or off for individual sync types. You can also apply auto-syncing to all your enabled schedules at once by selecting the toggle in the third column of the table header. The toggle column shows the auto-sync status of each individual sync type.
You can filter the table by sync type if you want to show only the sync types that you have enabled. The previous graphic shows the Bank Transfers sync type filtered out of the table. None of the enabled schedules are set for auto-sync.
The Catalog and Customer synchronization settings are global and apply across all of your Square locations. This is why the Location column shows All Locations for these sync types.
Did you know?
The disabled sync types cannot be enabled from the schedules page. You must update the integration settings from Settings → Integration Settings or Location Settings.
The audit log shows the history of all manual and automatic synchronizations that Square Bridge has attempted to run for the selected integration.
A sync job is composed of individual synchronization actions that can individually succeed while the job itself ultimately does not succeed. For example, a catalog sync job might synchronize several catalog object updates, catalog tax updates, and other catalog object updates. If you look at the Sync Data page for catalog data, you see the individual Successful sync states on the sync job. If the sync job itself could not finish, the audit log shows that the job failed even though individual objects might have been synchronized successfully.
The Sync Job details blade also provides a relevant error message if one is available. Before contacting the Square Bridge team, review the error message for details that might help you correct your integration or ERP settings. If you update your settings based on an error message, you can manually rerun the sync on the failed type.