How to Migrate From Wix to Payload CMS

The two conversions that actually cost you

A Wix to Payload migration is not difficult because Wix is closed. It is difficult because the two things you most want to carry across, rich text with images inside it and repeated values like author and category, are exactly the two things that do not survive a naive import.

Payload's own documentation is explicit about the first one. When converting HTML to Lexical, <img> tags are not automatically uploaded, because Payload cannot know which uploads-enabled collection to put them in. Nothing is flagged, queued or logged. The images are dropped silently. The post imports, the title is correct, the body reads fine in the admin list view, and every image in the article is gone. On a large blog you can reach client review before anyone notices.

The second failure is quieter. A Wix CSV carries the author's name as a plain string on every single row. Payload's relationship field stores a document ID. Handing it "Jane Doe" where it expects an ID gives you a validation error at best, and at worst a document that saves happily with an empty relation.

Everything below is the field-level mapping between the two models, and the order of operations that avoids both failures.

What Wix actually hands you, briefly

Wix has no code export. A CMS collection exports to CSV, capped at 1GB and 50,000 items, and store products export to a separate CSV. There is no blog export feature, and the RSS feed at /blog-feed.xml is capped at 20 truncated excerpts, so the archive has to be recovered by crawling the rendered pages listed in the sitemap.

That is the extent of what you have to work with. The full detail on what exports, what has to be crawled, and how to build the URL inventory lives in the Wix to code migration guide. This page assumes you have already got the CSVs and the crawled bodies in hand, and picks up at the point where you have to decide what shape they take inside Payload.

One dated fact worth carrying into the decision, because it is the clearest evidence of what a closed platform can do with your content: Wix discontinued ADI on 10 November 2024, and unpublished ADI sites that had been inactive for six months or more were deleted.

The two content models, side by side

Payload's hierarchy is Config, then Collections, then Fields. A Collection is the schema; there is no separate content-type layer sitting above it. Globals are singletons for things like site settings.

The field type values are a fixed list: array, blocks, checkbox, code, date, email, group, json, number, point, radio, relationship, richText, select, tabs, text, textarea, upload, plus presentational ones (collapsible, row, ui) and the virtual join.

Note the spelling: it is richText, camelCase. rich-text is only the docs URL slug, and typing it into a config is a common first-hour mistake.

Wix gives you the opposite shape. Every column is a scalar. Rich text arrives as an HTML blob or with its formatting already flattened. Images are absolute Wix CDN URLs, often carrying query-string transform parameters. Repeated values are denormalised onto every row. There are no stable IDs you can rely on across separate exports.

Column-by-column mapping

| What the Wix CSV gives you | Payload field | What you have to do to it | |---|---|---| | Title column | text | Trim. Wix exports frequently carry trailing whitespace. | | URL or slug column | text, indexed and unique | Keep the original Wix path verbatim in its own field too, for the redirect map. | | Short description | textarea | Direct. | | Post body HTML blob | richText (Lexical) | Run the image pre-pass first, then convertHTMLToLexical. See below. | | Date column | date | Cast explicitly. CSV gives you a string, and the format varies by locale setting. | | TRUE / FALSE column | checkbox | Cast explicitly. The string "FALSE" is truthy in JavaScript. | | Numeric column | number | Strip currency symbols and thousands separators before casting. | | Single-choice column | select | Only if the option set is closed. If editors must add options, model it as a relationship instead. | | Comma-separated tags in one cell | relationship, hasMany: true | Split, normalise, dedupe, create the tag documents in pass one. | | Author name string | relationship to an authors collection | Two passes. It cannot go in directly. | | Category name string | relationship to a categories collection | Two passes. | | Featured image (absolute Wix CDN URL) | upload | Download first. payload.create() takes filePath or file, not a remote URL. | | Inline images inside the body HTML | media documents plus rewritten <img> tags | The failure case. See the next section. | | Wix item identifier | text, indexed | Keep whatever identifier the export gives you. It is your reconciliation and resume key. | | Layout divs, inline styles, embedded widgets | no direct equivalent | Decide per construct, before the run: map to a blocks entry or drop it deliberately. |

The upload field is worth understanding structurally: it stores the media document's ID, so it behaves as a relationship, not as a file. That is why the media documents have to exist before anything that points at them.

Images: get the order right or lose them all

This is the single most important sequence in a Wix to Payload migration, and it is not intuitive, because the converter fails without complaining.

1. Parse the body HTML and extract every image source. Check srcset as well as src. Strip the Wix CDN query-string transforms so two references to the same asset at different sizes resolve to one file.

2. Download each image to disk. This is where the wall-clock time goes, not the writing.

3. Create the media document with payload.create({ collection: 'media', filePath }) and capture the returned ID.

4. Build a source-URL to document-ID map and persist it to disk.

5. Rewrite each `<img>` tag in the HTML with data-lexical-upload-id set to the new document ID and data-lexical-upload-relation-to set to the uploads collection slug.

6. Only then call `convertHTMLToLexical`.

Convert first and you get a clean-looking Lexical document with no images in it and no error to tell you.

Two further properties of the converter that shape how you run it. convertHTMLToLexical needs JSDOM as a peer dependency, so it runs in Node only and cannot be pushed into an edge function. And JSDOM normalises malformed source HTML on the way through, which with Wix output is usually a help: unclosed <p> tags wrapping block elements are the common case, and they come out sane.

