Learn how to configure Square Bridge to access your NetSuite account and synchronize with your Square account using data mapping.
Square Bridge

Oracle NetSuite 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 NetSuites account and synchronize with your Square account using the data mapping that you set up using this guide.

Prerequisites Permalink Get a link to this section

  • Appropriate system permissions. You can onboard your business onto Square Bridge if you are the owner of a Square seller account, the IT professional, the accountant, or an external value-added reseller (VAR). Your job title does not matter as much as the permissions that you have, which must include:

    • Full access to the Square account.

    • Administrator access to the NetSuite account.

    • Access to a Google or Microsoft account that can be shared amongst staff and used to log in to Square Bridge.

  • Item modifiers and units of measure. These must exist in your Square account before you configure Square Bridge. For more information, see Create Units and Modifiers in the Square Seller Dashboard.

When onboarding is completed, you can start synchronizing data between NetSuite and Square. With Square Bridge, you can leverage the best features of each system while maintaining a more complete picture of your business that shows relevant data from both systems.

Note

You need to complete the steps in Using Square Bridge before proceeding.

Data synchronization Permalink Get a link to this section

Data, also known as objects, can be created in NetSuite and pushed to Square. Data can also be created in Square and pushed to NetSuite. Data synchronization can also be pushed in both directions.

ObjectOriginSynchronize direction
CatalogNetSuitePush to Square
CustomersBothBidirectional
Payments & RefundsSquarePush to NetSuite
InvoicesSquarePush to NetSuite
Inventory adjustmentsSquarePush to NetSuite
Inventory levelsNetSuitePush to Square
Bank TransfersSquarePush to NetSuite

Bridge account Permalink Get a link to this section

A Square Bridge account is an account used to gate access to your Square Bridge integration. It is created automatically when you sign in with Microsoft or Google. When you sign in to Square Bridge, you can create and manage your business integrations. A Square Bridge account is not a Square seller account. If you want to access the Square Seller Dashboard to manage Square account data, you also need a Square seller account.

Square Bridge uses Microsoft and Google as authentication providers and, as of November 17, 2021, does not support sharing accounts with other users. Use a Microsoft or Google account you are comfortable sharing with your organization or create one if necessary.

The four tasks for configuring the integration are:

  • Configure NetSuite for Square Bridge.

  • Verify the existence of Square units and modifiers corresponding to NetSuite units.

  • Run the Square Bridge Integration Wizard.

  • Create account data mapping between NetSuite and Square Bridge.

    • Create discounts that are used at the Square Point of Sale.

Configure NetSuite for Square Bridge Permalink Get a link to this section

In this section, you enable the features and permissions needed for Square Bridge to connect to NetSuite for data access. This configuration must be done before configuring Square Bridge to sync data between NetSuite and Square.

Did you know?

You must have access to the Administrator role in your NetSuite account to perform the following steps in NetSuite.

Step 1. Enable permissions for token-based authentication Permalink Get a link to this section

Square Bridge accesses NetSuite by using credentials issued to a NetSuite user. The user provides those credentials to the integration in this step. The approach is called token-based authentication. Ensure that the necessary permissions for using token-based authentication are present for the user and their role.

In NetSuite, do the following:

  1. Enable required features. Under Setup, choose Company, choose Setup Tasks, choose Enable Features, and then navigate to the SuiteCloud subtab. Select the following checkboxes to enable the required features:

    • Client SuiteScript

    • Server SuiteScript

    • SOAP Web Services

    • Token-Based Authentication

  2. Enabled the required NetSuite user permissions:

    1. Navigate to Setup, choose Users/Roles, choose Manage Users, and then choose the user associated with this integration.

    2. On the user/employee page, choose Access, choose Global Permissions, and then verify that the user has at least the following permissions:

      PermissionLevel
      DepartmentsView
      SOAP Web ServicesFull

      The following graphic shows the NetSuite employee access and global permissions screen.

Step 2. Enable permissions for reading and writing NetSuite data Permalink Get a link to this section

