Learn about the Square Bridge to Microsoft Dynamics Business Central integration
Square Bridge

Business Central Onboarding Guide Beta release
This is pre-release documentation for an API in public beta and is subject to change.

This guide shows you how to configure Square Bridge to access your Business Central account and synchronize with your Square account using the default data mapping provided by Square Bridge.

Note

This topic assumes that you have read Using Square Bridge and have started to create your first Business Central integration. The information in this topic helps you find the Business Central pages and values that you need to configure your integration.

Scope of work Permalink Get a link to this section

A complete Square Bridge integration requires you to complete the following steps:

  • In Business Central, install the Business Central Square Bridge extension, which adds Business Central customization and connectivity with Square Bridge.

  • In Square Bridge, create a new integration by starting the Integration Wizard. Use the Integration Wizard to do the following:

    • Provide the Business Central credentials that Square Bridge needs to access your Business Central data.

    • Configure the integration with the Business Central codes that Square Bridge needs to find Business Central data to sync and to write data to Business Central correctly.

Step 1: Install the Square Bridge extension Permalink Get a link to this section

For data synchronization to work, Business Central must be extended with a Square Bridge application that runs the synchronization process on the Business Central side. Square Bridge adds several custom fields to customer and journal tables to identify records that are synchronized from Square.

In this step, you install the Square Bridge application from Square as an extension in Business Central.

  1. If you have not already done so, download the .app file from Square Bridge to a folder on your computer.

  2. In Business Central, visit the Extension Management page (page=2500).

    You can also find this page through the Business Central search feature with the expanded list of roles shown.

  3. Choose Manage and then choose Upload Extension to open the Upload And Deploy Extension dialog box.

  4. In the Select .app file box, choose the download .app file. In the Deploy to box, choose current version, and then choose the language of your choice. In the Schema Sync Mode box, choose Add, choose Accept for the disclaimer, and then choose the Deploy button.

    businesscentral.dynamics.com Update and Deploy Extension

  5. Choose Manage, choose Deployment Status (page=2508), and then choose the Square Bridge extension to view the progress of the deployment. The deployment might take several minutes.

    businesscentral.dynamics.com sandbox deploy status, page=22

    The Deployment Status page shows all versions of the Square Bridge extension that you have uploaded along with the final status of the deployment. If you have multiple versions, select the version whose status is InProgress.

Step 2: Create an integration Permalink Get a link to this section

After installing the Square Bridge Business Central extension, your Business Central account is ready to integrate with Square Bridge. To create an integration, you need to authorize Square Bridge to access your Square and Business Central accounts. This step describes how you configure Square Bridge with synchronized data mapping and describes how it is synchronized. After you have created the integration, you can start it to synchronize data between Business Central and your Square account.

Note

The first integration that you create should always be treated as a Sandbox environment. A Sandbox integration lets you and the Square Bridge team test your configuration by synchronizing data in the Sandbox environment. Use the Sandbox to review and fix any errors if they occur. You should synchronize from a Business Central environment whose data is very similar to your production account data.

When the Integration Wizard is complete, you have configured Square Bridge to get your Business Central data. You can now synchronize data between Square and Business Central.

Integration steps Permalink Get a link to this section

Complete the following steps to create an integration:

  1. Start the Square Bridge Integration Wizard.

    1. In your browser, go to https://v2.squarebridge.com.

    2. Sign in using the Microsoft or Google account that you intend to associate with Square Bridge and that you can share with your colleagues if needed.

    3. Follow the prompt on the home page to begin the Integration Wizard.

  2. If you have already authorized Square Bridge for a Square account with your Square Bridge account, choose your Square account from the drop-down menu. Otherwise, complete the next step.

  3. If you have not authorized Square Bridge yet, choose Link a Square Account to start linking your Sandbox Square account with your Business Central account.

    square-bridge-wizard-page one-square-account

    Important

    Do not create an integration between your live Square account and external system account until you have validated Square Bridge with test accounts and environments.

  4. When prompted, sign in to your Sandbox Square account.

  5. Review and authorize Square Bridge for all of the following Square account permissions so that it can act on your Sandbox Square account. Choose Allow to authorize account permissions and continue the Wizard.

    square-bridge-wizard-page-3-auth-square-bridge-permissions

    At this point, Square Bridge is set up to access your Square account as shown in the following:

    square-bridge-wizard-square-account-added

Step 3: Connect Square Bridge to Business Central Permalink Get a link to this section

Square Bridge must be configured with the Business Central credentials needed to access your Business Central sandbox environment.

Set the external source of data Permalink Get a link to this section