There is no lossy mode. Payload will not park unrecognised HTML in a passthrough node for you to clean up later. Wix layout wrappers, inline style attributes and embedded widgets such as booking forms or gallery components simply have no matching Lexical node. That is a modelling decision you make in advance for each construct, not something the script can infer.

Denormalised strings become relationship IDs, in two passes

A relationship field stores a document ID, so it cannot be populated from the same row that names the thing it points at. That forces two passes, and the sequencing matters.

Pass one, build the reference collections. Read every CSV column that repeats, take the distinct set of values, normalise case and whitespace, and create one document per value. Skipping normalisation is how "jane doe", "Jane Doe" and "Jane Doe" become three author documents and a broken filter in the admin UI. Write the resulting name-to-ID map to disk as you go.

Pass two, create the content documents, resolving each denormalised string to the ID you recorded in pass one.

Lock the schema before pass two starts, because two flags change the stored shape of every relationship value:

| relationTo | hasMany | What is stored | |---|---|---| | string | false | a bare ID | | array | false | { relationTo, value } | | string | true | an array of IDs | | array | true | an array of { relationTo, value } |

Change either flag after the import and every document that uses that field needs rewriting. Deciding halfway through that categories should be polymorphic across two collections is not a config edit, it is a second migration.

Localization carries the same warning and is worse to discover late. It is set at project level with locales, defaultLocale and fallback, and individual fields opt in with localized: true. Turning that on changes a field's storage from a scalar to a locale-keyed object, so it has to be decided before the first import, not after. Query with locale=all to see what is actually stored.

One naming trap while you are here: Payload's migrate command handles database schema migrations. It has nothing to do with importing content. Readers conflate the two constantly, and the docs endorse the Local API for seed and import scripts instead.

The good news: throughput is not your bottleneck

The import path is the Local API, payload.create(), called directly from a script rather than over HTTP. Payload's docs endorse this explicitly for seeding. There is no rate limit. Your ceiling is whatever your database will take.

That matters more than it sounds, because it moves the bottleneck somewhere you control. The slow part of a Wix to Payload migration is downloading a few thousand images off Wix's CDN, not writing them into Payload.

So build the import as two separable stages. Stage one fetches assets: slow, retryable, and cached to disk so a failure never costs you the same download twice. Stage two writes to Payload: fast, and cheap to re-run from scratch after a schema fix. If a bad hasMany decision means starting the write over, that should be a coffee break, not a day.

Wix Stores, if you sell

Products come out as their own CSV. Wix does not support an XML store export.

The straightforward columns map exactly as above: text for name and SKU, number for price and inventory once cast from strings, richText for the description if it holds HTML, upload for product images.

Variants are the awkward part, and they are awkward because a flat CSV has only two ways to express them: extra columns per option, or extra rows per combination. Neither is a data model. In Payload you either model variants as an array field with its own subfields on the product document, or as a separate collection with a relationship back to the parent. Both are defensible. Choosing after the import is not, for the same reason as above.

Payload is a CMS, not a checkout. Payments go to a dedicated service such as Stripe or a headless commerce platform, and orders and customers are a separate data task from the site migration.

Vendor status and what it costs to run

Two facts a technical buyer should have before committing. Payload was acquired by Figma in June 2025. And Payload Cloud has paused new deployments, so there is no first-party hosting product to sign up for.

The software itself is MIT licensed and free. Hosting and a database are a separate bill. Free database tiers are marginal for client work, since Neon's free plan suspends compute at its limits, which means the client's admin panel goes down. Realistically, budget $8 to $30 per month for a client-grade database, and roughly $20 to $50 per month total on Vercel with a managed database.

One trap that catches agencies and freelancers regularly: Vercel's Hobby tier is non-commercial only, and Vercel's own definition of commercial usage covers a paid employee or consultant writing the code and receiving payment to create, update or host the site. A client site on Hobby is a terms violation. Vercel Pro at $20 per user per month is the floor for client work.

For the migration itself, budget $5,000 to $25,000 for a 50 to 100 page site. On this pair the price is driven by two things: how much of the archive has to be crawled rather than exported, and how much of the body HTML is Wix widgets that need a modelling decision rather than a conversion rule.

Agent access is not the reason to move

Worth saying plainly, because it is a claim made carelessly. Wix ships an official MCP server at mcp.wix.com/mcp. An AI agent can reach a Wix site.

The difference after migrating is not access, it is the artifact. Against a Payload repo an agent gets the collection configs, the frontend and the content model in one place, can run the build to check its own work, and a bad change reverts with git. Against a hosted builder API it edits the fields the API exposes, with no build to verify against and no history to roll back. That is a real difference, but it is a difference of leverage, not of possibility.

When Payload is the wrong destination for a Wix site

If your Wix site is a dozen static pages with no CMS collections behind it, Payload gives you an admin UI nobody needs plus a database bill. Flat Markdown files in a repo do the same job for nothing.

Payload earns its cost in one specific situation: non-technical editors have to change structured, repeating content regularly, and you want that content typed, related and queryable rather than sitting in files. A blog with authors and categories, a directory, a case-study library, a product catalogue. If that is not your site, the mapping work described above is effort spent building a machine you will not use.

Where to go next

For what Wix exports and what has to be crawled, read the Wix to code migration guide. If you have not settled on Payload yet and want the destination comparison, that is covered in the headless CMS migration guide. For the redirect and ranking side, the SEO migration survival guide is the one to read before you cut DNS.

If you want a second opinion on the mapping specifically, that is what a free migration review is for. We look at your actual collections, your actual body HTML, and tell you which parts convert cleanly and which parts are a modelling decision you have to make yourself.