Square migration problems rarely come from missing record counts alone. They usually appear when a source Store is translated into Square without preserving the relationships among the item library, Point of Sale operations, locations, inventory, Customers, Orders, and Square Online. A Product can be present yet awkward to sell, an Order can be readable yet disconnected from its refund or fulfillment context, and a Customer can exist while the identifiers used by staff or integrations are lost.
The strongest prevention strategy is to treat each important source behavior as a Square operating relationship. Every pitfall below focuses on a recurring failure pattern, the signals that expose it early, and a concrete condition that proves the issue has been controlled.
Pitfall 1: Treating Square as a Generic Storefront Destination
What goes wrong
The migration is planned as a conventional website transfer: Products, Customers, and Orders move, so the project appears complete. Square, however, connects the item library with Point of Sale, locations, inventory, Orders, payments, Customer Directory, and optional online selling. When those relationships are not defined, staff receive records that exist but do not support the intended selling workflow.
A web-first merchant may discover that the migrated catalog is difficult to use at the counter. A POS-led merchant may discover that online visibility, fulfillment, and URLs were never assigned an owner. The failure begins with an unclear target role, not with an individual field.
Early warning signs
| Warning sign | Likely consequence |
|---|---|
| The project describes Square only as the new website. | POS, location, and payment-operating relationships remain undefined. |
| Product counts are the main catalog acceptance measure. | Items may exist without usable variations, modifiers, or channel visibility. |
| Square Online is discussed only after catalog migration. | Pages, routes, categories, and online availability become late rework. |
| Staff workflows are absent from examples. | Data may be technically present but operationally unusable. |
Prevention
Define Square’s target role before mapping records. State whether the Store will use Point of Sale, Square Online, multiple locations, pickup or delivery, services, retail inventory, or a combination. Then connect each migrated record type to the Square area that must consume it.
Use a simple ownership map: migrated data establishes historical or catalog records; Square configuration controls live selling behavior; integrations own synchronized or external data. This prevents one layer from being mistaken for another.
Recommendation example
For a retailer moving from a web-first Platform, select one representative Product family and trace it through the item library, a POS sale, online visibility, location inventory, and the resulting Order record. This exposes target-role gaps that a storefront-only review would miss.
Pass condition
The target operating model names the Square products and locations that will use each migrated data area, and representative records support the intended staff and buyer workflows without relying on undocumented assumptions.
Pitfall 2: Flattening Items, Variations, Options, and Modifiers
What goes wrong
A source Product structure is converted into a flat list of Square items. Variant choices, option values, sale-time modifiers, SKUs, prices, images, and stock behavior are mixed together or represented in the wrong layer. The result may multiply items unnecessarily, remove required choices, or turn inventory-bearing variants into non-stocked text selections.
Square distinguishes the parent item from item variations and can also use item options and modifier lists. These structures solve different problems. Variations represent sellable forms of an item; options standardize attributes used to generate or identify variations; modifiers represent sale-time selections applied to an item. A source choice cannot be mapped safely until its commercial function is understood.
Early warning signs
| Source behavior | Warning sign in Square |
|---|---|
| Size or color controls SKU and stock. | It is represented only as a modifier. |
| A meal choice adds an optional topping. | It is expanded into separate inventory variations. |
| Variant-specific images or prices matter. | Every selection inherits the same parent values. |
| Required selections exist in the source Store. | Square allows the item to be sold without the intended choice. |
Prevention
Classify every source option by function: identity, inventory, price, fulfillment, display, or sale-time customization. Map identity- and inventory-bearing choices to item variations or item options. Map optional sale-time additions to modifier lists only when modifier behavior matches the business rule.
Preserve SKUs and external identifiers at the level where downstream systems expect them. Also decide whether variation names should be generated from standardized option values or retained as explicit names.
Recommendation example
For a configurable apparel Product, compare a source combination such as medium, black, and embroidered with its Square representation. Size and color may belong to the variation, while embroidery may belong to a modifier if it is selected at sale time and does not carry separate stock.
Pass condition
Representative Product families remain easy to find and sell, and each choice preserves its intended SKU, price, image, inventory, required-selection, and Order-line meaning.
Pitfall 3: Collapsing Location-Specific Inventory Into One Quantity
What goes wrong
The source Store exposes a single stock total or several warehouse quantities, but migration reduces them to one Square quantity without defining location ownership. Products then appear available at the wrong store, online availability does not match pickup expectations, or staff cannot reconcile migrated opening stock with subsequent adjustments.
Square inventory is tracked for item variations at locations and can represent different inventory states. A quantity without its location and state is incomplete operational data.
Early warning signs
| Warning sign | Risk |
|---|---|
| The source export contains one total but the merchant operates several locations. | Stock is assigned arbitrarily or duplicated. |
| Pickup and in-store sales share inventory but location rules are undocumented. | Buyers see availability that staff cannot fulfill. |
| Bundles or ingredients are treated as ordinary variation stock. | The displayed quantity does not represent component availability. |
| Opening inventory is loaded without an ownership timestamp. | Later adjustments cannot be reconciled to the migrated balance. |
Prevention
Define the inventory grain before migration: Product variation, location, and required state. Decide which system owns the opening balance and which system becomes authoritative after cutover. When the source does not provide location-level quantities, document the allocation method instead of silently copying the same total to every location.
Separate inventory that Square can track directly from bundle, component, or integration-managed availability that requires another owner.
Recommendation example
A merchant with two retail stores and Square Online should select several stock-sensitive SKUs and document the expected opening count at each location, online availability, and pickup behavior. The comparison should include an out-of-stock variation and a Product available at only one location.
Pass condition
Each reviewed variation has an explainable location-level opening balance, the authoritative inventory owner is known, and online or pickup availability agrees with the approved location rules.
Pitfall 4: Preserving Catalog Records Without Preserving Channel Visibility
What goes wrong
Items, Categories, images, taxes, and discounts are present in the Square catalog, but they are not exposed in the intended channel. Products may be sellable in Point of Sale but absent online, visible online at the wrong location, or grouped into Categories that no longer support customer discovery.
The catalog is shared infrastructure, not proof that every item is published or correctly organized in every selling surface. Channel visibility, item type, image assignment, category membership, and online presentation still require an explicit relationship.
Early warning signs
| Catalog result | Hidden failure |
|---|---|
| The item appears in the Dashboard. | It may still be unavailable in Square Online or at the intended location. |
| Categories migrated by name. | Product membership and buyer navigation may not match. |
| Images exist in the catalog. | The primary or variation-level image may be wrong online. |
| Discounts and taxes exist as objects. | Their applicability may not match the source commercial rule. |
Prevention
Create a channel-visibility matrix for representative Products. Record where each Product should be sellable, whether it needs online images and content, which Category paths matter, and which location or fulfillment rules affect publication.
Treat Category migration as a discovery decision rather than a label transfer. Consolidate obsolete paths, preserve commercially important groupings, and identify online navigation that must be configured outside record migration.
Recommendation example
For a seasonal Product family, compare the item library, Point of Sale availability, Square Online Product page, Category membership, image order, and pickup location. The Product should not pass merely because its catalog object exists.
Pass condition
Representative Products are available only in the intended channels and locations, with correct Category membership, images, publication state, and commercial applicability for each buyer path.
Pitfall 5: Migrating Customers Without Their Group or Custom Context
What goes wrong
Customer profiles migrate as names, email addresses, phone numbers, and addresses, but the business meaning carried by groups, custom attributes, CRM identifiers, consent fields, or staff notes is omitted. Staff can find a Customer but cannot identify the relationship, segmentation, or external-system link that made the record useful.
Square can manage Customer profiles, group membership, and custom attributes, but these are separate relationships. A custom attribute is not automatically part of a basic Customer record, and a source segment may not have a meaningful Square destination.
Early warning signs
| Customer signal | Risk if ignored |
|---|---|
| Groups drive promotions or staff handling. | Customers become indistinguishable after migration. |
| External CRM IDs are stored in custom fields. | Synchronization creates duplicates or loses linkage. |
| Consent and communication preferences are mixed with profile data. | Marketing treatment becomes unreliable. |
| Duplicate profiles exist across POS and online channels. | Purchase history and identity remain fragmented. |
Prevention
Classify Customer data into identity, contact, group membership, custom attributes, consent, and external identifiers. Define which values belong in Customer Directory, which belong in Customer groups, which need custom attribute definitions, and which remain owned by another system.
Establish a duplicate-handling rule before import. Use stable identifiers where available and avoid merging Customers solely because names or email addresses look similar.
Recommendation example
Select one regular Customer, one Customer in a targeted group, one profile with an ERP or CRM identifier, and one likely duplicate. Confirm how each profile will be recognized by staff and integrations after migration.
Pass condition
Representative Customers retain the identity, group, custom, and external-system context required for support and synchronization, with no unexplained duplicate or merge outcome.
Pitfall 6: Treating Historical Orders as Live Payment and Fulfillment Configuration
What goes wrong
Historical Orders are imported or preserved for reference, and the team assumes that payment processing, refunds, pickup, delivery, shipment, taxes, or staff workflows are therefore configured. Historical data and live operating configuration are different layers.
Square Orders can contain line items, Customer references, taxes, discounts, returns, refunds, and fulfillment details. A migrated historical record may preserve some of this evidence, but it does not activate a payment method, create a live fulfillment workflow, or recreate every source status.
Early warning signs
| Order review shortcut | Consequence |
|---|---|
| Only Order number, date, and total are checked. | Line-item, discount, refund, and fulfillment context may be unreadable. |
| Source payment labels are treated as active payment setup. | Staff expect checkout behavior that was never configured. |
| Refunds are represented only as negative totals. | Return and payment evidence becomes difficult to explain. |
| Custom statuses are copied without an ownership rule. | Staff cannot tell whether a state is historical, live, or obsolete. |
Prevention
Define the purpose of historical Orders: Customer service, financial reference, fulfillment history, or reconciliation. Preserve the evidence needed for that purpose, including line items, totals, tax and discount context, Customer linkage, refunds or returns, and relevant fulfillment details.
Separately assign ownership for live payments, Order creation, fulfillment, refund operations, and staff permissions.
Recommendation example
Review one completed in-store Order, one online Order with shipment or pickup, one discounted Order, and one refunded or exchanged Order. Confirm that staff can explain the transaction without assuming the historical record controls live Square settings.
Pass condition
Historical Orders are readable for their approved business purpose, and every live payment, fulfillment, and refund workflow has a separate configured owner.
Pitfall 7: Losing Taxes, Discounts, and Sale-Time Pricing Meaning
What goes wrong
Tax and discount records migrate as labels or values while their scope and application logic are lost. A tax may belong to specific Products or locations. A discount may be automatic, line-based, order-based, or conditioned by another rule. If the target receives only the name and amount, the resulting sale can be priced incorrectly.
Square models taxes and discounts as catalog objects and applies pricing adjustments through Orders and catalog relationships. The source rule must therefore be translated into a Square-supported commercial relationship or intentionally rebuilt elsewhere.
Early warning signs
| Commercial rule | Early warning sign |
|---|---|
| Product-specific tax treatment | Every Product inherits the same tax after migration. |
| Automatic discount | The discount exists but never applies at sale time. |
| Customer- or channel-specific pricing | The target model has only a global base price. |
| Modifier price adjustment | The Order line does not explain the added charge. |
Prevention
Inventory the rules that alter sale value and classify each by trigger, scope, calculation, and owner. Preserve the source evidence needed to compare expected totals, but do not assume historical values recreate active logic.
Where a rule cannot be represented directly, define a target configuration, app, or integration owner and document how the final price will be calculated.
Recommendation example
Use a representative basket containing a taxable Product, a discounted Product, and an item with a priced modifier. Compare the expected line and Order-level adjustments with the Square representation.
Pass condition
The approved commercial rules produce explainable prices and totals for representative sales, with no rule represented only as an unused label.
Pitfall 8: Leaving Square Online Routes and Redirects Until the End
What goes wrong
Catalog migration is approved before Square Online pages, Product URLs, Category routes, domains, and redirects are planned. The new site then launches with broken inbound links, irrelevant redirect destinations, or important content paths missing even though Products are available.
Square Online can support URL redirects, but a redirect still needs a meaningful destination. Redirecting every old path to the home page preserves neither buyer intent nor content relevance.
Early warning signs
| Route condition | Prevention priority |
|---|---|
| A high-traffic Product URL changes. | Map it to the equivalent live Product page. |
| An old Category is consolidated. | Choose the closest surviving Category or landing page. |
| The domain changes as well as the Platform. | Confirm which redirects remain technically possible. |
| Images, documents, or unsupported paths are important. | Plan separate handling rather than assuming page redirects cover them. |
Prevention
Build the route inventory while catalog and content decisions are still being made. Classify each important path as preserved, redirected, consolidated, rebuilt, or retired. Prioritize Products, Categories, campaigns, policy pages, and externally linked content.
Verify that destination pages are published and relevant before redirects are activated.
Recommendation example
For a discontinued Category with several ranking Product pages, map each Product to its replacement or successor and map the Category to the closest active collection or buying guide. Do not use one blanket destination for all paths.
Pass condition
Priority source URLs resolve to relevant published Square Online destinations, and no important route depends on an undocumented or technically unsupported redirect assumption.
Pitfall 9: Hiding Integration-Owned Data in Ordinary Fields
What goes wrong
External IDs, app metadata, custom attributes, synchronization timestamps, or operational flags are copied into generic Square fields without defining who reads or maintains them. The values may be visible in an API but unavailable to Point of Sale staff, or they may be overwritten by an integration after cutover.
Square supports custom attributes for Catalog objects and Customers, but visibility differs by object and interface. Storing a value is not enough; the continuing consumer and access path must be known.
Early warning signs
| Data signal | Likely failure |
|---|---|
| A value is migrated because it might be useful later. | No system or person actually consumes it. |
| Staff need the value in Point of Sale. | It is stored only in an API-visible custom attribute. |
| An ERP will resynchronize the field. | The migrated value is overwritten or creates conflict. |
| External IDs are moved to a different record level. | Product, variation, Customer, or Order linkage breaks. |
Prevention
Create an integration-ownership ledger for every non-standard value. Record the source owner, target record, target field or custom attribute, continuing consumer, write authority, and visibility requirement. Exclude obsolete values rather than preserving them without purpose.
Test whether staff, reports, apps, and integrations can access the value through the interface they actually use.
Recommendation example
For a variation-level ERP identifier, confirm that it remains attached to the sellable variation rather than the parent item, and verify that the ERP integration reads that exact location after cutover.
Pass condition
Every retained custom or integration-owned value has a named consumer, stable target location, correct staff or API visibility, and unambiguous write ownership after synchronization begins.
Cross-Pitfall Prevention Map
| Control area | Pitfalls controlled | Required outcome |
|---|---|---|
| Target operating model | 1, 4, 6 | Square products, channels, locations, and live configuration owners are explicit. |
| Catalog relationship map | 2, 3, 4, 7 | Items, variations, modifiers, inventory, Categories, taxes, and discounts retain their functions. |
| Identity and integration ledger | 5, 9 | Customer and external-system context remains usable and governed. |
| Order evidence model | 6, 7 | Historical transactions remain explainable without being mistaken for live setup. |
| Route inventory | 4, 8 | Online discovery and important inbound paths remain intentional. |
Conclusion
Square migration quality depends on preserving operating relationships, not merely importing familiar record types. Item-library design affects selling, location inventory affects availability, Customer context affects service, Order evidence affects support, and Square Online routes affect discovery. When each relationship has a defined target owner and a specific pass condition, the recurring pitfalls become visible and preventable before they disrupt day-to-day operations.
Common Questions
Why is Square different from a conventional storefront migration?
Square can connect the same catalog with Point of Sale, locations, inventory, Customers, Orders, payments, and online selling. A record that appears correctly in one area may still be incomplete in another, so the target operating model must be explicit.
Should source variants always become Square item variations?
Not automatically. A choice that controls SKU, price, image, or inventory usually belongs in variation structure. A sale-time optional addition may fit a modifier. The commercial function should determine the target layer.
Can one inventory total be copied to every Square location?
Only when that duplication reflects the real operating rule. Multi-location merchants normally need an approved allocation or location-level source. Copying one total to every location can overstate available stock.
Do migrated Orders configure Square payments and fulfillment?
No. Historical Orders may preserve transaction evidence, but live payment processing, fulfillment, refunds, and staff workflows require separate Square configuration and ownership.
How should custom fields be handled in Square?
Keep only values with a continuing consumer. Decide whether each belongs in a native field, group, custom attribute, app, or external system, and confirm that the people or integrations that need it can access it.
What proves that Square Online route handling is ready?
Priority source URLs should resolve to relevant published destinations, with Product, Category, campaign, and content paths treated individually rather than redirected indiscriminately.