Square to Shopify: converting an item library export

Square’s item library is closer to Shopify’s shape than most exports — one row per sellable variation — but it is a point-of-sale catalogue, and three things a Shopify storefront needs are simply not in the file.

Where the file comes from

In the Square Dashboard go to Items & Orders → Items → Actions → Export Library. Shopify’s migrating-from-Square guide names the fields it expects to find: Item Name, Default Vendor Name, Category, Option Name 1, Option Value 1, SKU, Weight (kg), Price and Default Unit Cost.

Pitfall 1: products are identified by a repeated name

Square has no handle, no slug and no parent-id column. A multi-variation item appears as several consecutive rows that share the same Item Name, each with its own SKU, Price and option values. That makes Item Name the grouping key.

Two consequences. First, two genuinely different items with identical names merge into one product with a duplicated option combination — Shopify will reject that with options are not unique, and the validator here flags it with row numbers before you upload. Second, the handle is generated by slugifying the name, so “Café Latte” and “Cafe Latte” both become cafe-latte; the second one gets cafe-latte-2 to stay unique and stable within the file.

Pitfall 2: Option Name repeats on every row

Square writes the option name on every variation row. Shopify wants Option1 name on the product’s first row only, with Option1 value on all of them. Copying Square’s layout verbatim puts “Size” on rows two and three as well, which is at best noise and at worst ambiguous when the value differs between rows. The converter reads the option name once per product and leaves it blank on subsequent variant rows, matching the official template exactly.

Square supports more option sets than Shopify’s three. If your export has Option Name 4 populated, that option cannot be represented and you will need to fold it into another option’s value (“Large / Oat / Extra shot”) or split the item.

Pitfall 3: kilograms, and a cost column that is not a price

Weight (kg) must become integer grams: set the source weight unit to kg and 0.35 kg becomes 350. Leaving it on grams imports a 350 g item as “0 g”, which breaks weight-based shipping rates without any import error to warn you.

Default Unit Cost is your cost and maps to Cost per item, never to Price. It is used for Shopify’s margin reporting and is never shown to customers. Mapping it to Price is the mistake that publishes your wholesale cost as the retail price. If some rows have a cost but no price, use the cost × markup formula rather than letting Price fall back to 0.00, which is what Shopify does with a blank price cell.

Pitfall 4: three things Square does not export

• Images. The item library export has no image URL column — Square item photos live in its own CDN behind your account. There is nothing to map, so products import with no images and you add them in the Shopify admin or a second CSV pass once the images are hosted somewhere public.
• Descriptions worth publishing. Square’s description field is written for a register screen and is usually short or empty. Expect to write real product copy.
• Online visibility. Square has no “published to online store” concept matching Shopify’s. Set Published on online store and Status as constants — importing as draft is the safe default while you add images.

Square’s Category is a free-text POS category, not a Shopify taxonomy breadcrumb. The preset maps it to Type, which is free text, and leaves Product category blank rather than inventing a taxonomy path that Shopify would reject.

What the preset maps

Item Name → Title, Default Vendor Name → Vendor, Category → Type, SKU → SKU, GTIN → Variant Barcodes, Price → Price, Default Unit Cost → Cost per item, Weight (kg) → Weight value (grams) with kg conversion, and the two Option Name/Option Value pairs → Option1 and Option2. Grouping falls back to the title, which is correct here because the repeated Item Name is the only product identity Square gives you.

Before you upload to Shopify

• Import into a development store or a draft-status batch first. Set the default status to draft in the tool and nothing goes live by accident.
• Shopify caps a product CSV at 15 MB. Bigger catalogues are split into numbered parts, and a product is never split across two files.
• Overwriting existing products by handle is destructive: a blank cell can erase data that is currently there. Export your live products first if you are updating rather than creating.

Full column contract: the Shopify product CSV format, column by column. Nexum Gate is not affiliated with Shopify Inc.