Oracle NetSuite Onboarding Guide - NetSuite
Beta release
This is pre-release documentation for an API in public beta and is subject to change.
This guide shows you how to create an integration between your NetSuite account and your Square account. You use Square Bridge to configure and manage the integration.
To enable the integration, Square Bridge must access your NetSuite account to synchronize with your Square account using data mappings that you provide. You complete the first five steps of this topic in your NetSuite environment to configure it for the integration. The next seven steps are completed in Square Bridge to provide the required NetSuite access tokens and to create the data mapping (see Oracle NetSuite Onboarding Guide - Square Bridge).
Important
You need to complete the Get Started with Square Integrations guide before proceeding.
Before you start working on the steps in this guide, be sure you can meet the following prerequisites:
Square and NetSuite permissions. You can integrate your NetSuite environment if you are the owner of a Square account or you have a role in your business such as a NetSuite IT professional, an accountant, or an external value-added reseller (VAR). Regardless of your role in your business, you must have the following permissions:
Full access to the Square account.
Administrator access to the NetSuite account.
Access to a Google or Microsoft account that can be shared among staff and used to log in to Square Bridge.
Add units of measure. The units that you use in NetSuite need to exist in your Square account. For more information, see Add NetSuite Units of Measure to your Square Account.
Install the Square for NetSuite SuiteApp. The SuiteApp is available in the Oracle NetSuite SuiteApps store. For information about installing the SuiteApp, see Install the Square for NetSuite SuiteApp.
Enable the features and permissions needed for Square Bridge to connect to NetSuite for data access. This configuration, which is completed in your NetSuite environment, must be done before configuring Square Bridge to sync data between NetSuite and Square.
You provide a NetSuite user with the required permissions before generating access tokens to be used by Square Bridge to sync with your NetSuite instance. You also need to turn on the NetSuite features needed by Square Bridge.
Square Bridge accesses NetSuite by using tokens issued to a NetSuite user. This is known as token-based authentication. Before you get the user access tokens, confirm that the necessary permissions for using token-based authentication are present for the user and their role.
In NetSuite, Enable features to support the integration:
Choose Setup, choose Company, and then choose Enable Features. Choose the SuiteCloud subtab.
Select the following checkboxes to enable the required features:
Client SuiteScript
Server SuiteScript
SOAP Web Services
Token-Based Authentication
To get access tokens, you need to identify a NetSuite user (employee record) to "own" the integration and then get that user's access tokens. The tokens are provided to Square Bridge so that it can access your NetSuite account safely and securely as that chosen user.
Note
Several NetSuite record types can be returned when you search by the user's name. For example, a Contact can be returned. Be sure that you choose only an Employee record. Roles cannot be attached and access tokens cannot be created for other record types.
The following steps assign the "Square Bridge Integration" role to the NetSuite user is to be associated with all synced records.
In the NetSuite search field, type the name of the chosen employee, for example "William Oller".
In the search result, choose Edit to make changes to the employee associated with this integration.
In the user page—edit mode, choose Access, then Roles, and attach the role "Square Bridge Integration" and choose Save.
Important
The employee that you choose will be the "owner" of the integration. Records synced from Square Bridge will be created in NetSuite by this employee. If the chosen employee is deleted, the Square Bridge integration stops working until another employee is chosen and new tokens are generated.
You generate the NetSuite access tokens using the following steps:
In the NetSuite search field, type "Access Tokens".
In the Access Tokens page, choose New Access Token
In the APPLICATION NAME field, select the application "Square Bridge (custinteg_5abf5455e692)".
Choose USER and select the employee from the previous section.
Choose ROLE and select the role "Square Bridge Integration"
Choose Save and your token ID and secret are displayed.
Save the values for these fields:
Token ID
Token secret
Note
Until you provide these credentials to Square Bridge in the Integration Wizard (see Set the external source), you should save them in a secure location, such as a password manager note.
Your account ID can be found in NetSuite by choosing Setup, choosing Company, and then choosing Company Information (in the ACCOUNT ID field).
The Square Bridge catalog item sync depends on the RESTlet installed in NetSuite by the Square SuiteApp. To make that RESTlet available to Square Bridge, you need to get the URL string and save it. You provide it to Square Bridge in Enable synchronization support of the next section of this topic.
In NetSuite, choose Customization, choose Scripting, and then choose Scripts. Find the deployed script whose name is "Square Bridge Items and Inventory Search". Choose View, choose Deployments on the Script page, and then choose Square Bridge Items and Inventory Search RESTlet.
Copy the EXTERNAL URL of the Script Deployment.
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 to which account in NetSuite to assign that cash payment.
Square Bridge relies on NetSuite client JavaScript to enable the actual synchronization of data. SuiteScript must be enabled within NetSuite for the integration.
Within NetSuite, choose Setup, choose Company, choose Enable Features, and then choose the SuiteCloud tab.
Make sure the Client SuiteScript checkbox is selected.
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.
Go to the NetSuite home page by choosing the house icon in the navigation bar.
On the home page, within the Settings block, choose Set Preferences.
On the General tab, under the Defaults section, make sure that the Show Internal IDs checkbox is selected.
If your NetSuite account does not have a default customer defined for each location, you need to create one. Square Bridge uses a default customer to assign orders to when an actual customer is not specified in the order. The internal ID of your default customer is needed by the Square Bridge Integration Wizard if you sync orders from your Square account.
The default customer should have the status of CUSTOMER, but can have any name. For convenience, you can set the first name of the customer to "Default" and the last name to "Customer".
Square orders can have items or quantities that do not map directly to the NetSuite transaction model. Square Bridge uses non-inventory items in NetSuite to enable an order 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 Settings and Location Settings.
In NetSuite, choose Lists, choose Accounting, and then choose Items.
Choose New Item.
Under Non-inventory Item, choose For Sale. The page heading in NetSuite should now be Non-inventory Item for Sale.
Under Primary Information, enter names from the following table in the Item Name and Display Name fields.
You can provide a different name as long as the name denotes its purpose and it is used for Square.
Recommended item name Purpose SqRoundingItem If there is a <$0.05 discrepancy between corresponding Square and NetSuite transaction documents, the item appears as a line item representing the difference. SqCustomDiscount This item maps to discounts given in Square that are not explicitly mapped within your Square Bridge Integration settings. SqGiftCardItem This item maps to gift cards purchased in Square. SqGiftCardDiscount The item maps to the discount given when a Square gift card is used in a transaction. SqTip This item maps to tips given in Square. SqCustomAmount Depending on your Square setup, employees can charge customers arbitrary (or custom) amounts. This item maps to those custom amounts charged in Square. SqDefaultServiceCharge This item maps to service charges in Square. SqAdhocDefaultItem Depending 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. Under Classification, choose one or more Subsidiary options to use with Square. Choose Department, Class, and Location only if your organization requires these fields in a transaction line item.
Under the Accounting tab, choose the non-taxable tax schedule. This might be
S2. To verify, open the Tax Schedules page and read the description of each schedule.
Understanding the following concepts is helpful while working through the steps in this guide.
NetSuite records are synced to the Seller Dashboard as objects. These objects include customers, catalog categories, and items.
Some Square objects can also be synced to NetSuite as records. These record types include customers, customer invoices, and inventory adjustments. Customer synchronization is bidirectional, which means updates made in either system are synced to the other system.
| Object | Origin | Synchronize direction |
|---|---|---|
| Catalog | NetSuite | Push to Square |
| Customers | Both | Bidirectional |
| Payments & Refunds | Square | Push to NetSuite |
| Invoices & Credit Memos | Square | Push to NetSuite |
| Inventory adjustments | Square | Push to NetSuite |
| Inventory levels | NetSuite | Push to Square |
| Bank Transfers | Square | Push to NetSuite |
For more information about syncing details, see NetSuite Sync Mapping Reference.
A Square Bridge account is an account used to gate access to one or more Square Bridge integrations. 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 Seller Dashboard to manage Square account data, you need to log in to your Square seller account.
Square Bridge uses Microsoft and Google as authentication providers and does not currently support sharing access to the Square Bridge user interface with other users. Use a Microsoft or Google account you are comfortable sharing with your organization or create one if necessary.
The five tasks for configuring the integration are:
Configure NetSuite for Square Bridge.
Verify the existence of Square units of measure corresponding to NetSuite units.
Create discounts that are used at the Square Point of Sale.
Run the Square Bridge Integration Wizard.
Create account data mapping between NetSuite and Square Bridge.
The Square NetSuite SuiteApp created a new NetSuite role when the application was installed. The role is assigned the permissions shown in the following tables.
Choose the Permissions tab on the role page and set the following permissions.
Transaction Permissions | Level |
|---|---|
| Adjust Inventory | Edit |
| Credit Memo | Edit |
| Customer Payment | Edit |
| Customer Refunds | Edit |
| Invoice | Edit |
| Make Journal Entry | Edit |
| Transfer Inventory | Edit |
List Permissions | Level |
|---|---|
| Customers | View |
| Items | View |
| Accounts | View |
| Classes | View |
| Contacts | View |
| Currency | View |
| Customers | Edit |
| Items | View |
| Locations | View |
| Subsidiaries | View |
| Tax Records | View |
| Units | View |
Setup Permissions | Level |
|---|---|
| Access Token Management | Full |
| Accounting Lists | View |
| Log in using Access Tokens | Full |
| SOAP Web Services | Full |
| User Access Tokens | Full |
When step 2 is complete, your user has all the permissions required for creating a set of access tokens to be used by Square Bridge for connecting to NetSuite as that user.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.