Learn about the mapping between Dynamics Business Central fields and Square account objects.
Square Integrations: Business Central

Sync Mapping Reference Beta release
This is pre-release documentation for an API in public beta and is subject to change.

This guide describes in detail the synchronization types available for Square and Business Central with Square Bridge. There are three important attributes to note about each type:

  • Sync direction. Determines which system is the synchronization source and which system is the synchronization target.

  • Location specificity. Determines whether the data being synchronized is associated with a specific Square seller location. Non-specific location synchronization pushes data between systems regardless of its associated location.

  • Mappings. Determines how objects (records) and fields in Business Central map to objects and their properties in Square.

Some of the table values in this topic refer to custom Business Central fields that receive values from Square when a data sync runs. These fields are added to the Business Central environment automatically when the Square Bridge extension is installed in your Business Central environment.

Did you know?

If you do not see a Business Central table column that is referenced in this guide, you might want to personalize your workspace to add these columns to a table in question. For example, this guide refers to stockkeeping units for catalog items. You might choose to add the Stockkeeping Unit Exists column to the Items table so that you can quickly determine which items can be synced to a Square account inventory.

Custom fields added by the Square Bridge extension cannot be added as columns to Business Central tables.

The bank transfers synchronization creates Business Central Journal Entry records from settlements between Square and the bank linked to your Square account. It maps Square settlement types to Business Central accounts using G/L codes configured in the Square Bridge Location Settings.

  • The sync direction is from Square to NetSuite.

  • The sync is location-specific.

Note

You need to enter the General Journal Batch Name in the Square Bridge Integration Settings for this sync to be successful.

The Business Central general journal column labels in this table apply to the DEFAULT journal page=39.

This table maps the source of field values set in a new Business Central general journal entry for each Square bank transfer made on a Square seller account. Source values include:

  • Square account settlement records.

  • Square Bridge configuration settings.

  • Square account reference IDs.

Square
Business Central
Square Bridge Integration Settings: Square currency.Currency Code
Square account: Settlement entry credit amount.
Negation depends on whether it is a debit or credit entry.
Credit Amount
Square account: Settlement entry debit amount.
Negation depends on whether it is a debit or credit entry.
Debit Amount
Square Bridge setting:
"GENERAL"
Journal Template Name
Fixed value:
"G/L Account"
Account Type
Square Bridge setting:
Bank transfer adjustment type mappings and a payment source_type.
Account No.
Not setDocument Type
Square account: Settlement date.Posting Date
Square Bridge setting:
General Journal Batch Name, usually "DEFAULT"
Journal Batch Name
Fixed value:
"SQUARE"
External Document No
Square Bridge setting:
Derived from the current location Square Bridge mapping.
Sq Location (custom field)
memoSq Memo (custom field)
N/ASq Reference Id (custom field, used as a unique identifier)

Dynamics, Business Central. Default-batch entry page

The following Square settlement detail types are mapped to Business Central 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.

  • The sync is not 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 Business Central, the customer list is in Customers on the main company page (page=22).

SquareBusiness Central
Customer directoryCustomers
First NameSq Given Name (custom field)
Last NameSq Family Name (custom field)
Phone NumberPhone No.
Email AddressE-Mail
AddressCountry/Region Code
AddressAddress
AddressAddress 2
AddressCity
AddressState
AddressPost Code
CompanyName
Internal value, not visible in the Seller DashboardNo.
Internal value, not visible in the Seller DashboardSq Reference Id (custom field, used as a unique identifier)

Note

The Address field names in Business Central are localized to the seller region. For example, a US-based seller sees ZIP Code in the customer address section of the Customer Card. In the UK, the seller sees Post Code.

The following Business Central screen shows a list of customers synchronized from Square along with the current synchronized balances, sales, and payments for each customer:

Dynamics, Business Central. Customer search result with balances

Catalog synchronization has the following characteristics:

  • The synchronization direction is from Business Central to Square. Catalog records are only synchronized from Business Central to Square. Changes made in the Square account catalog cannot be synchronized back to Business Central.

  • The sync is not location-specific. Synchronization requires that you fully configure the Square Bridge Location Settings.

The Square Bridge Location Settings include assigning the Business Central sales code for a customer price group to a Square location in the Price List ID field. This Price List ID field is used by Square Bridge to sync the items from Business Central with that ID. Synced items must also have a Unit Price value greater than or equal to 0.

For example, you create a sales code in Business Central of "SQUARE". You apply that code to all items that you want to show in the Square Point of Sale application. By default, the Unit Price for each sales code is zero. You can exclude any of these items from syncing by setting its unit price to a negative value. When you run the catalog sync in Square Bridge, it only syncs items with the Price List ID of "SQUARE" and a non-negative unit price.

Note

