Migrating from Liferay to Payload: a 2026 guide for portal teams

Liferay’s move to Jakarta and its 2026 Free Tier set three conditions that matter to a portal team planning its next few years. Custom code that uses the old javax packages has to move to Jakarta from DXP 2025.Q3 and the 2026 Q1 Portal releases. On the Free Tier, multi-factor authentication, SAML, and advanced search tuning require an Enterprise Subscription key. And the free path stops receiving a quarter’s patches once that quarter’s stable release is declared.

None of the three requires you to leave Liferay, and each is set out below in the terms Liferay publishes.

This guide is written for the teams Liferay is built for: government departments, universities, banks, and large enterprises running a portal that has grown for a decade. It covers what a headless CMS can take over from a portal, what it cannot, how a Liferay to Payload migration runs, and the conditions under which staying is the better call.

Liferay is a portal, and a CMS does not replace a portal

Part of a Liferay estate probably does not belong in a CMS at all.

Liferay runs content, and it also runs authentication, user accounts, roles and permissions across applications, workflow, and portlet-based applications that hold business logic. A headless CMS manages structured content and serves it over an API. Moving the content out does not move the applications.

For a portal that is mostly public-facing content with a login area attached, the content is the larger half and the migration is worth scoping. For a portal that is mostly authenticated self-service, with forms that write to back-office systems and portlets carrying business rules, the content is the smaller half, and a CMS migration leaves most of the estate untouched.

Work out which of those describes your portal before reading anything else here. The answer changes the size of the project more than any other.

What changed with Jakarta and the 2026 platform

Custom code using javax packages must move to Jakarta

Liferay’s upgrade documentation states that Liferay DXP 2025.Q3+ and the 2026 Q1 Portal releases are Jakarta-based, and that if you have code using the old javax packages, you must modify that code, particularly its dependencies, to run on versions of Liferay that use the new Jakarta platform.

That sentence binds custom code carrying javax imports, so an installation with no custom modules has nothing to rewrite. Liferay also states that the process is in most cases straightforward and easy, and provides Liferay Workspace and Blade tooling to help upgrade projects.

Sizing starts with a count of the custom modules and their dependencies, which gives you the scope. A portal with a few custom portlets and a handful of hooks is a different proposition from one with dozens of modules accumulated across several upgrade cycles.

The Enterprise key, and what sits behind it

Liferay’s Free Tier documentation states that some Liferay DXP capabilities, including multi-factor authentication, SAML, and advanced search tuning, require an Enterprise Subscription key.

For the buyer this guide is written for, SAML is the gate most likely to matter, because government departments and large enterprises treat single sign-on as a baseline requirement. Liferay names SAML in the Free Tier’s gated list, while its OpenID Connect documentation carries no Subscription label, so an estate that signs in over OpenID Connect should confirm its position with Liferay. If your estate federates over SAML, the free path does not serve it and an Enterprise Subscription is the answer.

Payload has a comparable gate. It lists single sign-on, which integrates with SAML or OAuth 2.0 identity providers, among its enterprise features alongside Publishing Workflows, and it publishes no price for them. Its open-source core supports custom authentication strategies, which a team can build single sign-on on instead.

On either platform, the single sign-on gate is a procurement question. An Enterprise Subscription buys a supported Liferay platform, and staying on it is a legitimate answer.

Separately, Liferay states that starting with the 2026.Q1 release, all Liferay DXP installations including trial and free-tier environments require an XML activation key to enable core features and services. A Free Tier activation key is free, is valid for twelve months, is renewed from Liferay Marketplace, and is not version-exclusive.

The Free Tier patch boundary

Liferay’s Free Tier page sets the boundary in its own words: for each Liferay DXP quarterly release, Free Tier eligibility starts at the .0 release and continues through the patched release designated as stable for that quarter. Once a quarter’s stable version is declared, later patches in that quarter are no longer Free Tier eligible, and the options are to stay on the stable release or move to the next quarterly release.

Free Tier does receive patches. It receives them up to a boundary, and the boundary moves each quarter. For a team running a public service, the question is whether that cadence fits your security posture and your change-control process.

Liferay describes the Free Tier as designed for learning, development, and smaller-scale use, governed by a specific EULA, and highly recommends an Enterprise Subscription for production scenarios. That is a recommendation, and Liferay asks partners and teams planning client-facing deployments to review the EULA carefully because terms may vary by use case.

What has not changed

Three things get lost when these changes are summarised second-hand, and each one weakens the case for leaving.

The source licence continues. Liferay’s source code continues to be published under the LGPL, and the community remains part of how the platform develops. Nothing here is a move to closed source.

Liferay does not call the CE path a migration. Answering its own question about whether current Liferay Portal CE users need to migrate, Liferay says: not in the traditional sense, and that moving to the 2026 platform is a version upgrade, much like the CE upgrades you have done before.

Enterprise activation is a licensing step. Buying an Enterprise Subscription changes what you pay and what you are entitled to. Liferay’s Free Tier documentation states that no data migration or replatforming is required, and that the additional capabilities become available as soon as the Enterprise key is applied.

