Upgrade an enterprise

An Enterprise resource binds an organization to your EMM. Multiple enterprise bindings can be associated with a single organization to facilitate test and QA EMM environments, or separate regional EMM implementations.

Bindings can be of two different types:

• A managed Google Play Accounts enterprise, which is created by an IT admin using a Gmail account.
• A managed Google domain enterprise, which is created by an IT admin using their work email (as part of the new recommended signup flow).

Binding enterprises to a managed Google domain is now the default for Play EMM API and is strongly encouraged.

The benefits of using a managed Google domain for an IT admin include:

• Better security and manageability for the IT admin credentials when logging in using a work address versus a Gmail account.
• Multiple EMM instances can be bound and managed from the same managed Google domain.
• Multiple Google products and services can be managed with the same IT admin login.
• Account recovery is simpler for both admin and user accounts on a managed Google domain.

For users, having enterprises bound to a managed Google domain provides several advantages, including:

• Simplifies user login by allowing users to login with their work email on Android devices.
• Allows additional services including SSO, Google Workspace and Gemini on managed devices.
• Enables cross device experiences including Chrome Sync, sharing files across devices, transferring meetings between devices and more.

This guide describes how to upgrade a managed Google Play Accounts enterprise (created with a Gmail account) to a managed Google domain enterprise.

Types of upgrades

There are two mechanisms with which to upgrade a managed Google Play Accounts enterprise.

• EMM-initiated: EMMs use APIs to query the binding type, and provide a way for an IT admin to start the upgrade for eligible bindings using a button or a similar UX element directly from their console.
• Managed Google Play iframe-initiated: organization IT admins can start the upgrade process from the managed Google Play iframe.

Guidance for EMMs

The following steps are highly recommended for EMMs, in order to recognize when an upgrade happens, support EMM-initiated and iframe-initiated upgrades, and present the updated enterprise information to the IT admin.

1. Set up Pub/Sub notifications

It is highly recommended to sign up for Pub/Sub notifications to receive an alert when an enterprise is upgraded. Subscribe to EnterpriseUpgradeEvent with the enterprise ID of every bound organization enterprise to watch for upgrade events. Look for upgradeStateSucceeded to indicate a successful upgrade.

Since upgrades can happen using both the EMM-initiated flow and the managed Google Play iframe, Pub/Sub notifications allow EMMs to monitor both methods and take actions that could include:

• Updating contact info in their UI, removing the old Gmail account and updating to the new administrator[].email for the upgraded enterprise.
• Removing messaging that prompts IT admins to upgrade, once the upgrade is complete.

The same Pub/Sub notification is used for EMM-initiated upgrades as well as iframe-initiated upgrades.

2. Upgrade methods

EMM-initiated upgrade flow

EMMs are strongly encouraged to implement the EMM-initiated flow. IT admins that initiate an upgrade using this flow (typically from an EMM console) will be redirected to a URL that provides a similar upgrade experience to the iframe-initiated flow, however the IT admin will not be prompted to login to their existing Gmail account. This shortens and simplifies the upgrade process and also provides an upgrade option for customers that don't have access to the Gmail account originally used to bind the enterprise.

• The first step in the upgrade process is to determine the enterprise type, and whether that enterprise is eligible for upgrade. To determine the enterprise type, call enterprises.get, and receive "enterpriseType": String. Enterprises of type managedGooglePlayAccountsEnterprise are eligible for upgrade. Enterprises of type managedGoogleDomain have either been upgraded, or were created using a work email and thus are not eligible for upgrade.
• For eligible enterprises generate an enterprise upgrade URL using enterprises.generateEnterpriseUpgradeURL.
• After generating the upgrade URL, implement a button (or similar UI element) that embeds the URL which IT admins will use to initiate the upgrade process. This button or similar element should only be shown for enterprises that are eligible for upgrade.
• It is recommended to provide guidance to the IT admin, explaining the upgrade process and encouraging customers to upgrade. Refer to (or link directly to) this help center article for customer facing information on upgrades.

Note: Take care to only present the upgrade button (or similar UI element) to IT admin roles that are authorized to initiate the upgrade. Since the IT admin is not prompted for the enterprise owner's Gmail credentials, any admin presented with the upgrade URL will be able to execute the upgrade.

Play EMM API Python example:

# Enterprise ID
ENTERPRISE_ID = "LC01056q4j"

response =
msa_service.enterprises().get(enterpriseId=ENTERPRISE_ID).execute()
enterprise_type = response['enterpriseType']

# Generates an enterprise upgrade URL if the enterprise is a managed Google Play Accounts enterprise
if (enterprise_type != "managedGooglePlayAccountsEnterprise"):
  response = esa_service.enterprises().generateEnterpriseUpgradeUrl(
      enterpriseId=ENTERPRISE_ID
  ).execute()
  print(response['url'])

Iframe-initiated upgrade flow

EMMs should be familiar with the flow that IT admins will encounter when initiating an upgrade from the managed Google Play iframe:

• IT admins will encounter a banner on the top of the iframe for managed Google Play enterprises notifying them that they are eligible to upgrade to a managed Google domain. The IT admin has the opportunity to initiate the upgrade, or close the banner to delay the notification. If closed, the banner will reappear after 30 days.

• If an IT admin elects to begin the upgrade they will be prompted to sign in with their existing managed Google Play Accounts enterprise owner account (typically the Gmail address used to originally bind the enterprise). This step confirms the admin has rights to initiate the upgrade for this managed Google Play enterprise binding.

• Upon successful login, the admin will be prompted to provide their work email. If they are already an admin of a managed Google domain with sufficient privileges, they will be able to use that account to finish the upgrade steps. If there isn't already a domain verified managed Google Domain for that company name, the IT admin will be guided to create one.

Note: The managed Google domain created by this step will be an email-verified team. Later the IT admin will want to verify the domain using DNS in order to unlock the full capabilities of the managed Google domain.

• Upon successful login, or completion of the steps to create a managed Google domain admin account, the IT admin will be prompted to confirm their intent to upgrade to a managed Google domain. Completion of this step will result in a success screen and the admin can visit a help center article or log into the Google admin console.

3. After successful upgrade

Upon receiving a Pub/Sub notification of an enterprise upgrade, you can optionally call enterprises.get to confirm the binding type to be managedGoogleDomain. The enterprise ID remains the same as it was prior to the upgrade.

After upgrade, EMMs should remove any messaging shown in their console encouraging users to upgrade this enterprise.

The Gmail address of the IT admin (administrator[].email) will be replaced by a new work email address of the IT admin.

The enterprise field name will also be changed upon upgrade to reflect the name of the managed Google domain.

Note: Any contact info (e.g. Gmail address) for the previously associated binding is deleted upon successful upgrade. If the organization wishes to update contact information, it must be done in the admin console of the now associated managed Google domain.