Oracle NetSuite Onboarding Guide - Square Bridge

If you've completed part I (Oracle NetSuite Onboarding Guide - NetSuite), NetSuite is configured for the integration. In part II, you authorize Square Bridge to communicate with your Square and NetSuite accounts and configure Square Bridge with a sync map that defines the records you want to sync to your Square account.

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

Link to section

Step 1. Start the Integration Wizard

  1. In your browser, go to
  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.
Link to section

Step 2. Link a Square account

If you've 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.

Link to section

Step 3. Set the external source

  1. In the Select External Source drop-down menu, choose NetSuite.
  2. Verify that you've 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 described in Get NetSuite access tokens.


If the RESTlet URL isn't set or it's set with the wrong internal ID, the catalog sync fails on catalog items with the following error: SSS_INVALID_SCRIPTLET_ID - That Suitelet is invalid, disabled, or no longer exists.

Link to section

Step 4. Confirm integration

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

Link to section

Step 5. Configure integration

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.

Link to section


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.)".

Link to section

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 doesn't start automatic syncing.

  • Bank transfers - Sync from Square to NetSuite. End of day Square Balance payout to seller bank account.
  • Catalog - Sync from NetSuite to Square. Syncs items, taxes, and price levels into the Square POS.
  • Customers - Syncs in both directions. New customers are synced to Square. Updated customer records are synced in either direction.
  • Inventory changes - Synced to NetSuite. Inventory adjustments such as restock and waste adjustments are synced.
  • Inventory levels - Synced from NetSuite to Square. Inventory counts (levels) are updated in the Square POS after syncing from NetSuite.
  • Orders - Synced from Square to NetSuite. Square Orders are synced to NetSuite as invoices, customer payments, credit memos, and customer refunds.
Link to section

Catalog and orders sync

These settings determine how your NetSuite items are synced to your Square account and how Square orders are synced to NetSuite.

Select the Advanced Taxes checkbox if you're using advanced taxes in NetSuite. Selecting this item enables the Tax Settings tab of Square Bridge so that you can map the tax schedules used in Advanced Taxes. The exempt tax code ID is also entered if you plan to sell non-taxable items. The catalog sync creates a sales tax rate item in your Square account catalog for each tax group record in your NetSuite account. After syncing NetSuite taxes, you can find these tax items in your Seller Dashboard - Sales taxes page. For more information about NetSuite advanced taxes, see the NetSuite help topic Advanced Taxes.

Exempt Tax Code/Group - Set the internal ID of the NetSuite tax group that you've set up as non-taxable. A non-taxable group has a tax rate set to 0.0%. If NetSuite advanced taxes are used, a tax schedule determines if an item is taxable or not. If it's not taxable, the tax code/group that you set here is applied to a NetSuite transaction at the time the Orders sync is run. Note that the default NetSuite tax code is (-7) and tax group is (-8).

Rounding item ID, unknown item ID, and custom discount item IDs - In step 5 of the NetSuite onboarding guide, you created a set of non-inventory items. These IDs are mapped here and are used in order line detail to account for price modifiers that must be tracked.

Custom Discount Item ID - Use your NetSuite discount item code to map all unmapped or custom Square discounts. Square supports two types of discounts:

  • Catalog Discounts - Catalog Discounts are created in the Seller Dashboard, Items application. They're applied at the Point of Sale.
  • Custom Discounts - Custom Discounts are created in the Square Point of Sale during a transaction, or as "Ad-Hoc Discounts" through the Square Order API. Custom discounts one-time use and aren't saved in your Square Catalog.


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

Link to section

Subsidiary mapping

Square Bridge syncs the customer list maintained in the NetSuite subsidiary that you select. If you have a subsidiary hierarchy in NetSuite and you select a parent subsidiary, customers from that subsidiary and all of the descendant subsidiaries are synced. To sync all NetSuite customers to your Square account, select the root subsidiary — the subsidiary from which all other subsidiaries descend. For example, if you choose "Honeycomb Holdings, Inc" then all of its customers will sync and also those of "Honeycomb Mfg." and "Test Sub".

