Using Square Bridge
Beta release
This is pre-release documentation for an API in public beta and is subject to change.
Learn how to use the Square Bridge integration tool to monitor the results of synchronization with a Square integration. If you want to create your first integration, see Get Started with Square Integrations. After you've created a Square integration, you can monitor the health of your integration by using Square Bridge.
If you've created an integration, Square Bridge opens to the Overview page, which shows the current status of your selected integration. If you've 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've set up in the integration. When a title is selected, it opens a details page under Sync Data. Only sync data types that you've enabled are shown in the overview. In the following example integration, the bank transfer data type isn't enabled.
Instead of expanding Sync Data to review a synced data type, you only need to select the title for that type. When you select the title, you're 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 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 doesn't 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 cannot finish, the audit log shows that the job failed even though individual objects might have been synchronized successfully.
Sync Job details 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.
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're 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 the Square ID 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 isn't 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 doesn't 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've 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 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're 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 Seller Dashboard opens in whichever account was selected in Setting, Source Settings, and Square Account.
Bank transfers - A bank transfer is initiated by Square to move money from your Square Balance into your bank account. Square is the source of truth.
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's a “Full Sync” or a "Latest Changes" job.
Customers - The customers sync pulls the complete customer list from your ERP system. Any customer that doesn't exist in your Square account is added. Existing customers are updated to match their entries in your ERP system.
Inventory levels - Syncs the quantity of item variations on hand at a given location.
Note
If an inventory-level sync returns no items, verify that the 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.
Orders - Square is the source of truth. The orders sync writes transactions into your external system that represent sales made in the Square POS. An order contains a customer, items purchased, and sales amount. Orders can be aggregated by Square Bridge so that a single transaction is written into your system that represents all sales activity for a day.
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've 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've 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 by fully configured location. 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 sync schedule table by sync data type and by Square location as shown in the following image. The bank transfer data type has been filtered out and location-specific sync types are filtered to "My Business". If you've selected all of your locations, the "All Locations" filter is automatically selected so that you see global sync types.
Did you know?
The Square account location filter shows only the Square locations that you've fully configured in Square Bridge. You might have recently synced your locations from your Square account but have t completed the location settings for new locations. In this case, the new locations aren't available in the locations filter.
You can filter the table by sync type if you want to show only the sync types that you've enabled. The previous image 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 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 in Settings, Integration Settings or in Location Settings.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.