How to migrate from WordPress to a headless CMS

Plan a WordPress move to headless delivery or Payload. Map posts, fields, media and URLs, then rebuild preview and verify your published retail guidance.

To migrate from WordPress to a headless CMS, either keep WordPress as the editor or transfer its content into another system, such as Payload. Both routes need a new frontend. Moving records into Payload also needs a field mapping and a separate transfer of media files.

This procedure fits retail publishers moving articles and store guidance. The main risk is losing the relationship between a page, its images and its approved policy text. Themes and plugin behaviour need separate work, even when the exported words arrive intact.

Choose retained WordPress or content replacement

Keep WordPress when your editors want its existing authoring tools and you need a different way to display the content. The frontend reads WordPress through its application programming interface (API). You still operate WordPress, manage its access and maintain the plugins that supply your content.

Choose a Payload transfer when you also want to change the editing system or define a different content model. Your developers create the destination collections and convert the source records into their fields. Editors then work in Payload after the cutover.

A familiar WordPress workflow is a reason to retain WordPress, especially when editors rely on a plugin’s publishing process. A need for structured, reusable policy records can justify replacement. Choose on the editing and operating work your team can maintain, without assuming that decoupling alone removes that work.

Neither route carries a WordPress theme into the new frontend. Shortcodes, page-builder layouts and forms need an explicit replacement or renderer. A plugin’s settings and notifications also need their own plan. Copying an article body does not recreate these behaviours.

Inventory posts, fields and dependencies

List the source objects and their owners before exporting. Record counts by post type and publication status, then identify the material that belongs in the new public site.

  • Include posts and pages, plus every custom post type used for retail guidance.
  • Record categories, tags and other taxonomies, including their relationships to records.
  • List custom fields with their data types and an example value.
  • Inventory media originals, captions and alternative text. Note files stored outside the normal media library.
  • Record authors, editor roles and revisions you must retain for audit or recovery.
  • Save public URLs, canonical settings and existing redirect rules.
  • Identify plugin-owned content and dependencies, including embedded forms and scheduled publishing.

Take a database backup and a file backup before a trial transfer. WordPress’s backup guidance covers both parts. Keep them separate from the migration export, and prove you can restore them in an isolated environment.

For a content export, open Tools > Export and download the selected WordPress eXtended RSS (WXR) file. WordPress’s export documentation lists its content objects. A developer can also use WP-CLI, WordPress’s command-line tool, to produce WXR exports with documented filters.

The WP-CLI export reference states that WXR excludes site configuration and the attachment files themselves. Retain the actual image and document files. An attachment URL in an export is a reference, not a saved copy of that file.

For the retained-WordPress route, inspect the REST API responses needed by your frontend. WordPress’s custom content documentation requires REST support for custom post types and taxonomies. Inspect custom fields separately. A field visible in the editor must also be available through the chosen extraction route.

Paginate a bulk API extraction. WordPress documents page counts and collection totals, so compare the complete result against your inventory. A successful first response does not prove you collected every record.

Map and transfer the approved records

Map each source object to a destination field before importing. The following fictional mapping shows a retail publisher replacing WordPress with Payload. It is a proposed conversion, not an automatic import specification.

Source itemTargetRetained valuesLoss or conversionManual action
Article 418Articles collectionTitle, slug and approved publication stateBody HTML or blocks need conversionCheck headings, links and embedded content
Returns policy 72Policies collectionApproved wording and policy identifierShortcodes need replacementMark the approved policy version
Category 9Categories collectionName and slugRelationship identifiers changeMap each article’s category
Featured image 55Uploads collectionFile, caption and alternative textAttachment URL becomes a new referenceCopy the file and resolve the upload ID
Custom field delivery_regionStructured region fieldSupported source valueFree text may fail target validationReview unmatched regions
Authors and revisionsAgreed archive or destination recordsRequired attribution and historyAccount permissions need separate setupConfirm retention and editor access
  1. Create the destination fields and validation rules in a test environment. Define how drafts and approved policies differ before importing either.
  2. Extract only the agreed source set. Save each source record’s original identifier and type alongside the transformed data.
  3. Import taxonomy records and media files first. Record every resulting destination ID in a stable mapping such as wordpress:attachment:55 to its new upload ID.
  4. Convert article bodies and custom fields to the target schema. Replace source relationship IDs using that mapping, then import the article records.
  5. Repeat the transfer against the same source set in the test environment. Match existing records through the stored source identifier so a retry does not create duplicates.
  6. Inspect failures and resolve their cause before transferring the final approved set. Preserve rejected records for comparison with the source.

