Structure Requests

This guide details many of the intricacies of structuring requests that create and update Performance Max campaigns. It can be a useful resource as you design your integration. This guide explains how requests that mutate Performance Max campaigns are processed and can be a companion resource to the Performance Max troubleshooting guide and the Performance Max batch processing guide.

Create Performance Max campaigns

In the Google Ads API, Performance Max campaign entities are represented as a combination of several unique resources.

Standard Performance Max campaigns

Standard Performance Max campaigns require a minimum set of resources in order to serve.

• Campaign budget
• Campaign
• Asset groups
• Asset group assets
• Assets

It is important to note that the operations to create AssetGroup and AssetGroupAsset entities must be included together in a single request, and the AssetGroupAsset resources must combine to meet all minimum asset requirements and specifications; see how this is different for Retail campaigns. Requests to create an AssetGroup without all required AssetGroupAsset entities results in an error; see Invalid state versus invalid requests for more context.

There are different options when it comes to structuring requests that create Performance Max campaigns. The decision as to how to group operations and structure requests depends largely on your objectives and infrastructure.

• Create the CampaignBudget, Campaign, and Asset resources in separate requests prior to creating the AssetGroup and AssetGroupAsset resources.
• Include all of these resources in a single mutate request.

While you can successfully create the CampaignBudget, Campaign, and Asset resources in separate prior requests, the Performance Max campaign won't be eligible to serve until the AssetGroup and AssetGroupAsset resources are created as well.

Minimum requirements for a valid serving Performance Max campaign

You can further customize your Performance Max campaigns by creating additional resources as shown in the diagram.

• Asset Group Signals
• Campaign Conversion Goals
• Campaign Criteria

You can include operations to create AssetGroupSignal resources in the same request that creates the AssetGroup and AssetGroupAsset resources. Alternatively, you can create AssetGroupSignal entities in a separate request following the creation of the AssetGroup.

Performance Max campaign with additional options

Performance Max campaigns for retail

Retail campaigns are unique in that there are two discrete ways to create asset groups that result in a valid serving campaign:

• Asset groups without any assets
• Asset groups that contains ALL required assets (preferred)

When you choose to exclude assets from asset groups, Google automatically uses the assets provided in your linked Merchant Center account to create ads. However, we recommend providing assets to reach across all inventory. Performance Max campaigns for retail requires the following minimum set of resources in order to serve.

• CampaignBudget
• Campaign (with populated ShoppingSettings)
• AssetGroup
• AssetGroupListingGroupFilter

It is important to note that the Campaign.shopping_settings field must be populated in retail campaigns. In addition, the final_urls listed in each AssetGroup must match URLs associated with the Merchant Center account ID specified in the Campaign.shopping_settings. Finally, each AssetGroup must have an associated, valid product listing group tree composed of one or more AssetGroupListingGroupFilter resources. At a minimum, you must create a single node tree to account for all products in your specified Merchant Center feed.

Each of these resources can be created separately or in a single request. However, the campaign won't be eligible to serve until all of these resources have been created correctly.

Minimum requirements for a valid serving Retail Performance Max campaign

Retail campaigns can utilize all of the options available to standard Performance Max campaigns, including creating asset group signals, campaign conversion goals, and campaign criteria. If you do choose to add assets to an AssetGroup when creating the AssetGroup resource, your AssetGroup is subject to the minimum asset requirements. In other words, you can either include no assets or all required assets.

Retail Performance Max campaign with additional options

Invalid state versus invalid requests

When working with Performance Max campaigns in the Google Ads API, there is an important distinction between invalid states and invalid requests.

Invalid state

The campaign is not eligible to serve because of how it is configured. For example, you can create a standalone Campaign resource with an advertising_channel_type of PERFORMANCE_MAX. Although the request to create the campaign succeeds, it is not eligible to serve until you add at least one AssetGroup to the campaign. If your requests succeed but your campaign or asset groups are not serving, you can use CampaignPrimaryStatus, CampaignPrimaryStatusReason, AssetGroupPrimaryStatus, and AssetGroupPrimaryStatusReason to determine the reason, as detailed in the troubleshooting guide.

Invalid request

A request that wouldn't succeed because it would put the campaign or resource into an invalid state. For example, the Google Ads API throws an error if you try to create an AssetGroup for a non-retail campaign without including the minimum required assets. This is why you must include an AssetGroup and its AssetGroupAsset resources in the same request. This also means that all of your AssetGroupAsset resources must meet the correct specifications for a given field_type to prevent the entire request from failing.

Group operations with mutate requests

Performance Max campaigns are composed of multiple resources, and you have the option to create these separate resources in unique requests or in a single bulk mutate request. However, AssetGroups and associated AssetGroupAssets in standard Performance Max campaigns must be created in a single atomic request as already noted.

Your campaign is not eligible to serve until you've successfully created all of the required resources noted throughout this guide. When issuing separate requests, use the actual resource names of referenced resources in subsequent requests. When issuing bulk mutate requests containing multiple operations use resource names formed with the use of temporary IDs.

Order of operations

Regardless of whether you use a bulk mutate request to create a Performance Max campaign, you must order your requests and operations such that you never reference a resource before it is created. In the case of bulk mutate requests, this means ordering the operations in such a way that referenced resources are listed before the resources that reference them.

If you choose to create Asset resources in the same bulk mutate request that creates an AssetGroup and its AssetGroupAsset resources, all of the AssetOperations should come before all of the AssetGroupAssetOperations, as demonstrated in the diagram.

The Google Ads server batches consecutive AssetGroupAssetOperations together and evaluates whether an AssetGroup meets minimum asset requirements following the last operation in that group. If you alternate between AssetOperations and AssetGroupAssetOperations in your request, the API server will evaluate minimum asset requirements after the first AssetGroupAssetOperation and return an error without proceeding with the rest of the operations in the request. As a result, none of the assets in the request would be added to your Google Ads account. Furthermore, neither the AssetGroup nor any of the associated AssetGroupAsset resources would be created.

Update asset groups

After you've created a valid AssetGroup, you can't issue subsequent requests that would result in an invalid state in which the minimum asset requirements are no longer met. Any such requests throws an error. For example, if you create an AssetGroup with a single MARKETING_IMAGE (the minimum requirement), any requests to remove the AssetGroupAsset associated with that MARKETING_IMAGE would return an error.

This is particularly important in the case of asset groups in retail campaigns created without any associated assets. Subsequent requests to add assets to the AssetGroup by creating AssetGroupAsset resources would only succeed if the request met all asset requirements. In other words, you can't add assets to these asset groups incrementally.