NetSuite Sync Mapping Reference
Beta release
This is pre-release documentation for an API in public beta and is subject to change.
This topic describes in detail the synchronization types available with Square for NetSuite integration. There are three important attributes to note about each type:
Sync direction. Determines which system is the source of truth for records and which system receives the records in a sync job.
Location specificity. Determines whether the records being synchronized are associated with a specific Square seller location. Non-specific location synchronization pushes records between systems regardless of its associated location.
Mappings. Determines how records and fields in NetSuite map to objects and their properties in Square.
Note
The sections in this topic provide summaries of all records, sublists, and other objects available in NetSuite. Information about each object is displayed as a series of tables, both for ease of browsing and to provide additional details that you might need when solving sync issues.
The bank transfers synchronization creates NetSuite Journal Entry records from settlements between Square and the bank linked to your Square account. It maps Square settlement types to NetSuite accounts using the internal IDs for general ledger (G/L) codes that you configure in the Square Bridge Location Settings.
The sync direction is from Square to NetSuite.
The sync is location-specific.
A bank transfer is synced by following these mappings.
Square bank transfer records are not visible through the Seller Dashboard. In NetSuite, find synced bank transfers by choosing Transactions, Financial, Make Journal Entries, and List.
A Square bank transfer (settlement) is composed of multiple settlement detail lines with each line of a specific adjustment type. All settlement lines of a given type and balance (debit/credit) are aggregated into a single NetSuite journal entry line. The Square Bridge Bank Transfer Adjustment Type Mappings is used to assign a NetSuite GL code to a journal line entry.
Square | NetSuite |
|---|---|
| Square Bridge Integration Settings: Square currency. | Journal entry CURRENCY field |
| Square Bridge Location Settings, General, Subsidiary | Journal entry SUBSIDIARY |
| Square account: Settlement date | Journal entry DATE |
| Square Bridge Location Settings, General, Default Class | Journal entry detail CLASS |
| Square Bridge Location Settings, NetSuite GL code for adjustment type. | Journal entry detail ACCOUNT |
| Square account: Settlement entry credit amount | Journal entry detail CREDIT |
| Square account: Settlement entry debit amount | Journal entry detail DEBIT |
| Square Bridge: "Square Settlement" + ID | Journal entry detail MEMO |
| Square Bridge Location Settings NetSuite location configured for the Square location ID. | Journal entry detail LOCATION |
The following Square settlement detail types are mapped to NetSuite journal detail lines according to the following criteria:
Adjustment. A manual adjustment applied to your account by Square. This type is rarely encountered.
Credited if it is a positive adjustment.
Debited if it is a negative adjustment.
Balance. The outstanding balance in your Square account.
Credited if BALANCE to account.
Debited if BALANCE from account.
Bank. The financial institution where Square transfers the Square account funds to for a given Square Location.
This journal entry line is created based on the settlement total.
Credited if the settlement total is less than zero.
Debited if the settlement total is greater than zero.
Chargeback. Charges returned to payment cards after a buyer wins a dispute.
Credited if the amount is greater than zero.
Debited if the amount is less than zero.
Hold adjustment. An adjustment made by Square related to holding/releasing a payment, usually when fraud is suspected.
Credited if the amount is greater than zero.
Debited if the amount is less than zero.
Transaction fee. The Square fee associated with card transactions.
Credited if the amount is greater than zero.
Debited if the amount is less than zero.
Customer synchronization has the following characteristics:
The sync direction is bidirectional. Customers are synced from NetSuite to Square and from Square to NetSuite.
Non-location specific. All customer records that are accessible through the NetSuite SOAP web services are synced.
Customer mapping
The Square customer list is in the Seller Dashboard in the Customers application under Directory. In NetSuite, customers are found by choosing Lists, Relationships, and Customers. The customer field mapping is shown in the following table:
| Square | NetSuite |
|---|---|
| Customer directory | Choose Lists, Relationships, and Customers |
| First Name | NAME |
| Last Name | NAME |
| Phone Number | PHONE |
| Email Address | |
| Address | ADDRESS |
| Company | COMPANY NAME |
Catalog synchronization has the following characteristics:
The sync direction for catalog records is from NetSuite to Square. NetSuite is the source of truth.
Non-location specific. A single catalog is used for all locations. However, the catalog sync depends on location settings that you need to set for each location.
Square Bridge Location Settings tasks for NetSuite include assigning a NetSuite price level to a Square location. This price level is used to query for the subset of items in NetSuite that have a price >= $0.00 in that price level. This results in only synchronizing NetSuite items that you intend to sell through Square.
You should create a NetSuite price level dedicated to Square. If you have multiple Square locations, you might want to create multiple price levels just for Square so that each Square location can have a different inventory.
Catalog categories are automatically synced and are used to categorize groups of related items in Square.
In the Seller Dashboard, view catalog categories by choosing the Items application and then choosing Categories. In NetSuite, find classifications by choosing Setup, Company, and Classes.
Did you know?
Your NetSuite administration might have renamed the Class record. If so, you can find the list in NetSuite by entering "page: classes" in the search field at the top of any page. The renamed list should appear in the search results.
| Square | NetSuite |
|---|---|
| Catalog Category | Classification |
| Category Name | NAME |
Note
Square Bridge preserves the NetSuite class hierarchy by adding a : in the Square category name for every nested level in the corresponding NetSuite class. For example, a class named Manufacturing with a parent class Internal would be Manufacturing:Internal in the Seller Dashboard categories list.
A catalog item represents a product for sale or service for hire.
In the Seller Dashboard, choose Items and then choose Item Library. In NetSuite, find items by choosing Lists, Accounting, and Items.
Seller Dashboard | NetSuite |
|---|---|
| Catalog item library | Item |
| Category | CLASS |
| Description | DESCRIPTION/DISPLAY NAME |
| Locations | The locations listed depend on whether the item is present with a price greater than $0.00 in the price level with the "Price List ID" specified for all locations in the Square Bridge Location Settings. |
| Taxes | For more information, see Sales taxes. |
| Item name | • Square custom field: sq_itemnameoverride• DISPLAY NAME • DESCRIPTION • SALES DESCRIPTION • PURCHASE DESCRIPTION • The first field filled, in order of precedence. |
| Item type | If the item type is "Service", it is synced as a Square Appointments service item. |
A catalog item variation models varieties of a product or service so that the variations can be treated as a single product or service. Item variations are chargeable items related by certain variables. For example, a shirt can be represented by an item. However, a small red shirt is a chargeable item with specified variations in size and color. Catalog item variations are related to a catalog item.
In the Seller Dashboard, find item variations by choosing Items and then choosing Item Library. To view item variation details, choose an item that has variations, expand the variation list, and choose a variation. In the following image, the "Champion Hoodie" has a variation called "S, Black".
In NetSuite, choose Lists, Accounting, and Items.
Seller Dashboard | NetSuite |
|---|---|
| Catalog item library | Items |
| Choose an Item variation, choose Manage stock, and see the locations where the variation is available. | The locations listed depend on whether the item is present with a price greater than $0.00 in the price level with the “Price List ID” specified for all locations in the Square Bridge Location Settings. |
item_variation_data.name | • custitem_sq_itemnameoverride• ‘Regular’ (if child matrix item) • DISPLAY NAME • DESCRIPTION • SALES DESCRIPTION • PURCHASE DESCRIPTION (in order of precedence) |
| Manage Stock, Tracking | true if the QUANTITY ON HAND for the location is not zero. |
| Sales Information, Unit | PRIMARY SALE UNIT mapped using Measurement Mappings in the Square Bridge Integration Settings. |
| Sales Information, SKU | ITEM NAME/NUMBER |
item_variation_data.upc | UPC CODE |
item_variation_data.pricing_type | VARIABLE_PRICING if custitem_sq_isvariableprice is true, otherwise FIXED_PRICING. |
item_variation_data.price_money | The price from the configured price level in the Square Bridge Location Settings. |
Units of measure are not automatically synced. You need to manually create them in Square and map them in the Square Bridge Integration Settings. For more information, see Create Units and Modifiers in the Seller Dashboard.
After you have created Square units of measure, map the units to NetSuite units.
In the Square Bridge Integration Settings, map each unit to a NetSuite unit. If a unit of measure does not exist in NetSuite, you can create one by choosing Units Of Measure, and then choosing New.
Sales tax is partially configured using Square Bridge settings. On the ERP system side, there are three choices for taxes:
Advanced taxes. To determine whether NetSuite advanced taxes are enabled for your account, choose Setup, Company, and Enable Features. On the page, choose the Tax tab, and then select the Enable ADVANCED TAXES checkbox.
Basic taxes.
Avalara tax.
| Square | NetSuite |
|---|---|
| Seller Dashboard: Settings, Account & Settings Business information, Sales taxes | Tax Groups and Tax Codes |
| Square Bridge: Settings, Tax Settings (only available when Advanced Taxes is selected in Integration Settings) |
Discounts are configured using Square Bridge Integration Settings.
To set up discounts:
Choose Items, and then choose Discounts to create the discounts you want to map in Square.
In the Square Bridge Integration Settings, map each discount to a NetSuite discount.
Note
If a particular discount does not exist in NetSuite, you can create one in NetSuite by choosing Lists, Accounting, Items, and New.
If you have discounts set up in Square, set a Custom Discount Item Code in the Square Bridge Integration Settings. The custom discount item code maps the internal ID of a NetSuite discount or non-inventory item to any discounts created in Square that are not explicitly mapped in the Discount Mappings section.
| Square | NetSuite |
|---|---|
| Items, Discounts | Items > (filter by discount) |
| Square Bridge | |
| Settings, Integration Settings |
Modifiers are not currently supported by Square Bridge.
The sync direction pushes NetSuite inventory levels into the Square account.
The sync is location-specific.
NetSuite item inventory as shown in the Locations section on the Purchasing/Inventory tab is pushed into the Seller Dashboard as item variation stock levels and detailed by location as shown in the following.
Important
The synchronization overrides the Square item inventory level with the NetSuite item inventory level.
The sync direction is unidirectional between Square to NetSuite. The sync pushes positive and negative adjustments (such as restocks and waste) between Square and NetSuite.
The sync is location-specific.
In Square, inventory adjustments are made in the Items application in the Seller Dashboard under Edit variation, on the Manage stock tab. In NetSuite, choose Lists, Accounting, and Items.
The following table describes the mapping between Square inventory adjustment objects and properties and between NetSuite objects and properties:
Square | NetSuite |
|---|---|
| InventoryAdjustment | InventoryAdjustment |
| The internal ID of the NetSuite item mapped to the Square catalog item within Square Bridge associated with the inventory adjustment. | inventoryList.inventory[].item.internalID |
quantity | inventoryList.inventory[].adjustQtyBy |
| The internal ID of the NetSuite unit mapped to the Square unit within Bridge associated with the catalog item in the inventory adjustment. | inventoryList.inventory[].units.internalID |
| Per Square location, the NetSuite location internal ID in Square Bridge associated with the inventory adjustment. | inventoryList.inventory[].location.internalID |
| Square Bridge Location Settings, subsidiary ID | subsidiary.internalID |
occurred_at | tranDate |
| The Square location ID associated with the inventory adjustment. | adjLocation.internalID |
The sync direction pushes completed Square orders into NetSuite. This sync can create four records in NetSuite:
Invoices
Customer payments
Credit memos
Customer refunds
The sync is location-specific.
The following tables describe the mapping between Square orders and properties and their corresponding NetSuite records and properties.
Sales orders in Square are orders where items have been sold. Sales orders do not include exchanges or returns. Square sales orders correspond to NetSuite invoices.
In the Seller Dashboard, choose Orders, and then choose Overview. In NetSuite, choose Transactions, Sales, Create Invoices, and List.
| Square | NetSuite |
|---|---|
| Order | CreditMemo |
| Configured in the Square Bridge Location Settings. | _class.internalID |
| Configured in the Square Bridge Location Settings. | department.internalID |
| Configured in the Square Bridge Location Settings. | location.internalID |
| Configured in the Square Bridge Location Settings. | subsidiary.internalID |
total_money.currency, mapped in the Square Bridge Integration Settings to the currency ID in NetSuite. | currency.internalID |
customer_id; if no customer is on the order, the default customer configured in the Square Bridge Location Settings is used. | entity.internalID |
reference_id | externalID |
line_items[] | itemList.item[] |
line_items[].total_money.amount | itemList.item[].amount |
line_items[].catalog_object_id | itemList.item[].item.internalID |
line_items[].quantity | itemList.item[].quantity |
line_items[].applied_taxes[].tax_uid, mapped in the Square Bridge Location Settings. | itemList.item[].taxCode.internalID |
created_at | tranDate |
created_at | shipDate |
Payments are money that comes into a Square balance as a credit.
| Square | NetSuite | Entity | Field |
|---|---|---|---|
| Payments | Customer Payments | ||
| N/A | source_type (such as CASH or CARD, mapped to a G/L account in the Square Bridge Location Settings). | Account | account.internalId |
| N/A | true | applyList.apply[].apply | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].amount | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].doc | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].due | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].total | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].type | |
| Payment creation date | created_at | Transaction date | tranDate |
| Customer | customer_id (if no customer, the default customer from the Location Settings is used.) | Customer | entity.internalId |
| N/A | default_class_id (Square Bridge Location Settings) | Class (can also be renamed) | class.internalId |
| N/A | default_department_id (optional, Square Bridge Location Settings) | Department | department.internalId |
NetSuite credit memos are created for items that are returned or exchanged in Square. When an item is exchanged, a credit memo can be applied to the sale invoice.
| Square | NetSuite | Entity | Field |
|---|---|---|---|
| Return orders, exchange orders | Credit Memos | ||
| N/A | N/A | Account | account (determined by the customer) |
| N/A | true | applyList.apply[].apply | |
| N/A | Mapped to the credit memo using the originating Square exchange order by Square Bridge. | applyList.apply[].amount | |
| N/A | Mapped to the credit memo using the originating Square exchange order by Square Bridge. | applyList.apply[].doc | |
| N/A | Mapped to the credit memo using the originating Square exchange order by Square Bridge. | applyList.apply[].due | |
| N/A | Mapped to the credit memo using the originating Square exchange order by Square Bridge. | applyList.apply[].total | |
| N/A | Mapped to the credit memo using the originating Square exchange order by Square Bridge. | applyList.apply[].type | |
| Return line items | returns[].return_line_items[] | Items | itemList.item[] |
| Return line item amount | returns[].return_line_items[].total_money.amount | Item amount | itemList.item[].amount |
| Return line item ID | returns[].return_line_items[].catalog_object_id | Item id | itemList.item[].item.internalId |
| Return line item quantity | returns[].return_line_items[].quantity | Item quantity | itemList.item[].quantity |
| Return line item tax code | returns[].return_line_items[].applied_taxes[].tax_uid (mapped in the Square Bridge Location Settings) | Item tax code | itemList.item[].taxCode.internalId |
| Location | location_id (mapped in the Square Bridge Location Settings) | Location | location.internalId |
| N/A | subsidiary (Square Bridge Location Settings) | Subsidiary | subsidiary.internalId |
| Square | NetSuite | Entity | Field |
|---|---|---|---|
| Refunds | Customer refunds | ||
| N/A | source_type (such as CASH or CARD, mapped to a G/L account in the Square Bridge Location Settings) | Account | account.internalID |
| N/A | true | applyList.apply[].apply | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].amount | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].doc | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].due | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].total | |
| N/A | Mapped to an invoice using the originating Square order by Square Bridge. | applyList.apply[].type | |
| Payment creation date | created_at | Transaction date | tranDate |
| Customer | customer_id (if no customer, the default customer from the Location Settings is used) | Customer | entity.internalID |
| N/A | default_class_id (Square Bridge Location Settings) | Class (can also be renamed) | class.internalID |
| N/A | default_department_id (optional, Square Bridge Location Settings) | Department | department.internalID |
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.