Squarespace to Payload CMS: Mapping WXR Onto Collections and Lexical

The short version

Squarespace does not hand you a spreadsheet. It hands you a WordPress-oriented XML file, the WXR format, and Payload does not read XML. So the migration is a script you write once, and the order of operations inside that script decides whether it works.

The order that matters most is this: parse the HTML, download the images, create the Payload media documents, rewrite the HTML so each <img> points at a media document, and only then convert the HTML into Lexical rich text. Do it in any other order and you get a set of articles that look complete in the admin list view and have no images anywhere in the body.

That single failure is why this page exists as its own thing rather than as a paragraph in a general guide. Payload's HTML to Lexical converter drops <img> tags deliberately, and the Squarespace export delivers image references in two separate places at once. Both sets have to resolve to the same media document or you get duplicates.

Budget $5,000 to $25,000 for a 50 to 100 page site. The destination barely moves that number. What moves it on this particular pair is how much of the site lives in page types the Squarespace export refuses to carry.

What Squarespace actually gives you

The export is a single WordPress-oriented XML file covering layout pages, one blog page, text and image blocks, the text from embed and Instagram blocks, and gallery pages. It drops store pages, portfolios, album, index, info and calendar pages, every blog page after the first, page-specific headers and footers, drafts, style settings and custom CSS. Squarespace also states you cannot import that file into another Squarespace site.

That is the whole of it, and it is covered properly in the Squarespace to code migration guide. The rest of this page assumes you already have the file and now have to get it into Payload.

The shape of the file, element by element

Open the XML before you write a line of code. What you are looking at is a channel containing a long list of <item> elements, and everything hangs off those:

• `content:encoded` holds the post body as HTML, wrapped in CDATA. This is the payload, no pun intended, and it is where the image problem lives.

• `wp:post_type`, `wp:status`, `wp:post_date`, `wp:post_name` carry the type, publication state, date and slug. The slug is the one you need for redirects, so capture it before anything else.

• `wp:postmeta` entries are loose key and value pairs. There is no schema behind them. Some carry things you want, most carry things you do not.

• `<category>` elements do double duty. They represent both categories and tags, distinguished only by a domain attribute on the element.

• `wp:attachment_url` entries arrive as separate items in the same list, interleaved with the posts rather than nested inside them.

That last two points are the ones that generate real work, and the first of them cannot be answered from documentation.

The part nobody can tell you in advance

WXR is a WordPress format. WordPress documents it. Squarespace does not document its own dialect of it, and no vendor publishes a specification for what Squarespace writes into the domain attribute, which wp:postmeta keys it emits, or how consistently it distinguishes a category from a tag.

So do not trust any article, including this one, that tells you the exact values to branch on. Verify it empirically, per export, before you write the mapping:

1. Run the export and open the file.

2. Enumerate every distinct domain value present across all <category> elements, and count how many elements carry each.

3. Enumerate every distinct wp:postmeta key and count occurrences.

4. Spot check five posts against the live site. Confirm that what the site shows as a category appears with the domain you expect, and the same for tags.

If the domains turn out to be inconsistent, and on some exports they are, then the honest fallback is to reconstruct the category and tag split by crawling the live site rather than trusting the file. That is a half day of work you can plan for. Discovering it after you have imported 400 posts is not.

A named unknown you check in ten minutes is cheaper than a confident guess you find out about in production.

Mapping WXR onto Payload's content model

Payload's hierarchy is Config, then Collections, then Fields. A Collection is the schema. There is no separate content-type layer sitting above it, so what you are really doing is writing a TypeScript config that describes the shape of the WXR data you just inventoried.

The field types are exact strings: array, blocks, checkbox, code, date, email, group, json, number, point, radio, relationship, richText, select, tabs, text, textarea, upload. Note that it is richText in camelCase. The hyphenated rich-text you may have seen is only the docs URL slug, and using it in a config is a straightforward error.

The mapping itself:

• <title> becomes a text field.

• wp:post_name becomes your slug text field. Keep the original value verbatim, because it is also your redirect map.

• wp:post_date becomes a date field.

• wp:status becomes Payload's draft state rather than a field of your own.

• content:encoded becomes a richText field holding Lexical JSON. This is the expensive one.

• <category> elements become relationship fields pointing at a categories collection and a tags collection, once you have established which is which.

• wp:attachment_url items become documents in a media collection, referenced by upload fields.

• wp:postmeta is a case by case decision. Most of it is discardable. Anything you keep is usually a text field or a group.

The image problem, and why it lands harder from WXR

Payload's documentation is explicit about this, and it is worth quoting because people assume it is a bug: "When converting HTML to Lexical, <img> tags are NOT automatically uploaded. This is intentional because we don't know which uploads-enabled collection to add them to."

The converter does not error. It does not warn. It produces valid Lexical JSON with the images silently absent. Your import script reports success, the admin list view shows every post present with the right titles and dates, and the bodies are text only. This is usually discovered by a client, after handoff.

Coming from a flat CSV that would be annoying. Coming from WXR it is worse, because the same image reaches you twice:

• as a standalone item carrying a wp:attachment_url, sitting in the item list next to the posts, and

• as an <img> tag inside the content:encoded HTML of the post that displays it.

If you process both paths independently you upload each image twice and end up with a media collection where half the documents are orphans. Both paths have to reconcile to one media document, keyed on the source URL.

The correct order of operations

1. Parse the content:encoded HTML for each post and extract every <img> src.

2. Union those with the wp:attachment_url values from the attachment items, deduplicating by normalised URL. Squarespace CDN URLs frequently carry query-string parameters such as ?format=, so normalise before comparing or you will treat one image as several.