Square Bridge syncs any items whose sales code matches the location-specific Price List ID you set in Square Bridge. This means you can sync with any existing sales code, including codes used for other customer groups.

Square strongly recommends that you create a Business Central customer price group with a unique sales code to be used only for Square syncing. This allows you to control item synchronization without affecting other Business Central item pricing. If you have multiple Square locations, you might choose to create multiple price levels. This lets each Square location have a unique item inventory.

The following shows the Business Central table for Item card: Prices & Discounts, Sales Prices and details the customer price groups assigned to a catalog item. In this example, the two variations of the item are both assigned to a customer price group with the sales code "SQUARE".

Dynamics Business Central, custom price group for Square

Optional: Catalog categories in Square are used to categorize groups of related items.

The Square items list is in the Seller Dashboard, in the Items application under Categories.

The following table maps Seller Dashboard items to corresponding pages in Business Central and Square catalog API objects to Business Central catalog items:

SquareBusiness Central
Catalog CategoryItem Categories
category_data.nameDescription
idCode

Dynamics Business Central. Item categories list

A catalog item represents a product for sale or service for hire. If appointments are enabled, they are visible in Square by choosing Items and then choosing Service Library.

The Square item list is in the Seller Dashboard, in the Items application. Choose Item Library to see the items list. In Business Central, the customer list is in Customers on the main company page (page=22).

The following table maps Seller Dashboard items to corresponding pages in Business Central and Square Catalog API objects to Business Central catalog items.

The data source for a synchronization can be a Business Central record, a Square Bridge configuration setting, or a literal string supplied by Square Bridge sync logic.

SquareData source
Catalog item libraryBusiness Central: Items
LocationsSquare Bridge: The locations listed depend on whether the item has a price ≥ 0 in a customer price group with the Price List ID set on all locations in Square Bridge.
LocationsSquare Bridge: false
Item nameBusiness Central: Description
DescriptionBusiness Central: Sq Description (custom field)
TaxesSquare Bridge: The tax IDs are determined based on the tax area code chosen in the Square Bridge Location Settings and the item tax group.
CategoryBusiness Central: Item Category Code
VariationsBusiness Central: See Catalog Item Variation

Dynamics, Business Central. Items list

A catalog item variation models varieties of a product or service so that each variation is treated as a single product or service. Item variations are catalog items differentiated by certain attributes. For example, a generic shirt is a catalog item. However, a red shirt is a catalog item with a specified variation (the color attribute of red). A red shirt is a catalog item variation that is related to the shirt 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.

The Square item variation maps to a Business Central item variant code (through the Sales Prices card for an item). New variations can be created by visiting the Business Central item card, choosing Prices & Discounts, and then choosing Sales Prices. If you create a new variant code in Sales Prices, you need to have a corresponding stockkeeping unit to sync inventory levels.

Important

  • The Starting Date and Ending Date columns for Sales Prices require Full catalog syncs on or after the dates specified to take effect.

  • You can run a Full sync on the Catalog Sync Data page.

SquareData source
Catalog item libraryBC: Variant Code
Choose an item variation, choose Manage stock, and see the locations where the variation is available.Square Bridge: Locations listed for items with a customer price group unit_price ≥ 0 and a Sales Code that matches the Price List ID for a location in the Square Bridge Location Settings.
N/ABC: Item No.
Variation nameBusiness Central: Variant Code. An empty Variant Code is a "default item" and is synchronized to Square with the name Regular.
TrackingBusiness Central: If the item is of the Inventory type, this property is true. Otherwise, it is false.
UnitBusiness Central: Unit of Measure Code
SKUBusiness Central: Item No. + Variant Code. For example, 1896-S_RED.
GTINBusiness Central: Parent item gtin
N/ASquare Bridge: FIXED_PRICING
N/ASquare Bridge: Location overrides are determined by the variant customer price group, the location mapped to that group, and the unit price.
PriceItems : Unit Price
The currency for the location that stocks this variant.Items : Currency Code
idItems : Base64-encoded ID of item_no and Variant_code. For example, {"Item_No":"1896-S","Variant_Code":"RED"}.

Sales tax synchronization has the following characteristics:

  • The synchronization direction is from Business Central to Square.

  • The sync is location-specific. Synchronization requires that you fully configure the Square Bridge Location Settings.

The Square sales taxes list is in the Seller Dashboard, under Account & Settings. Choose Business, and then choose Sales Taxes to see the list. In Business Central, taxes are managed in Tax Areas, Tax Jurisdictions, and Tax Groups.

The data source for a synchronization can be a Business Central record, a Square Bridge configuration setting, or a literal string supplied by Square Bridge sync logic.

