Tag Archives: adwords_api

Announcing v6.1 of the Google Ads API

Today, we’re announcing the v6.1 release of the Google Ads API. To use some of the v6.1 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. This version has no breaking changes.

Here are the highlights: Where can I learn more?
The following resources can help you get started: If you have any questions or need additional help, contact us via the forum.
Josh Radcliff, on behalf of the Google Ads API Team

Sunsetting Portofolio Enhanced CPC Bid Strategies

On March 22, 2021 we will begin to sunset portfolio (shared) Enhanced cost-per-click (ECPC) bid strategies. The following behaviors will be blocked in all versions of both the AdWords API and the Google Ads API:
  • Creating new portfolio ECPC strategies.
  • Attaching portfolio ECPC strategies to campaigns.
Note that standard (non-portfolio) ECPC strategies will not be affected.

Affected Portfolio Enhanced CPC Strategies
Google Ads API Bidding_strategy.type = BiddingStrategyType.ENHANCED_CPC
AdWords API SharedBiddingStrategy.type = MANUAL_CPC,

SharedBiddingStrategy.biddingScheme.enhancedCpcEnabled = TRUE


Change Description
Any operation creating new portfolio ECPC strategies, or attaching a portfolio ECPC strategy to a campaign, will generate one of the following errors:

Error Upon Creation Error Upon Attaching
Google Ads API BIDDING_STRATEGY_NOT_SUPPORTED CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN
AdWords API BIDDING_STRATEGY_NOT_SUPPORTED CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN


Migration Description
In the future, we will remove the portfolio ECPC strategy entirely, in favor of standard ECPC. In order to prepare for this change, you can proactively migrate all your portfolio ECPC strategies to standard ECPC strategies using the instructions below.

All remaining portfolio ECPC campaigns and strategies will be automatically migrated at a later date. We will post an update on this blog ahead of that migration.

Self-migration using Google Ads API
Update a campaign by using CampaignService.MutateCampaigns() to set its manual_cpc.enhanced_cpc_enabled field to true. Be sure to set the update_mask on your request to match: 

operations: [
  {
    update: {
      resource_mame: customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID,
      manual_cpc: {
        enhanced_cpc_enabled: true
      }
    },
    update_mask: manual_cpc.enhanced_cpc_enabled
  }
]
Self-migration using AdWords API
Update a campaign by using CampaignService.mutate() to set its biddingStrategyType to MANUAL_CPC, and its biddingScheme.enhancedCpc field to true: 

<operations>
  <operator>SET</operator>
  <operand>
    <id>CAMPAIGN_ID</id>
    <biddingStrategyConfiguration>
      <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
      <biddingScheme>
        <enhancedCpcEnabled>true</enhancedCpcEnabled>
      </biddingScheme>
    </biddingStrategyConfiguration>
  </operand>
</operations>
If you have any questions or need additional help, contact us via the forum or at [email protected].
Adam Ohren, Google Ads API Team

Changes to phrase match and broad match modifier

On February 4, 2021, we announced upcoming changes to phrase match and broad match modifier. To simplify the keyword portfolio and help advertisers reach more relevant user searches, we are bringing behaviors of broad match modifier (BMM) into phrase match, and phasing out support for BMM. This will be a gradual rollout that will change the back end processing for keyword match types (AdWords API, Google Ads API, Google Ads scripts) in order to simplify keywords and make it easier to reach relevant customers.

The updated phrase match will contain the best of both match types: the control of phrase match, and the expanded reach of broad match modifier. Both phrase and BMM keywords will continue to work and beginning February 18, 2021 for our first wave of languages (English, German, Spanish, French, Italian, Dutch, Portuguese, Russian), keywords using the phrase or BMM notations will begin to use the updated phrase match behavior. In Q2 we will begin the same process for all other Google Ads languages, and expect to complete in July 2021.

In July 2021, once all languages have the updated phrase match behavior, advertisers will be prevented from creating new BMM keywords (but any legacy BMM keywords will still work).

The changes to phrase match and BMM will not impact negative keyword match types.

How does this change affect the AdWords API, Google Ads API and Google Ads scripts?
Starting in July 2021, you will no longer be able to create new BMM keywords (i.e. matchType of BROAD and keyword text in which tokens begin with +). We will do a separate reminder announcement as we get closer to this milestone.