Payload documents CSV and JSON imports through its Import Export plugin. The input must match the destination structure, so transform WXR first. Its import settings include a match field for updating existing documents.

A developer can instead use Payload’s Local API to create or update collection records and upload local files. Keep that migration process restricted to its intended environment. Local API operations bypass access control by default, so a user-facing endpoint must not inherit the migration process’s permissions.

Rebuild rendering and preview alongside the transfer. Test editor permissions and draft access separately from import success. Recreate required plugin behaviour, including publication hooks, before making the new editor authoritative.

Validate pages and the answer source

Validate the complete approved content set and the rendered pages before switching traffic. Counts can reveal missing records, while field comparisons reveal conversions that silently changed meaning.

For a fictional inventory of 120 approved articles and eight policies, expect exactly those destination counts. Rejected or deliberately excluded items need an explicit record. Compare source IDs to destination IDs as well as totals, because duplicates can hide omissions.

Open examples from every content type. Compare rich text, custom fields and taxonomy links with the source. Check each referenced media file loads from its intended destination and retains its alternative text. Test an article containing a shortcode or embedded form as a separate case.

Compare every old public URL with the release map. A retained URL must serve the intended page with its correct canonical URL. A moved URL must redirect to the approved replacement, which must itself load successfully. Check navigation and in-body links against those destinations.

Then trace one policy change through the systems that answer customer questions. In a fictional returns policy, replace an old 14-day period with an approved 30-day period. Publish the approved destination record, rebuild or refresh the frontend as required, then refresh the shopping-answer source.

Where you use shoppa, give it the approved policy document and the correct catalogue.

shoppa helps customers find, compare and buy products in the chat, and answers policy questions from your store documents. Ask a returns question that needs the changed period. The expected answer uses 30 days and the approved conditions.

Test a draft containing different wording and a superseded source copy too. Neither must replace the approved answer or appear on the public frontend. Remove retired documents from the retrieval source, then repeat the same question in a fresh conversation. Keep the old WordPress endpoint out of the new ingestion route when Payload becomes the content owner.

Cut over and preserve a supported return route

Freeze source editing for the final transfer, assign a release owner and keep the previous site available for recovery. Agree how urgent policy corrections will be recorded during the freeze.

Give editors their destination access before release. Recreate role permissions and confirm preview uses authenticated access. Assign ownership of the public domain change and retain its previous settings. Inventory identity connections, publishing integrations and notification recipients so the move does not send duplicate alerts or leave editors on the wrong system.

After the final import, reconcile changes made since the trial. Release only after the count, page and policy-answer checks pass. Repeat the public URL and policy-answer checks after the switch, including a fresh request that cannot rely on the previous page’s cached output.

A return to the old frontend requires its retained deployment and the recorded routing settings. A content restoration requires the matching database and files. Edits made in Payload after cutover need reconciliation before returning to WordPress, because a source backup will not contain them.

Keep source records, exports and assets until validation and the agreed recovery period finish. If a transfer fails, stop the affected import and give the developer its source IDs, target schema and error details. Escalate backup restoration to the hosting team using the retained backup set. Resume only when the missing records and the customer-facing policy answer match the approved source.

Give your store its own shopping agent

Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.

See it in actionFree trial · Simple setup