SquareData source
Catalog item library, Edit variationSquare Bridge: false
Catalog item library, Edit variationSquare Bridge: Depends on the Tax Area Code chosen in the Square Bridge Location Settings.
Sales TaxesBusiness Central: Tax Type + Tax Area (For example: Sales and Use Tax - ATLANTA, GA)
N/ASquare Bridge: TAX_SUBTOTAL_PHASE
Tax calculationSquare Bridge: ADDITIVE
Custom amountsSquare Bridge: false
Tax rateBusiness Central: Tax Below Maximum (depends on other factors)

Dynamics, Business Central. Tax details list

  • The synchronization direction is from Business Central to Square.

  • The sync is location-specific. You must completely configure the Square Bridge Location Settings for the synchronization to work.

Important

The synchronization overrides the Square item inventory level with the Business Central item inventory level.

Square Bridge synchronization pushes Business Central inventory levels (quantity on hand) into the Square account.

In Business Central, the inventory levels are sourced from Stockkeeping Units, which should be created for each item, variation, and location code combination.

Note

To create new Stockkeeping units in Business Central, search for "Create Stockkeeping Unit" and enter the information. If you want to use variants, you should create options per Location & Variant. You can create units for all items by leaving the filters blank or for specific items by searching for the item in the item filter.

The inventory changes synchronization pushes inventory adjustments made in Square into Business Central. Adjustments include Stock received, Damage, Theft, Loss, Restock return, and Transfers.

  • The synchronization direction is from Square to Business Central. Inventory changes are synchronized from Square to Business Central.

  • The sync is location-specific. Synchronization requires that you completely configure the Square Bridge Location Settings.

  • Inventory change synchronization requires that you enter the Item Journal Batch Name and the Transfer Journal Batch Name in the Square Bridge Integration Settings.

Note

  • Square Bridge does not support synchronizing physical count adjustments (Inventory recount) made in Square.

In Business Central, the Item Journal is used to create goods receipts and goods issues and the Item Reclassification Journal (or Transfer Journal) is used to create item transfers between two locations.

Square Bridge requires that each catalog item in Business Central have a corresponding stockkeeping card for each Square location. Inventory levels are kept in the Item Journal entries associated with an item Stockkeeping card.

In Square, inventory adjustments are made in the Seller Dashboard, in the Items application under Edit variation, on the Manage stock tab.

Data sourceBusiness Central
Square Bridge: Negative AdjmtEntry Type
Square Bridge: SQUAREExternal Document No.
Square Bridge: Integration Settings Item Journal Batch Name.Journal Batch Name
Square Bridge: ITEMJournal Template Name
Square: Not visible in the Seller Dashboard.Sq Reference Id (custom field, used as a unique identifier)
Square Bridge: Current location's Square Bridge mapping.Location Id
Square Bridge: Derived from the base64 encoded ID of the item.Item No.
Square Bridge: Derived from the base64 encoded ID of the item variation.Variant Code
Square: Manage stock, Add stock/Remove stock fieldsQuantity
Square: Stock History, DatePosting Date
Square Bridge: The state of the item inventory before an adjustment.Sq From State (custom field)
Square Bridge: The state of the item inventory after an adjustment.Sq To State (custom field)
Square Bridge: Derived from Integration Settings measurement mappings and the unit of measure of the item.Unit of Measure Code

SquareBusiness Central
InventoryAdjustmentItem Journal
page=40
Positive Adjmt.Entry Type
SQUAREExternal Document No.
Based on the Square Bridge Integration Settings Item Journal Batch Name.Journal Batch Name
ITEMJournal Template Name
N/ASq Reference Id (custom field, used as a unique identifier)
The location ID is derived from the current location’s Square Bridge mapping.Location Id
Item number derived from the base64 encoded item ID.Item No.
Variant code derived from the base64 encoded item ID.Variant Code
quantityQuantity
Posting Date
from_stateSq From State (custom field)
to_stateSq To State (custom field)
The unit of measure code is derived from the Square Bridge Integration Settings measurement mappings and the unit of measure of the item.Unit of Measure Code

Dynamics Business Central. Item journal entry

SquareBusiness Central
InventoryAdjustmentItem Reclassification Journal
page=40
SQUAREExternal Document No.
Based on the Square Bridge Integration Settings Transfer Journal Batch Name.Journal Batch Name
TRANSERJournal Template Name
N/ASq Reference Id (custom field, used as a unique identifier)
The location id is derived from the current location’s Square Bridge mapping and the from_location_id.Location Id
The location ID is derived from the current location's Square Bridge mapping and the to_location_id.New Location Id
Item number derived from the base64 encoded item ID.Item No.
Variant code derived from the base64 encoded item ID.Variant Code
quantityQuantity
Posting Date
The unit of measure code is derived from the Square Bridge Integration Settings measurement mappings and the unit of measure of the item.Unit of Measure Code

Dynamics Business Central. Item reclassification journal entry

We've made improvements to our docs.
Prefer the old format?