This cmdlet has the following aliases,
New-AzSubscriptionDeployment
Description
Submits a deployment to the target subscription. Use subscription-scope deployments for resources that live outside a resource group, such as resource groups themselves, policy assignments, and role assignments. The template is supplied as a local ARM JSON or Bicep file (-TemplateFile), a URL (-TemplateUri), a template spec (-TemplateSpecId), or an inline hashtable (-TemplateObject). Bicep files are compiled with the Bicep CLI, which must be installed. Template parameters can be supplied via file (-ParametersFile), URI (-ParametersUri), or as Name=Value pairs through -Parameter. -QueryString supplies a query string for the template URI, not template parameter values. -Mode sets the deployment mode, Incremental or Complete. The cmdlet waits for the deployment to finish and returns the result.
Examples
Deploy a Bicep file at subscription scope
Submit main.bicep with parameter file main.parameters.json as deployment sub-infra-2026-06-16, storing the deployment metadata in eastus.
The Azure region that stores the deployment metadata, for example eastus. Subscription-scope deployments have no resource group to inherit a region from, so a location is required.
Template parameters supplied as inline Name=Value pairs. Use this when you don't have a parameters file. Pass an array for multiple values. Values are parsed as JSON when possible, and otherwise treated as strings. Inline values overlay same-named keys from -ParametersFile and cannot be combined with -ParametersUri.
Path to a local ARM/Bicep parameters file (*.parameters.json or *.bicepparam). A .bicepparam file names its own template through its using declaration, so no template parameter is needed alongside it.
Optional SAS token or query string sent on the template link. Requires -TemplateUri.
A leading ? or & is removed. This value is not added to -ParametersUri.
Resource ID of an existing template spec version to deploy (for example, /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Resources/templateSpecs/{name}/versions/{version}).
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
about_CommonParameters.
The completed DeploymentExtended object containing the deployment name, provisioning state, outputs declared by the template, and correlation ID.
Notes
Subscription-scope templates must use the subscriptionDeploymentTemplate.json schema, or targetScope = 'subscription' in Bicep. Use New-AzResourceGroupDeployment to deploy into a resource group instead.
The legacy Az.Resources name New-AzSubscriptionDeployment and the parameter names -DeploymentName, -TemplateParameterFile, and -TemplateParameterUri are accepted as aliases.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.