Update Pay-as-you-go environment types

This page applies to Apigee, but not to Apigee hybrid.

View Apigee Edge documentation.

Apigee's Pay-as-you-go pricing attributes are based in part upon the environment types you attach to your Apigee instance. You can choose to add Base, Intermediate, or Comprehensive environments to your Pay-as-you-go organization at any time, tailoring a pricing scheme based on your feature and capacity needs. This topic explains how to upgrade or downgrade the type of an existing environment to add or remove feature capabilities and manage your Apigee Pay-as-you-go billing and resource usage.

Required roles and permissions

To get the permissions that you need to update a Pay-as-you-go environment type, ask your administrator to grant you the following IAM roles on the project:

  • Apigee Organization Admin (apigee.organization.admin)
  • Apigee Environment Admin (apigee.environment.admin)

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Update your environment type using the API

To update the type of an existing Pay-as-you-go environment, use the following command:

curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME?updateMask=type" \
  -H "Authorization: Bearer $token" \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"type":"ENV_TYPE"}'


  • ORG_NAME is the name of your Apigee Pay-as-you-go organization.
  • ENV_NAME is the name of the Apigee environment to update.
  • ENV_TYPE is the updated environment type. Options are BASE, INTERMEDIATE, or COMPREHENSIVE.

For example, to upgrade a Base environment named test-env to Comprehensive, use the following command:

curl "https://apigee.googleapis.com/v1/organizations/my-org/environments/test-env?updateMask=type" \
  -H "Authorization: Bearer $token" \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"type":"COMPREHENSIVE"}'

After the operation completes, use the following command to confirm the change in environment type:

curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME" -H "Authorization: Bearer $token"

This command returns the environment resource object, which includes the selected environment type.

Error reference

When upgrading or downgrading environment type, the operation will fail if the existing environment contains resources that are incompatible with the newly selected environment type. For more information on available features and limitations by environment type, see Comparison of environment types.

If the operation fails, you will see an error with the following format:

    "error": {
      "code": "FAILED_PRECONDITION",
      "message": "environment type update invalid: ...<detailed message here >... :failed precondition",
      "status": "FAILED_PRECONDITION"

The following table summarizes possible error messages and potential steps you can take to resolve the issue and upgrade or downgrade the environment type:

Failure condition Error message Steps to resolve
Maximum number of environments per organization exceeded cannot transfer active environments to INTERMEDIATE, will exceed limit

cannot transfer active environments to BASE, will exceed limit

Delete one or more environments from your organization.
Extensible proxy deployed in the environment existing environment has an extensible API Undeploy the extensible proxy from the environment.
Shared flow deployed in the environment existing environment has a shared flow Undeploy the shared flow from the environment.
Maximum number of proxy deployment units per environment per region pdu count, 50, cannot exceed 20

pdu count, 425, cannot exceed 50

Undeploy and delete shared flows or proxies from the environment.
Add-ons enabled in the environment Existing environment has an addon enabled Disable the add-ons in the environment.
Multi-region support enabled in the environment instance attachment count, 2, cannot exceed 1 for BASE environment

instance attachment count, 2, cannot exceed 1 for INTERMEDIATE environment

Delete the second instance attachment for the environment.