Unified Manifest for Word, Excel and PowerPoint Add-Ins: Migration, Dual Manifests and Your Support Matrix

In July 2026 Microsoft announced “the general availability of unified manifest support for Word, Excel, PowerPoint Add-ins, in addition to Outlook Add-ins.” The JSON-based unified manifest for Microsoft 365 is now the manifest Microsoft recommends “for most scenarios”. The older XML format, which Microsoft now calls the add-in only manifest, remains valid for production add-ins.

That sounds like a straightforward upgrade. For many vendors it is not, for one reason: not every Office client can install an add-in that uses the unified manifest. If your customers use perpetual Office on Windows, Outlook on Mac or Office on mobile, Microsoft’s own guidance is that “you must create and deploy two versions of the add-in”. At the same time, the end of support for older Office versions is reshaping which clients you need to support at all.

This article covers the unified manifest for Office add-ins from a product owner’s and engineering lead’s point of view: which clients support it, what it does not yet support, how to migrate, how to run two manifests without confusing your users, and how the decision connects to Microsoft’s Copilot agent roadmap. Every fact about Microsoft’s platform is taken from Microsoft’s documentation, checked on 9 October 2026 and listed at the end. Our recommendations are labelled as ours.

Which Clients Can Install a Unified-Manifest Add-In

Microsoft’s unified manifest overview states that “Add-ins that use the unified manifest can’t be installed on all platforms”, and gives this table:

Two further constraints apply. “Add-ins for OneNote and Project don’t support the unified manifest.” And for development, “Add-ins that use the unified manifest can be sideloaded only on Office Version 2304 (Build 16320.20000) or later.”

Perpetual includes LTSC. Microsoft’s add-ins glossary defines LTSC as “the perpetual version of Office that’s available through a volume-licensing agreement”. Office LTSC 2021 and Office LTSC 2024 therefore fall in the “perpetual versions: No” row.

There is one important exception. Microsoft’s guidance on managing both manifest types states: “if the user’s Microsoft 365 administrator deploys the add-in for all users, then the add-in can be installed on older versions of Microsoft 365 and on perpetual license versions of Office.” If your add-in reaches perpetual-Office customers only through central deployment by their administrators, you may not need a second version for them. Users who install the add-in themselves, from Microsoft Marketplace or by sideloading, are not covered by the exception.

What the Unified Manifest Does Not Yet Support

Microsoft lists features that “aren’t yet supported by the unified manifest”:

• Excel, PowerPoint and Word: the OnDocumentOpened event.
• Outlook: the OnMessageReadWithCustomAttachment and OnMessageReadWithCustomHeader events. Multi-item select and spam reporting are supported in classic Outlook on Windows, but not in new Outlook or Outlook on the web.

Two Outlook features are not supported with the unified manifest because they are “little used or deprecated”, and Microsoft says they have “been replaced by effectively equivalent features”: Outlook modules and Outlook contextual add-ins (activation rules). Microsoft suggests a Teams tab and event-based activation respectively as alternatives.

Check your add-in against this list before you plan a migration. A Word add-in that depends on OnDocumentOpened to set up a document as it opens has a feature gap to design around.

The Support Matrix Is Moving Underneath You

The manifest question coincides with changes to the Office versions you can reasonably support.

This is our reading of what that table means for an add-in vendor.

Your perpetual-Office audience is narrowing to Office 2024. Microsoft’s end-of-support page gives 13 October 2026 as the end of support for Office LTSC 2021. From that date, Office LTSC 2024 is the only volume-licensed perpetual Windows version on the list above with Microsoft support, and customers still on older versions are running unsupported software. You can reasonably say so in your own support policy. Retail Office 2024, which is also perpetual, is listed on Microsoft’s lifecycle site as supported until October 2029.

Requirement sets are frozen on two groups of clients. LTSC 2024 has the features of its September 2024 release. Microsoft 365 Apps on Windows 10 devices stop taking feature updates at Version 2608. Our expectation is that requirement sets Microsoft ships after those points will not reach those clients. If you adopt a new API, guard it with Office.context.requirements.isSetSupported() and design a fallback, or accept that the feature will not work for those users.

A dual-manifest period is a support-matrix decision, not just a packaging decision. How long you ship the add-in only manifest depends on how many of your customers are on perpetual Office, Outlook on Mac or mobile, and how they install your add-in.

