Migrate to Innovate Summit:
Learn how migrating and modernizing to Azure can boost your business's performance, resilience, and security, enabling you to fully embrace AI.Register now
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Programmatically create Azure subscriptions for a Microsoft Customer Agreement with the latest APIs
Article
This article helps you programmatically create Azure subscriptions for a Microsoft Customer Agreement using the most recent API versions. If you're still using the older preview version, see Programmatically create Azure subscriptions with legacy APIs.
In this article, you learn how to create subscriptions programmatically using Azure Resource Manager.
When you create an Azure subscription programmatically, that subscription is governed by the agreement under which you obtained Azure services from Microsoft or an authorized reseller. For more information, see Microsoft Azure Legal Information.
You can't create support plans programmatically. You can buy a new support plan or upgrade one in the Azure portal. Navigate to Help + support and then at the top of the page, select Choose the right support plan.
Prerequisites
You must have an owner, contributor, or Azure subscription creator role on an invoice section or owner or contributor role on a billing profile or a billing account to create subscriptions. You can also give the same role to a service principal name (SPN). For more information about roles and assigning permission to them, see Subscription billing roles and tasks.
If you're using an SPN to create subscriptions, use the ObjectId of the Microsoft Entra Enterprise application as the Principal ID using Microsoft Graph PowerShell or Azure CLI.
Note
Permissions differ between the legacy API (api-version=2018-03-01-preview) and the latest API (api-version=2020-05-01). Although you may have a role sufficient to use the legacy API, you might need an EA admin to delegate you a role to use the latest API.
Use the displayName property to identify the billing account for which you want to create subscriptions. Ensure, the agreementType of the account is MicrosoftCustomerAgreement. Copy the name of the account. For example, to create a subscription for the Contoso billing account, copy aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx. Paste the value somewhere so that you can use it in the next step.
Azure PowerShell
Get-AzBillingAccount
You'll get back a list of all billing accounts that you have access to
JSON
Name : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx
DisplayName : Contoso
AccountStatus : Active
AccountType : Enterprise
AgreementType : MicrosoftCustomerAgreement
HasReadAccess : True
Use the displayName property to identify the billing account for which you want to create subscriptions. Ensure, the agreementType of the account is MicrosoftCustomerAgreement. Copy the name of the account. For example, to create a subscription for the Contoso billing account, copy aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx. Paste the value somewhere so that you can use it in the next step.
Azure CLI
az billing account list
You'll get back a list of all billing accounts that you have access to.
Use the displayName property to identify the billing account for which you want to create subscriptions. Ensure, the agreementType of the account is MicrosoftCustomerAgreement. Copy the name of the account. For example, to create a subscription for the Contoso billing account, copy aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx. Paste the value somewhere so that you can use it in the next step.
Find billing profiles & invoice sections to create subscriptions
The charges for your subscription appear on a section of a billing profile's invoice. Use the following API to get the list of billing profiles and invoice sections on which you have permission to create Azure subscriptions.
First you get the list of billing profiles under the billing account that you have access to (Use the name that you got from the previous step)
GET https://management.azure.com/providers/Microsoft.Billing/billingaccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingprofiles/?api-version=2020-05-01
The API response lists all the billing profiles on which you have access to create subscriptions:
Copy the id to next identify the invoice sections underneath the billing profile. For example, copy /providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx and call the following API.
JSON
GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoicesections?api-version=2020-05-01
Use the id property to identify the invoice section for which you want to create subscriptions. Copy the entire string. For example, /providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx.
You'll get the list of billing profiles under this account as part of the response.
JSON
Name : AW4F-xxxx-xxx-xxx
DisplayName : Contoso Billing Profile
Currency : USD
InvoiceDay : 5
InvoiceEmailOptIn : True
SpendingLimit : Off
Status : Active
EnabledAzurePlans : {0002, 0001}
HasReadAccess : True
BillTo :
CompanyName : Contoso
AddressLine1 : One Microsoft Way
AddressLine2 :
City : Redmond
Region : WA
Country : US
PostalCode : 98052
Note the name of the billing profile from the above response. The next step is to get the invoice section that you have access to underneath this billing profile. You'll need the name of the billing account and billing profile.
Name : SH3V-xxxx-xxx-xxx
DisplayName : Development
The name above is the Invoice section name you need to create a subscription under. Construct your billing scope using the format /providers/Microsoft.Billing/billingAccounts/<BillingAccountName>/billingProfiles/<BillingProfileName>/invoiceSections/<InvoiceSectionName>. In this example, this value equates to "/providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx".
Azure CLI
az billing profile list --account-name"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx"--expand"InvoiceSections"
This API returns the list of billing profiles and invoice sections under the provided billing account.
Use the id property under the invoice section object to identify the invoice section for which you want to create subscriptions. Copy the entire string. For example, /providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx.
Create a subscription for an invoice section
The following example creates a subscription named Dev Team subscription for the Development invoice section. The subscription is billed to the Contoso Billing Profile billing profile and appears on the Development section of its invoice. You use the copied billing scope from the previous step: /providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx.
An in-progress status is returned as an Accepted state under provisioningState.
To install the version of the module that contains the New-AzSubscriptionAlias cmdlet, in below example run Install-Module Az.Subscription -RequiredVersion 0.9.0. To install version 0.9.0 of PowerShellGet, see Get PowerShellGet Module.
Run the following New-AzSubscriptionAlias command and the billing scope "/providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx".
Azure PowerShell
New-AzSubscriptionAlias -AliasName"sampleAlias" -SubscriptionName"Dev Team Subscription" -BillingScope"/providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx" -Workload"Production"
You get the subscriptionId as part of the response from the command.
az account alias create --name"sampleAlias"--billing-scope"/providers/Microsoft.Billing/billingAccounts/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx"--display-name"Dev Team Subscription"--workload"Production"
You get the subscriptionId as part of the response from the command.
The previous section showed how to create a subscription with PowerShell, CLI, or REST API. If you need to automate creating subscriptions, consider using an Azure Resource Manager template (ARM template) or Bicep file.
The following template creates a subscription. For billingScope, provide the invoice section ID. The subscription is created in the root management group. After creating the subscription, you can move it to another management group.
JSON
{
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"subscriptionAliasName": {
"type": "string",
"metadata": {
"description": "Provide a name for the alias. This name will also be the display name of the subscription."
}
},
"billingScope": {
"type": "string",
"metadata": {
"description": "Provide the full resource ID of billing scope to use for subscription creation."
}
}
},
"resources": [
{
"scope": "/",
"name": "[parameters('subscriptionAliasName')]",
"type": "Microsoft.Subscription/aliases",
"apiVersion": "2021-10-01",
"properties": {
"workLoad": "Production",
"displayName": "[parameters('subscriptionAliasName')]",
"billingScope": "[parameters('billingScope')]"
}
}
],
"outputs": {}
}
Or, use a Bicep file to create the subscription.
Bicep
targetScope = 'managementGroup'
@description('Provide a name for the alias. This name will also be the display name of the subscription.')paramsubscriptionAliasNamestring
@description('Provide the full resource ID of billing scope to use for subscription creation.')parambillingScopestringresourcesubscriptionAlias'Microsoft.Subscription/aliases@2021-10-01' = {
scope: tenant()name: subscriptionAliasNameproperties: {
workload: 'Production'displayName: subscriptionAliasNamebillingScope: billingScope
}
}
Deploy the template at the management group level. The following examples show deploying the JSON ARM template, but you can deploy a Bicep file instead.
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/mg1/providers/Microsoft.Resources/deployments/exampledeployment?api-version=2020-06-01
To move a subscription to a new management group, use the following ARM template.
JSON
{
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"targetMgId": {
"type": "string",
"metadata": {
"description": "Provide the ID of the management group that you want to move the subscription to."
}
},
"subscriptionId": {
"type": "string",
"metadata": {
"description": "Provide the ID of the existing subscription to move."
}
}
},
"resources": [
{
"scope": "/",
"type": "Microsoft.Management/managementGroups/subscriptions",
"apiVersion": "2020-05-01",
"name": "[concat(parameters('targetMgId'), '/', parameters('subscriptionId'))]",
"properties": {
}
}
],
"outputs": {}
}
Or, the following Bicep file.
Bicep
targetScope = 'managementGroup'
@description('Provide the ID of the management group that you want to move the subscription to.')paramtargetMgIdstring
@description('Provide the ID of the existing subscription to move.')paramsubscriptionIdstringresourcesubToMG'Microsoft.Management/managementGroups/subscriptions@2020-05-01' = {
scope: tenant()name: '${targetMgId}/${subscriptionId}'
}