In the Integration Wizard, set the External Source of data to synchronize. This is your Business Central environment.

  1. In the Select External Source drop-down menu, choose Business Central.

  2. Choose Start Authentication to begin linking Square Bridge to Business Central.

    square-bridge-wizard-external-source-start-authentication

  3. After authenticating with Business Central, you are redirected back to the Square Bridge External Source page.

    Business Central login-pick-an-account

  4. Enter the Environment Name, Tenant ID, and Company ID from Business Central.

    • Environment Name. This value is the first part of the Environment Name field, as found in the Business Central Help and Support, Troubleshooting page. For example, if the Azure environment is “Environment: sandbox (Sandbox)”, then the Environment Name field value should be “sandbox”.

      Business Central, tenant ID highlighted

    • Tenant ID. This value is the Azure AD tenant field, found in the Business Central Help and Support, Troubleshooting page. The ID is normally a GUID as shown in the following:

      azure-ad-tenant-hilight (2)

    • Company ID. This value is the Company field, found in the Business Central Settings, My Settings dialog box. Business Central settings are accessed by selecting the gear icon on the toolbar. This is usually the same as the Business Name on the Business Central home page. The Settings.Company field is always correct.

      Business Central, settings, company name field

Confirm connectivity in the integration Permalink Get a link to this section

This step confirms that you have configured account credentials correctly. There is nothing to do in this step of the Integration Wizard other than to confirm that you want to integrate the Square and Business Central accounts displayed.

square-bridge-wizard-confirm-integration

Choose Continue to confirm that Square Bridge can connect to Square and Business Central.

Did you know?

You can avoid problems later by verifying that the accounts that appear on this Confirmation Page are the correct accounts.

Step 4: Provide integration settings Permalink Get a link to this section

Use this step to provide information about your Business Central account, map Business Central attributes to Square attributes, and set default values for your integration.

Read the placeholders and tips for each form field for more information about how to configure Square Bridge. This section of the documentation provides more details about each form section.

The following sections explain where Business Central holds the values that you provide to Square Bridge integration settings fields.

General settings Permalink Get a link to this section

The general configuration page holds values that apply globally across all your Square account locations.

  • Integration Name. You can change the default name of your integration in Square Bridge. The name of your integration is arbitrary and has no effect on data synchronization. The value in this setting is shown in the Square Bridge integration list on the Square Bridge home page.

    Did you know?

    If you have multiple integrations such as a test integration and a production integration, you should prepend "Test" or "Prod" to the integration name so that the integration list shows unique entries. For example, "Test - Business Central (CRONUS USA, Inc.)" and "Prod - Business Central (CRONUS USA, Inc.)".

  • Company system ID. The company system ID is not the same as the company ID that you set in step 3. The company system ID is necessary to make requests to Business Central.

    Find your company system ID by visiting the Companies page (page=357), choosing ?, choosing Help & Support, choosing Inspect pages and data, and then searching for systemId after making sure that the correct company is selected in the list.

    Business Central company System ID

Batch names Permalink Get a link to this section

All of these batch names are arbitrary. Use batch names that meet your business requirements. Be sure that whatever batch name you choose in Business Central is used in the Square Bridge integration.

  • Cash receipt journal batch name. The cash receipt journal (page=255) batch name is used for creating incoming and outgoing payment lines (payments portion of the order sync) through the Business Central "Cash Receipt Journals".

    The following shows the GENERAL cash receipt journal batch name:

    businesscentral cash-reciept-journal-name

  • General journal batch name. The general journal batch name is used for creating bank transfer journal lines in the bank transfers synchronization through the Business Central "General Journals".

    The following shows the DEFAULT general journal batch name:

    businesscentral general-journal

  • Item journal batch name. The item journal (page=40) batch name is used for creating goods receipts and goods issues (the inventory adjustments portion of the inventory changes sync) through the Business Central "Item Journals".

    The following shows the DEFAULT item journal batch name:

    businesscentral item-journal

  • Transfer journal batch name. The transfer journal batch (page=393) name is used for creating inventory transfers (the inventory transfer portion of the inventory changes sync) through the Business Central "Item Reclassification Journal".

    The following shows the DEFAULT item reclassification journal:

    businesscentral item-reclassification-journal

  • New Business Central sales pricing experience. If you want to sync more than 1,000 items from Business Central to Square, you must enable the Business Central sales pricing feature (if not already enabled). Enable the feature in Business Central using Feature Management (page=2610) and then look for Feature Update: New sales pricing experience. Make sure this is enabled for All Users before checking the box in Square Bridge.

    The following shows how the new sales pricing experienced is enabled in Business Central Feature Management:

    dynamics.com feature-management pricing-switch page=2610

Data types Permalink Get a link to this section

