Square - 2 Way Interface
Last Updated 8/23/2023
As of 8/23/2023, all new clients will use our new SquareConsole for this integration. More information can be found here.
Overview
Our Square Interface supports a 2-Way integration in which Yellow Dog Inventory can both pulls sales data from a Square Account as well as push in new or changed items. Yellow Dog is now available through the Square App Marketplace.
Sync Approach
This interface contains one element:
A Micros Sync application which pulls sales (orders), codes, menu items and attributes from Square and pushes in new/changed items (products) via the Square API.
Sync Frequency
By default the sync is scheduled to run hourly. Additional scheduling options are available upon request.
Configuration
The Yellow Dog inventory system can be setup with multiple stores that can connect to a single or multiple instances of Square. The reverse (multiple Yellow Dog Inventory systems to one instance of Square) is not possible.
Existing clients who want to add an additional Square account or instance will need to be upgraded to our the Lambda version of our integration.
Configuration Options
This integration supports multiple item configurations. Please consult with your Yellow Dog Implementation Guide to determine the appropriate option for your business need.
Options:
Pull Sales Only
Push On Hand QTY per store + Pull Sales
Push On Hand QTY total for all stores + Pull Sales
Push Item Creation + Item Updates + Pull Sales
Push Item Creation + Item Updates + On Hand QTY per location + Pull Sales
Push Item Creation + Item Updates + On Hand QTY total for all locations + Pull Sales
Note:
Prior to the start of your implementation, let the Yellow Dog team know if items already exist in Square, as this will impact and potentially change our implementation approach..
Requirements
Client
The Yellow Dog Sync program will need internet access to exchange information with the Square API. If the Yellow Dog database is not hosted by Yellow Dog Software, there may be additional firewall rules or port configurations necessary to facilitate communication.
The client will need to download the Yellow Dog app from the Square Marketplace and create a Square user for Yellow Dog for each Instance of Square.
Yellow Dog
Yellow Dog will use the login information provided to access Yellow Dog’s Third Party Proxy application and associate the Square Business Account.
Yellow Dog also requires:
This interface requires a Yellow Dog version 364 or higher.
A list of Square Location names to match to our Store Revenue Center Codes.
We recommend that Yellow Dog is hosted by us, otherwise additional steps will be required to set up Non-Hosted API access.
Data Exchange
Sales Data
We pull in the following sales data:
| Square Field | Yellow Dog Field |
|---|---|
| Id | TransactionNumber |
| closed_at | CheckClosed |
| catalog_object_id | ItemNumber |
| item_varation_data sku | SKU |
| lin_items name + item_variation_name | Item |
| base_price money | ItemRetail |
| discount_moneyamount | ItemDiscount |
| quantity | Quantity |
| paymentNames | Tender |
Each time the sync runs we look at the transactions for the past 7 days to ensure all sales are accounted for. This can be configured based on integration needs.
Item Data
Yellow Dog’s pushes the following item details:
| Square Field | Yellow Dog Field | Created First In Square |
|---|---|---|
| Tax Group | Square Tax 1, 2, and 3 (Interface Setting) | X |
| Skip Detail Screen | Square Skip Detail Screen Interface Setting | |
| Square Available Online (True/False) | Square Availabile Online Interface Setting | |
| Available for Pickup (True/False) | Square Available for Pickup Interface Setting | |
| Category | Square Category Interface Setting | X |
| Price Type (Fixed/Variable) | Square Price Type Interface Setting | |
| Hi-Res Image 15 MB | Picture 1 | |
| Attributes | Attributes | |
| Name | POS Description 1, else Item Description | |
| Description | Web Extended Description | |
| SKU | SKU | |
| Variation Name | Dimensions, per matrix item | |
| Variation SKU | SKU | |
| Price | Retail 1 | |
| Price Override | Per Store Retail 1 (Location specific pricing) | |
| Location | Store Availability | X |
| Stock | On Hands | |
| Square Measurement_Unit | Square Measurement_Unit Interface Setting | X |
Note: If any of the item Properties change in Yellow Dog, we will repush all the item properties.
You can use the Match Items button to match existing products in Square with items in YDI on SKU.
Note: This will only work when the SKUs match on simple items in both systems.
There is an optional ability to push On Hands to Square from Yellow Dog Inventory.
Select (not set) to not push on hands and turn off the Tracking in Square.
Select Total to push a total of the item's on hand across all stores in the YD database, regardless of whether those stores are configured to push to Square. Note: When we push the Total on hand, we push that total to each Location in Square; this will make Square's total on hand across all stores larger than it should be, because the total from YD will be duplicated.
Select Store to push the item's on hand per store.
Yellow Dog can optionally push UPC's to Square.
When enabled, this option will push UPC1 for each item; if items do not have a UPC, SKU will be pushed instead. This value will push to Square's SKU field.
When disabled, the SKU for each item will be pushed to Square, whether items have UPCs or not.
Item Attributes
Yellow Dog can manage additional Item Attributes that are dynamic to each installation. Attributes can be numeric, text, string, or boolean. An example of these fields are listed below (available April 2020):
| Attribute Field | Yellow Dog Field |
|---|---|
| Secondary Category | Secondary Category |
| Dietary Info | Dietary Info |
| Calories | Calories |
| Allergens | Allergens |
| Ingredients | Ingredients |
| Mobile Description | Mobile Description |
| Menu Board Description | Menu Board Descripiton |
| Allow Alcohol Sale | Allow Alcohol Sale Interface |
Modifiers
Modifier sales are now pulled in as individual TPTransaction lines
Modifiers, once sold, will populate into POS Item Map
For size modifiers, there is a configuration option to Concatenate Modifier Groups for use when the main recipe is the modifier. This will amend the menu item that needs to be deducted to the size modifier selected. This can be limited to the modifier groups of your choosing.
System Codes
Yellow Dog pulls the following system codes from Square to be assigned to items in Yellow Dog.
| Square Field | Yellow Dog Field |
|---|---|
| Category | Square Category |
| Tax Groups | Square Tax 1, 2, 3 |
| Attributes | Not currently in UI |
| Measurement Unit | Defaults to Per Item if not set in YD |
Note: Interfaces set in Yellow Dog are pushed to all locations in the same instance of Square from the interfaces store as designated in the sync’s configure tab. This controls the following:
Category
Tax
Available Online
Available for Pickup
Skip Detail Screen
Price Type
Publish
Measurement Unit
Reviewing Item Details
To identify how Yellow Dog Items have last been updated to the POS, users can access the POS (as of Last Synced) View
Workflows - Where Performed
| Workflow | Yellow Dog Inventory | Square POS |
|---|---|---|
| Create Retail POS Items | Done Only in Yellow Dog | |
| Create Stadium Stand POS Items | Done Only in Yellow Dog | |
| Create Restaurant POS Items | Could be Done in Yellow Dog | Typically Done in Square |
| Modifer Creation | Done Only in Square | |
| Modifer Assignment to Items | Done Only in Square | |
| Screen Placement for Items | Done Only in Square | |
| Discount Setup | Done Only in Square | |
| Discount Assignment | YDI can auto-assign Square Catergories which may control some discounting | Item specific discounting done in Square |
| Tax Setup | Done Only in Square | |
| Tax Assignment | YDI can assign up to 3 Tax Codes automatically via levels | |
| Category Setup | Done Only in Square | |
| Category Assignment | Yellow Dog can assign Categories to the Item or Level (All Items in a Level will Inherit) | |
| Price Type Setup | Done Only in Square | |
| Price Type Assignment | Done Only in Yellow Dog | |
| Attribute Creation | Done Only in Square | |
| Attribute Assignment | Done Only in Yellow Dog |
Actions in Yellow Dog Inventory - Result in Square
| Yellow Dog Inventory Action | Square Result |
|---|---|
| Item Edited In Anyway and Saved | All the item properties are re-applied to Square. |
| Item Changed to Not Available to Store in YDI | The item will be removed from the corresponding location |
| Item Inactivated | No Change - The item in Square is untouched |
| Item Removed | No Change - The item in Square is untouched |
| Level Is Changed | Change occurs if item inherits new Category or Tax codes from level in YD |
| Item has POSDescription 1, Publish set to "Yes" and POS Available set to "True" | Item Created |
| Publish set to "No" | Item in Square is untouched and no changes made to the item in YD will affect the item in Square |
| POS available set to "False" | The item in Square is untouched and no changes made to the item in YD will affect the item in square |
| Uncheck Availability to One Store; Item still available to other Stores | The item will be removed from the Location's Availabilty in Square |
| Uncheck Availbility for All Stores | The item in Square is untoched and no changes made to the item in YD will affect the item in Square |
| Image added to Item in YD | Image Added to Square during next sync |
| Image removed to Item in YD | Remove in Square during next sync |
| On Hand changed in Yellow Dog | All the item properties are re-applied to Square |
Actions in Square - Result in Yellow Dog Inventory
| Square Action | Yellow Dog Inventory Result | Using Square V2 |
|---|---|---|
| Item Returned | No Change, not available in Square V1 to be itemized in Yellow Dog | Item will be returned and restocked automatically if not a FB Menu Item |
| Item Voided | No Change | No Change |
| Previous Check Voided | No Change | No Change |
| User Created Item in Square, not in YD | If Variation SKU matches Yellow Dog SKU those will be mapped however Yellow Dog will not manage the item unless "Match Items" is turned on in the sync, otherwise we will see the sale but it will be unmapped to any inventory item | Same Behavior |
| Change Item Detail in Square, not in YD | Overwrite items in Square the next time YD makes a change to the item in our system | Same Behavior |
| Item is sold in Square that is removed in YD | Sales is processed and assigned to the item as normal; item in Yd may be un-removed because on hand has changed. Inventory will be depleted. | Same Behavior |
| Item sold in Square that is Inactive in YD | Sales is processed and assigned to the item as normal. Inventory will be depleted. | Same Behavior |
| Menu Item Sold at POS | Populates in YD POS Item Mapping | Same Behavior |
| Menu Item Created at POS | Does not populate in Yellow Dog until Sold | Same Behavior |
| Modifier Sold at POS | Populates in YD POS Item Mapping | Same Behavior |
| Modifier Created at POS | Does not populate in Yellow Dog until Sold | Same Behavior |
| Image added to Item in Square Only | Image will be removed the next time an item update is pushed from Yellow Dog | Same Behavior |
Accounting Integration
The table below indicates if we are able to retrieve certain information from this POS system and present it to an accounting system.
This requires a configuration to be enabled.
| Accounting Data | Yelow Dog Field |
|---|---|
| Tax Name | Tax Description |
| Tax amount | Tax |
| TenderName | Tender |
| Tender Amount | Tender Amount |
Additional Information
Limitations
Square’s API does not provide register (device) or employee name and number.
Square’s API does not provide modifier quantities so we use the quantity of the parent item for modifier sold.
$0 Retail items are not supported
Yellow Dog does not support the use of Options to create/update Matrix Items. If using Options, it is best to map.
Open Modifiers that a user types in a descriptions and are not connected to Menu Items are not supported.
Yellow Dog does not integrate with Weebly
Items are limited to a single SKU per variant in Square.
Items are limited to 1 picture per main/parent item in Square.
Returns are currently unsupported until the implementation of using Square V2 API.
In Square, Products share the same settings across all Locations in an instance. A store will need to be defined as the interface locations which includes all Products for an instance.
Only Tax Groups 1, 2, and 3 are supported.
Square only allows up to 5 characters for their Abbreviation (POS Description 1 in Yellow Dog)
UPC Changes or Additons on Parent/Child or Matrix items after being created need to be done in Square only.
We are only able to match existing Products in Square to Items in Yellow Dog (based on SKU) if:
They don’t have more than one Variation in Square
If the Yellow Dog Item is not part of a Matrix or Parent/Child relationship.
NOTE: Products in Square with multiple Variations must be removed from Square before they can be pushed in from Yellow Dog so as not to create duplicates.
We are unable to support pushing detail to Square’s GTIN field via the api (4/24/2023)
Modifiers do not have SKUs in Square (7/7/2023)
Other Notes
Our sync does support multiple RVC codes per store for pushing and pulling data to/from Square.