Step 1 grants Square Bridge access to NetSuite as a platform. Step 2 grants access to objects within NetSuite such as accounts, items, and subsidiaries. You do this by giving the role assigned to your NetSuite user access to these objects.

In NetSuite, do the following:

Navigate to Setup, choose Users/Roles, and then choose Manage Roles. Select the most appropriate role assigned to the user you configured in step 1.1. You can also create and assign a new role to the user.

Did you know?

In some NetSuite implementations, a user with the Administrator role cannot be used with token-based authentication.

Navigate to the Permissions tab on the role page and set the following permissions.

Transactions Permalink Get a link to this section

PermissionLevel
Adjust InventoryEdit
Credit MemoEdit
Customer PaymentEdit
Customer RefundsEdit
InvoiceEdit
Make Journal EntryEdit
Transfer InventoryEdit

Lists Permalink Get a link to this section

PermissionLevel
CustomersView
ItemsView
AccountsView
ClassesView
ContactsView
CurrencyView
CustomersEdit
ItemsView
LocationsView
SubsidiariesView
Tax RecordsView
UnitsView

Setup Permalink Get a link to this section

PermissionLevel
Access Token ManagementFull
Accounting ListsView
Log in using Access TokensFull
SOAP Web ServicesFull
User Access TokensFull

Step 3. Retrieve NetSuite authentication credentials Permalink Get a link to this section

You need to provide Square Bridge with a set of NetSuite authentication credentials for Square Bridge to access your NetSuite account. These credentials are a client ID and secret generated by a new NetSuite integration record for Square Bridge and a token ID and secret generated by a new or existing user record.

You will generate the NetSuite authentication credentials in this step. Until you provide these credentials to Square Bridge in the Integration Wizard (see Step 3. Set the external source), you should save them in a secure location, such as a password manager note.

NetSuite account ID Permalink Get a link to this section

Your account ID can be found in NetSuite by choosing Setup, choosing Company, and then choosing Company Information (in the ACCOUNT ID field).

Consumer key and consumer secret Permalink Get a link to this section

The consumer key is also known as a client ID and the consumer secret is also known as a client secret.

To retrieve your NetSuite consumer key and secret, you need to create a new integration.

In NetSuite, do the following:

  1. Choose Setup, choose Integration, choose Manage Integrations, and then choose New.

  2. At a minimum, complete the following:

    • Name (for example, Square Bridge)

    • Select the checkboxes for the following fields:

      • TOKEN-BASED AUTHENTICATION

      • TBA: ISSUETOKEN ENDPOINT

      • TBA: AUTHORIZATION FLOW

    • CALLBACK URL. Enter https://auth.cloudelements.io/oauth.

    • REDIRECT URI. Enter https://auth.cloudelements.io/oauth.

  3. When you choose Save, your consumer key and secret are displayed.

    Important

    Save the key and secret in a secure place because they are only shown once.

Token ID and token secret Permalink Get a link to this section

To retrieve your NetSuite token ID and secret, you need to generate them first.

  1. In NetSuite, choose Setup, choose Users/Roles, choose Access Tokens, and then choose New.

  2. In the APPLICATION NAME field, select the application created in the previous step.

  3. Choose USER and ROLE.

  4. Choose Save and your token ID and secret are displayed.

    Important

    Save the ID and secret in a secure place because they are only shown once.

NetSuite RESTlet Permalink Get a link to this section

You are prompted to download a RESTlet for NetSuite in the Square Bridge Integration Wizard.

Square Bridge. External source, download a restlet

To learn how to deploy the restlet script to your NetSuite environment, see Uploading and Deploying Scripts to NetSuite.

Step 4. Expose NetSuite internal IDs Permalink Get a link to this section

For Square Bridge to successfully sync data between Square and NetSuite, it needs to know what to map objects to in each system. For example, if Square Bridge attempts to sync a cash payment from Square to NetSuite, it needs to know what account in NetSuite to assign that cash payment to.