Use these six on/off sliders to specify the data types you want to synchronize between Business Central and your Square accounts. If you turn on synchronization for a given data type, you can configure Square Bridge for that synchronization, run manual synchronizations, and schedule automatic synchronizations. Enabling a synchronization in the Integration Settings does not start an automatic synchronization. Automatic synchronization is managed on the Business Central Sync Schedules page.

The following shows the six data type selectors:

v2.squarebridge.com home integration settings integration

Codes Permalink Get a link to this section

Codes are objects created in Business Central that are applied to catalog items for the purpose of inventory syncing. You might need to create one of these codes if it does not exist in your Business Central environment.

  • Exempt tax code. For Business Central, this is likely the tax group NONTAXABLE. This is used when a line item on an order has a $0 tax. To confirm, open Business Central Tax Setup (page=485) and use the value of the Non-Taxable Tax Group code.

  • Rounding item code. The rounding item should be a custom non-inventory item that you create in Business Central (page=30). The rounding item code is used when Square Bridge is syncing Square orders to Business Central and encounters a discrepancy on an order or credit memo of less than 5 cents. Use the No. (SQ_ROUNDING) of the item to enter in this field. If this code does not exist, create a new item with the following values:

    • No. SQ_ROUNDING

    • Description Square Rounding

    • Type Non-Inventory

  • Unknown item code. Similar to the rounding item, for unknown items a custom non-inventory item should also be created in Business Central. Create an item with the following values:

    • No. SQ_UNKNOWN

    • Description Square Unknown

    • Type Non-Inventory The SQ_UNKNOWN code is used by Square Bridge for your Square account non-inventory items that are to be synced to Business Central.

Currency mappings Permalink Get a link to this section

You can find the currency codes supported by your instance of Business Central by choosing Finance, and then choosing Currencies. The ISO Code column in the currency table maps to the Square currency used for a given Square account.

Choose the corresponding Business Central currency code for each Square currency.

Important

You should leave this field blank so that synchronization maps to the default Business Central currency.

If you select the entry field, choose esc on your keyboard to deselects the field without entering a value.

Step 5: Configure your locations Permalink Get a link to this section

Square Bridge lets you set up synchronization for each of your locations to account for differences that each of your locations might have. For example, you might not use the same catalog items in each location or might not use inventory tracking in one location.

For each location, you need to select the data types that you want to enable, the Business Central warehouse and time zone that corresponds to a Square location, and catalog settings that are applied to the location.

The list of Square seller locations is blank until you choose Sync Locations. When you have synchronized the Square Bridge locations list with your Square account locations, you can individually configure each location with the appropriate location-specific Business Central values.

Note

For more information about configuring Square Bridge, read about the placeholders and tips for each form field. This part of the documentation provides more details about each form section.

Data types Permalink Get a link to this section

Choose which types of Square and Business Central account data that you want to sync with Square Bridge by sliding the on/off toggle for each data type. Each data type has an associated set of mapping properties. When you turn on data sync for a given type, the associated mappings are shown in following sections of the Location Settings page.

Bank transfer adjustment types Permalink Get a link to this section

Bank transfer adjustment mapping requires that you have the list of Business Central GL codes used to categorize asset transactions that affect Business Central asset balances. If you are not sure which GL codes to use, you should consult with your accounting team. Square Bridge bank transfer syncing records ledger entries in Business Central, which could put your ledger out of balance if the incorrect GL codes are configured in Square Bridge.

The following shows the Square Bridge bank transfer adjustment type mappings that you configure with Business Central GL codes:

squarebridge.com integration settings locations bank codes

You can find the general ledger (GL) codes in Business Central by choosing the Chart of Accounts page.

Payment type mappings Permalink Get a link to this section

Similar to the bank transfer mappings, you can find the GL codes for payment mappings on the Business Central Chart of Accounts page.

Catalog Permalink Get a link to this section

  • Price list ID. The price list ID maps to a code in a Business Central Customer Price Group. To find the code, go to Business Central, and then choose Customer Price Groups under Go to Pages and Tasks. The Code (Sales Code) column corresponds to the price list ID.

    Square Bridge synchronizes items whose customer price group Sales Code matches the price list ID that you set as the catalog Price List ID. The ID also determines the item price for a location. Square Bridge only synchronizes items set for unit prices greater than or equal to 0.00.

    In the following example, item 1900-S syncs because it is assigned a customer price group code of SQUARE and it has a unit price of 130.00, which is a value greater than or equal to 0.00. Inventory levels on the item sync because the price group Variant Code is used in a Business Central stockkeeping unit for the item at this location.

    businesscentral.dynamics.com item-sales-prices

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.