The Square Bridge to Oracle NetSuite synchronization mapping reference.
Square Integrations: NetSuite

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, SubsidiaryJournal entry SUBSIDIARY
Square account: Settlement dateJournal entry DATE
Square Bridge Location Settings, General, Default ClassJournal entry detail CLASS
Square Bridge Location Settings, NetSuite GL code for adjustment type.Journal entry detail ACCOUNT
Square account: Settlement entry credit amountJournal entry detail CREDIT
Square account: Settlement entry debit amountJournal entry detail DEBIT
Square Bridge: "Square Settlement" + IDJournal 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:

SquareNetSuite
Customer directoryChoose Lists, Relationships, and Customers
First NameNAME
Last NameNAME
Phone NumberPHONE
Email AddressE-MAIL
AddressADDRESS
CompanyCOMPANY 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.

SquareNetSuite
Catalog CategoryClassification
Category NameNAME

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 libraryItem
CategoryCLASS
DescriptionDESCRIPTION/DISPLAY NAME
LocationsThe 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.
TaxesFor 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 typeIf 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".

Square seller dashboard. Items library, variations shown

In NetSuite, choose Lists, Accounting, and Items.

Seller Dashboard
NetSuite
Catalog item libraryItems
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.namecustitem_sq_itemnameoverride
• ‘Regular’ (if child matrix item)
DISPLAY NAME
DESCRIPTION
SALES DESCRIPTION
PURCHASE DESCRIPTION
(in order of precedence)
Manage Stock, Trackingtrue if the QUANTITY ON HAND for the location is not zero.
Sales Information, UnitPRIMARY SALE UNIT mapped using Measurement Mappings in the Square Bridge Integration Settings.
Sales Information, SKUITEM NAME/NUMBER
item_variation_data.upcUPC CODE
item_variation_data.pricing_typeVARIABLE_PRICING if custitem_sq_isvariableprice is true, otherwise FIXED_PRICING.
item_variation_data.price_moneyThe 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:

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

  2. Basic taxes.

  3. Avalara tax.

SquareNetSuite
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:

  1. Choose Items, and then choose Discounts to create the discounts you want to map in Square.

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

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

SquareNetSuite
Items, DiscountsItems > (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.

A graphic showing the Square Dashboard, Item variation dialog with stock levels

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
InventoryAdjustmentInventoryAdjustment
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
quantityinventoryList.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 IDsubsidiary.internalID
occurred_attranDate
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.

SquareNetSuite
OrderCreditMemo
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_idexternalID
line_items[]itemList.item[]
line_items[].total_money.amountitemList.item[].amount
line_items[].catalog_object_iditemList.item[].item.internalID
line_items[].quantityitemList.item[].quantity
line_items[].applied_taxes[].tax_uid, mapped in the Square Bridge Location Settings.itemList.item[].taxCode.internalID
created_attranDate
created_atshipDate

Payments are money that comes into a Square balance as a credit.

SquareNetSuiteEntity
Field
PaymentsCustomer Payments
N/Asource_type (such as CASH or CARD, mapped to a G/L account in the Square Bridge Location Settings).Accountaccount.internalId
N/AtrueapplyList.apply[].apply
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].amount
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].doc
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].due
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].total
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].type
Payment creation datecreated_atTransaction datetranDate
Customercustomer_id (if no customer, the default customer from the Location Settings is used.)Customerentity.internalId
N/Adefault_class_id (Square Bridge Location Settings)Class (can also be renamed)class.internalId
N/Adefault_department_id (optional, Square Bridge Location Settings)Departmentdepartment.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.

SquareNetSuiteEntity
Field
Return orders, exchange ordersCredit Memos
N/AN/AAccountaccount (determined by the customer)
N/AtrueapplyList.apply[].apply
N/AMapped to the credit memo using the originating Square exchange order by Square Bridge.applyList.apply[].amount
N/AMapped to the credit memo using the originating Square exchange order by Square Bridge.applyList.apply[].doc
N/AMapped to the credit memo using the originating Square exchange order by Square Bridge.applyList.apply[].due
N/AMapped to the credit memo using the originating Square exchange order by Square Bridge.applyList.apply[].total
N/AMapped to the credit memo using the originating Square exchange order by Square Bridge.applyList.apply[].type
Return line itemsreturns[].return_line_items[]ItemsitemList.item[]
Return line item amountreturns[].return_line_items[].total_money.amountItem amountitemList.item[].amount
Return line item IDreturns[].return_line_items[].catalog_object_idItem iditemList.item[].item.internalId
Return line item quantityreturns[].return_line_items[].quantityItem quantityitemList.item[].quantity
Return line item tax codereturns[].return_line_items[].applied_taxes[].tax_uid (mapped in the Square Bridge Location Settings)Item tax codeitemList.item[].taxCode.internalId
Locationlocation_id (mapped in the Square Bridge Location Settings)Locationlocation.internalId
N/Asubsidiary (Square Bridge Location Settings)Subsidiarysubsidiary.internalId

SquareNetSuiteEntity
Field
RefundsCustomer refunds
N/Asource_type (such as CASH or CARD, mapped to a G/L account in the Square Bridge Location Settings)Accountaccount.internalID
N/AtrueapplyList.apply[].apply
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].amount
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].doc
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].due
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].total
N/AMapped to an invoice using the originating Square order by Square Bridge.applyList.apply[].type
Payment creation datecreated_atTransaction datetranDate
Customercustomer_id (if no customer, the default customer from the Location Settings is used)Customerentity.internalID
N/Adefault_class_id (Square Bridge Location Settings)Class (can also be renamed)class.internalID
N/Adefault_department_id (optional, Square Bridge Location Settings)Departmentdepartment.internalID

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.