{"title":"Deploy a per-tenant extension","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-deploy-tenant-customization/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-deploy-tenant-customization, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-deploy-tenant-customization","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Overview of how you deploy an .app package with a tenant customization to Dynamics 365 Business Central.","date":"2025-01-08","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Deploy a per-tenant extension","slug":"deploy-a-per-tenant-extension","at":0,"chars":6096},{"level":2,"title":"Extension uniqueness requirements","slug":"extension-uniqueness-requirements","at":1367,"chars":1093},{"level":2,"title":"Upload and schedule installation from the Admin Center","slug":"upload-and-schedule-installation-from-the-admin-center","at":2460,"chars":823},{"level":2,"title":"Upload and schedule installation from the Extension Management page","slug":"upload-and-schedule-installation-from-the-extension-management-page","at":3283,"chars":2065},{"level":3,"title":"Steps for deploying your .app file","slug":"steps-for-deploying-your-app-file","at":4224,"chars":1124},{"level":2,"title":"Upgrades and per-tenant extensions","slug":"upgrades-and-per-tenant-extensions","at":5348,"chars":552},{"level":2,"title":"Related information","slug":"related-information","at":5900,"chars":196}],"text":"# Deploy a per-tenant extension\nWhen you finish developing and testing your per-tenant extension (PTE), deploy the extension (.app file) containing the customization to your customer's production tenant. You can upload and deploy PTEs to an environment by using App Management in the Admin Center<../administration/tenant-admin-center-manage-apps> or by using the Extension Management page in the environment.\n> IMPORTANT\n> The recommended way to upload, install, and manage per-tenant extensions is now the Business Central Admin Center<../administration/tenant-admin-center-manage-apps> and its ../administration/administration-center-api_app_management. The in-product Extension Management upload flow and the Automation API extensionUpload endpoint are deprecated and planned for removal in 2027 release wave 1. See ../upgrade/deprecated-features-platform.\n> NOTE\n> You can only view scheduled installation details in the interface you use (Admin Center or Extension Management) to upload the PTE. To avoid confusion, use a single method consistently when deploying and installing PTEs for a given environment.\nWhen you deploy an .app file for the next version, the extension is queued to be deployed as part of the customer's tenant update to the next version. Typically, use this feature when you build an update of the extension to work with the next version.\n## Extension uniqueness requirements\nIf you're developing and deploying an updated version of a previously deployed extension, you must keep the app ID the same and increase the version number to successfully upgrade the extension. The deployment services require that uploaded extension packages be unique per tenant based on several sets of keys:\n Package ID\n App ID + Version\n Name + Publisher + Version\n> NOTE\n> These parameters are defined in the app.json file of the extension. See devenv-json-files#appjson-file.\nIf you successfully deployed an extension to a tenant, and then recompile the extension's source code without updating version number, this action generates a new extension package file with a new package ID. If you try to upload this new extension package file to a different tenant, the upload fails with the error similar to `An extension with same App ID and version has already been uploaded. Resolve and deploy again.`. Similarly, if an extension failed to deploy, and you try to upload a new extension package with the same version number, the upload fails as well.\n## Upload and schedule installation from the Admin Center\nAdministrators and applications can upload and schedule installation of PTEs from the Manage Apps page in the Admin Center or using its API. To upload a new PTE or an update to an existing PTE, choose Install Extension on the Manage Apps or App Details page. Uploading and deploying PTEs through the Admin Center requires internal, delegated, or application administrator permissions to access the Admin Center (API), but no more permissions are needed within the target environment itself.\nFor more information on required permissions, see The Business Central Admin Center<../administration/tenant-admin-center>.\nFor more information on managing apps in the Admin Center, see App Management in the Admin Center<../administration/tenant-admin-center-manage-apps>.\n## Upload and schedule installation from the Extension Management page\nUsers and applications can upload and schedule installation of PTEs from the Extension Management page in the environment or by using the Automation API. You must be able to sign in to the customer's tenant as a user with permissions to the Extension Management page to complete the deployment.\nUnder Manage, use the Upload Extension action to deploy the extension. You can deploy the extension for the current version or for the next version of the service. In most cases, select the current version, unless you developed the extension specifically for the next version.\nThe extension you're deploying might be the initial release of the customization or an upgrade to a previous version. Use the same steps for uploading a new extension or an extension upgrade. The service determines if the extension needs to be upgraded based on the extension's app ID and version.\n### Steps for deploying your .app file\n1. Sign in to your customer's Dynamics 365 Business Central tenant.\n1. Open the Extension Management page.\n1. Under Manage, choose the Upload Extension action.\n1. Select the browse button to select the .app file to upload. Browse to and select the extension's .app file.\n1. Select if you want to deploy for the current version (most common) or next minor or major version. Select the language for the deployment.\n1. Choose the Schema Sync Mode and select whether to add schema changes or to force the schema changes.\n1. Select the option switch to on to accept the disclaimer.\n1. Choose the Deploy button.\n1. The extension is deployed in the background.\n To check the status of the deployment, choose Deployment Status and then view the status of the extension deployment. Select the row to see other details.\n In the deployment status details, there's a Refresh button in the actions you must select to retrieve the most recent status and details.\n1. When the extension is successfully deployed, choose the Refresh button to see the new extension in the list of installed extensions.\n## Upgrades and per-tenant extensions\nIn some cases, Microsoft can't automatically upgrade a customer's production environment that includes a per-tenant extension. In those cases, Microsoft contacts the reselling partner and provides guidance for how to update the extension. However, if the extension remains impossible to update when the Business Central version the environment is on reaches its Enforced Update Period, the extension is uninstalled automatically to succeed the update. See Update Cycles<../administration/update-rollout-timeline>.\n## Related information\nGet started with AL<devenv-get-started>\nAL development environment<devenv-reference-overview>\nFAQ for developing in AL<devenv-dev-faq>\nUse Designer<devenv-inclient-designer>"}