What impact should advertisers expect?
Impact will depend on each advertiser's usage of phrase and/or BMM and how comprehensive their query coverage is.
  • Advertisers predominantly using phrase match are expected to see an incremental increase in clicks and conversions
    • This is due to the additional queries to which these keywords will now be eligible to match. For example, “holidays in zambia” as a phrase keyword will now begin to match to “holiday spots in zambia”, which was previously only eligible for BMM.
  • Advertisers predominantly using BMM are expected to see a slight decrease in clicks and conversions
    • The majority of this loss is from BMMs where the modifier was only applied to part of the keyword, e.g. tennis +shoes.
    • In addition we are now considering word order when it’s important to the meaning of the keyword, so some matches that previously matched to BMM will be filtered out.
What should I do?
Advertisers may experience traffic shifts. User queries that previously matched to keywords in one match type may become eligible to match to a phrase or legacy BMM keyword causing the volume to move across keywords. For this reason it is important for advertisers to monitor their accounts and adjust budgets if needed to accommodate additional volume. Additional best practices are outlined in the announcement.

If you have any questions or need additional help, contact us via the forum.
, Google Ads API Team

The Invoice Service of Google Ads API is out of beta

The InvoiceService is now available for all API users starting with version 6 of the Google Ads API. Earlier API versions will continue to only support this service for allowlisted accounts.

This service retrieves the monthly invoices of Google Ads accounts. Each returned Invoice comes loaded with data (for example: adjustments, regulatory costs, taxes, account budgets) and can be downloaded as a PDF file. Google Ads manager accounts can use the data to automatically reconcile customer invoices. To get started, read through our dedicated guide.

If you have any questions or need additional help, contact us through the forum or at [email protected].
Pierrick Voulet, Google Ads API Team

Disabling "lead" category mutates in AdWords API

On March 8, 2021 we're disabling mutates to the Lead category in the AdWords API. The Google Ads API ConversionActionCategory is not affected. This is a follow-on to the conversion category changes and expanded conversion categories announced in September 2020, which provided a finer grained categorization of conversions.

We are making this change because we are seeing some advertisers change their new category conversion types back to Lead category through the AdWords API, resulting in ambiguity since multiple new categories map to this old category. The following table summarizes how the AdWords API will respond to mutates that set the conversion category to Lead.
Existing Category AdWords API READs (Existing behavior) AdWords API Mutate to LEAD Response
Lead Lead OK
“Old” category “Old” category ERROR
“New” lead category Lead OK
“New” non-lead category “Old” category ERROR

Since the AdWords API does not support all the new conversion categories, reading in a new fine grained Lead conversion category will be mapped to Lead upon read, but will continue to be persisted as the finer grained new category. If read through the Google Ads UI or Google Ads API, the new conversion category will be accurately retrieved.

As a recap from our September 2020 announcement, here is the mapping of new conversion category types to existing AdWords API ConversionTracker.Category enum values:
New Conversion Category Mapping to ConversionTracker.Category
Add to cart LEAD
Begin checkout LEAD
Purchase PURCHASE
Subscribe PURCHASE
Sign-up SIGNUP
Phone call lead LEAD
Imported lead LEAD
Submit lead form LEAD
Book appointment LEAD
Request quote LEAD
Get directions LEAD
Outbound click LEAD
Contact LEAD
Download DOWNLOAD
Page view PAGE_VIEW
Engagement DEFAULT
Store visit DEFAULT
Store sale PURCHASE
Other DEFAULT

If you have any questions or need additional help, contact us via the forum.
, Google Ads API Team

Ad Policy Error Management is evolving in Google Ads API

On March 1st, 2021, all versions of the Google Ads API will replace policy violations with policy findings for all remaining ad types.

The impact is limited to the creation and update of ads that trigger ad policy errors for the following types:
  • CALL_ONLY_AD
  • EXPANDED_DYNAMIC_SEARCH_AD
  • GMAIL_AD
  • HTML5_UPLOAD_AD
  • IMAGE_AD
  • LEGACY_APP_INSTALL_AD
  • LOCAL_AD
  • RESPONSIVE_DISPLAY_AD
  • RESPONSIVE_SEARCH_AD
  • VIDEO_RESPONSIVE_AD
If your application is impacted by this change and not upgraded before March 1st, 2021, then the ad policy errors will no longer be recognized and the requested exemptions will not be applied.

What’s Changing
Both AdGroupAdService.MutateAdGroupAds and AdService.MutateAds methods will behave differently: What’s Not Changing What to Do
Before March 1st, 2021, make sure to add the support of policy findings in your management of ad policy errors. To get started, you can refer to our guide and code example that are both dedicated to ad policy error management. We recommend testing with the ad types that already use policy findings: EXPANDED_TEXT_AD and RESPONSIVE_SEARCH_AD.

If you have any questions or need additional help, contact us through the forum or at [email protected].
Pierrick Voulet, Google Ads API Team

