Square - 2 Way Interface
Last Updated: 12/10/2024
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 now uses our new SquareConsole. This interface contains three elements:
Yellow Dog’s SquareConsole pulls sales (orders), codes, menu items and attributes from Square and pushes in new/changed items (products) via the Square API.
Yellow Dog’s Balto application to assign locations in Square to stores in Yellow Dog.
Yellow Dog’s Process Sales Data application that processes the sales data provided by Square.
Information on our previous Square integration using a Sync application can be found here.
Note: All new clients will use SquareConsole for this integration.
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 Console 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:
For clients with existing data, the best approach in a 2-Way configured integration is for Yellow Dog to push in everything as new. If this cannot be supported, we will only be able to support a 1-Way Sales Pull integration.
Other Notes
Our sync does support multiple RVC codes per store for pushing and pulling data to/from Square.
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 Square 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 374+.
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 | Additional Info |
|---|---|---|
| orderId | TransactionNumber | |
| order.closed_at | CheckClosed | NOTE: Yellow Dog can use order.closed_at, order.created_at, order.updated_at, or tender.created_at as CheckClosed depending on the sync option selected |
| line.catalog_object_id | ItemNumber | |
| item.item_varation_data.sku | SKU | |
| line.name | Item | |
| unitPrice | ItemRetail | |
| unitDiscount | ItemDiscount | |
| quantity | Quantity | |
| mods/returns | Reference | |
| isCancelled | Void | |
| isRefund | Return | |
| orderState | Order Status | NOTE: Yellow Dog can limit the orders pulled in based on their status; for example, pulling in orders with a status of COMPLETED only, or including any combination of OPEN, COMPLETED, and CANCELLED orders |
| order.source.name | SalesChannel | |
| tenderId | Order Number |
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.
Accounting Export Ability
This integration does not support the export of tender or tax data to an accounting system.
Item Data
Yellow Dog’s pushes the following item details:
| Square Field | Yellow Dog Field |
|---|---|
| Location | Store |
| Name | POS Description 1/MatrixDescription |
| Name | POS Description 2/MatrixDescription |
| Name | Description/MatrixDescription |
| Name | ShortDescription/MatrixDescription |
| Price | Item Retail |
| SKU | SKU or UPC |
| GTIN | SKU or UPC |
| Variation Name | Dimensions |
| Product/Variations | Matrix Items - Product/Variants |
| Stock | On Hand - Store |
| Stock | On Hand - Total (All Stores) |
| Image | Images |
| Description | Web Extended Description |
| Currency | Native Currency |
| YD Item Property | Required to Push On Hands (including Push On Hands only) | Required to Push Items | Required to Update Items |
|---|---|---|---|
| Publish = Yes | x | x | x |
| POS Block = 0 | x | x | x |
| Publish = Yes | x | x | x |
| Active | x | x | x |
| Not Removed | x | x | x |
| Available to Primary (Interfaces) Store | x | x | x |
| Square SKU matches YD SKU (or UPC1 if configured for pushing UPC) | x | ||
| Retail1 - $0 Retail is now supported, but the item MUST have $0 explicitly set (cannot just have a blank/not set retail in YD) | x | x |
Note: If any of the Item Properties change in Yellow Dog, we will repush all the item properties.
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 or, optionally, to Square’s GTIN field.
When disabled, the SKU for each item will be pushed to Square, whether items have UPCs or not.
Varation Names
Yellow Dog can be configured to push either
Comibination of Dimension 1 + 2
Dimensions 1-6 (as configured in Yellow Dog)
as the variation name in Square.
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 |
| Point of Sale Behavior: Automatically Add Item to Check | Square Skip Detail Screen |
| Price Type | Square Price Type |
| Unit | Square Measurement_unit |
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 |
Additional Information
Limitations
We no longer support attributes in this integration (8/23/2023)
We only push a single image to the parent item in Square (8/23/2023)
This integration does not support the ability to match pre-existing items for an item push (8/23/2023)
Yellow Dog does not integrate with Weebly (8/23/2023)
If an image is overwritten or removed in Square we will not automatically update it from YD, even if the item has been retriggered (8/23/2023)
If an image for an item was pushed from Yellow Dog to Square, then deleted and not replaced in Yellow Dog, we will not delete the image in Square (8/23/2023)
The image must be removed manually in Square
This integration does not support revenue (tax/tender) data for accounting exports/API (8/23/2023)
Modifiers do not have SKUs in Square (8/23/2023)