NetSuite assigns unique internal IDs to every NetSuite record. When configuring Square Bridge, you must provide the internal IDs of many records so that objects can be successfully transformed during the sync process. One of the easiest ways to look up these internal IDs is by exposing them within the NetSuite graphical user interface.

  1. Within NetSuite, choose Setup, choose Company, choose Enable Features, and then choose the SuiteCloud tab.

  2. Make sure the Client SuiteScript checkbox is selected.

  3. Go to your NetSuite home page by choosing the house icon in the navigation bar.

  4. On the home page, within the Settings block, choose Set Preferences.

  5. On the General tab, under the Defaults section, make sure the Show Internal IDs checkbox is selected.

Step 5. Create user-defined fields Permalink Get a link to this section

The NetSuite data model does not represent transaction properties exactly the way they are represented in Square. To address this mismatch and allow accurate data synchronization, add user-defined fields (UDFs) to NetSuite. Square Bridge requires three UDFs to accurately sync data.

Create a UDF in NetSuite by choosing Customization, choosing List, Records, & Fields, and then choosing New after hovering over the list/record type you want to modify. Add the following UDFs to NetSuite for transactions.

SqIsVariablePrice Permalink Get a link to this section

Determines whether an item has a variable or fixed price within the Square Seller Dashboard when synced. This also applies to variations.

  • Label: SqIsVariablePrice

  • ID: _sq_isvariableprice

  • Custom field type: Item Field

  • Type: Checkbox

  • List/Record: Custom Item Fields

  • Applies to: Inventory, Non-inventory, Service, Other Charge, Group, Kit/Package, Assembly/Bill of Materials
    Subtype: Both

SquareItemVariationNameOverride Permalink Get a link to this section

Overrides any display name provided by NetSuite to Square.

  • Label: SquareItemVariationNameOverride

  • ID: _sq_itemvariationnameoverride

  • Custom field type: Item Field

  • Type: Free-Form Text

  • List/Record: Custom Item Fields

SquareReferenceId Permalink Get a link to this section

Adds an external identifier to line items in an invoice to aid in mapping to Square data.

  • Label: SquareReferenceId

  • ID: _sq_referenceid

  • Custom field type: Transaction Line Field

  • Type: Free-Form Text

  • List/Record: Transaction Line Fields

  • Applies to: Sale Item

Step 6. Create NetSuite non-inventory items for Square Permalink Get a link to this section

Square transactions might have items or quantities that do not map directly to the NetSuite transaction model. Square Bridge uses non-inventory items in NetSuite to enable a transaction to be represented correctly in both systems. In this step, you create several non-inventory items that map to Square items or quantities in the Square Bridge Integration and Location settings.

  1. In NetSuite, choose Lists, choose Accounting, and then choose Items.

  2. Choose New Item.

  3. Under Non-inventory Item, choose For Sale. The page heading in NetSuite should now be Non-inventory Item for Sale.

  4. Under Primary Information, enter names from the following table in Item Name and Display Name fields.

    You can provide a different name as long as the name denotes its purpose and that it is used for Square.

    Recommended item namePurpose
    SqRoundingItemIf there is a <$0.05 discrepancy between corresponding Square and NetSuite transaction documents, the item appears as a line item representing the difference.
    SqCustomDiscountThis item maps to discounts given in Square that are not explicitly mapped within your Square Bridge Integration settings.
    SqGiftCardItemThis item maps to gift cards purchased in Square.
    SqGiftCardDiscountThe item maps to the discount given when a Square gift card is used in a transaction.
    SqTipThis item maps to tips given in Square.
    SqCustomAmountDepending on your Square setup, employees can charge customers arbitrary (or custom) amounts. This item maps to those custom amounts charged in Square.
    SqDefaultServiceChargeThis item maps to service charges in Square.
    SqAdhocDefaultItemDepending on your Square setup, employees can create a new one-off line item to charge a customer during a transaction. This item maps to those ad hoc line items.
  5. Under Classification, choose one or more Subsidiary items to use with Square. Choose Department, Class, and Location only if needed.

Run the Square Bridge Integration Wizard Permalink Get a link to this section