An image showing a list of NetSuite subsidiaries in a hierarchy.

Your Square Account customer list is created from the customer list in this subsidiary. Customer updates made in the Seller Dashboard sync back to it.

Link to section

Currency mappings

The country of your Square account determines the currency used in the account. The currency mappings table contains a row for each currency in your account. Normally this is one currency. For information about multiple currency support, see Can I accept Multiple Currencies with Square? To map a NetSuite currency to your Square account currency, select the internal ID of that currency.

An image showing the Oracle NetSuite page that lists the currencies set up for a NetSuite account.

For information about adding the Internal ID column to your NetSuite lists, see Step 3. Enable synchronization support.

Link to section

Measurement unit mappings

You should have created units of measure in the Seller Dashboard that map directly to corresponding units in NetSuite. If the table in this section has only a row for EACH, you haven't created measurement units. You need to complete the steps in Create Units and Modifiers in the Seller Dashboard before you can complete the Integration Settings page.

Link to section

Item modifier mappings

Choose the corresponding NetSuite non-inventory item internal ID for each Square item modifier.

Link to section

Discount mappings

Enter the corresponding NetSuite discount item internal ID for each Square discount.

Link to section

Step 6. Tax settings

The Tax Settings page needs to be completed if your NetSuite account uses Advanced Taxes and has assigned tax schedules to items to be synced with Square.

You need to add a row to the Tax Schedule Mappings table for each tax schedule in NetSuite. The tax schedule name must exactly match the NetSuite schedule. For each row you create, Square Bridge populates the row with all of your tax groups. This is done so you can specify the taxable status for synced items sold in any of your locations.

Link to section

Tax settings example

In this example, your NetSuite account has enabled Advanced Taxes, created tax schedules, set taxable nexuses, and assigned a tax schedule to each item. After completing the tax settings page and allowing the Square Bridge catalog sync to complete, your taxable and non-taxable items are shown in the Square POS with no sales tax for locations in your non-taxable nexuses.

An image showing the Square Bridge application, Tax Settings page.


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.

The following items apply to the previous example:

  • Your NetSuite account has a tax schedule for items of the class Services.
  • The Services tax schedule specifies that the CA, OR, and AK tax jurisdictions aren't taxable for "service" items.
  • All service items are assigned the Services tax schedule.
  • In Square Bridge, you add the Services tax schedule and the row is populated with your tax groups.
  • You select all the checkboxes for groups whose city, county, or state is in one of the Taxable tax jurisdictions. Leave the non-taxable groups unselected (CA, OR, and AK).
  • In Square Bridge, Location Settings, Catalog. All your tax groups and tax codes are listed. For a given location, select all applicable items.
  • The items sync creates manual taxes with rates from your tax groups and codes for the taxable locations.
  • When an order is created in the Square POS, the taxable or non-taxable taxes are applied, depending on the POS location.


You need to add a row to the table for each tax schedule that you've assigned to an item in NetSuite.

Link to section

Step 7. Location settings

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.

Link to section

Data Types

Use these settings to override the default data type syncing defaults that you set for your NetSuite integration.

Link to section

General settings

  • The Location must belong to the mapped Subsidiary or the descendent subsidiary for this physical location.
  • The subsidiary to which the chosen location is associated in NetSuite. It maps to the physical location of the inventory that orders for this subsidiary pull from. </br>When orders are created for this Square location, they're synced to NetSuite for the mapped subsidiary. Any inventory adjustments made at this Square location are also synced to the mapped NetSuite subsidiary.
  • The Time Zone must be the time zone set for this location in NetSuite. If a time zone isn't configured in NetSuite, choose a time zone corresponding to the physical address of the chosen location. </br>The Square Bridge Order sync gets sets of Order records for a single day into an aggregated order which is then synced to NetSuite. The chosen time zone allows Square Bridge to calculate the end of a day for this location.
Link to section

NetSuite general ledger mapping

Bank transfer adjustments and payments generated in your Square account are mapped to GL codes in NetSuite. The currency of the GL accounts that you choose for the following sections must match the location currency.