Ad Policy Error Management is evolving in Google Ads API

On March 1st, 2021, all versions of the Google Ads API will replace policy violations with policy findings for all remaining ad types.

The impact is limited to the creation and update of ads that trigger ad policy errors for the following types:
  • CALL_ONLY_AD
  • EXPANDED_DYNAMIC_SEARCH_AD
  • GMAIL_AD
  • HTML5_UPLOAD_AD
  • IMAGE_AD
  • LEGACY_APP_INSTALL_AD
  • LOCAL_AD
  • RESPONSIVE_DISPLAY_AD
  • RESPONSIVE_SEARCH_AD
  • VIDEO_RESPONSIVE_AD
If your application is impacted by this change and not upgraded before March 1st, 2021, then the ad policy errors will no longer be recognized and the requested exemptions will not be applied.

What’s Changing
Both AdGroupAdService.MutateAdGroupAds and AdService.MutateAds methods will behave differently: What’s Not Changing What to Do
Before March 1st, 2021, make sure to add the support of policy findings in your management of ad policy errors. To get started, you can refer to our guide and code example that are both dedicated to ad policy error management. We recommend testing with the ad types that already use policy findings: EXPANDED_TEXT_AD and RESPONSIVE_SEARCH_AD.

If you have any questions or need additional help, contact us through the forum or at [email protected].
Pierrick Voulet, Google Ads API Team

Changes to conversion columns in AdWords API and Scripts

What's changing?
We are introducing restrictions on certain combinations of conversion columns in AdWords API and Google Ads scripts reports. If your reporting queries include these column combinations, you need to fix your queries before Feb 15, 2021.

Technical details
Starting the week of Feb 15, 2021, you will receive a ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT error if your AdWords API report request contains columns from both of the restricted column sets listed below. Similarly, calls to the AdsApp.report method in Google Ads scripts will fail for queries with these restricted column combinations.

Restricted conversion columns:
  • ConversionAdjustment
  • ConversionAdjustmentLagBucket
  • ConversionAttributionEventType
  • ConversionCategoryName
  • ConversionLagBucket
  • ConversionTrackerId
  • ConversionTypeName
Metrics columns:
  • AllConversionRate
  • ConversionRate
  • CostPerAllConversion
  • CostPerConversion
  • CostPerCurrentModelAttributedConversion
The ReportDefinitionService.getReportFields method will reflect these restrictions in the exclusiveFields list of each impacted column.

What should you do?
Before Feb 15, 2021, review and modify the reporting queries in your AdWords API and Google Ads scripts applications to stop using the prohibited column combinations.

Why is this changing?
These column combinations are currently disallowed by the Google Ads UI, Google Ads Editor and the Google Ads API. This change makes the AdWords API and Google Ads scripts behaviour consistent with the rest of the Google Ads platform.

If you have any questions or need help, please contact us via the forum.
- Anash P. Oommen, Google Ads API Team

Update to Customer Match Uploads in the Google Ads API and the AdWords API Starting March 1, 2021

On March 1, 2021, the Google Ads API and the AdWords API will have a new upload limit for each Customer Match upload request. There is no change to the limit of the overall Customer Match audience list size.

What code do I need to change?
When uploading user identifiers for Customer Match, check that the number of user identifiers you are uploading per request is within the limit.
Google Ads API AdWords API
Limit 100,000 per request 500,000 per user list ID per request
Method OfflineUserDataJobService.AddOfflineUserDataJobOperations() AdWordsUserListService.mutateMembers()
Field userIdentifiers membersList
Error on exceeding upload limit TOO_MANY_USER_IDENTIFIERS TOO_MANY


Why is this changing?
In order to make the processing of Customer Match user identifiers more efficient, we needed to set the new upload limit.

If you have any questions while updating your code, please reach out to us on our Google Ads API and AdWords API forum.
Nadine Wang, Google Ads API Team

Announcing v6 of the Google Ads API

Today, we’re announcing the v6 release of the Google Ads API. To use the v6 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published this week. For more information on breaking changes, see the migration guide.

Here are the highlights:
  • The API now has Change History similar to the Google Ads UI with ChangeEvent including what interface and who made the changes.
  • You can now manage user access in your Google Ads account.
  • Maximize conversion value and maximize conversions are now available as portfolio bidding strategies, which includes Search.
  • The new Customer.optimization_score_weight helps you calculate your overall optimization score for your manager account.
  • New audience types are available including CombinedAudience and CustomAudience.
Where can I learn more?
The following resources can help you get started:
If you have any questions or need additional help, contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team