If your reason for reading this guide is only that one of the three changes above landed on your desk, the proportionate response is an upgrade plan.

The four options in front of you

1. Upgrade in place and stay on the free path. Move custom code to Jakarta, track each quarter’s stable release, and accept the patch boundary. Works when you have few custom modules, no SAML or multi-factor authentication requirement, and no need for more than three cluster nodes.
2. Upgrade in place with an Enterprise Subscription. The same technical work, with support, security patches, hotfixes, and the gated capabilities included. Liferay licenses Enterprise per server instance rather than per user, which matters when sizing.
3. Split the estate. Keep the portal for the authenticated applications and move the public content to a CMS. Most of this guide is about this option.
4. Replatform the content estate to Payload and retire what the portal was only holding for convenience. Works when the portal has drifted into being a content site with a login page attached.

Options three and four differ in how much stays behind. Both need the same first step, which is an inventory that separates content from applications.

What moves cleanly, and what does not

Web content and structures

Liferay web content is built on structures, which define fields, and templates, which render them. Payload models content as typed collections defined in code, with generated TypeScript types.

Structures map onto collections reasonably well. The work is deciding which structures survive. A decade-old portal usually carries structures that were created for one campaign, structures that duplicate each other with one field’s difference, and structures whose owner is no longer on record. Copied one-to-one, those structures arrive in Payload unchanged, which is why the model is redesigned as part of the migration.

Liferay exposes content through headless REST and GraphQL APIs, and they are the practical extraction route. Liferay’s Web Content API Basics names three services in the Headless Delivery API: StructuredContent for articles, ContentStructure for structures, and ContentTemplate for templates. For bulk extraction, the Headless Batch Engine provides REST APIs to import and export data. Liferay documents all of them in its API Explorer, reachable on any running instance at /o/api.

Article content, its structure definition, and the template that rendered it come out separately, and only the first two have a destination in Payload. Templates are rebuilt as front-end components.

The document library

The document library carries more metadata than a file copy preserves: folder hierarchy, document types with their own fields, versions, and permissions per folder.

Decide three things before moving it. Which assets are still referenced by live content, which versions you are obliged to retain, and whether folder permissions were doing access-control work that the CMS will not reproduce. On a portal the third needs checking folder by folder: a document library folder restricted to one department is an access-control rule, and moving those files into a CMS media library removes it.

Users, roles and permissions

This is the part that does not move automatically.

Liferay’s permission model runs across sites, organisations, user groups, roles, and individual resources, and it governs applications as well as content. Payload has access control, and it is well suited to editorial roles: functions written in code, reviewed like code, controlling who can read and change which collections and fields.

Those two things solve different problems. Payload’s access control governs the CMS and does not carry permissions for applications that live outside it. Payload’s auth-enabled collections can hold end-user accounts for your own applications, but Payload does not become your identity provider, and none of Liferay’s users, organisations, roles or resource permissions carries over automatically. If Liferay is currently acting as your identity layer, the target architecture has to name where that responsibility goes, and the migration scope has to include it.

Portlets and the applications behind them

A portlet is an application. Rebuilding one is a build project, sized by what the portlet does.

The useful discipline is to sort them into three groups. Portlets that only render content are replaced by front-end components reading from the CMS. Portlets that are thin front ends over another system are replaced by an integration with that system directly. Portlets carrying their own business logic and data are rebuilt as services, and those are the ones that dominate a budget.

Do this sort before anyone quotes the project. Without it, the quote covers the content only, and the portlets arrive later as change requests.

How a Liferay to Payload migration runs

Inventory first, and separate content from applications. Count web content articles by structure, document library assets by folder, portlets by the three groups above, and every integration wired into the portal. The rest of the plan is built on this inventory, and it also tells you whether option three or option four fits.

Design the Payload model. Structures become collections with typed fields and relationships. The taxonomy, the content left behind, and the boundaries between content types are settled at this stage.

Extract through the headless APIs. Liferay’s REST and GraphQL endpoints are the route for content and for document library metadata. Assets themselves come across as files with their metadata reattached on the other side.

Rebuild the front end. Payload runs inside a Next.js application, so the CMS and the site can be one codebase and one deployment. Templates become components. Anything that was a portlet rendering content becomes a component reading from the API.

Handle identity and permissions explicitly. Decide where authentication lives, who owns user accounts, and how any retained portal application authenticates against the new front end. Put the answer in writing before cutover.

Redirects and SEO. Liferay’s friendly URLs and site structure rarely map one-to-one onto a new information architecture. The redirect map is built before anything moves, and it is tested before cutover.

Verify against the original. Content counts reconciled, a representative sample checked field by field, links and redirects tested, permissions exercised, integrations exercised. Then the cutover decision.

What it costs and how long it takes

The content half of a Liferay migration is sized by the number of surviving structures and the document library, and the application half is sized by the portlets in the third group above. Two portals with identical page counts can differ widely once the portlets are counted.

Estimates go wrong in three places: a skipped portlet inventory, document library permissions that turn out to be doing access control, and an identity question left until after the content has moved.

When you should stay on Liferay