You have configured NetSuite for integration and retrieved the necessary information for Square Bridge to interface with NetSuite. Now, you authorize Square Bridge to communicate with your Square and NetSuite accounts, as well as tell Square Bridge what data you want to sync and how to sync it.

When the Integration Wizard is complete, you can sync data between Square and NetSuite.

Step 1. Start the Integration Wizard Permalink Get a link to this section

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

  2. Sign in using the Microsoft or Google account that you want associated 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.

Step 2. Link a Square account Permalink Get a link to this section

If you have already authorized Square Bridge for a Square account with your Square Bridge account, it appears in the drop-down menu. Otherwise, you need to choose Link a Square Account and authorize Square Bridge to read and write data in your Square account.

Step 3. Set the external source Permalink Get a link to this section

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

  2. Verify that you have completed the listed preparatory steps and if not complete them.

  3. Enter values for Account Id, Client Id and Secret, Token Id and Secret, and RESTlet URL as detailed in Retrieve NetSuite authentication credentials.

Step 4. Confirm integration Permalink Get a link to this section

There is nothing to do in this step of the Integration Wizard other than to confirm that you want to integrate the Square and NetSuite accounts displayed.

Step 5. Configure integration Permalink Get a link to this section

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

  • General. You can change the default name of your integration in Square Bridge. The name of your integration has no effect on how or when data is synced. This setting is merely exposed for your convenience.

  • Data types. You need to specify what types of data you need to sync between your NetSuite and Square accounts. Enabling a sync allows you to configure Square Bridge for that sync, run manual syncs, and schedule automatic syncs. Note that enabling a sync in the Integration settings does not start automatic syncing.

  • Codes. Make sure NetSuite non-inventory items created for the Square Bridge sync have been assigned values for all required fields (such as class) and are in the correct subsidiary.

Step 6. Tax settings Permalink Get a link to this section

If the Advanced Taxes feature is enabled in NetSuite, Square Bridge must have the tax groups that are taxable within all NetSuite account tax schedules. Choose Settings and choose Tax Settings in Square Bridge to create a new tax schedule mapping. Create a new row with the tax schedule name, checking each tax group that is taxable within that tax schedule, and choosing Save Settings.

Square Bridge, Tax Settings

Note

To get the latest NetSuite tax settings, refresh the Tax Settings page to retrieve any NetSuite tax groups that were added, changed, or removed while configuring tax schedule mappings in Square Bridge.

Step 7. Location settings Permalink Get a link to this section

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

Bank transfer adjustment type mappings Permalink Get a link to this section

NetSuite account internal IDs can be found by choosing Lists, choosing Accounting, and then choosing Accounts. The value in the Internal ID column is used for Square Bridge mappings.

Payment type mappings Permalink Get a link to this section

NetSuite account internal IDs can be found by choosing Lists, choosing Accounting, and then choosing Accounts. The value in the Internal ID column is used for Square Bridge mappings.

NetSuite. Accounting, General Ledger Accounts

Catalog Permalink Get a link to this section

The price level ID determines which items are synced for each location and what their price is for that location. Square Bridge only syncs items that belong to configured price levels and that have a price greater than or equal to 0.00.

Orders Permalink Get a link to this section

Like all fields, enter the internal ID of the items or customer. Make sure that for all of these records, the subsidiary on the records matches the subsidiary selected in the General section of Square Bridge Location settings.

  • Default Customer ID (this customer should have a credit limit than can support the invoices assigned to them or have no credit limit at all)

  • Gift Card Item Code

  • Gift Card Discount Item Code

  • Tip Item Code

  • Custom Amount Item Code

Next steps Permalink Get a link to this section

Congratulations! Now that you have fully configured your Square Bridge integration, you are ready to start syncing data. You can choose Settings and then choose Sync Schedules within Square Bridge to enable automatic syncs or you can choose Sync Data and then choose Sync Data Type to run a manual sync and monitor the sync status of each NetSuite record and Square object. You should run some manual syncs and audit the results if you are creating an integration with Square Bridge for your business for the first time.

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.