Square - 2 Way Interface
Last Updated: 11/09/2026
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 three elements:
Yellow Dog’s Square sync application pulls sales (orders), codes, and menu items (for POS Item Mapping, if needed) from Square and pushes in new/changed items (products), all via the Square API.
Yellow Dog’s Balto application to assign locations in Square to stores in Yellow Dog.
Yellow Dog’s Process Sales application that ensures the sales data from Square has been fully processed, including updating sales reports.
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.
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 376+.
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:
AUTOMATIC MATCHING TO YD SKU: The Yellow Dog Item SKU must be populated to the Square SKU field (note: pre-existing items are not supported for 2-way integration).
| 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 |
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 | Can be configured to use one of the following: POS Description 1 POS Description 2 Description Short Description NOTE: Matrices always use the Matrix Description |
| Price | Item Retail |
| SKU | SKU or UPC* |
| GTIN | UPC* |
| Variation Name | Dimensions |
| Product/Variations | Matrix Items - Product/Variants |
| Stock | Can be configured to push either Store or Total (All Stores)** |
| Image | Images |
| Description | Web Extended Description |
| Currency | Native Currency |
Note: If any of the Item Properties change in Yellow Dog, we will repush all the item properties.
* Yellow Dog’s sync can be configured to push UPC1 to Square for each item, either to the SKU field or the GTIN field in Square; if an item doesn’t have a UPC1 in YD, the item’s SKU will be pushed to the configured field instead.
** When on hands are configured to Total, this will 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; additionally, when we push the Total on hand, we push that total to each Location in Square, which will make Square's total on hand across all stores larger than it should be, because the total from YD will be duplicated.
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-10 |
| 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.
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 |
Actions in Yellow Dog Inventory - Result in Square
| Yellow Dog Inventory Action | Result in Square |
|---|---|
| Item Creation | Created in POS (if item set to POSBlock=0, Publish=Yes, Active, Not Removed, and available to Interfaces/Primary store) |
| Item Edit/Update | Updated in POS (if item set to POSBlock=0, Publish=Yes, Active, Not Removed, and available to Interfaces/Primary store) |
| SKU Edited | Updated in POS (if item set to POSBlock=0, Publish=Yes, Active, Not Removed, and available to Interfaces/Primary store) |
| Inactivated | No Changes will be pushed to the item in Square |
| Removed | No Changes will be pushed to the item in Square |
| Level Is Changed | Only change occurs if item inherits new Category or Tax codes if assigned to level in YD |
| Item is configured to Push to POS (required: Publish=Yes, POS Available, active, not removed, item available to Interface/Primary store) | Item Created/Updated |
| Publish set to "No" | No Changes will be pushed to the item in Square |
| POS Available set to "False" | No Changes will be pushed to the item in Square |
| Unchecked availability to one store/location | The item will be removed from the Location's Availability in Square - UNLESS item is unavailable to the Interfaces/Primary store, in which case no change to the item in the POS |
| No longer available to Any Store/Location | The item will be removed from the Location's Availability in Square - UNLESS item is unavailable to the Interfaces/Primary store, in which case no change to the item in the POS |
| Image 1 added to item in YD | Image pushed to Square as primary image |
| Image 1 removed from item in YD | No Change - we do NOT remove images from Square |
| On Hand changed in Yellow Dog | Stock updated in Square, dependent on On Hand push setting in sync config |
Actions in Square - Result in Yellow Dog Inventory
| Action in Square | Results in Yellow Dog |
|---|---|
| Item Returned | Item returned in YD (on hand returned to inventory) |
| Item Voided | transaction quantity = 0 |
| Previous Check Voided | transaction quantity = 0 |
| Item created in POS, not in YD | Can be used in a one-way sync for pulling sales only, or, if SKU/UPC matches (depending on pushUPCs setting) can be configured to push on hands only and pull sales |
| Item deleted in POS | If still configured to push from YD, will repush to Square next time it is triggered |
| Item properties changed in POS, not in YD | If still configured to push from YD, will overwrite those item properties in Square next time it is triggered |
| Item sold at POS but is Removed in YD | Sale is processed and assigned to the item as normal; Item in YD will be un-removed because on hand changed |
| Item sold at POS but is Inactive in YD | Sale is processed and assigned to the item as normal |
| Menu item sold at POS | Populates in YD POS Item Mapping |
| Menu item created at POS but not sold | Populates in unsold items that can be pulled in to POS Item Map and mapped to YD item |
| Modifier created at POS but not sold | Populates in unsold items that can be pulled in to POS Item Map and mapped to YD item |
| Modifier sold at POS | Populates in YD POS Item Mapping |
| Image attached to item at POS, not in YD | YD will not overwrite unless we pushed it |
| Image deleted at POS, not in YD | Image will not repush to Square unless a change is made to the image in YD (i.e., change the image in YD, or switch image placement in YD and push a different image, then switch back and push again) |
| Sales pulled in from Square via SquareConsole | Transaction data visible in All Sales Captured, and will be matched to YD items when possible; if processItemAdjusts setting is enabled in the sync config, items that matched will also have their on hands adjusted. Note: Matching requires that the item is available to the store it was sold in, and that the item can be matched via the matchOnTypes setting. |
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)
Square “Options” (which are similar to variations in Square) are not supported by Yellow Dog and we are unable to update data for items that have “Options” configured at the POS.