Migrating: The Conversion Tools

Microsoft documents three routes for converting an add-in only manifest:

• Projects created with the Yeoman generator for Office Add-ins: npx office-addin-project convert -m <relative-path-to-XML-manifest>. “The new unified manifest is in the root of the project and the old add-in only manifest is in a backup.zip file.”
• Other Node.js projects: npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>.
• Microsoft 365 Agents Toolkit: “If the existing project uses the add-in only manifest, the importation feature automatically converts it to a unified manifest.” Microsoft also states that “Add-in projects in Agents Toolkit must use the unified manifest for Microsoft 365.”

Three caveats from the same documentation:

• “Visual Studio doesn’t support the unified manifest for Office Add-ins. Projects that were created in Visual Studio shouldn’t be converted.” If your add-in was created in Visual Studio, plan a project restructure, not a conversion.
• Excel custom functions need manual work. “Currently, neither of the tools… add the needed custom function support to the unified manifest.”
• There is a command limit. “An add-in that uses the unified manifest may not have more than 20 add-in commands”. Count your ribbon buttons and menu items before you start.

Our view is that the conversion command is the smaller part of the job. Plan most of the effort for testing the converted add-in on every client in your support matrix and resolving the differences.

Running Two Manifests Without Confusing Users

If you need both versions, Microsoft’s guidance is specific, and getting it wrong produces a visibly broken experience: two copies of your ribbon buttons.

1. Give the new version a new identity. The unified manifest’s "id" must be “a different GUID from the <Id> element in the add-in only manifest of the existing add-in”. Microsoft also advises: “Give the new version a different name from the existing add-in” and “Create and use different icons for the new version”, because “If you use the same name and icon, the old and new solutions appear indistinguishable in the Office UI for add-in installation.”

2. Link the two so that Office hides the old one. In the unified manifest’s extension object, add an "alternates" entry with a "hide" object that names the old add-in. For an add-in sold through Microsoft Marketplace:

"alternates": [
  {
    "hide": {
      "storeOfficeAddin": {
        "officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
        "assetId": "WA999999999"
      }
    }
  }
]

For an add-in distributed another way, such as centrally deployed by administrators, use "customOfficeAddin": { "officeAddinId": "..." } instead.

3. Expect a 24-hour overlap. “The configuration described below doesn’t take effect for up to 24 hours after the new version is installed on a user’s computer. During that period, the UI of both versions is visible.” Warn your customers’ administrators, and do not schedule a launch demonstration for the day after deployment.

4. Keep the old version published. “Don’t remove the existing add-in from Microsoft Marketplace or the Microsoft 365 Admin Center, or earlier versions of Office will no longer be able to use your add-in.”

5. Get the Marketplace details right. “If the asset ID of the add-in that you have linked in your unified manifest doesn’t match an existing offer published by your seller account, the unified manifest submission will fail.” And: “An existing add-in can only be hidden by a single unified manifest.”

Testing Both Manifests: Our Approach

This is our recommended practice rather than Microsoft guidance.

• One codebase, two manifests. The web application behind both versions should be the same build. The manifests differ in identity, name, icons and the features they declare. They should not point at different code.
• Treat manifest parity as a test. Keep a checklist of every command, event and permission in each manifest. Review the checklist in code review whenever either manifest changes, so that a button added to one is not forgotten in the other.
• Test by client, not by manifest. Your matrix should list the clients you support and which manifest each one receives. That might be Office on the web, Microsoft 365 Apps on Windows 11, a Windows 10 device on Version 2608, Office LTSC 2024 or retail Office 2024, Word on Mac and Outlook on Mac. Run the critical paths on each client.
• Feature-detect everything newer than your baseline. Wrap newer APIs in isSetSupported() checks and test the fallback path on a frozen client.

We covered requirement sets and cross-platform testing in more depth in Cross-Platform Office Add-Ins in 2026: One Codebase for Windows, Mac, Web, iOS, and Android.

Authentication Across Hosts: Nested App Authentication

A manifest migration is a good moment to modernise authentication. Microsoft’s single sign-on guidance for Office Add-ins is to use MSAL.js with nested app authentication (NAA) “to enable single sign-on (SSO) from your Office Add-in”, and its authentication overview describes the older Office.js getAccessToken approach as legacy.

The essentials from Microsoft’s documentation:

• Call createNestablePublicClientApplication from @azure/msal-browser. acquireTokenSilent and acquireTokenPopup are supported. acquireTokenRedirect is not.
• Check for the NestedAppAuth 1.1 requirement set at run time.
• Register a redirect URI of type Single Page Application in the form brk-multihub://your-add-in-domain, using the origin only. “Currently the brk-multihub group includes Word, Excel, PowerPoint, Outlook, and Teams (for when Office is activated inside)”. Word, Excel and PowerPoint on the web also need an additional redirect URI.
• In Office on the web, NAA is currently supported “only for documents that are opened from Microsoft SharePoint Online and OneDrive.” Design a fallback sign-in for documents opened from elsewhere.

Manifest First, Copilot Later

Microsoft’s add-ins overview now lists the ability to “Create custom Copilot agents that read and write to documents open in Office applications (preview)”. Excel also has custom skills for Copilot, which Microsoft says are “in preview … available in only the Beta and Current Channel (Preview) channels” and warns: “Don’t use them in a production Copilot extension.”

Both are previews. Nothing in this article suggests building production features on them. But there is a connection to the manifest decision. Microsoft’s Agents Toolkit, the tooling for Microsoft 365 extensibility, works only with the unified manifest for add-in projects. Our view is that an add-in already on the unified manifest is better placed to adopt agent capabilities once they mature, because it already uses the same manifest format as other Microsoft 365 extensions. If a Copilot integration is on your roadmap for 2027, migrating the manifest now is preparation you can ship today.

A Decision Guide

Our recommendation, by situation:

How McKenna Consultants Can Help

McKenna Consultants is a UK Office add-in development consultancy. We build and maintain Word, Excel, PowerPoint and Outlook add-ins for software vendors and enterprises. For AuditBoard, we accelerated the development of Word and Excel add-ins that link evidence in documents to their audit platform, working inside their planning processes and advising on Microsoft AppSource submission.

We can assess your add-in against the unified manifest’s gaps, convert and restructure the project, set up a dual-manifest release with correct linking, and build the test matrix for the clients your customers actually use. Contact us or read more about our Microsoft Office add-in services.

Sources

All sources checked on 9 October 2026.

• Microsoft 365 Developer Blog — Build Once, Run Everywhere: Unified Manifest for Office Add-Ins now Generally Available (16 July 2026): GA for Word, Excel and PowerPoint, in addition to Outlook.
• Microsoft Learn — Office Add-ins with the unified manifest for Microsoft 365: client and platform support table; the two-versions requirement; features not yet supported; OneNote and Project.
• Microsoft Learn — Office Add-ins manifest and Office Add-ins platform overview: unified manifest recommended for most scenarios; add-in only manifest valid for production; custom Copilot agents (preview).
• Microsoft Learn — Convert an add-in to use the unified manifest for Microsoft 365: conversion tools; Visual Studio; custom functions; 20-command limit; sideloading version.
• Microsoft Learn — Manage both a unified manifest and an add-in only manifest version of your Office Add-in: "alternates"/"hide" linking; 24-hour overlap; naming, icons and IDs; Marketplace asset ID; admin-deployment exception; unsupported Outlook features.
• Microsoft Learn — Import an add-in project into Agents Toolkit: automatic conversion; Agents Toolkit projects must use the unified manifest.
• Microsoft Learn — Office Add-ins glossary: LTSC is a perpetual version; perpetual includes retail versions.
• Microsoft Learn — End of support for older versions of Office: Office LTSC 2021, Office 2019 and Office 2016 dates; LTSC feature scope.
• Microsoft Lifecycle — Office 2024: retail Office 2024 (Home, and Home & Business) supported until October 2029.
• Microsoft Lifecycle — Office 2021: retail Office 2021 retirement in October 2026.
• Microsoft Learn — Microsoft 365 Apps on Windows 10: Version 2608 and security updates until 10 October 2028.
• Microsoft Learn — Enable nested app authentication in your add-in: MSAL API, redirect URI, supported hosts and limitations.
• Microsoft Learn — Nested app auth requirement sets: NAA in Office on the web only for documents opened from SharePoint Online and OneDrive.
• Microsoft Learn — Overview of authentication and authorization in Office Add-ins: NAA as the SSO path; getAccessToken described as legacy.
• Microsoft Learn — Overview of Copilot skills for Excel (preview): preview status and channel limits.