3. Download each unique image to local disk. Payload's payload.create() takes a filePath or a file, not a remote URL, so this step is not optional.

4. Create the media document: payload.create({ collection: 'media', filePath }).

5. Build a map from the original source URL to the returned media document ID.

6. Rewrite the HTML. Each <img> gets data-lexical-upload-id set to the media document ID and data-lexical-upload-relation-to="media".

7. Only now call convertHTMLToLexical on the rewritten HTML.

Step 7 last. Every time.

convertHTMLToLexical is Node-only, and it will rewrite your markup

Two practical consequences that catch people out.

First, convertHTMLToLexical requires JSDOM as a peer dependency. That makes it Node-only. It will not run in an edge runtime, and it does not belong in a serverless function you were hoping to trigger from a browser. Import scripts run locally or in a Node process, which is fine, but plan for it rather than discovering it at deploy time.

Second, JSDOM normalises malformed HTML as it parses. That is usually helpful and occasionally surprising. The common case is an unclosed <p> wrapping block-level elements: JSDOM closes the paragraph where the spec says it should close, which can move content up or down a level relative to how a browser rendered the original page.

This matters more than usual here because Squarespace's exported HTML is not consistently clean. Blocks that render fine on a Squarespace page can come out of content:encoded with structure that a strict parser reads differently. Diff a handful of converted posts against the live pages before you run the full import.

Categories and tags become IDs, which forces a two-pass import

In the XML, a category is a string. In Payload, a relationship field stores a document ID. So you cannot write posts and categories in a single pass unless you are willing to update every post afterwards.

The two passes:

1. Walk every <category> element, build the distinct set, and create the category and tag documents first. Keep a map from the string to the created ID.

2. Import the posts, resolving each category string to its ID through that map.

The reason the schema has to be locked before pass two, and not merely designed, is that Payload's relationship field stores four different shapes depending on two flags:

• relationTo a string with hasMany false stores a bare ID.

• relationTo an array with hasMany false stores { relationTo, value }.

• relationTo a string with hasMany true stores an array of IDs.

• relationTo an array with hasMany true stores an array of { relationTo, value } objects.

Change either flag after pass two and every document you wrote holds the wrong shape. There is no in-place fix that is cheaper than re-running the import.

The same logic applies to localization, which is set at project level with locales, defaultLocale and fallback, and opted into per field with localized: true. Turning that on changes a field's storage from a scalar to a locale-keyed object. Decide it before the first document, not after. You can verify what is actually stored by querying with locale=all.

The genuine upside: there is no rate limit

Payload's Local API is the documented import path, and the docs endorse it directly for seed scripts. payload.create() runs in process against your database. There is no HTTP funnel and no requests-per-second ceiling to design around, so you do not need a token bucket, backoff logic, or a resumable ledger just to get through the write phase.

On this pair, that shifts the bottleneck somewhere useful. The slow part of a Squarespace to Payload import is downloading images from Squarespace's CDN, not writing to Payload. That is a problem you can solve with a concurrency limit and a local cache, and it is a problem you can retry cheaply.

If you want the comparison against other headless destinations, where the write path is metered and the throughput maths changes completely, that is covered in the headless CMS migration guide.

payload migrate is not a content import

This one is worth stating plainly because the naming invites the mistake. Payload's migrate command performs database schema migrations. It creates and applies changes to the underlying database structure when your collections change.

It does not import content from another CMS. It has nothing to do with your Squarespace XML. If you go looking for a "Squarespace migration" flag on it, you will not find one, and the reason is not that the feature is hidden.

What Payload actually costs

Payload was acquired by Figma in June 2025. Payload Cloud has paused new deployments, so there is no first-party hosting option for a new project. This is not a criticism of the software, but it changes the shape of the bill and a technical buyer assessing vendor risk will already know about it.

The licence is MIT, so the software is free. Hosting plus a database is a separate cost, realistically $8 to $30 a month for anything client-grade. Payload requires a database, and the free database tiers are marginal for production: Neon's free tier suspends compute at its usage ceiling, which means the client's CMS goes down.

On the hosting side, Vercel's Hobby tier is non-commercial only. Their terms name "a paid employee or consultant writing the code" and "receiving payment to create, update, or host the site" as commercial usage, so it is not a licensed option for client work. Vercel Pro at $20 per user per month is the realistic floor there, and roughly $20 to $50 a month with a managed database is the honest range for a Payload site on that stack.

When you should not do this

Some Squarespace sites are not good candidates, and it is cheaper to find that out now.

If the site is mostly a portfolio, a store, or a calendar, most of the content is not in the export at all, and the migration becomes a re-extraction project with a Payload import bolted on the end. It is still doable, it is just priced differently, and you should scope the extraction separately.

If the site is a small brochure with a handful of pages and nobody is fighting the platform, Squarespace from $19 a month on annual billing is a reasonable deal and a Payload migration will not pay for itself. Note that Squarespace A/B tests its pricing, so treat "from $19" as the shape of the number rather than a quote.

One thing that does push the other way: Squarespace ships no official MCP server, unlike Webflow, Wix and WordPress. Third-party servers built on its public APIs exist, so this is a question of first-party support rather than a total blackout, but it does mean agent access to your content is someone else's integration. (Unrelated aside worth making, since search results conflate them: developer.squareup.com belongs to Square, a different company entirely.) Once the site is a Payload project in a Git repo, an agent gets the whole artifact, can run the build, and a bad change is one revert away.

The order, one more time

If you take one thing from this page: images before conversion, categories before posts, and schema flags locked before either. Everything else in a Squarespace to Payload migration is ordinary work. Those three orderings are where the silent failures live.