Square Online Product Image CSV Import Preflight: Validate Hosted Image URLs Before Updating a Catalog

Why Square Online CSV imports break mid-catalog

Square Online stores are powered by Squarespace Commerce, and the product CSV importer lives under Commerce → Products → Import / Export. It accepts a single .csv file with 22 columns covering the full product model: Product Type, Product Page, Product URL, Title, Description, SKU, GTIN, MPN, three Option Name / Option Value pairs, Price, Sale Price, On Sale, Stock, Categories, Tags, weight and dimension, Visible, and the column that decides whether the gallery actually shows up: Hosted Image URLs.

The pattern we keep seeing in failed imports is the same four issues, in roughly this order:

• Local file paths or base64 blocks in the image column. Square Online's importer cannot read from the hard drive. A cell that contains file:///Users/me/tee.jpg or a raw base64 string is silently treated as a failed URL, and the product imports without any image.
• URLs that do not end in an image extension. Squarespace checks the path. A cdn.example.com/img/tee-front.jpg?v=2 URL sometimes fails the extension test because of the query string. Plain HTML product pages never work.
• Wrong separator between multiple image URLs. The official help article says "separate multiple with spaces or line breaks." Sellers frequently paste URLs with commas or semicolons and lose every image after the first.
• Product Page slug does not exist on the receiving site. v7.1 requires the slug to point to an existing store page. A typo here makes the entire row fail to import, even when the URL is perfect.

Required columns and v7.1 vs v7.0 differences

The Squarespace product CSV ships with a fixed column order. Most "the import half-worked" stories come from sellers editing the wrong columns. The reference table below covers the columns that drive an image-only update, with the v7.1 vs v7.0 difference called out where Squarespace treats them differently.

The Hosted Image URLs column and what it accepts

Square Online has a single column for images: Hosted Image URLs. Every other platform we cover — Shopify, Ecwid, Wix, TikTok Shop — has its own quirks, but the Squarespace rule is the strictest of the four. The CSV importer runs a strict extension check on the URL and silently drops anything that fails it. Three categories fail that check on most imports:

• HTML product pages. A URL like https://example.com/products/tee returns a 200 to a browser, but Squarespace's worker looks at the path, sees no image extension, and skips it. The product imports with no image.
• Query strings on otherwise-valid URLs. A URL like https://cdn.example.com/img/tee-front.jpg?v=2 works in a browser, but some Squarespace builds reject the path because the extension is followed by characters Squarespace does not parse. Host the clean URL when possible.
• Local file paths and base64 blocks. file:///Users/me/Desktop/tee.jpg and raw base64 strings are not URLs. Squarespace cannot fetch them. The image column stays empty after import.

Two more cases that look like failures but are actually fine: a URL on a CDN that returns 200 to a fetch but is hot-link protected (returns 403 to the Squarespace import worker) shows up as a broken image on the live product page. And a URL that works in the cell but contains a non-ASCII character or an unencoded space will sometimes pass the extension check and then fail the actual fetch. Run a local backup before the import so the URLs that do fail can be re-hosted without losing the file.

Multi-image separator: space or line break

The Squarespace help article is explicit: "separate multiple with spaces or line breaks." Google Sheets uses Alt+Enter to enter a line break inside a cell. Excel on Windows uses Ctrl+Alt+Enter. Excel on Mac uses Control+Option+Return. The line break sits between two URLs in one cell and Squarespace's parser walks through them in order.

Two common mistakes to avoid:

• Comma-separated URLs. A cell with https://a.com/1.jpg, https://a.com/2.jpg reads as one URL with a comma in the middle. The extension check fails and the cell becomes empty.
• Adding image URLs to every variant row. When a product has Option Names, image URLs must only appear on the first product row of that variant set. Squarespace reads the first row's image cell as the gallery for the whole variant group.

v7.1 vs v7.0 and the bulk-edit limitation

The Square Online product CSV is built around three use cases that the help article calls out explicitly: moving products between Squarespace sites, editing products in bulk on the same site, and importing from a different platform. Each use case has a different set of required columns. Image handling differs the most between the first use case and the other two.

For moving products between sites, the Hosted Image URLs column is editable and re-import will pull the URLs in from the CSV. For editing products in bulk on the same site, the Squarespace help article states that Hosted Image URLs is "not editable when bulk-editing." The same restriction applies when importing from an external platform: the image column is honored, but any URL that returns a non-200 response or fails the extension check is silently skipped without re-trying the row.

This is the practical reason a preflight matters: a Hosted Image URL that worked last month on a bulk import may fail the extension check after a CDN switches to a query-string format. The local backup you create before the import is the only copy of the file that exists outside Squarespace.

Version-specific rules that change which column is required:

• v7.0 sites: Categories is required on every active product row. A blank Categories cell fails the import for that row, even when every other field is correct. Product Page is optional when importing new products from another platform, and required when bulk-editing on the same site.
• v7.1 sites: Categories is optional. A product row with a blank Categories cell imports successfully and goes live without a category assignment. Product Page is required on v7.1 in every use case.
• Import caps: v7.1 accepts up to 10,000 products per import; v7.0 caps at 200. Both cap at 250 variants per product. If a v7.0 catalog has more than 200 products, split the CSV into chunks of 200 or fewer before importing.

Eight-step preflight workflow

The workflow assumes you have already exported your catalog from another platform or built the CSV by hand, and that you have the Squarespace product CSV template downloaded as a reference. The preflight itself runs locally: no data leaves your machine.

Eight checks before uploading the CSV

These checks are derived directly from Squarespace's Importing products from a .csv help article and from the failure patterns we have seen in repeated runs. Run them in order and the importer will catch fewer surprises.

1. Product Type is set on every row. Required. Do not edit existing values; leave blank cells blank.
2. Product Page slug matches an existing store page. On v7.1 sites, a non-matching slug fails the entire row. Re-create the store page first, or change the slug.
3. Product URL slug is 3-200 chars with dashes only. Spaces and special characters are rejected. Capital letters auto-lowercase, so what you type is not always what is stored.
4. Categories match the slug from an existing category page. Use /clothing not Clothing. Use /clothing/blouses for nested. Comma-separate multiple categories.
5. Visible = Yes on every active product row. Only set on the first product row when there are options. No hides the product.
6. Hosted Image URLs ends in .jpg, .png, or .gif. No HTML pages, no local files, no base64. Query strings sometimes break the extension check — host a clean URL when possible.
7. Multi-image separator is space or line break. Google Sheets: Alt+Enter. Excel Windows: Ctrl+Alt+Enter. Comma or semicolon will collapse the URLs into a single broken path.
8. Local backup completed. Save the files to disk before importing. After import, Squarespace hosts the images and the URLs in your CSV no longer point at the original source.

Common import problems and how to spot them

Frequently asked questions