Link to section

Bank transfer adjustment type mappings

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.

Link to section

Payment type mappings

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

Link to 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.

Your tax groups and tax codes are listed, regardless of the location at which they might be used. To apply the appropriate set of tax items to your location, review the list and select the desired taxes. When the catalog sync runs, these selected items are assigned to the location you're configuring.

Link to section


For orders entry fields in Square Bridge, enter the Internal ID value assigned in NetSuite for each record.

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 page.

  • Always Use Square Default Customer - When enabled, all orders are attributed to the default customer. The default customer is attached to every order regardless of whether the customer sync has run and your customer list is in the Square POS.
  • Default Customer ID - If the previous option is enabled, this is the default customer assigned to every order. If it's not enable, this customer is assigned to orders that don't already have a customer assigned. Note: This NetSuite customer should have a credit limit that can support the invoices assigned to them or have no credit limit at all.
  • Default Department ID - NetSuite's internal ID for the default department for synced orders. This department is associated with created invoices and credit memos for this subsidiary.
  • Gift Card Item Code - Use the NetSuite item code for a gift card being sold to a buyer.
  • Gift Card Discount Item Code - Use a NetSuite non-inventory item code to track the order line item for the liability portion gift card purchase amount.
  • Tip Item Code - Use a NetSuite non-inventory item code to track service gratuity order line items.
  • Custom Amount Item Code - Use a NetSuite non-inventory item code to track Square orders with ad-hoc (custom) order items.
  • Default Service Charge - This location's Netsuite non-inventory item internal ID for ad-hoc service charges. This field must be filled with a NetSuite item code. You should create a dedicated non-inventory item for this purpose and give it an id/name like "SqDefaultServiceCharge".

Did you know?

You should prefix an item code with "Sq" so that you can distinguish it from item codes created for other purposes. "Sq" + "DefaultServiceCharge" tells you that the item code is for your Square integration and that it's used mapped to the Default Service Charge setting in Square Bridge.

  • Ad hoc Default Item - This location's Netsuite non-inventory item internal ID for ad hoc items. This field must be filled with a NetSuite item code. You should create a dedicated non-inventory item for this purpose and give it an id/name like "SqAdhocDefaultItem".
Link to section

Order aggregation

When order aggregation is enabled, during a business day time window, all orders fully paid for are reported to NetSuite as a single aggregated order that reports the total amount for each item category sold in the time window. Any non-paid order is aggregated in a future time window during which the payment is completed.


Why would an order not be fully paid?

  • An order might use a payment method that takes hours to confirm payment. Such an order isn't fully paid until confirmation.
  • An order whose delivery fulfillment must be complete before a payment card is processed is unpaid until after delivery.

For example, if a food service business creates item categories such as "food", "beverage", and "merchandise", then any individual beer, wine, or soda purchase is aggregated into an order item called "beverage". The business might occasionally sell an item that doesn't fit in any of the previous categories. They need those items aggregated too, so they define a default category for the miscellaneous items. The final aggregated order synced to NetSuite would have these line items:

  1. Food, with the total food purchase amount.
  2. Beverage, with the total beverage purchase amount.
  3. Merchandise, with the total merchandise purchase amount.
  4. Default, with the total of all miscellaneous purchases that aren't categorized as food, beverage, or merchandise.

It's a best practice to define an aggregation time window for a 24-hour period. That window is applied to each business day, starting at the window start time and ending 24 hours later. You can define shorter periods and any order completed outside of the aggregation window is synced as a single order.

After you've saved the location settings page, any aggregation settings you make can be changed up to the point the first order sync is completed. At that time, further aggregation setting changes aren't allowed.

  • Aggregate Orders - Enable or disable aggregating orders for this location. This setting can be changed until the first aggregated order is synced. After that, it's locked.
  • Aggregation Window Start Time - The start time during any business day when new orders are aggregated.
  • Aggregation Window End Time - The end time during any business day after which new orders are no longer aggregated.
  • Default Uncategorized Item - For order line items that don't have a category, such an item is sent to the default category specified.