Oracle NetSuite Onboarding Guide - Square Bridge
Beta release
This is pre-release documentation for an API in public beta and is subject to change.
If you have 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.
In your browser, go to https://v2.squarebridge.com.
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.
Follow the prompt on the home page to begin the Integration Wizard.
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.
In the Select External Source drop-down menu, choose NetSuite.
Verify that you have completed the listed preparatory steps and if not complete them.
Enter values for Account Id, Client Id and Secret, Token Id and Secret, and RESTlet URL as described in Get NetSuite access tokens.
Note
If the RESTlet URL is not set or it is 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.
There is 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.
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.
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.)".
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.
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, customer refunds.
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 are 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 have 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 is 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 are 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 are not saved in your Square Catalog.
Note
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.
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".
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.
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.
For information about adding the Internal ID column to your NetSuite lists, see Step 3. Enable synchronization support
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 have not 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.
Choose the corresponding NetSuite non-inventory item internal ID for each Square item modifier.
Enter the corresponding NetSuite discount item internal ID for each Square discount.
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.
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.
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.
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 are not 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.
Important
You need to add a row to the table for each tax schedule that you have assigned to an item in NetSuite.
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.
Use these settings to override the default data type syncing defaults that you set for your NetSuite integration.
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. When orders are created for this Square location, they are 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 is not configured in NetSuite, choose a time zone corresponding to the physical address of the chosen location. 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.
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.
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 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.
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 are configuring.
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 is not enable, this customer is assigned to orders that do not 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 will be 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 is 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".
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.
Note
Why would an order not be fully paid?
An order might use a payment method that takes hours to confirm payment. Such an order is not 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 does not 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:
Food, with the total food purchase amount.
Beverage, with the total beverage purchase amount.
Merchandise, with the total merchandise purchase amount.
Default, with the total of all miscellaneous purchases that are not categorized as food, beverage, or merchandise.
It is 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 have 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 are not 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 is 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 do not have a category, such an item is sent to the default category specified.
Congratulations! Now that you have fully configured your Square Bridge integration, you can sync data. In Square Bridge, choose Sync Data, choose the record type you want to sync (for example, Customers), and then choose Run Sync to run a manual sync. Use the page to monitor the sync status of mapped ERP and Square records.
Did you know?
You can use the manual sync to audit sync results if you are creating an integration with Square Bridge for your business for the first time.
When you are satisfied that manual synchronization is providing correct results, you can choose Settings and then choose Sync Schedules within Square Bridge to enable automatic syncs.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.