How to migrate WordPress to a headless CMS without losing your URLs

To migrate WordPress to a headless CMS, inventory your content and URLs, convert posts to the destination schema, move media, and connect a new frontend before switching traffic. genko.me accepts CSV and JSON imports, but it does not directly import WordPress WXR files. Preserve existing URLs where possible and use permanent 301 or 308 redirects for URLs that change.

This article is written by the genko.me team. Product behavior and official references were checked on October 20, 2026.

When is moving from WordPress worth the effort?

A headless CMS is worth evaluating when you want a custom Next.js or Astro frontend, or when several applications need the same content. Changing the CMS alone does not improve search rankings or page speed. Your new frontend still needs routing, metadata, rendering, image handling, and caching.

You can also keep WordPress and use its REST API with a separate frontend. That lets you evaluate a headless architecture without moving the editorial system. Our headless CMS versus WordPress comparison explains that distinction.

1. Inventory posts, media, and existing URLs

Include posts, pages, drafts, authors, categories, tags, custom fields, and attachments. Record what you will exclude and why, so a missing category archive is not discovered after launch.

Build a URL mapping sheet with the old URL, WordPress ID, destination ID, new URL, and redirect requirement. A move from /2024/10/article/ to /blog/article/ changes more than the slug. Include trailing slashes, archive pages, pagination, and media paths in the review.

Choose representative test articles before converting everything. Include an older post, a non-ASCII slug, and examples containing images, tables, code, and embeds. Problems found in these samples should shape your transformation rules.

Also decide who owns the final update window. If editors continue changing content after your export, you need a way to identify and reprocess those changes before launch.

2. Export WordPress content and keep the actual media files

Use Tools → Export in WordPress. The official export documentation describes the WXR XML format used for posts and associated data.

1. Save an export covering the content you intend to migrate.

2. Separately preserve the actual images and attachments using your hosting backup facilities or another appropriate backup method.

3. Keep the old site available while you transform and compare content.

4. Freeze editing before the final export and reconcile changes since the rehearsal.

Do not treat a content export as proof that all media is safely moved. If imported HTML still points at the old host, canceling that hosting service can break images on otherwise working pages.

Check content that depends on WordPress rendering. Raw shortcodes and block-specific markup may need conversion to usable HTML. Interactive features such as forms need a functional replacement; copying their surrounding markup does not recreate their behavior.

3. Map WordPress data to a genko.me schema

Create a list-format API using APIs and schemas. Add only the fields needed for publishing, editing, and displaying your content.

A slug field does not automatically create a route. Your frontend must resolve it and return the article at the intended path.

genko.me content IDs support letters, digits, hyphens, and underscores, up to 64 characters. Keep an incompatible slug, such as one containing Japanese characters or slashes, in a separate text field and use a valid destination ID.

For shared authors and categories, create the referenced records first. Maintain an old-to-new ID map and rewrite article references. The importer does not automatically translate reference IDs.

4. Convert WXR to CSV or JSON and import drafts

The import and export documentation describes the supported file formats. WXR must be transformed locally into those formats; selecting the original XML file is not a migration path.

This minimal JSON works with an API containing title, body, slug, and originalPublishedAt. Replace the sample date with the source article's date.

{  "contents": [    {      "id": "wp-123",      "title": "Our first migrated article",      "body": "<p>Article HTML converted from the original post.</p>",      "slug": "first-article",      "originalPublishedAt": "2024-10-01T00:00:00.000Z"    }  ]}

1. Open Import for the destination API and select the converted file.

2. Review validation results and decide whether to preserve content IDs.

3. Import the first batch as drafts.

4. Compare previews against the old pages before expanding the batch.

As of October 2026, the limit is 10MB per file and 1,000 entries per import. Split files to satisfy both constraints. A batch of long articles can exceed the size limit before reaching the entry limit. Required fields must be present even when importing drafts.

List-format imports add records rather than update existing ones. If an ID already exists, processing stops at that entry and earlier successful saves remain. Inspect the destination before retrying, then import only missing records.

Source publication status, schedules, and creation timestamps are not restored. The import screen determines whether records become drafts or published content. Use a custom datetime field when your frontend needs the original publication date, and separate published and draft source records into appropriate batches.

5. Move images and rewrite internal links

There is no WordPress-specific automatic media copier. Upload images through the destination content's image or file fields, then save the content to establish its media references.

For a small migration, adding images after importing the text can be the simplest approach. For a larger one, keep a media ledger containing the original URL, saved file, destination media ID, and articles using it. An export of a manually prepared destination article provides an example of the stored import values.

Do not confuse delivery data with import data. An image returned by the delivery API as { url, alt } is not the same as a stored image value containing a destination media ID. The automatic image migration documented for Newt is not a WordPress migration feature.

Inspect inline images, srcset, captions, alt text, PDF links, and absolute links back to the old domain. Keeping article routes does not automatically preserve attachment URLs.

6. Preserve URLs or configure permanent redirects

If the old paths can stay, make the new application serve the same content at those paths. If they change, configure a server-side 301 or 308 from each old URL to its corresponding new page. Redirects belong in your hosting or application configuration, not in the CMS import screen.

Google's site move guide covers URL mapping and permanent redirects. Avoid sending unrelated old pages to the homepage.

Check that old URLs redirect correctly, destination pages return 200, and canonical links, internal links, sitemaps, and indexing directives match the intended public site. Redirects reduce avoidable migration problems; they cannot guarantee unchanged rankings.

WordPress migration cutover checklist

1. Reconcile record counts, including the published and draft breakdown.

2. Check images, tables, embeds, related articles, and original dates.

3. Exercise listing pages, detail pages, pagination, search, and forms.

4. Freeze editing and apply the final content and media changes.

5. Publish content, refresh caches, and switch routing in the agreed order.

6. Test old URLs and publish an update through the new editor.

7. Retain the source backup and an agreed rollback procedure.

Before choosing genko.me, compare your data with the plan and storage limits. See the Next.js integration guide for the frontend connection and the Contentful migration guide for another example of separating content conversion from site cutover.

FAQ

Can genko.me import a WordPress XML export directly?

No. Convert the WXR file into CSV or JSON matching a destination schema, then use the content importer.

Will switching from WordPress improve SEO?

A CMS change does not guarantee better rankings. Your implementation must preserve or improve content, URLs, metadata, internal linking, and performance.

Are WordPress images migrated automatically?

There is no WordPress-specific automatic image migration. Preserve the files, register them in the destination, and update image fields and article HTML.

Can I preserve WordPress publication dates and drafts?

The importer does not restore source status or creation timestamps. Keep original dates in custom fields and import draft and published batches with their intended destination status.

Sources

Checked October 20, 2026.

• WordPress export screen

• WordPress REST API Handbook

• Google: Site moves with URL changes

• genko.me import and export

• genko.me media management