Programmatically create Azure Enterprise subscriptions (preview)

As an Azure customer on Enterprise Agreement (EA), you can create EA (MS-AZR-0017P) and EA Dev/Test (MS-AZR-0148P) subscriptions programmatically. In this article, you learn how to create subscriptions programmatically using Azure Resource Manager.

When you create an Azure subscription from this API, that subscription is governed by the agreement under which you obtained Microsoft Azure services from Microsoft or an authorized reseller. To learn more, see Microsoft Azure Legal Information.

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Prerequisites

You must have an Owner role on the Enrollment Account you wish to create subscriptions under. There are two ways to get these roles:

  • Your Enrollment Administrator can make you an Account Owner (sign in required) which makes you an Owner of the Enrollment Account. Follow the instructions in the invitation email you receive to manually create an initial subscription. Confirm account ownership and manually create an initial EA subscription before proceeding to the next step. Just adding the account to the enrollment isn't enough.

  • An existing Owner of the Enrollment Account can grant you access. Similarly, if you want to use a service principal to create the EA subscription, you must grant that service principal the ability to create subscriptions.

Find accounts you have access to

After you're added to an Azure EA enrollment as an Account Owner, Azure uses the account-to-enrollment relationship to determine where to bill the subscription charges. All subscriptions created under the account are billed towards the EA enrollment that the account is in. To create subscriptions, you must pass in values about the enrollment account and the user principals to own the subscription.

To run the following commands, you must be logged in to the Account Owner's home directory, which is the directory that subscriptions are created in by default.

Request to list all enrollment accounts you have access to:

GET https://management.azure.com/providers/Microsoft.Billing/enrollmentAccounts?api-version=2018-03-01-preview

Azure responds with a list of all enrollment accounts you have access to:

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/enrollmentAccounts/747ddfe5-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "747ddfe5-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "Microsoft.Billing/enrollmentAccounts",
      "properties": {
        "principalName": "SignUpEngineering@contoso.com"
      }
    },
    {
      "id": "/providers/Microsoft.Billing/enrollmentAccounts/4cd2fcf6-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "4cd2fcf6-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "Microsoft.Billing/enrollmentAccounts",
      "properties": {
        "principalName": "BillingPlatformTeam@contoso.com"
      }
    }
  ]
}

Use the principalName property to identify the account that you want subscriptions to be billed to. Copy the name of that account. For example, if you wanted to create subscriptions under the SignUpEngineering@contoso.com enrollment account, you'd copy 747ddfe5-xxxx-xxxx-xxxx-xxxxxxxxxxxx. This identifier is the object ID of the enrollment account. Paste this value somewhere so that you can use it in the next step as enrollmentAccountObjectId.

Create subscriptions under a specific enrollment account

The following example creates a subscription named Dev Team Subscription in the enrollment account selected in the previous step. The subscription offer is MS-AZR-0017P (regular Microsoft Enterprise Agreement). It also optionally adds two users as RBAC Owners for the subscription.

Make the following request, replacing <enrollmentAccountObjectId> with the name copied from the first step (747ddfe5-xxxx-xxxx-xxxx-xxxxxxxxxxxx). If you'd like to specify owners, learn how to get user object IDs.

POST https://management.azure.com/providers/Microsoft.Billing/enrollmentAccounts/<enrollmentAccountObjectId>/providers/Microsoft.Subscription/createSubscription?api-version=2018-03-01-preview

{
  "displayName": "Dev Team Subscription",
  "offerType": "MS-AZR-0017P",
  "owners": [
    {
      "objectId": "<userObjectId>"
    },
    {
      "objectId": "<servicePrincipalObjectId>"
    }
  ]
}
Element Name Required Type Description
displayName No String The display name of the subscription. If not specified, it's set to the name of the offer, like "Microsoft Azure Enterprise."
offerType Yes String The offer of the subscription. The two options for EA are MS-AZR-0017P (production use) and MS-AZR-0148P (dev/test, needs to be turned on using the EA portal).
owners No String The Object ID of any user that you'd like to add as an RBAC Owner on the subscription when it's created.

In the response, you get back a subscriptionOperation object for monitoring. When the subscription creation is finished, the subscriptionOperation object would return a subscriptionLink object, which has the subscription ID.

Limitations of Azure Enterprise subscription creation API

  • Only Azure Enterprise subscriptions can be created using this API.
  • There's a limit of 200 subscriptions per enrollment account. After that, more subscriptions for the account can only be created through the Account Center. If you want to create more subscriptions through the API, create another enrollment account.
  • Users who aren't Account Owners, but were added to an enrollment account via RBAC, can't create subscriptions using the Account Center.
  • You can't select the tenant for the subscription to be created in. The subscription is always created in the home tenant of the Account Owner. To move the subscription to a different tenant, see change subscription tenant.

Next steps