Several conditions make staying the better decision, and they are common in the installed base this guide addresses.

Your estate is mostly authenticated applications. If the public content is a minority of the portal, moving it out solves a small problem and leaves you running both platforms.

Liferay’s permission model carries institutional structure. A portal with organisations, user groups, and resource-level permissions that reflect an actual institutional structure is holding value that a CMS will not reproduce.

You need SAML and an Enterprise Subscription is affordable. Buying the subscription solves the requirement directly and keeps a supported platform under you. Payload licenses its single sign-on as an enterprise feature too, so a move does not by itself remove the licensing question.

Your custom code is small. If the Jakarta scope is a handful of modules, Liferay’s own assessment that the process is in most cases straightforward and easy is likely to hold for you, and the upgrade is the proportionate answer.

You have upgrade discipline. If your team has kept up with Liferay’s releases, the Jakarta move and the quarterly patch boundary fit a process you already run.

Where WAYF fits

WAYF is an official Payload partner and Top Contributor, and we build content platforms on Payload for enterprises and public institutions. Our work with Ingersoll Rand covers an enterprise CMS migration at scale, and the Council of Europe Development Bank build is an events platform with a Participants Manager on Payload and a separate participant experience.

If you are at the inventory stage, the pre-migration checklist sets out what your side needs to prepare, and the CMS RFP template turns that into a buyer brief with a vendor scorecard. Our CMS replatforming service sets out how discovery becomes a written scope and a fixed price.

FAQ

1. Does Liferay's move to Jakarta EE force a migration?

   No. It requires custom code to be updated. Liferay's own upgrade documentation states that Liferay DXP 2025.Q3+ and the 2026 Q1 Portal releases are Jakarta-based, and that code using the old javax packages must be modified, particularly its dependencies, to run on them. Liferay also says the process is in most cases straightforward and easy, and ships Liferay Workspace and Blade tooling to assist. On that reading, an installation carrying no custom modules has nothing to rewrite, and the work is an upgrade task with a defined scope.

2. Do I have to pay for Liferay now?

   Liferay's source code continues to be published under the LGPL. On the 2026 Free Tier, some Liferay DXP capabilities, including multi-factor authentication, SAML, and advanced search tuning, require an Enterprise Subscription key. From the 2026.Q1 release, every DXP installation including trial and free-tier environments also requires an XML activation key to enable core features and services. A Free Tier activation key is free, is valid for twelve months, and is renewed from Liferay Marketplace.

3. Can I run Liferay DXP Free Tier in production?

   Liferay describes the Free Tier as designed for learning, development, and smaller-scale use, governed by a specific EULA, and highly recommends an Enterprise Subscription for production scenarios. That is a recommendation, and Liferay asks partners and teams planning client-facing deployments to review the EULA carefully because terms may vary by use case. The practical constraint is patching: Free Tier eligibility runs from a quarter's .0 release through the patched release designated stable for that quarter, and later patches in that quarter are not Free Tier eligible.

4. Can Payload replace everything Liferay does?

   No. Liferay is a portal platform and Payload is a headless CMS. Portal workflows, an identity provider, user accounts, fine-grained permissions across applications, and portlet-based applications are not automatically replaced by moving content into a CMS. The realistic scope is the content and publishing part of the estate, with the application parts either staying where they are or moving to services of their own.

5. Is a Liferay to Payload migration a lift and shift?

   No. Liferay web content is built on structures and templates, and Payload uses typed collections defined in code. The content model is redesigned as part of the move, which is where much of the content-side effort sits. Document library assets, URL structure, and any integration wired into the portal each need their own decision before content moves.

Sources

Every claim about Liferay’s and Payload’s platforms in this guide comes from the vendors’ own documentation, checked on 11 September 2026.

• Upgrading to Jakarta — the Jakarta-based releases, what must be modified, and Liferay’s assessment of the process.
• Liferay DXP Free Tier — the capabilities requiring an Enterprise Subscription key, the three-node clustering limit, the Free Tier patch boundary, key validity, and the statement that moving to Enterprise requires no data migration or replatforming.
• Activating Liferay DXP — the activation-key requirement from 2026.Q1.
• Liferay DXP Free Tier: What It Is, How to Get It, and When to Upgrade — the Free Tier’s intended use, the production recommendation, the EULA review advice, the LGPL statement, the CE upgrade answer, and per-instance Enterprise licensing.
• Download Liferay DXP Free Tier — the current Free Tier releases and the Marketplace activation step.
• Authenticating with SAML and Using OpenID Connect — the SAML adapter’s Subscription label, and the OpenID Connect page, which carries none.
• Using Liferay as a Headless Platform and Web Content API Basics — the REST and GraphQL extraction routes, the StructuredContent, ContentStructure and ContentTemplate services, and the API Explorer path.
• Batch Engine API Basics: Exporting Data — bulk export through the Headless Batch Engine.
• Payload Enterprise — single sign-on and Publishing Workflows listed as enterprise features. Payload publishes no price list.
• Payload Authentication Overview — user accounts for the admin panel and for external applications, and custom authentication strategies.